Free cookie consent management tool by TermsFeed

Record Type Tutorial (Web Service)

On This Page

Your enterprise data may be spread across a number of different systems. If your data sources provide access with a REST API, you can easily bring that data together in Appian by creating a record type that connects to a web service, otherwise known as a service-backed record type.

This tutorial guides you through the steps for creating a record type that uses the Art Institute of Chicago API as the data source.

Most APIs require applications to send authentication credentials with each request. The Art Institute of Chicago's API is a free, public, open-source API that doesn't require authentication. This makes it ideal for this tutorial because we don't need credentials in order to connect to it.

Note:  Appian is not a maintainer of this API, and the API is used in this tutorial for example purposes only. In the event the API changes, is deprecated, or is made unavailable, this tutorial will continue to be available as a reference, but there is no guarantee that the tutorial can be used to create working application code.

Tutorial objectives

You'll learn how to create a record type that connects to an external data source using the following design objects:

  • Connected system: Stores the connection information to the external system.
  • Integration: Uses the connected system to access and call the external system.
  • Expression rule: Calls the integration and formats the returned data so it can be used in the record type. This expression is used as the source of the record type.

You'll also learn how to configure a record list, a Summary view, and how to manage external documents using a record type.

After you complete this tutorial, you will understand how to use your own API to create a service-backed record type.

Tutorial requirements

To follow along with this tutorial, you'll need an environment. If you don't have one available, you can use an environment from Appian Community Edition.

Ensure you are familiar with REST APIs and how to use them.

Create the Appian Tutorial application

Tip:  The Appian Tutorial application is used throughout Appian tutorials. Skip the steps in this section if you've already created this application in another tutorial.

To begin, we need to create an application to contain our design objects.

We will be creating the Appian Tutorial application for this tutorial. All of Appian's tutorials use the Appian Tutorial application as the reference application. After completing this tutorial, you can reuse this application as you work through other Appian tutorials.

To create the Appian Tutorial application:

  1. Log in to Appian Designer.
  2. In the Applications view, click + New Application.

  3. In the Create New Application dialog, configure the following properties:

    Property Description
    Name Enter Appian Tutorial.
    Prefix Keep the default prefix, AT, which Appian constructs using the initial characters of each word you entered in the Name parameter. We'll be following the recommended naming standard, and using this short, unique prefix whenever we name an object in this application.
    Description Enter Application used to complete all tutorials from the Appian documentation at docs.appian.com.
    Generate groups and folders to secure and organize objects Keep this checkbox selected, so that Appian will automatically generate standard groups and folders and assign default security groups for this application.
  4. Click CREATE.

  5. In the Review Application Security dialog, keep the default security settings. Because we selected the Generate groups and folders option in the previous step, Appian automatically uses the AT Users and AT Administrator groups it generated to set our application security appropriately.

    Note:  The security of the application object is unrelated to the security of each of the objects contained within the application. You will need to set security permissions for every object in an application in addition to the application object itself.

  6. Click SAVE.

    screenshot of the Explore view

  7. Click X to close the What do you want to build first? dialog.

Right now, the application contains the folders and groups Appian generated automatically. To see these, click Build in the navigation pane.

Each design object that you create during the course of this tutorial will appear in this list in the Build view and be associated with the tutorial application.

screenshot of the build view

Generated groups and folders

Because we selected the Generate groups and folders to secure and organize objects option while creating the object, Appian generates standard groups and folders for the application, as well as assigns the generated groups as the default security groups for the application.

In this tutorial, we'll be using the following generated groups and folders:

  • AT Administrators group to contain all administrators of the Appian Tutorial application.
  • AT Users group to contain all users of the Appian Tutorial application.
  • AT Rules & Constants folder to contain all our expression rules, constants, and interfaces in this folder throughout the tutorial.

For each object we create in this tutorial, Appian will prepopulate the AT Administrators and AT Users groups in the object role maps. For this tutorial, we won't need to make changes to those prepopulated values.

Now, let's create and configure our new record type.

Create the record type

First, we'll create a record type to store and reference the artworks from the Art Institute of Chicago.

To create the record type:

  1. In the Build view of the Appian Tutorial application, click NEW > Record type.

  2. Configure the following properties:

    Property Action
    Name Keep the application prefix that prepopulates this property, and add Artwork, so that the name is AT Artwork.
    Display Name (Plural) Keep the generated value of Artworks.
    Description Enter Artworks at the Art Institute of Chicago.
  3. Click CREATE.
  4. In the Review Record Type Security dialog, keep the default settings. AT Administrators group should be assigned Administrator permissions for the group.
  5. Click SAVE.

Configure the record data source

After creating the record type, we'll configure the record type to connect to a web service. To do this, we must have a record data source expression. This is an expression rule that structures and formats data returned from a REST API through an integration object so it can be used in Appian.

