Records: Design and Build a View into Your Data
Learn how to build an entity-backed record, which allows us to view and modify data from a relational database.
In this article, you will learn how to create and configure a record type. For guided walkthroughs on creating records, check out our tutorials.
A record type allows you to define a set of records from your business data and processes, and create views for that data that you can make available to your end users. Before creating a record type, it may be helpful to review how records are used in Tempo.
Record types are created in Appian Designer.
From the New dropdown, select Record Type.
Enter a name and description for your record type in the appropriate fields.
Every record type needs a data source. This can be a database table, a data store entity (DSE), a process, a Salesforce connected system, or an external web service. When you select anything other than a process as your data source, you can also choose to sync your record data with Appian. To configure a data source with sync enabled, see Enable sync.
This section explains how to configure each type of data source for a record type without sync enabled.
A record type that uses a database as the data source is the easiest and the most common type of record to configure. Choose this option when your data source is a synced or non-synced database table or a data store entity.
To create a record type that uses a data store entity:
For CHOOSE SOURCE TYPE, select Database.
Note that every row in the table or entity will be treated as an individual record of your record type.
You can use any process model as the data source for a record type. Each running instance of that process model will be treated as an individual record of your record type. This type of record is less common, and can be a little more challenging to configure. It may be helpful to walk through the process model tutorial, which has a section on record types that use a process model as the data source.
To create a record type from a process model:
For CHOOSE SOURCE TYPE, select Process.
You may have external data in Salesforce that you want to use as your data source for your record type. Appian allows you to bring that data in through a Salesforce connected system and use it as the to your data source for your record type.
To create a record type that uses a Salesforce object:
For CHOOSE SOURCE TYPE, select Salesforce.
See the Salesforce Connected Systems for more information.
Your enterprise data may be spread across a number of different systems. With the power of Appian integrations, you can use a web service as the data source for a record type.
To learn more about using a web service as the record type data source, see the Record Type Object page.
For a full walkthrough on using a web service as the record type data source without enabling sync, see the Service-Backed Records Tutorial.
To create an unsynced record type from a web service:
After configuring your record type to use a web service, you can enable paging and search for your record list by adding appropriate rule inputs to the record data source expression rule.
Add a rule input of type PagingInfo to the record data source expression rule to enable paging and sorting. Then, select the rule input from the Paging Info dropdown.
Similarly, to configure searching on your record, you must add a rule input of type Text and select the rule input from the Search Text dropdown in the record type.
To enable filtering on the record list, you must add a rule input for each user filter to the integration for your connected system and the Record Data Source expression rule for the record type. Each rule input should correspond to the type that will be returned by the associated user filter dropdown. The selected value will then be passed to the Record Data Source expression rule, where the developer can apply it to the integration.
To learn more, see User Filters for Service-Backed Record Types.
For information about legacy expression-backed records created on Appian 19.4 or earlier, see the Appian 19.4 documentation.
If the source of your record type's data comes from a database table, a Salesforce object, or another web service, you can sync your data to cache it in Appian for faster queries and confident performance wherever you are working with that data in Appian.
Before enabling see, review the guidelines on when to enable sync for your record types.
To enable sync:
The record list is a display of all of the records for a given record type and any filters configured for the record type. By default, new record types are created with a grid-style list.
The record list can be displayed as a feed or a grid. When the list is a feed, each record is displayed in a vertical list like a news feed. When the list is a grid, the records display in rows like a spreadsheet.
In the Orders list shown, you can see the same set of records displayed in both a feed (left) and a grid (right).
Additionally, the grid-style list allows you to sort the record data by columns. See grid-level settings for more information.
For new record types, grid-style is the default record list format. The grid-style list is configured with an interface that is similar to the interface object. It allows you to easily navigate and configure the components of the grid.
To configure your grid-style list, go to the List page and click Edit List to open the Edit Record List dialog. If this is a new record, you'll notice that there's already a grid configured. A column is automatically generated for the first 50 fields in your source table. You can add, remove, or modify columns as necessary to display the record data you want to appear in the grid. If you've configured a read-only grid for an interface in Design Mode before, this interface should be familiar.
Also note that the record link component is automatically configured for the second column in the grid. You can remove this record link or configure another column to display as a record link.
There are three main levels to the grid that allow you to easily navigate between the record list configurations in the left pane: (1) Grid level, (2) Column level, and (3) Component level.
A grid's general settings allow you to set which columns to display and how many rows to display per page. It also allows you to configure the initial sort you want to apply when the record list is first opened, the secondary sort to apply after the user interacts with a grid column, and a number of styling settings.
In the Edit Record List dialog, you can see the grid is divided into four main areas described in the table below.
Section | Name | Description |
---|---|---|
(A) | Grid navigation | The grid navigation is the highest level available and provides a drop-down view of the grid settings, including the column and component levels. You can click here at any time to navigate and return to the grid settings. |
(B) | Column selection | This section allows you to choose the columns and define the column order you want the grid to display. You can add a new column by clicking Add Column at the bottom of the column list. You can also hover over the options menu ( ) for a selected column to add another column above or below the column, reorder the column by moving it up or down, or delete the selected column. |
(C) | Display settings | This section allows you to define how many rows you want displayed per page, the initial and secondary sort parameters, and styling options. See Record Design for more information. |
(D) | Test | Click Test at any time to refresh the grid preview. This resets sorting so you can preview how the grid will look when it's first loaded. |
See Grid-Style Record List for a full list of grid properties.
You can configure a number of settings for a grid column, including its label, width, alignment, and sort.
There are two ways to edit a column's settings. You can edit a column by clicking on any column name in the navigation pane or the Columns section of the Grid settings.
In the example shown, the first column in the grid list, Order #, is configured as the default sort. This means the record data is sorted on this column in ascending order to make this column sortable by your end users. The Label for column #3, Purchase Name, was changed to Contact. By selecting purchaserName in the Sort Field dropdown, we've made this column sortable.
In the DEFAULT FILTERS section, select the By Field radio button. You can also edit the columns as an expression. Simply click the Expression Editor icon next to the grid column you want to modify.
In the DEFAULT FILTERS section, select the By Field radio button. The example below shows how to make the same label changes to column #3 by clicking the Expression Editor icon next to Title (Grid Column). Notice the Label field is now set to "Contact".
You can also set the sort feature on any column field.
If you don't set a Sort Field for a column, users won't be able to click on that column to sort it.
Each grid column can take an expression that evaluates to an accepted component in Display Value and apply it across all column rows. Grid columns can display plain text or an allowed component in each column row.
The image above shows a text component configured for the Contact column. It has a Display Value of fv!row[recordType!Purchase Order.fields.purchaserName]
.
At the component level, record variables must be called with the record type field reference, using fv!row[recordType!recordName.fields.fieldName]
. Every field in your data source is available as a record field.
DISPLAY OPTIONS provides a list of formatting templates for the most common component types and allows you to select the one you want to set up. To edit an existing component, simply click on the component's name.
If you don't configure a component for your column, the column fields will display as plain text.
For a full list of available components, see Grid-Style Record List.
To give your records a title that will display at the top of every record view, go to the Views page and enter a title in the Record Title field. Note that this is an expression field so encase text values in quotes.
You can allow users to export grid-style record lists to Excel. Simply select the checkbox under the Style section to add an Export to Excel button to the record list. This button allows users to download a copy of their filtered record list in Excel.
For additional information, see: Optimizing Export to Excel.
To keep the list up-to-date, you can define a Refresh Interval to seamlessly refresh the record list with the latest record data every few minutes.
With a time-based refresh, your list of records will be automatically refreshed even when the user doesn't interact with the list. If the Refresh Interval is set to None, users will need to click the refresh button on the list or manually refresh the page on the browser to view the latest records in the list.
Defining a Refresh Interval will not trigger a sync on record type with data sync enabled. Instead, refreshing the record list will only re-query the cached version of your data.
To automatically refresh the record list:
Under Refresh Interval, use the dropdown to select how often the list should be refreshed in minutes.
Note that refresh intervals may impact performance. See Performance considerations for more information.
A feed-style record list is a vertical list of records that resembles a news feed. This is an alternative to the grid-style list in the previous section.
The feed-style list is created with the listViewItem function.
A feed-style record list cannot display more than 100 records. If the record set includes more than 100 records, consider a Grid-style record list. You may also consider creating user filters so that users can filter the records to return only those that match the selected filter.
To create a feed-style record list, from the List page, select Feed, then click Edit Record List.
This will display the Edit List dialog, which contains the List View editor and Sort Field setting. In List View, enter a function or expression for your list view. In Sort Field, select a field to sort on and the sort order.
Notice that record variables are references with the record variable domain (rv!
). Every field in your data source can be referenced using rv!record
with a record type field reference. For example, rv!record[recordType!Employee.fields.firstName]
refers to the firstName field of the Employee record.
The listViewItem
expression in the previous image results in a list that looks like this:
The first record in the above image has been color coded against the listViewItem
function so you can see how the parameters display.
Many users find it helpful to create the list view in a separate expression rule and call that rule here.
In this example, the record image itself (in the image parameter) is called from a rule that returns an image for each record based on the record's status. Below is the rule we used to choose the appropriate image.
fetchOrderIcon
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
a!localVariables(
local!status: choose(wherecontains(ri!status,cons!CASE_APP_OrderStatus),
"EYE",
"CLOCK",
"WARNING",
"PAPER_AIRPLANE",
"TASK"
),
local!color: choose(wherecontains(ri!status,cons!CASE_APP_OrderStatus),
"BLUE",
"GREY",
"ORANGE",
"GREEN",
"GREEN"
),
a!iconNewsEvent(local!status,local!color)
)
A record list action is a link to a process model the user can start directly from the record list. It is common to configure this action for users to create a new record for that record type.
To create a record list action,
From the List page, click New Action at the bottom of the Action grid.
Select the process model you want to use as a record list action in the Process Model field.
Save the record type.
Default filters allow you to filter records before they are loaded in the record list. Records filtered this way are completely inaccessible to the user, and won't show up in searches or queries by that user.
Each default filter defines a condition that must be true for a record to display in the list. If you have multiple conditions, the record must meet all conditions in order to display.
From the Source & Default Filters page, you can create a default filter using one of the following options:
a!queryFilter()
or a!queryLogicalExpression()
.You can apply default filters to any object, or component that allows you to reference the record type. This includes the record list, record views, or read-only grid. You can also apply default filters to any function that allows you to reference the record type, such as a!queryRecordType
, a!queryFilter()
or a!queryLogicalExpression()
.
For more information about default filters, see Default Filters.
To create a default filter,
Click on New Default Filter. This will display the Create New Default Filter form.
Enter the value for the comparison in the Value field. This is an expression field, so encase text values in quotes.
For example, the filter in the following screenshot removes all records with a status of Closed.
queryFilter
or queryLogicalExpression
. For additional details, see Default Filters on Record Types.The Default Filters field doesn't exist for record types that use a web service as the data source, and should instead be implemented directly in the Record List Source expression rule.
User filters, like default filters, allow you to define conditions that must be true for a record to display in the list. You can have multiple user filters for the record list. Unlike default filters, users control user filters on the record list.
Configure each filter using the guided configuration experience or the expression-based approach.
User filters for record types that use a web service as the data source are configured differently than user filters for other record types. To learn more, see User Filters for Record Types that Use a Web Service.
Click New User Filter in the User Filters section. This displays the Create New User Filter form.
By default, user filters are visible to all users with permission to view the record type. If you want to restrict the filter visibility, click Only show when… from the Visibility section and enter an expression that displays the filter when the expression evaluates to true.
Now it's time to create some filter options. Each one of these will display under the filter dropdown at the top of the record list. When the user clicks on one of the options, it'll filter the records for all that match that condition. By default, multiple filter options can be selected at a time from a single user filter. To change the filter setting to allow a single selection only, disable the "Users can select multiple options" field.
To create a new user filter:
Click New Option.
You can choose one of your options as the Default Filter Option, which means when a user first loads the record list, this option will already be selected. They can clear the option by clicking on it, if they want to choose another.
To choose a default option, select the Set default option checkbox. This will open the expression editor. Enter in an expression that evaluates to one of the option labels defined in the user filter.
Click New User Filter in the User Filters section. This displays the Create New User Filter form.
By default, user filters are visible to all users who can see the record type. If you want to restrict the filter visibility, click Only show when… from the Visibility section and enter an expression that displays the filter when the expression evaluates to true.
You can choose to add a default From or default To value. This means when a user first loads the record list, the configured values will already be selected. They can clear the option by clicking on it, if they want to choose another.
In addition to default filters set by developers, users can also save and manage their own filters. These user-saved filters can be saved by choosing values from the existing user filters and selecting Save filters as… from the Filters menu.
The Filters menu allows each user to name their filters and choose which filter they want to load by default when they navigate to the record list or the grid that uses the record type as a data source. The Filters menu also allows users to access and view all of their saved filters by selecting Manage my filters…. From here, users can remove or rename existing filters.
Each saved filter will display with a shortcut at the top of the page next to My Filters.
All saved filters are also visible by selecting Manage my filters… from the filters menu. Here users can remove or rename existing filters. Each user can save up to 10 filters on each record list. If saving filters on a grid that pulls in the record data, users can also save 10 additional filters each time a different combination of filters is used.
Users can save values for any filters visible on the record list. However, some changes to the record type may affect user-saved selections. If you deploy any of the following changes to the record type, the corresponding saved filter is affected:
In all of these cases, users may need to update the saved values. A warning message also displays that describes what has happened.
For record types that use an entity or process as the data source, you can construct a user filter with an expression. Simply use the a!recordFilterList() or a!recordFilterDateRange() function.
For configuration information and examples, see Expression-Based User Filters.
For a record type that uses a web service, click New User Filter in the User Filters section. This displays the Configure User Filter form.
By default, user filters are visible to all users who can see the record type. If you want to restrict the filter visibility, click Only show when… from the Visibility section and enter an expression that displays the filter when the expression evaluates to true.
Now it's time to create the filter choices. These choices will be displayed under the filter dropdown at the top of the record list. When the user selects one or more choices, the selected value will be applied to the Record List Source and the records will be filtered to all that match that condition.
By default, users can select multiple choices for a single user filter at a time. You must set the selected rule input to be an array to allow selection of multiple choices for a user filter. To change the filter to only allow a single selection, disable the "Users can select multiple choices" field.
Use the a!recordFilterChoices function to create user filter choices for record types that use a web service.
You can set one of the choices as the Default Filter Choice, which means that when a user loads the record list, this choice will already be selected. The user can update the filter value, including removing the default filter choice.
To choose a default choice, enter in an expression in the Default Choice expression box that evaluates to one of the choice labels defined in the user filter.
For record types that use a web service, you can also preview the user filter to verify how it will be displayed above the record list. In the Filter Preview, you can select the choice(s) from the filter dropdown and the value(s) associated with the choice(s) will be displayed besides the dropdown. You can also update the preview using the Update Filter Preview button to preview any recent changes to the user filter configuration.
For record types with sync enabled, you have the option to create a schedule so that your data outside of Appian will automatically sync with your record type once a day.
To schedule a sync:
You can edit your sync schedule here or on the Data Model page by opening the page's properties menu and selecting Change Sync Schedule.
For more information on when to schedule your sync, see Sync Schedule.
Manual Sync
If you don't want to set up an everyday sync, you can manually sync your external data with your record type. To trigger a manual sync:
A record view is an interface that allows you to display record information to users. These are defined on the Views page, where you will find a tabular display of the record type's views.
If you do not have a record view created yet, we recommend creating your record views as separate interface objects. You can define a rule input for your record type in the interface, use rule!
to call your interface in the record view, and then use rv!record
to pass the record information for the rule input into the view. To learn more about this method of creating a record view and passing the record data, see Create a Record View.
At a minimum, all records must have the Summary view, which is the default view for a record.
The summary view is the first view a user sees when they click on a record from a feed-style record list. To define a summary view,
In the views grid, click Summary.
This will open the Edit View dialog.
Enter an expression that calls your record view in the Interface field.
You can add additional views to a record (up to a maximum of 20 additional record views).
To add another view to a record:
Open the record type and click New View, under Record View Details. This will open the Create New View form.
When related actions have been selected as shortcuts, you have the ability to set the launch type for these actions. By default, Dialog Box
is selected for new views but you can also choose Same Tab
or New Tab
as launch options.
You can customize the header style in a record from the Views page.
Record headers can be styled using colors or a billboard image. By default, your record header will have no style.
You can configure the color style using Static
, Variable
, or Expression
options. This style displays an auto-height card of the selected color style with the record title, breadcrumbs, and related action buttons in the card.
To configure the Static option for color:
To configure the Variable option for color:
From the Color dropdown, select the record variable of your color. This picker returns the record variables of type TEXT
.
To configure the Expression option for color, input an expression that evaluates to a valid hex color code.
Another option for configuring your record header style is with a billboard image.
You can configure the image style with Document, URL, Variable, or Expression options. The record header will display the billboard image of your choice, where you can style the overlay, height, and background color. The overlay will contain the record title, breadcrumbs, and related action buttons:
Style | Options |
---|---|
Image Height | Short , Medium , Tall , and Auto . |
Overlay Type | Bar and Full . |
Overlay Position | Top , Middle , and Bottom . |
Overlay Style | Dark , Semi-Dark , None , Semi-Light , and Light . |
Background Color | Any valid hex code. |
To configure the Document option for an image:
To configure the URL option for an image:
To configure the Variable option for an image:
From the Color dropdown, select the record variable of your image. This picker returns record variables of type TEXT
, INTEGER
, and DOCUMENT
.
To configure the Expression option for an image:
If you use variable or expression, the live preview will not display the selected image.
Related actions are links to process models the user can start directly from the record view with information about that record. We call that information the context for the related action. We recommend limiting related actions to processes relevant to the specific record from which they are started. To learn more about how related actions work from records, see Related Actions and Starting Processes From an Interface.
Related action process models are the same as any other process model, except for a start-form restriction: if the process model has a start form, that form must be a SAIL form. This restriction doesn't apply to Quick Tasks.
Before you can add a related action to a record view, you must first add it to the record type.
Go to Related Actions and click New Related Action.
Note: When you select a process model for a new related action, Appian pre-populates this field with all process parameters found in the selected process model, sets their values to null
, and adds a comment with the data type for reference. As shown in the example below, simply replace the null
with the value you want to pass to the process parameter. You do not need to include all parameters from the process model; only include the parameters you need for the related action, and remove the rest. If you make changes to the process parameters later, you'll need to manually update this field.
Now that you've added you related action to the record type, it'll be visible from the Related Actions view of your records.
If you want the related action to show up as a button in the upper-right-hand corner of a record view, you'll need to go back to the Views page and open the desired view.
From there, you should see your available related actions on the right under Related Action Shortcuts.
Simply check a box next to the ones you want to display on this view.
Related actions from Quick Tasks won't show up in this list.
Users will see selected related actions as buttons when they are on that particular record view. Different views can display different related actions.
You can also specify how related action shortcuts should open per record view. Dialog Box is the default.
In the example shown, you can see our record type has two related actions available to add to the Summary view: Update Order Status and New Request.
Record types are displayed as a list of cards on the Records tab in Tempo.
By default, new record types do not display on the Records tab in Tempo. You can change this selecting the Show this record type on the records tab in Tempo checkbox from the Tempo page.
To help differentiate records, you can select an icon and color for each record type. Multiple colors can be overwhelming, so avoid using different colors for each record type.
To set up a icon and color for your record type:
Note that it is best practice to hide a record type which defines reference or supplemental data that is only created and managed in the context of another record. Hiding a record type does not prevent users from viewing a record's list or views in Tempo.
Security should be set on each record type individually.
See Editing Object Security to learn more about how to set and update a record type's security. See Record Type Security to learn more about the security permission levels available for record types.