Reference Record Types in your Applications

You can directly reference the record type object in your expression or interface using the recordType! domain. This domain prefix is a direct object reference that removes the need to create a constant to reference your record type.

Using a record type reference allows you to use elements of your record type throughout your applications.

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

This page describes how to reference a record type and its related elements throughout your applications.

Reference a record type

You can use the recordType! domain to reference a record type in functions, like a!queryRecordType() and a!queryRecordByIdentifier(), and components, like the Record Link component or the Record Picker component.

For example, recordType! is used to reference the CSA Case record type in the a!queryRecordType() function to return data from select record fields and related record fields.

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

It's easy to construct your record type references since the recordType! leverages typeahead to suggest a selection of existing record types. If you already know the name of your record type, you can even skip entering the domain and simply type the name of the record type for the domain and record type object reference to appear.

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

The record type object reference combined with . dot notation allows you to directly access different elements of the record type, such as:

• Fields (and their related field properties and interfaces).
• Record type relationships.
• User filters.
• Record actions.
• Record type properties.
• Smart search results.

Reference record fields

The fields property allows you to reference any record field or custom record field configured in the record type.

You can use record field references in a query to return specific field values, or in an interface component to display record field values in a report.

To reference a record field:

1. Enter the recordType! domain and select your record type.
2. Enter . after recordType!<Record Type Name> to autosuggest the record type properties.
3. Select fields to access the hierarchical menu of record fields configured in the record type.

4. Select a record field from the dropdown to append to the fields property. For example, the reference below refers to the closedon field on the Case record type.

   When you highlight a record field from the dropdown, Appian automatically provides additional information about the record field key, including:

   • Full record type field reference.
   • Field name.
   • Field data type.
   

   Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

When using a record type field reference, Appian will automatically shorten the reference to improve the readability of your expressions. To display the full reference, simply hover over it.

Reference record fields in variables

When referencing a record field in a process variable, activity class parameter, rule input, or record variable, you can use dot notation to index into your selected field. Appian will then automatically format the field reference as needed.

For example, if you have a rule input of type record data type, you can reference individual record fields by using dot notation (.) to index into the rule input and select a record field or related record field. The field reference will be automatically wrapped in brackets.

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

Reference record field properties

Through the fields property, you can also reference the following record fields properties:

To reference these record field properties:

1. Enter the recordType! domain and select your record type.
2. Enter . after recordType!<Record Type Name> to autosuggest the record type options.
3. Select fields to access the hierarchical menu of record fields configured in the record type.
4. Select a record field from the dropdown to append to fields.
5. Enter . after you've selected a field to autosuggest the record field metadata.
6. Select properties to reference either the record field display name or description.
   • Select description to display the record field's description.
   • Select displayName to display the record field's display name.

Reference record field interfaces

Through the fields property, you can also reference the following reusable user interfaces associated with the record field:

The references for reusable record field UIs require a rule input of the record type you are referencing. The rule input should directly follow the record type field reference. For example: recordType!Case.field.description.ui.readOnly(ri!case).

To reference reusable record field UIs:

1. Add the record type you want to reference as a rule input to the interface.
2. Enter the recordType! domain and select your record type.
3. Enter . after recordType!<Record Type Name> to autosuggest the record type options.
4. Select fields to access the hierarchical menu of record fields configured in the record type.
5. Select a record field from the dropdown to append to fields.
6. Enter . after you've selected a field to autosuggest the record field metadata.
7. Select ui to reference either the record field user interface for read-only interfaces or for input interfaces.
   • Select input to call the input user interface for the record field.
   • Select readOnly to call the read-only user interface for the record field.
8. Call the record type rule input in parentheses directly after the UI reference.
   • For example: recordType!Employee.fields.email.ui.input(ri!employee).

Here's an example of what a form calling the reusable interfaces for multiple record fields might look like:

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

To learn more about best practices for configuring reusable interfaces for your record fields, see Build Your Best Data Fabric.

Reference a relationship

The relationships property allows you to reference related record fields from any relationships defined on your record type. You can also use this property to index into relationships defined on your related record types so you can select fields from record types that are not directly related to the base record type.

You may reference a record type relationship in a query to return related record data, or in an interface component to display related record data among your record fields (like in a grid or chart).