Since we don't have an existing record data source expression, we'll create one while we configure the source of the record type.

To configure the record data source:

  1. On the Data Model page, click TELL US ABOUT YOUR DATA.
  2. For Choose Source Type, click Web Service.
  3. Click NEXT.
  4. For Choose how to access data, keep the default selection Optimized Data Access. The data will be synced in Appian to automatically optimize performance.
  5. Click NEXT.
  6. For Choose Record Data Source, click Create Record Data Source.

Set up the connected system

To create our record data source, we'll start by creating a connected system to store the base URL used to connect the Art Institute of Chicago API.

To create the connected system:

  1. Keep the default option, Create a new integration, selected.
  2. Next to the Connected System field, click Create Connected System.
  3. In the Create Connected System dialog, select HTTP.
  4. For Name, enter AT Art Institute of Chicago.
  5. For Description, enter API that returns data from the Art Institute of Chicago.
  6. For System Logo, upload a logo image for the Art Institute of Chicago.
  7. For Base URL, enter https://api.artic.edu/api/v1/.
  8. For Authentication, keep the default None selected since this is an unauthenticated API.

  9. Leave Show as a shortcut in record type configuration de-selected. Since we only want to create one record type from this source, we don't need to make it a shortcut.

    Tutorial_XBR_RDS_Connected_System_Fields

  10. Click CREATE.

The new object is created and appears as the Connected System in the Create Record Data Source dialog.

Create the integration

Next, we'll create an integration that uses the connected system to call the Art Institute of Chicago API.

To create the integration:

  1. For Name, enter AT_getArtworks.
  2. For Description, enter Integration that gets artworks for the Artworks record type.

  3. For Save In, select the AT Rules & Constants folder.

    Create integration

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

  4. Click NEXT.

Create the record data source expression

Next, we'll create the record data source expression. The configuration wizard automatically defines the properties for our expression rule based on the properties of the integration.

Verify that the following information is automatically populated in each property:

Property Value
Name AT_getArtworks_recordDataSource
Description The Record Data Source for the AT Artwork Record Type
Application Appian Tutorial
Save In AT Rules & Constants

Click NEXT.

Configure syncing in batches

In the last step of the Create Record Data Source wizard, you'll specify whether you want to sync your data in batches. To allow the record type to sync more than 1,000 rows, we'll enable batching.

To determine how to batch data, review the documentation for your API. In this tutorial, the API documentation indicates that pagination is controlled by the page parameter. Since this is a number-based property, we will batch by sequential values.

To batch by sequential values:

  1. Select Batch by Sequential Values. A rule input of type Number (Integer) will be automatically configured on the record data source expression and the integration object.
  2. Click CREATE.

Two generated objects are listed on the confirmation page. Before you close the Create Record Data Source wizard, we need to edit the generated objects so they return the right data in the right format.

Caution:  If you click OK now, you will see an error on the Choose Record Data Source dialog.

Created record data source objects

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to closeCreated record data source objects

Configure the integration path

First, we'll edit the generated integration object AT_getArtworks. We need to configure two things:

  • A relative path to specify which API endpoint to call. Based on the API's documentation, we'll use artworks.
  • Query parameters to control pagination (page) and the number of results per page (limit).

To configure the relative path and query parameters:

  1. On the Create Record Data Source dialog, click the AT_getArtworks integration object to open it.

  2. For Relative Path, enter artworks.

    This will be appended to the Base URL of the connected system to form a URL Preview of https://api.artic.edu/api/v1/artworks.

    /xbr-tutorial-url-configuration

  3. Click TEST REQUEST. This should return a success message:

    /xbr-tutorial-url-success

  4. Under the success message, click Convert JSON to Appian value.

  5. Click TEST REQUEST. The results should be converted from JSON to an Appian dictionary.

    For example:

    /xbr-tutorial-returned-data

  6. Expand the Query Parameters section of the integration.
  7. Click Add Query Parameter.
  8. For Name, enter page.
  9. For Value, hover over the input field and click Edit as Expression.
  10. Enter ri!batchNumber in the expression box.

  11. Click OK.

    /xbr-tutorial-returned-data

  12. Click Add Query Parameter.
  13. For Name, enter limit.

  14. For Value, enter 100. This increases the number of results returned per page from the default of 12 to 100, reducing the total number of integration calls needed during a full sync.

    /xbr-tutorial-returned-data

  15. Click TEST REQUEST. The result.body should contain 100 items.
  16. Click SAVE.

Specify fields returned in the integration

Right now, the integration returns several fields that we won't need to use in our application. While we will map specific fields to the record type in a later step, removing unnecessary fields from the integration response can enable better performance.

