Choose a Record Type Data Source

This page provides guidance on which data source option to select based on where your source data lives and how to configure the data source when you first create a record type.

Overview

Using data modeling concepts and a guided experience, the record type object makes it easy for you to bring in the data you need to create an application that simplifies and streamlines your business processes.

Create a Record Data Model

The Configure Data Source dialog displays four card options that allow you to select the right data source for your record type based on where your source data lives. You can choose one of the following source types:

When you select a database, Salesforce, or a web service as the source your record type, you have the option to enable data sync.

When you enable data sync, a copy of your source is cached in Appian. Keeping this data in sync, and close by in Appian, means Appian can execute queries against your data much faster. As a result, Appian can leverage this increased performance to not only give you more responsive queries and reports, but also enable a host of powerful features, like relationships and custom record fields.

There are some data structures that are better fit for data sync than others. Before enabling sync, review when to use data sync to ensure your data structure is a good fit.

Database

A record type that uses a database as the source is the easiest and the most common record to configure.

If your data lives in a relational database or a database table, the record type can access your source data through a data store entity (DSE) or from a cached copy of your database table if you sync your data in Appian. Learn more about data sync and when to use it.

Use a data store entity

To use a data store entity as the source of your record type, you'll need the following:

Field Description
Data Type The source of the record data.
Data Store The name of the data store selected as the source for the record type.
Entity The name of the entity that maps to the data store selected for the record type. Note that the CDT that connects to the DSE must have a primary key, and that each row in the data store entity is a record.

See the Records Tutorial for detailed guidance on configuring a record type that uses a data store entity as the data source.

To configure a record type to use a data store entity as its source:

  1. In your application, create a new record type object.
  2. On the Data Model page, click TELL US ABOUT YOUR DATA. The Configure Data Source dialog opens.
  3. For CHOOSE SOURCE TYPE, select Database.

    /Create Record Type/create a record data source module

  4. Click NEXT.
  5. For CHOOSE DATA STORE AND SOURCE, select a data store for your record type.
  6. For Entity, select an entity from the selected data store.
  7. Click FINISH.

Use a database table with sync enabled

To use a database table with sync enabled as the source of your record type, you'll need the following:

Field Description
Type The source of the record data.
Table The name of the database table selected as the source of the record type. Note that the table must have a defined primary key column.
Sync Schedule The setting toggle for Sync Schedule. Valid values: on or off. This setting is only shown if Sync in Appian is selected for the record type.

To configure a record type to use a database table with sync enabled as the source, you'll use the Configure Data Source guided experience. Here you can:

Choose a source type

The first step of the Configure Data Source guided experience is to select a source type.

  1. In your application, create a new record type object.
  2. On the Data Model page, click TELL US ABOUT YOUR DATA. The Configure Data Source dialog opens.
  3. For CHOOSE SOURCE TYPE, select Database.

    /Create Record Type/create a record data source module

  4. Select the Sync in Appian checkbox.
  5. Click NEXT.
  6. For CHOOSE DATABASE TABLE, select a database table for your record type.
  7. Click NEXT.

Define source filters

After you select the source type, you will be prompted to configure source filters.

Source filters allow you to determine which rows from your data source are synced in Appian based on the conditions you specify. By applying source filters, you can sync data from large sources that exceed the 500,000 row limit on synced data, and focus your data so your record type only has data relevant to your business process.

If you expect the source to meet or exceed the row limit, consider applying one or more source filters to avoid reaching the 500,000 row limit or disable data sync.

You do not have to add source filters during configuration. You can add source filters anytime after configuration by clicking ADD FILTERS on the Data Model page of the record type. For more information, see Filter the Record Type Source Data.

To define source filters:

  1. Click Add Filter.
  2. From the Source Field picker, select the source field you want to filter the data. Only source types that can be converted to Appian types appear in the dropdown.
  3. From the Condition list, select the operator to apply to the filter.
  4. Use the context menu next to the Value field to select how you want to pass the value into the filter. The options in this menu change based on the data type of the field selected. You can enter a value directly or using an expression.
  5. Click Test Filter to validate your filter conditions.
  6. If you have more than one filter, use the up and down arrows to change the order in which the filters are applied. You can also delete a filter by clicking X.
  7. Click NEXT.

If you need more advanced filters or wish to use OR logic instead of AND when applying the filters, select Expression to create your filters manually. For additional information on specifying filters as an expression, see a!queryFilter() or a!queryLogicalExpression(). For example of a source filter created in expression mode, see Filter the Record Type Source Data

Select and configure record fields

