Create a Record Type for a Web Service

If your data lives in an external system, you can create a record type to connect to that system using optimized data access or direct data access. A record type that connects to a web service is known as a service-backed record type.

To create a service-backed record type:

1. Create a record type object.
2. Choose a data access method.
3. Create a connected system and integration to the web service.
4. Create a record data source expression.
5. Connect the record type to the web service using your preferred data access method.

Create a record type object

To create a record type:

1. In your application, go to the Build view.
2. Click NEW > Record Type.

3. In Create Record Type, configure the following properties:

   Property	Description
   Name	The name of the record type that is displayed in the Appian Designer. For example, in the Appian Retail application, you could have AR Order, AR Customer, or AR Support Ticket. Follow the recommended naming standard when creating this name.
   Display Name (Plural)	The name of the record type in plural form. For example, Orders, Customers, or Support Tickets. This is the name that business users see in Process HQ, Tempo, and as the search placeholder text in the record list and any records-powered grids.
   Description	The description of the record type shown in Process HQ, Tempo, and in Appian Designer. Click Generate AI Description to allow Appian AI Copilot to generate a record type description for you.

4. Click Create.
5. In the Review Application Security dialog, review the record type security settings.
6. Click SAVE.

Choose a data access method

After you create the record type object, choose a data access method to connect to your data source. The data access method determines the type of record type you create and the features available to you.

Data access method	Record type created	Data fabric features
Optimized data access	Synced record type	All features
Direct data access	Legacy record type	Basic filtering and security only

Appian recommends using optimized data access whenever possible. If you cannot sync your data, use direct data access instead.

For a detailed comparison of each method, see Data Access for Record Types.

Create an integration for the web service

To connect a record type to a web service, you must configure the following objects:

• A connected system to authenticate with your external system.
• An integration that uses the connected system for authentication and returns the response data that the record type will use.

Create a record data source

After you create your integration, create a record data source to allow the record type to access data from the web service.

The record data source is an expression rule that calls an integration and returns data from the response body. Within the expression, you can add rule inputs and functions to configure additional record type behavior.

To create a record data source, create a new expression rule that meets the following requirements. Some requirements apply only to a specific data access method:

• Integration response requirements:
  • The expression calls the necessary integration. This could be in the form of a local variable, like local!integrationResponse: rule!AR_getIntegrationData.
  • The response body must cast to a List of Map, List of Dictionary, or a List of CDT, and it must have at least one Number (Integer) field that's non-null for every entry to act as the primary key for the record type.
    
    
• Function requirements:
  • The expression does not use plug-ins or any of the following functions: a!query, a!queryEntity, a!queryProcessAnalytics, a!queryRecordType.
    
    
• Batching requirements (optimized data access):
  • A record type syncs 1,000 rows from the web service by default.
  • You can enable batching to sync more than 1,000 rows. Depending on your web service's paging method, you can:
    • Batch by sequential values.
    • Batch by cursors or tokens.
    • Batch by full URLs.
      
      
      
• Rule input requirements (direct data access):
  • The expression has a rule input of type PagingInfo to allow for paging and sorting of records.
  • The expression has a rule input of type Text to allow users to search for records.
  • If you add rule inputs for paging and search to your record data source expression, you must update the underlying integration to reference the rule inputs from the expression.

Batch by sequential values

If your web service uses an integer pagination value, you can batch by sequential values {1,2,3…} to sync more than 1,000 rows from the web service.

The following Appian Community video provides a guided walkthrough on how to batch by sequential values.

To batch data by sequential values:

1. In the record data source expression:

   1. Add exactly one rule input with the following properties:

      Property	Value
      Name	batchNumber
      Type	Number (Integer)

   2. Click SAVE.

2. In the underlying integration:

   1. Add a rule input of the same name and type as the rule input in the record data source expression.

   2. Add a query parameter that uses the rule input as the Value.

      If the underlying API requires a Start Index, you can calculate the index with the following formula: 1 + ((batchNumber - 1) * batchSize) = startIndex.

      For example, the query parameter below uses the formula, where ri!batchNumber passes in each sequential value. If you have a batch size of 1,000, batch 1 would have a start index of 1 + ((1 - 1) * 1000) = 1.

      

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

   3. Click SAVE.

3. In the record data source expression:

   1. Update the local variable that calls the integration so you can pass the rule input to the integration.

      For example:

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      28
      29
      a!localVariables(
              
      /* Calls the integration and stores the response in a local variable */
      /* Uses the batchNumber rule input to pass sequential values to the integration */
      local!integrationResponse: rule!AR_getOrderData(
      +   batchNumber: ri!batchNumber
        ),
              
      if(
      /* This will return true if the integration succeeds */
      local!integrationResponse.success,
              
      /* Returns the list of values from the integration response that will map to your record data */
      local!integrationResponse.result.body,
              
      /* If the integration is unsuccessful, handle accordingly */
              
      if(
        /* Note: handling of out of bounds exceptions varies by web service */
        tointeger(index(local!integrationResponse.result, "statusCode", 0)) = 416,
              
        /* If this is an out of bounds error, return an empty list to finish syncing */
        {},
               
        /* If this is a different error, return the integration error. */
        local!integrationResponse.error
          )
         )
        )
      

   2. Click SAVE.

