Smart Component Builder Best Practices

Learning Team

Overview

Smart Component Builder is an AI-powered tool that lets you create and customize the tiles and data tables that appear on record pages throughout Practifi. Rather than requiring developer expertise or manual JSON configuration, Smart Component Builder lets you describe what you want to see in plain language and generates the component for you.

Whether you want to surface active services for a client, highlight upcoming tasks for the current user, or display a count of deals in a specific stage, Smart Component Builder puts that capability at your fingertips. Components you create can be added to various page layouts in your organization, giving your team the precise views they need without waiting on a development cycle.

Smart Component Builder supports two component types:

Tiles: Compact summary views ideal for displaying aggregated values, key metrics, or a focused set of records at a glance.
Data Tables: Full list views that let users browse, filter, and act on related records directly from a record page.

This article covers best practices for getting the most out of Smart Component Builder and includes answers to frequently asked questions.

Best Practices
Frequently Asked Questions
Troubleshooting

Best Practices

Be Specific and Include Key Details

The key to getting great results from Smart Component Builder is using clear, structured prompts. Think of each prompt as a set of instructions that tells the builder exactly what you want to create.

When describing a component, use concise, structured sentences that include:

The object you want to display data from
The fields you want to show
Any filters to apply to the data
Sorting preferences
Actions users can take on the data

For example, instead of “Create a table of deals,” try “Create a table of open deals for this household, sorted by expected close date, with columns for deal name, value, stage, and owner.”

Always specify the base object explicitly in your first prompt. If the base object is ambiguous, the AI may select the wrong one, and the base object cannot be changed once the component has been started. If that happens, you will need to restart the request from the beginning.

Give Instructions One at a Time

Providing too many instructions in a single message can lead to incomplete or inconsistent results. Instead of combining all requirements into a single prompt, start with the core component definition and build from there with follow-up messages.

A good starting point is to describe the record selection criteria you want, then continue chatting with the AI until you reach the desired result. The AI may ask clarifying questions, and your responses help it make better decisions.

For example, rather than writing one long message that combines component type, columns, filters, and actions all at once, break it into a series of shorter exchanges:

Start with: “Create a tile of active services for the current account.”
Then add: “Include columns for Service Name, AUM, Related Entity, Created Date, and Owner.”
Then: “Add interactive filters for Service Type and Stage.”

Use Iterative Refinement

Do not feel pressured to include everything in a single message. Start with the basics and add details through follow-up messages.

Make one change at a time and confirm in the preview before making additional changes. This approach helps you identify exactly which modifications produce which results.

After the initial component is generated, you can refine it with statements like:

“Add a Priority column.”
“Remove the Created Date column.”
“Filter to only show high priority items.”
“Add a row action to mark tasks complete.”
“Change the sort order to Priority descending.”

Use the Correct Filter Terminology

Smart Component Builder distinguishes between two types of filtering, and using the correct terminology helps the AI apply the right behavior:

DataSource Filter: Controls which records are included in the component. Use terms like “restrict table data” or “DataSource Filter” when defining record selection criteria. For example: “Count the number of tasks that are in Open status. Restrict the task data to Task Type = Call and Owner = logged in user.”
Interactive Filter / Table Filter: Adds a visible filter control that users can interact with on the component. Use terms like “interactive filter” or “table filter” when you want users be able to filter the data themselves.

Use Example Prompts as a Starting Point

You can use either a conversational style or a structured technical style when creating prompts. Both work effectively; choose the approach that feels most natural to you.

Conversational Style

Basic Table: “Create a table of tasks showing Subject, Due Date, and Priority.”

Filtered Table: “Create a table of open tasks assigned to the current user." "Show the Subject, Due Date, Status, and Related To columns." "Sort by Due Date ascending.”

Aggregation Tile: “Build a tile that counts Deals in the Proposal stage for the current account.”

Current User Filter: “Show only records owned by the current user.”