Once you’ve selected the source type and set your source filters, the last step is to select and configure the record fields in your record type.

When you configure your record fields, the record type schema must match the source schema. The source schema includes the names, types, and uniqueness constraints of all the fields in your source. By default, Appian creates a mapping between the source schema and the record type schema. As a result, the names of your record fields will match the source field names, and the types of your record fields will be the Appian data types that correspond with the source field types.

To select and configure the record fields:

  1. In SELECT AND CONFIGURE FIELDS TO INCLUDE, use the checkbox next to a Source Field to add or remove a field from your record type. You can have up to 100 fields.
  2. In Record Field Name, enter the name for the record field. This is the name that will be used to reference the field in Appian.
  3. In Record Field Type, use the dropdown to select the record field type. You can change text and integer record field types to type User or Group.
  4. Use the up and down arrows to change the order in which the record fields are displayed.
  5. Click FINISH.
  6. Click SAVE CHANGES to sync your data.

If a change is made to the source schema, you will need to update the record type with the corresponding change, otherwise the record type will fail to sync. To update or modify the record fields mapped to source fields, click CONFIGURE FIELDS on the Data Model page of the record type.

Process model

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 use a process model as the source of your record type, you'll need the following:

Field Description
Source The source of the record data.
Process Model The source process model. For process-backed record types only. Each active (unarchived) process instance is a record.

To create a record type from a process model:

  1. In your application, create a new record type object.
  2. On the Data Model page, click TELL US ABOUT YOUR DATA. The Configure Data Source dialog opens.
  3. For CHOOSE SOURCE TYPE, select Process.

    /Create Record Type/processmodel entity

  4. Click NEXT.
  5. For CHOOSE PROCESS MODEL, select a process model.
  6. Click FINISH.

Salesforce object

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 data source of your record type.

You can either select an existing Salesforce connected system or configure a new one, if none exist. When configuring a record type to use a Salesforce object, you have the option to enable data sync. By syncing your Salesforce data in Appian, you'll experience faster queries and better performance. Learn more about data sync and when to use it.

Use a Salesforce object

To create a record type that uses a Salesforce object:

  1. In your application, create a new record type object.
  2. On the Data Model page, click TELL US ABOUT YOUR DATA. The Configure Data Source dialog opens.
  3. For CHOOSE SOURCE TYPE, select Salesforce.

    /Create Record Type/salesforce data model select

  4. Click NEXT.
  5. For CHOOSE SALESFORCE OBJECT, select a Salesforce connected system for your record type.
  6. For DATA TYPE, select a custom data type. This custom data type must match the output of the integration's expected response.
  7. Click FINISH.

Use a Salesforce object with sync enabled

To configure a record type to use a Salesforce object with sync enabled as the source, you'll use the Configure Data Source guided experience. Here you can:

Syncing 1,000 rows of data requires a single API call, so ensure the API limit on your Salesforce instance is large enough to support all Salesforce-backed record types with data sync enabled. Learn more about the row limit for record types with sync enabled.

Choose a source type

The first step of the Configure Data Source guided experience is to select a source type.

  1. In your application, create a new record type object.
  2. On the Data Model page, click TELL US ABOUT YOUR DATA. The Configure Data Source dialog opens.
  3. For CHOOSE SOURCE TYPE, select Salesforce.

    /Create Record Type/salesforce data model select

  4. Select the Sync in Appian checkbox.
  5. Click NEXT.
  6. For CHOOSE SALESFORCE OBJECT, select a Salesforce connected system for your record type.
  7. Click NEXT.

Define source filters

After you select the source type, you will be prompted to configure source filters.

Source filters allow you to determine which rows from your data source are synced in Appian based on the conditions you specify. By applying source filters, you can sync data from large sources that exceed the 500,000 row limit on synced data, and focus your data so your record type only has data relevant to your business process.

If you expect the source to meet or exceed the row limit, consider applying one or more source filters to avoid reaching the 500,000 row limit or disable data sync.

You do not have to add source filters during configuration. You can add source filters anytime after configuration by clicking ADD FILTERS on the Data Model page of the record type. For more information, see Filter the Record Type Source Data.

To define source filters:

  1. Click Add Filter.
  2. From the Source Field picker, select the source field you want to filter the data. Only source types that can be converted to Appian types appear in the dropdown.
  3. From the Condition list, select the operator to apply to the filter.
  4. Use the context menu next to the Value field to select how you want to pass the value into the filter. The options in this menu change based on the data type of the field selected. You can enter a value directly or using an expression.
  5. Click Test Filter to validate your filter conditions.
  6. If you have more than one filter, use the up and down arrows to change the order in which the filters are applied. You can also delete a filter by clicking X.
  7. Click NEXT.