To reference related record fields from a record type relationship:

1. Enter the recordType! domain and select your record type.
2. Enter . after recordType!<Record Type Name> to autosuggest the record type properties.
3. Select relationships to access the hierarchical menu of record type relationships configured in the record type.

4. Select a relationship from the dropdown to append to the relationships property.

   

   Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

5. Enter . after the recordType!<Record Type Name>.relationships.<Relationship Name> to autosuggest the fields and relationships property on the related record type:
   • Select fields to select a related record field.

   • Select relationships to index into the relationships available on the related record type.

     For example, the reference below refers to the accountmanager field on the related record type Customer.

     

     Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

When you highlight a relationship from the dropdown, the following information is presented:

• Shortened record type relationship reference.
• Relationship name.
• Related record type name.
• Relationship type.
• Relationship path, which is the full record type relationship reference.
• Properties on the related record type that can be indexed into.

When you highlight a related record field from the dropdown, the following information is presented:

• Shortened related record field reference.
• Related record field name.
• Related record field data type.
• Relationship path, which is the full record type relationship reference.

Reference a record action

The actions property allows you to reference any record list actions or related actions defined on your record type. You may use this property to configure a Record Action component.

To reference a record action:

1. Enter the recordType! domain and select your record type.
2. Enter . after recordType!<Record Type Name> to autosuggest the record type properties.
3. Select actions to access the hierarchical menu of actions configured in the record type.

4. Select a record action from the dropdown to append to the actions property.

   For example, the reference below refers to the Update Case related record action on the Case record type.

   

   Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

When you highlight a record action from the dropdown, Appian automatically provides additional information about it, including:

• Full record type action reference.
• Action description.
• Record type name.
• Action name.
• Process model that supports the record action.
• Action context.
• Visibility setting.

When using a record type action reference, Appian will automatically shorten the reference to improve the readability of your expressions. To display the full reference, simply hover over it.

Reference a user filter

The filters property allows you to reference any user filters configured in the record type. You may use this property when adding a user filter on a read-only grid.

To reference a user filter:

1. Enter the recordType! domain and select your record type.
2. Enter . after recordType!<Record Type Name> to autosuggest the record type properties.
3. Select filters to access the hierarchical menu of user filters configured in the record type.

4. Select a user filter from the dropdown to append to the filters property.

   For example, the reference below refers to the Status user filter configured on the Case record type.

   

   Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

When you highlight a user filter from the dropdown, Appian automatically provides additional information about it, including:

• Full user filter reference.
• User filter name. This name is only visible in the record type and is not shown to application users.
• User filter label. This label appears to application users.
• The unique definition of the user filter.
• Visibility setting.

When using a record type user filter reference, Appian will automatically shorten the reference to improve the readability of your expressions. To display the full reference, simply hover over it.

Reference record type properties

The properties property allows to you to reference the record title configured for every record in the record type. You can use this property to show the record title in a field label or just generally in an interface.

To reference the record title for a record type:

1. Enter the recordType! domain and select your record type.
2. Enter . after recordType!<Record Type Name> to autosuggest the record type properties.
3. Select properties.

4. Select recordTitle to access the record title.

   

   Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

5. Pass in the context to use for the record title:

   • If you are using the reference in a function or interface component that uses fv!data, after the record type reference, enter (fv!data).

     For example:

     1
     2
     3
     4
     5
     6
     7
     8
     9
     10
     11
     12
     13
     14
     15
     {
      a!dropdownField(
        data: recordType!RE Customer,
        /* Displays the record title for each customer as a choice label */
        choiceLabels: recordType!RE Customer.properties.recordTitle(fv!data),
        choiceValues: recordType!RE Customer.fields.id,
        label: "Customer",
        labelPosition: "ABOVE",
        placeholder: "Select a customer",
        saveInto: ri!customer[recordType!RE Customer.fields.id],
        value: ri!customer[recordType!RE Customer.fields.id],
        searchDisplay: "AUTO",
        validations: {}
       )
     }
     

   • If you are using the reference with a rule input, call the record type rule input in parentheses directly after the record title reference.

     For example:

     1
     2
     3
     4
     5
     6
     a!headingField(
       text: recordType!AKG Project.properties.recordTitle(ri!project),
       size: "LARGE",
       fontWeight: "SEMI_BOLD",
       headingTag: "H1"
     )
     