Record Context Filter: “Show tasks related to the current Household.”

Structured Technical Style

Table Component: “Build a table of Tasks with columns: Subject, Status, Priority, Due Date; filter to Open tasks assigned to the current user; sort by Due Date asc; add action to Open Record.”

Tile Component: “Create a tile view of Tasks showing Subject, Status, and Due Date; filter to Overdue tasks; group by Owner; add action to Open Record.”

Use the Preview Panel Effectively

Take time to examine the live preview before saving. The preview shows real data from your organization so that you can verify that:

Columns appear in the right order
Filters are applied correctly
Actions work as intended
Data displays as expected for different records (use the Record Variable selector to test)

Catching issues in preview is much easier than correcting them after saving.

Follow Naming Conventions

Use clear, descriptive names that follow a consistent pattern. A recommended naming convention is:

[Context] - [Category] - [Description]

This format makes components easier to find and manage as your component library grows.

Examples:

Advisor - Tasks - Open Tasks Table
Client - Processes - Active Processes Tile Row
Home - Activity - Weekly Summary Tiles
Household - Deals - Open Deals by Stage

Experiment with Different Approaches

If a component doesn’t look quite right, try describing the desired outcome differently. The AI assistant can often achieve the same result through multiple paths, and rephrasing your requirements sometimes produces better results.

If the AI does not seem to understand a condition you’ve described, reiterate it with more explicit language. For example, if you prompt “Get all active services” and the AI excludes only cancelled and terminated stages, follow up with a more specific instruction that lists exactly which stages to include or exclude.

Learn from the Config File View

Even if you don’t plan to edit JSON directly, occasionally switching to the Config File view helps you understand how conversational requirements translate into technical configuration. This knowledge makes you more effective at describing future components.

Advanced users can edit the raw JSON in the Config File view for fine-grained control. If you do make manual edits, validate the configuration against the schema before saving to avoid runtime errors in your production environment. The Config File view includes built-in validation to help ensure your configuration is properly structured.

Validate Before Saving

For most users working through the conversational interface, the AI assistant handles validation automatically. It’s still good practice to thoroughly test components in the preview panel before saving.

If you are working in the Config File view and making manual edits, validate your component configuration before saving to avoid runtime errors in your production environment.

Test Before Deploying Widely

When creating new components for record pages, test them in Lightning App Builder before rolling them out to all users. Verify that the component displays correctly, performs well, and provides the intended functionality.

Verify Component Usage Before Deleting

Before deleting a component, verify that no Lightning pages are still using it. Pages referencing deleted components will display an error or empty state where the component used to be.

Frequently Asked Questions

General Questions

Do I need to know JSON to use Smart Component Builder?

No. The AI assistant handles all JSON generation. You describe what you want in plain English, and the system creates the proper configuration. If you prefer to work directly with the underlying configuration, the Config File view is available for advanced users.

Can I still manually edit the JSON if needed?

Yes. The Builder includes a Config File view that lets you view and edit the raw JSON. This is useful for advanced users who want fine-grained control over a component’s configuration.

Is there a limit to how many components I can create?

There is no hard limit on the number of components. Follow your organization’s governance policies for component management to keep your library organized and maintainable.

Why is the Restore Original button active when I have just started editing a component?

When a component is opened in Smart Component Builder, it is considered edited. The Restore Original button is always active, but it only has an effect when a previously saved instance exists. If you have not yet saved any changes, clicking Restore Original will return the component to its last saved state.

Access and Permissions

Why can’t a user see Smart Component Builder?

Check that:

The user has the Practifi - Smart Component Builder permission set assigned
The AI feature is enabled for your organization
The Smart Component Builder tab is added to their Settings app

Can I restrict which users can create vs. only view components?

Currently, the Practifi - Smart Component Builder permission set grants full access to create, edit, and save components. For view-only access, users can use components on Lightning pages without needing Builder access.

Can non-administrator users create components?