If you need more advanced filters or wish to use OR logic instead of AND when applying the filters, select Expression to create your filters manually. For additional information on specifying filters as an expression, see a!queryFilter() or a!queryLogicalExpression(). For example of a source filter created in expression mode, see Filter the Record Type Source Data

Select and configure record fields

Once you’ve selected the source type and set your source filters, the last step is to select and configure the record fields in your record type.

When you configure your record fields, the record type schema must match the source schema. The source schema includes the names, types, and uniqueness constraints of all the fields in your source. By default, Appian creates a mapping between the source schema and the record type schema. As a result, the names of your record fields will match the source field names, and the types of your record fields will be the Appian data types that correspond with the source field types.

To select and configure the record fields:

  1. In SELECT AND CONFIGURE FIELDS TO INCLUDE, use the checkbox next to a Source Field to add or remove a field from your record type. You can have up to 100 fields.
  2. In Record Field Name, enter the name for the record field. This is the name that will be used to reference the field in Appian.
  3. In Record Field Type, use the dropdown to select the record field type. You can change text and integer record field types to type User or Group.
  4. Use the up and down arrows to change the order in which the record fields are displayed.
  5. Click FINISH.
  6. Click SAVE CHANGES to sync your data.

If a change is made to the source schema, you will need to update the record type with the corresponding change, otherwise the record type will fail to sync. To update or modify the record fields mapped to source fields, click CONFIGURE FIELDS on the Data Model page of the record type.

Other web service

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.

When configuring a record type to use a web service, you have the option to enable data sync. By syncing your external data in Appian, you'll experience faster queries and better performance. Learn more about data sync and when to use it.

Use a web service

To use a web service without sync enabled as the source of your record type, you'll need the following:

Field Description
Type The source type of the record data.
Data Type The custom data type (CDT) that corresponds to the record type.
Record Data Source The Record Data Source expression that calls the integration for your record and returns a DataSubset for the record list view. The data parameter of this DataSubset should contain an array of dictionaries that map to the selected data type. Note that this is not the record data that is used to fetch the data for a single record, for which you must configure the Data (Dictionary) field for the Single Record Source.
Paging Info The rule input of the Record Data Source expression that passes the paging and sorting configuration of the record list. The selected rule input must be of type PagingInfo.
Search Text The rule input of the Record Data Source expression that passes the search query string that runs against the record list. The selected rule input must be of type Text.
Data (Dictionary) The Single Record Source expression that calls an integration and returns a dictionary that maps to the selected Data Type. This integration will be used to fetch the data for a record when rendering a record view, launching a related action, or using a!recordLink() to define a record link.
Record Identifier The rule input that corresponds to the record identifier (ID) for the Single Record Source expression. The value of this unique identifier is used to return the data for a single record.

To create a record type that uses a web service:

  1. In your application, create a new record type object.
  2. On the Data Model page, click TELL US ABOUT YOUR DATA. The Configure Data Source dialog opens.
  3. For CHOOSE SOURCE TYPE, select Other Web Service.

/Create Record Type/expression backed record with pickers

  1. Click NEXT.
  2. For CHOOSE RECORD DATA SOURCE, select an expression that returns a list of records.
  3. Click NEXT.
  4. For DATA TYPE, select a custom data type. This custom data type must match the output of the integration's expected response.
  5. Click FINISH.

Record data source (sync not enabled)

For a full walkthrough, see the Service-Backed Record Tutorial.

The RECORD DATA SOURCE configuration section is where you'll configure the data for your record type. This section allows you to configure the integration that pulls in your external data source, the expression rule that calls your integration, and the rule inputs that define your paging, searching, and filtering parameters. Learn how to create user filters for a web service.

wizard rds connected system create

Single record source

The SINGLE RECORD SOURCE configuration section is where you'll configure the data for a single record view. This section allows you to configure an integration that pulls in the data for a single record, the expression rule that calls in the integration, and the rule input that defines the record identifier for the record view that returns when the integration is called.

wizard srs integration create

Enable paging, search, and filtering

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.

/Create Record Type/Paging and Search Dropdowns

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.

Test the record type

After configuring the expression rules that call the integrations for your record type, you can use the Test Record Source box to verify that the data results returned for your Record Data Source expression and Single Record Data expression are correct.

Simply select the view for the source expression you want to verify and click the TEST button.

record type test pane

The results of your record data source expression will be cast to the data type you selected for your record type, and displayed in a grid.

record type test pane source view