According to the API's documentation, we can use a fields parameter to specify which fields to return.

To specify the fields to return in the integration:

  1. In the Query Parameters section, click Add Query Parameter.
  2. For Name, enter fields.
  3. For Value, hover over the input field and click Edit as Expression.

  4. Enter the following expression:

    1

    "id,image_id,title,artist_display,date_display,main_reference_number"
  5. Click OK.

  6. Click TEST REQUEST and verify that only the desired fields are included in the results.body.data.

    images/xbr-tutorial-fields-parameter.png

    Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to closeimages/xbr-tutorial-fields-parameter.png

  7. Click SAVE.
  8. Close the integration tab.

Edit the expression rule

Next, we'll edit the generated record data source expression. We need to ensure that the expression returns the data we need in the format we need.

By default, the expression returns data in the pagination, data, info, and config headings. However, we only need the information nested under the data heading.

To configure the record data source expression:

  1. Return to the AT Artwork record type.
  2. In the Create Record Data Source dialog, click the AT_getArtworks_recordDataSource expression rule.

  3. Replace the entire expression with the following:

    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

    a!localVariables(
/* Call the integration and store the response in a local variable */
local!integrationResponse: rule!AT_getArtworks(batchNumber: ri!batchNumber),
   
/* When the batch number exceeds 10, stop returning data. Since each page returns 100 items, the record type syncs approximately 1,000 artworks. */
if(
   ri!batchNumber > 10,
   null,
   if(
      /* This will return true if the integration succeeds */
      local!integrationResponse.success,
         
      /* Map the following to your record data */
      index(
      local!integrationResponse.result.body,
      "data",
      {}
      ),
         
      /* 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
      )
   )
  )
)
  4. Click TEST RULE. The output should return a List of Dictionary with 100 items.
  5. Click SAVE.
  6. Close the expression rule tab.

Preview the record data source

Now that the integration and expression rule are properly configured, we can return to the record type to see a preview of the record data source.

To preview the record data source:

  1. Return to the AT Artwork record type.

  2. On the Create Record Data Source dialog, click OK.

    A data preview of the record data source expression appears in the Configure Data Source dialog.

    images/xbr-tutorial-data-preview.png

    Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to closeimages/xbr-tutorial-data-preview.png

  3. Click NEXT.

Configure record type fields

Appian automatically maps the source fields to record fields and then lets you pick a primary key field and any unique fields.

We'll keep all the fields selected, but we'll clean up some of the record field names to use camel casing instead of underscores. We'll also choose which field is the primary key field.

To configure the record type fields:

  1. For Primary Key, select id.
  2. Leave Unique Fields blank. We don't have any other fields that require unique values.

  3. Rename the following fields:

    Original Record Field Name Updated Record Field Name
    main_reference_number referenceNumber
    date_display dateDisplay
    artist_display artistDisplay
    image_id imageId

  4. (Optional) Update the Display Name for the following fields so they're more descriptive:

    Original Display Name Updated Display Name
    Id ID
    Main Reference Number Reference Number
    Date Display Date
    Artist Display Artist
    Image Id Image ID
  5. Click FINISH.

  6. Click SAVE.

    images/xbr-tutorial-configure-fields.png

    Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to closeimages/xbr-tutorial-configure-fields.png

Saving the record type starts a full sync. It may take a few minutes to sync all the necessary data. You can track the status of your sync by going to the Sync History page in the record type.

Manage documents

The Art Institute of Chicago API allows us to download images of individual art pieces. To easily view and download these images in the application, we will:

  • Create a download integration that returns a single image for a specific artwork, using the artwork's imageId field to construct the request URL.
  • Configure the record type to use the download integration so images are accessible from record views.

Create download integration

First, we'll create an integration to return a single image. Based on the API documentation, we can use the imageId field to help structure the URL to call each image.

To create a document download integration:

  1. In the Build view of the Appian Tutorial application, click NEW > Integration.

  2. Configure the following integration properties:

    Property Action
    Connected System Select AT Art Institute of Chicago.
    Name Enter AT_getArtwork_downloadIntegration.
    Description Enter Downloads a single artwork image for the AT Artwork record type.
    Save In Keep AT Rules & Constants selected.
  3. Click CREATE.
  4. In the Rule Input pane of the integration, click New Rule Input.

  5. Configure the following rule input properties:

    Property Action
    Name Enter imageId.
    Type Select Text.
  6. In the Connection pane of the integration, select Build URL from Scratch.
  7. For URL, hover over the field and click Edit as Expression.

  8. In the expression box, replace the existing URL with the following:

    1

    "https://www.artic.edu/iiif/2/" & ri!imageId & "/full/843,/0/default.jpg"
  9. Click OK.
  10. Expand the Response section of the integration.
  11. For Response Body Parsing, select Convert binary to Appian document.
  12. For Save Document In, select Record Type. This will automatically store the documents in the AT Artwork record type.
  13. Click SAVE.
  14. To test the integration:
    1. In the test pane, paste a value from the imageId field in the Expression box. For example, "175b403f-cd01-eba7-2dec-465b4d4451da".
    2. Click TEST REQUEST.
    images/xbr-tutorial-example-document-download.png

    Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to closeimages/xbr-tutorial-example-document-download.png

  15. Close the integration tab.

Configure the download integration on the record type

Now that we have a document download integration, we'll configure the record type to reference this integration.

To configure the download integration on the record type:

  1. Return to the AT Artwork record type.
  2. Go to Documents.
  3. Click SELECT INTEGRATION. The Select Integration dialog appears.
  4. For Integration, select AT_getArtwork_downloadIntegration. The Rule Input and Rule Input Type are automatically populated.
  5. For Field to Map to Rule Input, select imageId.
  6. Test the integration by entering a title in Search Record Titles and clicking DOWNLOAD.
  7. Click DONE.
  8. Click SAVE.

Configure the list view

Now that our data is available in the record type, we'll configure the record list so users can browse that data.

By default, the record list displays all fields configured on the record type. However, we only want to display select fields since this data is meant to be viewed at a glance before users drill into each record.

To configure the record list:

  1. In the record type, go to List.
  2. Leave the default Style option as Grid.
  3. Click EDIT LIST.
  4. For Empty Grid Message, enter No artworks exist with this criteria.
  5. In the Grid pane, go to the Data tab.
  6. For Rows to Display Per Page, enter 20.
  7. For Initial Sort, click ADD SORT and configure sorting:
    1. Click Sort Info.
    2. For Field, select title.
    3. For Order, select Ascending.
    4. Click Grid to return to the grid configurations.
  8. In the Columns section, delete the following columns by hovering over and clicking :
    • Id
    • Reference Number
    • Image Id

  9. Click the following column names to rename them:

    Original Column Name Updated Column Name
    Date Display Date
    Artist Display Artist
  10. In the Columns section, click Title. The grid configuration pane will show details about that column.
  11. Go to the Data tab.
  12. Click DISPLAY OPTIONS.
  13. Click RECORD LINK.
  14. For Display Value, click Edit as Expression.

  15. Enter the following expression:

    1
2
3
4
5
6
7
8
9
10
11
12

    a!linkField(
links: {
   a!recordLink(
      label: a!defaultValue(
      fv!row[recordType!AT Artwork.fields.title],
      "–"
      ),
      recordType: recordType!AT Artwork,
      identifier: fv!identifier
   )
  }
)

    Note:  Record field references are specific to each record type and environment. You need to reference the record fields from the record type in your own environment whenever you copy and paste a record field reference from outside the application.

  16. Click OK to close the expression editor.
  17. Click OK to close the list editor.
  18. Click SAVE.
  19. To test your record list configuration, click the link under URL.

The record list should look something like this:

images/xbr-tutorial-final-record-list.png

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to closeimages/xbr-tutorial-final-record-list.png

Generate a Summary view

In the last step of this tutorial, we'll create the Summary view to provide a brief overview of each piece of artwork. We can quickly create and configure this view using the record view generator.

Since we configured a document download integration on the record type, the generated Summary view is automatically formatted with components to display and download the file.

To generate a Summary view:

  1. In the record type, go to Views.

  2. Click GENERATE RECORD VIEW.

    /record view empty state

  3. For Selected Record Types, keep the Artwork record type selected. This will display all fields from the record type in the view.
  4. Click NEXT.

  5. For Edit Settings, leave the default configurations:

    Property Value
    View Name Summary
    Application Appian Tutorial
    Rule Input Name artwork
  6. Click NEXT. The Review Objects dialog appears outlining the objects that Appian will use for your new Summary view.
  7. Click GENERATE.
  8. Click CLOSE. Your new Summary view displays in the Record Views table.
  9. Click SAVE.
  10. Test the Summary view configuration:
    1. In the record type, go to List.
    2. Click the link under URL.
    3. Select an artwork title to view the Summary view.

/xbr-tutorial-summary-view

Success!

You now have a fully functioning service-backed record type that connects to an external API, syncs data in batches, and displays artwork information in a record list and Summary view.

In this tutorial, you learned how to:

  • Create a connected system to store connection information for a REST API.
  • Build an integration with query parameters to control pagination and limit results.
  • Write a record data source expression that formats API data.
  • Configure a document download integration to retrieve individual images from an external source.
  • Set up a record list with custom columns and record links.
  • Generate a Summary view with document display capabilities.

To continue learning, check out the Database-Backed Record Type Tutorial to see how record types work with a database as the data source.

Feedback