Yes. Non-administrator users with the Practifi - Smart Component Builder permission set can create and edit components. However, adding components to Lightning record pages requires administrator access in Lightning App Builder. If you need a component deployed to a page and do not have administrator access, coordinate with your Practifi Administrator.

Component Building

Why doesn’t the AI understand what object I’m referring to?

Try using the exact object name or a common variation:

For Practifi objects, you can say “Tasks” instead of “Task.”
For custom objects, try the label name (such as Asset & Liability) or the API name.

When the base object is not explicitly stated, the AI may infer the wrong one. Always name the base object directly in your first prompt to avoid this. The base object cannot be changed once the component has been started, so getting this right from the beginning is important.

Can I change a tile to a table after I’ve started building?

No. The component type (tile or data table) is set during the initial prompt and cannot be changed afterward. If you need a different component type, you must restart the request from the beginning, specifying the correct type in the first prompt.

Can I change the base object of a component after the initial prompt?

No. Once a component has been created and the base object has been set, it cannot be changed through the chat interface. This applies to both new components and existing components you are editing. If you need a different base object, restart the request and specify the object explicitly in your first prompt.

Can I create components that query multiple objects?

No. Smart Component Builder supports single-object queries. Each component is based on one object.

Can I query fields that are two levels deep in the data model?

Yes, two-level field lookups are supported. If the AI is not picking up the correct field at the second level, explicitly include the full field path in your prompt. For example, to access the Group field from a Service Type, specify the path as:

practifi__Service_Type__r.practifi__Group__c

Can I specify multiple criteria on the same field?

Yes. Multiple criteria on the same field are supported. Be explicit about each condition in your prompt. For example: “Select clients only with AUM > 30000 and AUM < 3000000.”

Can I create components for custom objects I’ve added to Practifi?

Smart Component Builder supports Practifi's standard objects. For custom objects, you may need to work with your implementation team.

Why isn’t my filter working in the preview?

Common causes include:

The filter field may not have data that matches your criteria
A Record Variable may need to be selected for context-dependent filters
The filter operator may not be appropriate for the field type

Saving and Deployment

I saved my component, but it’s not showing up on the page. What’s wrong?

Ensure that:

The Lightning page component is configured with the exact component name
The page has been saved and activated
Users have refreshed their browsers

Can I have multiple versions of the same component?

Yes. You can save components with different names and use different versions on different pages.

What happens if I delete a component that’s being used on a page?

The page will show an error or empty state where the component was. Always verify a component is not in use before deleting it.

Known Issue

Why does the multi-select lookup filter show IDs instead of names after selections are made?

This is a known issue. When selections are made in a multi-select lookup filter created through Smart Component Builder, the selected records display as IDs rather than their names. The filter itself functions correctly. An enhancement to resolve this display behavior is planned for a future release.

Troubleshooting

The table below outlines common issues and suggested solutions.

Issue	Possible Cause	Solution
"Feature not enabled" message	Issue with the AI feature parameter	Contact your Client Success Manager to enable the feature
User can't access Smart Component Builder	Missing permission set	Contact your Practifi Administrator to assign the Practifi - Smart Component Builder permission set
Chat not loading	Network connectivity issue	Verify access to https://services.practifi.com/ Contact your administrator if connectivity issues persist
Preview shows no data	Filters too restrictive or no matching records	Adjust filters or select the appropriate Record Variable
Can't save component	Validation errors	Review error messages and fix component structure
Can't edit packaged component	Component is locked	The system automatically creates a clone when you save changes to packaged components (see the Working with Cloned Components section in Understanding and Using Smart Component Builder)
Filters not updating table	Missing event handler	Contact your Client Success Manager for component updates
Component type needs to change (tile to table or vice versa)	Component type is locked after initial creation	Start a new component with the correct type specified in the first prompt
Multi-select lookup filter shows IDs instead of names	Known display issue	The filter functions correctly. An enhancement to resolve the display is planned for a future release