Although this view may look similar to the record list view you configured, it is not the same. Rather than showing your configured columns, the Test Record Source view will show you all of the fields on the data type that correspond to the record type. These record type fields can be used as inputs when configuring your record list. Note that in the record list you must use fv!row to reference the record fields values, not rv!.

You can also use this view to evaluate your rule inputs for paging, searching, and filtering. The rule inputs for these parameters apply to your record list view so you'll want to ensure they're working as expected.

When you select Single Record Source view, you will see the expression output cast to your selected data type. This displays all of the fields and values available for a single record. You can also choose how you want these record fields and values displayed in the view.

record type test pane single record

The Test Record Source pane displays the first 100 records of the DataSubset only.

See the Service-Backed Record Tutorial for detailed guidance on configuring the record data source and single record source. This tutorial also demonstrates how to use the Test Record Source pane to verify your record type views.

See the Appian 20.1 documentation for more information about service-backed record types, formerly called expression-backed record types, created with Appian 20.1 or earlier.

Use a web service with sync enabled

To use a web service with sync enabled as the source of your record type, you'll need the following:

Field Description
Record Data Source The Record Data Source expression that calls the integration for your record and returns record data from the response body in a format that casts to a List of Maps (e.g. a List of Dictionary).

To create a record type that uses a web service with sync enabled:

  1. In your application, create a new record type object.
  2. On the Data Model page, click TELL US ABOUT YOUR DATA. The Configure Data Source dialog opens.
  3. For CHOOSE SOURCE TYPE, select Other Web Service.

/Create Record Type/expression backed record with pickers

  1. Select the Sync in Appian checkbox.
  2. Click NEXT.

Record data source (sync enabled)

After selecting a web service as your source type, the next part of the configuration is to use the rule picker for Record Data Source.

/record_type_object_sxbr_1__configure_data_source

You can either select an existing expression rule, or create a new one by clicking the Create Record Data Source link to launch a guided experience that helps you easily create and configure the objects you'll need.

The Record Data Source is an expression rule that calls an integration and returns record data from the response body. This data needs to cast to a List of Map. This means you can return a List of Dictionary or a List of CDT as well. This will need to have at least one field that's non-null for every entry, to act as the primary key for the record.

If you've chosen to allow more than 1,000 records by enabling syncing in batches, then you will need to apply the rule input to the underlying integration.

/record type object sxbr 3 test record data source

Once you've selected or created your Record Data Source, if the expression rule returns something that casts to a List of Map (such as a List of Dictionary), then you will see the first three rows of data in the Preview grid.

When you choose Other Web Service as the source type with sync enabled, the data is intended to come from a web service. For this reason, the Record Data Source cannot use plugins, query rules, or any of the following functions: query, queryEntity, queryProcessAnalytics, queryRecordType.

Syncing in batches

When the Record Data Source has no rule input, syncing in batches is not enabled. This means that your record type will be limited to 1,000 records.

If the Record Data Source has more than one rule input or the rule input is any type other than Number (Integer), then it is invalid. You will need to update the expression rule to proceed.

When the Record Data Source has exactly one rule input of type Number (Integer), syncing in batches is enabled. Although your record type is still limited to 1,000 records per batch, the expression rule will be executed multiple times to pull back multiple batches, allowing you to sync more than 1,000 records. With syncing in batches enabled, you can sync just as many records from a web service as you can from a Database Table or Salesforce.

It's important that you modify the underlying integration to apply this rule input in order to implement syncing in batches. Otherwise, sequential calls will just pull back the same data and the sync will fail. The expression rule will be executed multiple times, with sequential values {1,2,3…} being passed to the rule input. The expression will continue to execute until an empty set or null is returned.

If the underlying API requires a Start Index, you can calculate it with the formula 1 + ((batchNumber - 1) * batchSize) = startIndex. For an example of how this works with a batch size of 1000, see the table below:

Batch Number Start Index
1 1 + ((1 - 1) * 1000) = 1
2 1 + ((2 - 1) * 1000) = 1001
3 1 + ((3 - 1) * 1000) = 2001
4 1 + ((4 - 1) * 1000) = 3001

An error will appear if the Record Data Source returns anything other than an empty set, a null, or something that casts to a List of Map (e.g. a List of Dictionary). An error will also appear if the same primary key shows up in a single batch more than once.

Note that, while the example above uses a batch size of 1,000, Appian also supports fewer records per batch. For example, you could use a batch size of 100 if that's the largest number the web service can return in a single response.

Open in Github Built: Tue, May 23, 2023 (06:12:33 PM)

On This Page

FEEDBACK