Batch by cursor or token

If your web service returns a cursor or token in the response header or body that identifies the next page of data, you can batch by that value. The cursor or token is automatically appended to the integration URL, which allows you to sync more than 1,000 rows from the web service.

To batch data by cursor or token:

1. In the record data source expression:

   1. Add exactly one rule input with the following properties:

      Property	Value
      Name	nextPageUri
      Type	Text

   2. Add the a!pageResponse() function to the expression to identify the data in the current integration response, and the path for the next set of data to request. The nextPage parameter value is automatically passed to the rule input.

   3. Click SAVE.

2. In the underlying integration:
   1. Add a rule input of the same name and data type as the rule input in the record data source expression.

   2. Add a query parameter that uses the rule input as the Value.

      

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

   3. Click SAVE.
3. In the record data source expression:

   1. Update the local variable that calls the integration so you can pass the rule input to the integration.

      You must use a!defaultValue() to pass a null value when the next page is empty or null. Passing null ensures the sync ends when there is no more data to sync. For example:

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      28
      29
      30
      31
      32
      33
      34
      35
      36
      37
      38
      a!localVariables(
      
      /* Calls the integration and stores the response in a local variable */
      /* Uses the nextPageUri rule input to pass the URI for the next page */
      /* If the next page is empty, returns null to stop paging */
            local!integrationResponse: rule!AR_getCustomerData(
      +        a!defaultValue(value: ri!nextPageUri, default: fn!null())
        ), 
      
        if(
      
         /* This will return true if the integration succeeds */
         local!integrationResponse.success,
      
         a!pageResponse(
                     
             /* Returns a list of maps, dictionaries, or CDTs that map to your record data */
             data: local!integrationResponse.result.body.results,
      
             /* Identifies the location of the next page of results */
             /* which is automatically used in the nextPageUri rule input */
             nextPage: local!integrationResponse.result.body.next
         ),
      
         /* If the integration is unsuccessful, handle accordingly */
         if(
      
             /* Note: handling of out of bounds exceptions varies by web service */
             tointeger(index(local!integrationResponse.result, "statusCode", 0)) = 416,
      
             /* If this is an out of bounds error, return an empty list to finish syncing */
             {},
      
             /* If this is a different error, return the integration error. */
             local!integrationResponse.error
           )
          )
        )
      

   2. Click SAVE.

Batch by a full URL or URI

If your web service returns a full URL or URI that contains the next page of data, you can batch by that value.

If the full URL or URI is embedded within a response parameter, you can use familiar functions to extract the value in your record data source expression.

To batch data by a full URL or URI:

1. In the record data source expression:

   1. Add exactly one rule input with the following properties:

      Property	Value
      Name	nextPageUri
      Type	Text

   2. Add the a!pageResponse() function to the expression to identify the data in the current integration response, and the path for the next set of data to request. The nextPage parameter value is automatically passed to the rule input.

   If the next page link is embedded in a response parameter, use the appropriate functions to extract it. See an example.

   1. Click SAVE.
2. In the underlying integration:
   1. Add a rule input of the same name and data type as the rule input in the record data source expression.

   2. For URL, select Build URL from Scratch.

      Note:  This option only appears if you use a connected system to configure your integration.

   3. Hover over the URL input and click Edit as Expression.

   4. In the expression, reference the rule input.

      As a best practice, use a!defaultValue() to provide the rule input value until it returns null or empty. When the rule input is null or empty, the function returns a static URL instead.

      

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

   5. Click SAVE.