Reference smart search results

The searchResults property allows you to reference the search results from queries that filter data using smart search. You can use these smart search results to filter and sort the returned results in a query, or to send the results to an AI skill so it can guide future decision making.

You can use the searchResults property to reference the results for:

• Fields with the primary similarity score.
• A specific field.

Return results for fields with the primary similarity score

When you search across multiple fields, a single row of data may have multiple search matches. You can reference the search results for the field with the highest similarity score (also known as the primary similarity score) using the following reference:

a!recordType.<Record Type Name>.searchResults.allSearchFields

For example, let's say you have smart search enabled on the title and description fields in the Case record type, and you search across these fields in a read-only grid. After a search occurs, you can use a!recordType.Case.searchResults.allSearchFields to see which field had the primary similarity score in each row and why. In one row, title may have the primary similarity score, while in another row, description may have the primary similarity score.

From the a!recordType.<Record Type Name>.searchResults.allSearchFields reference, you can index into the following information:

• sourceField: The field where the search term with the highest similarity score was found.
• similarityScore: A number between 0 and 1 that shows how closely the content matches the search query. This is the primary similarity score.
• sourceContent: The piece of text where the search term was found.
• page: This property is only available for fields of type Document that contain a PDF. It indicate the page number where the match was found.

To reference the smart search results for the field with the primary similarity score:

1. Enter the recordType! domain and select your record type.
2. Enter . after recordType!<Record Type Name> to autosuggest the record type properties.
3. Select searchResults.

4. Select allSearchFields.

   By default, if you only reference the allSearchFields property, it will return all of the available information: page, similarityScore, sourceContent, and sourceField.

   

5. Enter . to index into a specific search result.

   

Return results for a specific field

You can use a!recordType.<Record Type Name>.searchResults.<Field Name> to reference the search results for a specific field.

For example, a!recordType.Case.searchResults.description allows you to reference the search results returned for the description field.

From this reference, you can index into the following information:

• similarityScore: A number between 0 and 1 that shows how closely the content matches the search query.
• sourceContent: The piece of text where the search term was found.

• searchMatches: A list of maps that show where your search matched the field content. This property is only available when you enable smart search on a field of type extra long text or document.

  Each item in the list includes:

  • similarityScore
  • sourceContent
  • page (This property is only available for fields of type Document that contain a PDF. It indicate the page number where the match was found.)

To reference the smart search results for a single field:

1. Enter the recordType! domain and select your record type.
2. Enter . after recordType!<Record Type Name> to autosuggest the record type properties.
3. Select searchResults.

4. Select one of the fields that has smart search enabled.

   By default, if you only reference the smart search field, it will return the similarityScore and sourceContent for the field.

   

5. Enter . to index into a specific search result.

   

Reference record values in the record type

You often need to reference record values within the record type itself, like when configuring a record view or a related action. To do so, use the rv! domain.

The rv! domain allows you to reference record data in two ways:

• rv!identifier: References only the record's primary key.
• rv!record: References the entire record data structure and its relationships.

Use rv!identifier

Use rv!identifier to pass a record's identifier into an interface, expression, or process model.

This is the most performant method for configuring:

• Record views with complex interfaces.
• Related actions with a start form containing a grid or other component that must be filtered to show specific record data.

Configuring record views

When configuring a record view, using rv!identifier is a best practice for performance, especially for interfaces with conditional logic or large data requirements.

You can use rv!identifier to execute a targeted query (such as a!queryRecordByIdentifier()) within the record view configuration, so you only retrieve the data you need.

For example: The summary view interface for the Order record type displays large volumes of data from multiple record types and conditionally shows information depending on whether the customer used a discount code or purchased a certain item.

To efficiently pass record data to this interface, the record view is configured to pass record data using rv!identifier and the a!queryRecordByIdentifier() function.

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

Configuring related actions

You can use rv!identifier to pass a record's ID into a related action's start form. This is common when the start form contains a component (like a grid) that must be filtered to show specific record data.

For example: You have a start form where a manager provides a performance review for each employee within a grid. To filter the grid, you use a rule input like this:

1
2
3
4
5
6
7
8
9
10
11
12
a!gridField(
   data: a!recordData(
      recordType: recordType!AT Employee,
      filters: {
         a!queryFilter(
         field: recordType!AT Employee.fields.id,
         operator: "=",
         value: ri!employee[recordType!AT Employee.fields.id]
         )
      }
   )
)

In the related action configuration, you can pass rv!identifier to the form's rule input. The grid on the form then uses that input to filter and display only that employee's data.

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

Use rv!record

Use rv!record when you need to reference the entire record or specific fields, including those that make up a composite primary key. By default, rv!record returns a record and up to 250 related records for each one-to-many relationship.

You should use rv!record to configure:

• Record titles.
• Simple record views.

Configuring record titles

You can rv!record to to write an expression for your record title.

For example: If the Employee record type has a single primary key field, you could use rv!record to define the Record Title so the appropriate employee name appears on each record header.

1
2
3
4
5
concat(
   rv!record[recordType!Employee.fields.firstName],
   " ",
   rv!record[recordType!Employee.fields.lastName],
)

For example: If the Part Supplier record type has a composite primary key of {partId, supplierId}, you could configure the Record Title to display both values.

1
2
3
4
5
6
concat(
  "Part: ",
  rv!record[recordType!Part Supplier.fields.partId],
  " Supplier: ",
  rv!record[recordType!Part Supplier.fields.suppKey]
)

Reference record data in an interface

All record type objects have their own unique data type, which is specific to each record type and automatically generated when the record type is created. The record data type allows you to easily access the data associated with a specific record type and use field references to call the record data into your expressions and interfaces.

For interfaces connected to a record type, such as record views, you can pull in record data by using the record data type as a rule input in your interface.

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

Once you configure the rule input, you can reference your record fields in the interface by calling the rule input followed by a record field reference wrapped in brackets.

For example, the expression below uses ri!case to call the rule input containing the record data type for the Case record type. Then, the rule input is followed by a record field reference to Case record type to display the case status in a text field.

1
2
3
4
5
6
7
8
9
a!textField(
  label: "Customer",
  labelPosition: "JUSTIFIED",
  value: a!defaultValue(
      ri!case[recordType!Case.fields.status],
      "–"
      ),
   readOnly: true
),

After you configure the interface, you can add it as a record view and seamlessly pull the record data into the rule input using rv!record.

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

For examples of how to use record data types as rule inputs in interfaces and views, see Create a Record View.

Reference record data in a process model

Record types can be used as variables in a process model. This allows you to use record data in your process model as a process variable or an activity class parameter.

You can use record types as process variables to manage the full lifecycle of your business data and power a variety of workflows. For example, record data can be used to:

• Update and sync changes using the Write Records and Delete Records smart services.
• Pass in data from a start form that uses a record type as a rule input.
• Sync external data changes using the Sync Records smart service.
• Examine record data to make decisions in a gateway node.
• Determine who needs to be informed of the process and send them an email or push notification.

See Create a record using a process model for an example.

Use a record type constructor

You can use a record type constructor to create a single record in your expression. The record type constructor allows you to map each value to a particular field reference or relationship reference in the record type.

To create a record type constructor:

1. In an expression rule, enter a record type reference followed by parentheses.

   For example: recordType!Case()

2. In between the parentheses, enter the record field references followed by a : colon and its corresponding data value on the right.

   For example:

   1
   2
   3
   4
   5
   recordType!Case(
      recordType!Case.fields.id: 1,
      recordType!Case.fields.status: "Open",
      recordType!issueType: "Shipping"
   )
   

3. If you have record type relationships, you can create related record data by referencing the record type relationship followed by a : colon and the related record type reference on the right. You'll create a nested constructor to define the related record data.

   For example:

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   recordType!Case(
      recordType!Case.fields.id: 1,
      recordType!Case.fields.status: "Open",
      recordType!Case.fields.issueType: "Shipping",
      recordType!Case.relationships.customer: recordType!Customer(
         recordType!Customer.fields.firstName: "Amy",
         recordType!Customer.fields.lastName: "Smith",
         recordType!Customer.fields.title: "Manager"
      )
   )
   

4. Click TEST RULE to view the data output.

   For example:

   

Feedback