3. In the record data source expression:

   1. Update the local variable that calls the integration so you can pass the rule input to the integration.

      You must use a!defaultValue() to pass a null value when the next page is empty or null. Passing null ensures the sync ends when there is no more data to sync.

      For example:

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      28
      29
      30
      31
      32
      33
      34
      35
      36
      37
      38
      39
      40
      41
      42
      43
      44
      45
      46
        a!localVariables(
              
        /* Call the integration and store the response in a local variable */
        local!integrationResponse: rule!SXBR_newChicagoInt(
              
        /* The record data source will be executed multiple times, passing the nextPageUri until an empty next page value is returned */
        /* The batch size is limited to 1000 records per batch */
      +    a!defaultValue(value: ri!nextPageUri, default: fn!null())),
      
        if(
        /* This will return true if the integration succeeds */
        local!integrationResponse.success,
      
        /* If needed, modify the expression below to return a list of maps, dictionaries, or CDTs that map to your record data */
        /* Update the nextPage parameter value to the location of the nextPage value */
           
        a!pageResponse(
          data: a!forEach(
             items: local!integrationResponse.result.body.data, 
             expression: 
             a!map(
                  id: fv!item.id,
                  title: fv!item.title,
                  description: fv!item.description,
                  price: fv!item.price_display,
                  max_price: todecimal(fv!item.max_current_price)
             )
          ),
          nextPage: local!integrationResponse.result.body.pagination.next_url
        ),
      
        /* If the integration is unsuccessful, handle accordingly */
      
        if(
             /* Note: handling of out of bounds exceptions varies by web service */
             tointeger(index(local!integrationResponse.result, "statusCode", 0)) = 416,
      
             /* If this is an out of bounds error, return an empty list to finish syncing */
             {},
      
             /* If this is a different error, return the integration error. */
             /* If you need additional logic to determine the error, use a!integrationError() in the integration to format the error displayed in the sync monitor */
             local!integrationResponse.error
           )
          )
        )
      

   2. Click SAVE.

Connect to a web service

After choosing a data access method and creating your record data source, connect the record type to your web service. Follow the steps for your chosen method.

Use optimized data access

Connecting to a web service with optimized data access creates a synced record type. Appian syncs your source data in the record type, which enables faster queries and access to all data fabric features.

To connect a record type to a web service using optimized data access:

1. Create a connected system and integration for your web service.
2. Create a record data source for your web service.
3. In your record type, go to Data Model.
4. Click Tell Us About Your Data.

5. Select Web Service.

   

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

6. Click NEXT.

7. For Choose how to access data, keep the default selection Optimized Data Access.

   

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

8. Click NEXT.

9. For Choose Record Data Source, select the expression rule for your record data source.

   If you do not have an existing expression rule, click Create Record Data Source to create one. As you create the record data source, choose a batching option to allow the record type to sync more than 1,000 rows from the web service.

10. Click NEXT.
11. For Select primary key field and unique fields, configure the following:
    • Primary Key Field: From the dropdown, select a field of any data type to use as the primary key. A primary key field is required.
    • Unique Fields: (Optional) Select any fields that contain all unique values. Unique fields can be used as a common field on the one-side of a record type relationship configuration.

12. In the grid of fields, clear the checkbox next to any source fields you don't want to include in the record type. By default, all source fields are selected.

    Note:  A record type can have up to 100 fields.

13. Configure the following field properties:

    Property	Action
    Record Field Name	Enter the name for the record field. This is the name that will be used to reference the field in Appian Designer.
    Record Field Type	Use the dropdown to select the data types for the record fields. Appian automatically suggest types based on the data type in the source. Appian recommends at least the following changes: For fields containing usernames, change the type from Text to User. For fields containing group identifiers, change the type from Number (Integer) to Group. For fields containing more than 4,000 characters, change the type from Text to Extra Long Text. You can only have a maximum of 3 Extra Long Text fields on a record type for optimal performance.
    Display Name	Enter a user-friendly field name to display to business users in Process HQ. Use title case formatting and spaces in the display name so it's easy for users to read. For example, Year-to-Date. When this field is blank, the Record Field Name is displayed in Process HQ using title case formatting.
    Description	Enter a description of the field to display to business users in Process HQ.

14. Drag and drop the rows to change the order in which the record fields are displayed.
15. Click FINISH.
16. Click SAVE to sync your data.

Use direct data access

Connecting to a web service with direct data access creates a legacy record type. Appian queries the source data directly, but relationships and related features are not available.

Legacy service-backed record types require a custom data type (CDT) to define the integration response structure, and you must manually configure paging, search, and user filters.

To connect a record type to a web service using direct data access:

1. Create a connected system and integration for your web service.
2. Create a record data source for your web service.
3. Create a custom data type (CDT) that defines the output of the integration's expected response. Each response property must have a field in the CDT.
4. In your record type, go to Data Model.
5. Click Tell Us About Your Data.

6. Select Web Service.

   

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

7. Click NEXT.

8. For Choose how to access data, select Direct Data Access.

   Relationships and all related features are disabled by default.

   

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

9. Click NEXT.

10. For Choose Record Data Source, select the expression rule for your record data source.

    If you do not have an existing expression rule, click Create Record Data Source to create one.

11. Click NEXT.
12. For Data Type, select the CDT that matches the output of the integration's expected response.
13. Click FINISH.
14. Enable paging.
15. Enable search.
16. Enable user filters.
17. Configure a single record source.
18. Test your configurations:
    1. In the Test Record Source section of the record type, select one of the expressions to test: Record Data Source or Single Record Source.
    2. Click TEST. The first 100 records of the DataSubset are returned.

Feedback