Free cookie consent management tool by TermsFeed Service-Backed Record Tutorial [Integrations]
Service-Backed Record Tutorial

Introduction

Your enterprise data may be spread across a number of different systems. With our newly improved service-backed records, you can easily bring all of your data together and use it in one place.

This tutorial pertains to service-backed records without sync enabled. To learn how to use a web service as the record type data source with sync enabled, see Use a web service with sync enabled.

The r/SpaceX API

This tutorial guides you through the steps for creating a service-backed record that powers a fictional SpaceX Launch application. Service-backed records differ from other kinds of record types in that they use web services as their data source. We'll use the r/SpaceX API to configure an service-backed record to power a test application designed to manage space launch data.

Most APIs require authentication. The r/SpaceX API is a freely available, open source API that uses JSON, which doesn't require authentication. This makes it ideal for this tutorial because we don't need verification credentials in order to connect to it. Specifically, we will use the Launches API, which is resourced within the r/SpaceX API and supports paging, searching, and filtering.

Objectives

You'll learn how to use a web service integration to create a record type. Although this tutorial focuses more on the specifics of configuring the record type's data source and record list view, you'll also have an opportunity to create other Appian design objects required to build the record type and SpaceX Launch application.

You'll create the following design objects:

After you complete this tutorial, you will understand how to use your own data or API to create a service-backed record. The final configurations for your Appian records will change based on your field names and data types.

Requirements

To successfully complete this tutorial, you must first complete the Application Building Tutorial. We'll use some of the objects created in the application tutorial to set up our SpaceX Launch application. You also need to have a basic familiarity with Appian Interfaces and a basic understanding of APIs and how to use them. To gain practice designing Appian interfaces, walk through the Interface Tutorial and Process-Backed and Entity-Backed Record Tutorial.

Setup

Before we create the record type, we need to set up our application and user groups. We'll also need to create a Custom Data Type (CDT) that will define the structure and organization of the data for our record type.

Create the application and user groups

Let's start by creating our SpaceX Launch application and a new user group. We'll leverage the AT Administrators user group created in the Application Building Tutorial as the parent group in our application.

Let's begin:

  1. Log in to Appian Designer.
  2. Click NEW APPLICATION.

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

    Property Description
    Name Enter SpaceX Launch.
    Prefix Replace the default prefix with SpaceX. This prefix departs a bit from the recommended naming standard, but it's within the character limits allowed, it meets our needs for this tutorial, and it's more fun. We'll be using this short, unique prefix whenever we name an object in this application.
    Description Enter Container for components of the SpaceX Launch application.
    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 settings for the Default (All Other Users) and SpaceX Users.
  6. Click X next to SpaceX Administrators to remove it.
  7. Click Add Users or Groups. Another row appears in the row map.
  8. Click in the User and Groups column for the new row.

  9. In the Create Group dialog, configure the following properties:

    Property Description
    Name Enter: SpaceX Managers
    Description Enter: Manager group for the Launch application
    Parent Group Enter: SpaceX Users
    Group Members Enter your user name.
  10. Keep the default settings for Group Type, Visibility, and Privacy Policy.
  11. Click CREATE to return to the Review Application Security dialog.
  12. From the Permission Level dropdown, select the Administrator permission level for the SpaceX Managers group.

  13. Click SAVE.

    The security of the application object is unrelated to the security of each of the objects contained within the application. This means that you will need to set security permissions for every object in an application in addition to the application object itself. For more information about security permissions for the application object, see Application Security.

Now we're ready to create our CDTs.

Create the source data type

We need to define a custom data type with fields that match the expected integration response. These CDT fields will become the record fields that are available for use in our record list, record views, and record actions.

For this tutorial, we'll actually need to create two data types. Our main data type, SpaceX_Launch, will define the data related to a specific launch. However, since our response is returning nested data about the rocket that was used in the launch, we also need to create a child CDT called SpaceX_Rocket to represent it.

When creating the CDTs, follow the field order provided in the steps below. This will ensure the columns in your record list view match the order presented in this tutorial.

First we'll create the SpaceX_Rocket data type:

  1. In the application view of the SpaceX Launch application, click NEW > Data Type.
  2. In the Create Data Type dialog, configure the following properties:
    • Select Create from scratch.
    • For Namespace, replace the default ending SpaceX with launch.
    • For Name, enter: SpaceX_Rocket
    • For Description, enter: This custom data type defines the data fields associated with each rocket.
  3. Click CREATE. The SpaceX_Rocket data type will open in a new tab.
  4. Under Fields, click New Field to add a new field name and data type for each item specified below.
    • rocket_id (Number (Integer))
    • rocket_name (Text)
    • rocket_type (Text)

    The fields should look like this: /Tutorial_XBR_CDT_Rocket

  5. Click SAVE CHANGES.
  6. Close the data type.

Now let's create the SpaceX_Launch data type:

  1. Return to the application view for the SpaceX Launch application.
  2. Click NEW > Data Type.
  3. In the Create Data Type dialog, configure the following properties:
    • Select Create from scratch.
    • For Namespace, replace the default ending SpaceX with launch.
    • For Name, enter: SpaceX_Launch
    • For Description, enter: This custom data type defines the data fields associated with each launch.
  4. Click CREATE. The SpaceX_Launch data type will open in a new tab.
  5. Under Fields, click New Field to add a new field name and data type for each item specified below.
    • flight_number (Number (Integer))
    • mission_name (Text)
    • launch_year (Text)
    • launch_date_utc (Date)
    • rocket (SpaceX_Rocket)
    • launch_success (Boolean)
    • details (Text)

    The fields should look like this: /Tutorial_XBR_CDT_Launch

  6. Click SAVE CHANGES.
  7. Close the data type.

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

Create the record type

We will create and configure the record type in steps. We'll start with creating the data source objects, followed by setting up filters and configuring the integrations and expressions, and finally creating the record list view and record type's Summary view.

To begin:

  1. In the application view of the SpaceX Launch application, click NEW > Record Type.
  2. For Name, enter SpaceX Launch. SpaceX Launches will automatically populate in the Plural Name field.
  3. For Description, enter Record type for the SpaceX Launch application.
  4. Click CREATE.
  5. In the Review Record Type Security dialog, keep the default security group settings.
  6. Click Add Users or Groups.
  7. Click .
  8. Configure the following properties of the new group:
    • For Name, enter: SpaceX Managers
    • For Parent Group, select SpaceX Users.
    • For Group Members, select your user.
  9. Click CREATE.
  10. For the Permission Level of the new group, select Administrator.
  11. Click SAVE. The SpaceX Launch record type will open in a new tab.

Configure the record data source

Before we can configure the integration objects, expression rules, and rule inputs needed to configure our record type, we need to select a data source for the record type.

When the SpaceX Launch record type opens in a new tab, the Data Model page opens by default. From this page, we'll select our data source and configure the record type.

  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 Data Sync, choose Disable sync and related features.
  5. Click NEXT.
  6. For Choose Record Data Source, click Create Record Data Source to set up the connected system.

screenshot pointing to the Create Record Data Source link

Set up the connected system

Now, we'll set up an HTTP connected system for the r/SpaceX API and the expression rule that calls that integration. This will allow us to use an integration to call the external data into the record type. The configuration wizard will guide us through the process of creating the Appian design objects you need to configure the record data source.

To create an HTTP connected system:

  1. Keep the default option, Create a new integration, selected.
  2. Next to the Connected System field, click .
  3. In the Create Connected System dialog, select HTTP.

    For more information about a specific connected system option, including a detailed description, hover over the connected system button to access the tool tip.

  4. For Name, enter: r/SpaceX API
  5. For Description, enter: An API that returns data about SpaceX launches.
  6. For System Logo, upload a system logo image.
  7. For Base URL, enter https://api.spacexdata.com/v3/.
  8. For Authentication, keep the default None selected since this is an unauthenticated API.

  9. Click CREATE.

    Tutorial_XBR_RDS_Connected_System_Fields

Create the record data source integration

Now we'll create an integration that connects to the r/SpaceX API connected system and calls the external data for the record type.

  1. For Name, enter: SpaceX_getAllLaunches
  2. For Description, enter: The integration that calls in data for the record data source
  3. For Save In, select the SpaceX Rules & Constants folder.
  4. Click NEXT.

We still need to configure the path and query parameters for the record data source integration, which we'll do in Configure the integration path and Configure query parameters for the integration.

Create the record data source expression rule

After we create the integration for the record data source, the configuration wizard automatically defines the property fields for our expression rule. The record data source expression connects the integration to the record type, calls the integration, and transforms it into a DataSubset.

In the CREATE EXPRESSION RULE step, verify that the following information is automatically populated in each field below:

  • Name field - SpaceX_getAllLaunches_recordDataSource
  • Description field - The Record Data Source for the SpaceX Launch Record Type.
  • Application field - SpaceX Launch
  • Save In field (folder) - SpaceX Rules & Constants

We still need to use SAIL to build the Record Data Source expression, which we'll do in Build the record data source expression rule.

Click NEXT to continue on to configuring rule inputs.

Configure the rule inputs for paging, searching, and filtering

In the next step, we'll configure the integration to handle paging, searching, and filtering. The configuration wizard takes care of most of this for you by automatically enabling and mapping the rule inputs that control paging and searching to the record type. We'll add rule inputs to enable filtering by launch year, launch success, and flight number.

  1. In the CONFIGURE RULE INPUTS dialog, verify that the checkboxes under Paging and Search are selected. These checkboxes enable the rule inputs for the record type.
  2. Verify that the following rules inputs are configured:
    • pagingInfo of type PagingInfo
    • searchText of type Text
  3. Click Add new Rule Input for Filtering to add the rule inputs below:
    • launch_year of type Text
    • launch_success of type Boolean
    • flight_number of type Integer
  4. Click CREATE. Tutorial_XBR_RDS_Objects_List
  5. Click OK. The Choose Record Data Source dialog now opens so that we can finish setting up our data source and data type.
  6. For Record Data Source, select SpaceX_source_getAllLaunches_recordDataSource. Click Search to see this automatically selected.
  7. Click NEXT.
  8. For Data Type, select the SpaceX_Launch CDT that we created earlier.
  9. Click FINISH.
  10. Click SAVE CHANGES.

Configure the integration path

Now it's time to configure the integration path, which allows the integration to populate the record list and return a list of the objects that will map to the Data Type we selected for the record type. We'll use the launches endpoint to return an array of SpaceX launches. The rule inputs for this integration will be passed into the corresponding expression rule for the record data source.

  1. In the application view, click the SpaceX_getAllLaunches integration object to open it. If you don't see your new objects, refresh the page.

  2. For Relative Path, enter launches. This will be appended to the Base URL of the connected system to form a URL of https://api.spacexdata.com/v3/launches.

    /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 to convert this response body to an Appian dictionary.
  5. Click TEST REQUEST again to ensure the test results successfully converted to JSON.
  6. Click SAVE CHANGES.

Configure query parameters for the integration

Next, we'll configure the integration's offset, limit, sort, and order query parameters to enable paging and the rocket_name parameter to enable search.

Paging is often the most complicated parameter to configure. This is because APIs don't understand the PagingInfo type, and different APIs handle paging in different ways. See the r/SpaceX API documentation for details on their pagination parameters.

We'll also configure the launch_year and launch_success parameters to enable filtering by launch year and launch success. All of these query parameters have dynamic values, and should be configured as expressions. We will populate their values using the rule inputs we previously created.

Let's begin:

  1. Expand the Query Parameters section of the integration.
  2. Click Add Query Parameter to configure each query parameter and value listed below. Make sure to click the icon next to each query Value field to configure each Query Parameter value as an expression.
    • Add the offset parameter and use the expression editor to enter ri!pagingInfo.startIndex - 1 as the parameter value.
    • Add the limit parameter and use the expression editor to enter ri!pagingInfo.batchSize as the parameter value.
    • Add the sort parameter and use the expression editor to enter index(ri!pagingInfo.sort, "field", null) as the parameter value.
    • Add the order parameter and use the expression editor to enter if(index(ri!pagingInfo.sort, "ascending", null), "asc", "desc") as the parameter value.
    • Add the rocket_name parameter to enable searching by name and use the expression editor to enter ri!searchText as the parameter value.
    • Add the launch_year parameter to enable filtering by launch year and use the expression editor to enter ri!launch_year as the parameter value.

    • Add the launch_success parameter to enable filtering by launch success and use the expression editor to enter ri!launch_success as the parameter value.

      /xbr-tutorial-query-parameters

  3. Click TEST REQUEST. This allows us to run some tests to ensure the integration is behaving as expected.
  4. Click SAVE CHANGES.

ri!searchText and any rule inputs being used for filtering can have null values. However, a configured service-backed record will never have a null value for startIndex or batchSize. Therefore, test values should be set such that ri!pagingInfo.startIndex and ri!pagingInfo.batchSize are not null.

Build the record data source expression rule

Now we'll use SAIL to build an expression rule for our record data source. This expression rule will transform the integration response into a DataSubset for the record list view. The rule inputs for this expression rule are taken from the record data source's integration rule inputs.

We've made this process easy for you by providing a SAIL template in the expression rule object. To build the expression rule, simply follow the instructions and comments provided in the template along with the steps below. Note that some sections of the SAIL code are preconfigured for you. As you go through each step in the template, verify that the preconfigured code matches the configurations defined in the steps below.

Let's begin:

  1. In the application view, open the SpaceX_getAllLaunches_recordDataSource expression rule object. The expression rule will open in a new tab.
  2. The expression rule is preconfigured to to call the integration and successfully return a DataSubset.
    • Review the SAIL code in the expression rule and verify that it uses a!localVariables to call the integration with the following rule inputs.
      • Set the pagingInfo parameter value to ri!pagingInfo
      • Set the searchText parameter value to ri!searchText
      • Set the launch_year parameter value to ri!launch_year
      • Set the launch_success parameter value to ri!launch_success

      See the SAIL code below.

      sail a!localVariables(local!integrationResponse: rule!SpaceX_getAllLaunches( pagingInfo: ri!pagingInfo, searchText: ri!searchText, launch_year: ri!launch_year, launch_success: ri!launch_success, flight_number: ri!flight_number ),

  3. Now, test the expression rule to ensure that it correctly calls the integration and returns the DataSubset for a start index of 1 and a batch size of 5 as expected.

    • From the Ad Hoc Test view, enter a!pagingInfo(1,5) in the expression value field for the pagingInfo rule input.

      /Tutorial XBR RDS Test Expression

    • Click TEST RULE. Your results should look similar to the test results shown below.

      /Tutorial XBR RDS Test Expression Results

  4. After successfully calling the integration, comment out local!integrationResponse (line 15) in the expression rule.

    1

     /*local!integrationResponse*/
  5. Use a!dataSubset to configure the expression rule to transform the integration result into a DataSubset. First, verify the preconfigured pagingInfo parameter values match the configurations below.
    • Set the startIndex parameter value to ri!pagingInfo.startIndex
    • Set the batchSize parameter value to ri!pagingInfo.batchSize

    • Set the sort parameter value to ri!pagingInfo.sort

      1
2
3
4

      a!dataSubset(
    startIndex: ri!pagingInfo.startIndex,
    batchSize: ri!pagingInfo.batchSize,
    sort: ri!pagingInfo.sort,
    • Configure the data parameter value to local!integrationResponse.result.body to use the list of launches for the record list data.

    • Use the if() function to configure the identifiers parameter value to return any flights from the DataSubset by the flight_number identifier as shown below.

      1
2
3
4

       identifiers: if(tointeger(local!integrationResponse.result.headers.'Spacex-Api-Count') > 0,
 index(local!integrationResponse.result.body, "flight_number", null),
 {}
 ),

    • Next, use the tointeger() function to configure the totalCount parameter returned by the integration response as shown below.

      1

      totalCount: tointeger(local!integrationResponse.result.headers.'Spacex-Api-Count')
  6. Remove the comment marks around the closed parenthesis ) (line 39)
  7. Click TEST RULE again to ensure that the expression rule returns a DataSubset correctly.
  8. Click SAVE CHANGES.

  9. Check your code with the expression below.

    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

    a!localVariables(

  /* 1. First, configure the integration object to return successfully */

   local!integrationResponse:    rule!SpaceX_getAllLaunches(
 pagingInfo: ri!pagingInfo,
 searchText: ri!searchText,
 launch_year: ri!launch_year,
 launch_success: ri!launch_success,
 flight_number: ri!flight_number
  ),

  /* 2. Then, ensure that you can call the integration from this expression rule */

 /*local!integrationResponse*/

  /* 3. Once you've called the integration successfully, comment out the line above this */

   /* 4. Finally, use the successful response to construct the DataSubset below */

  /*Transform the integration result into a DataSubset*/

  a!dataSubset(
    startIndex: ri!pagingInfo.startIndex,
    batchSize: ri!pagingInfo.batchSize,
    sort: ri!pagingInfo.sort,

    /*Use the list of launches for the record list data*/
 data: local!integrationResponse.result.body,

    /*If any launches were returned, use the flight number as the identifier*/
    identifiers: if(
      tointeger(local!integrationResponse.result.headers.'Spacex-Api-Count') > 0,
      local!integrationResponse.result.body.flight_number,
   {}
 ),

     /*Use the totalCount returned by the response*/
    totalCount:    tointeger(local!integrationResponse.result.headers.'Spacex-Api-Count'),
  )
)

Now that we've configured the record data source, let's verify that the data returned for your record data source expression matches the fields in our data type.

Test the record data source

You can access the Test Record Source box from the Source page of your record type to test both the record data source expression and the single record source expression. You should test your expression rules after completing any of the following testable increments.

  • After configuring the record data source expression
  • After configuring rule inputs and filters
  • After configuring the single record source expression

Now let's verify that the data results returned for our record data source expression matches the DataSubset we expect for the record type.

  1. Go back to the record type.
  2. From the Test Record Source box, select the Record Data Source view.
  3. Click TEST.

  4. Verify the column titles match the fields in SpaceX_Launch CDT and the record data returns as expected.

    Tutorial_XBR_Test_Pane_Source_View

Configure the single record source

Now that we've configured our record data source, we can create our single record source. First, we will create an integration, and then we will create an expression to wrap it.

Create the single record source integration and expression

The second integration we build will populate the record views. This integration should return a single object that will map to the data type for the record type.

We will be using the launches/{{flight_number}} endpoint to return data for a single SpaceX launch.

Let's begin:

  1. In the record type Source page, click Create Single Record Source. This will open the single record source configuration wizard.

    Tutorial XBR Single Record Source

    By default, the Create a new integration option is selected.

  2. For Connected System, enter r/SpaceX API.
  3. For Name, enter: SpaceX_getOneLaunch
  4. For Description, enter: The single record source integration for the SpaceX Launch application.
  5. For Save In, select the SpaceX Rules & Constants folder.
  6. Click NEXT. Appian will automatically define the fields for your Single Record Source expression.
  7. Click CREATE.

We still need to configure the path and rule input for the record data source integration and build the expression, which we'll do in Configure the single record source integration and Build the single record source expression rule.

Configure the single record source integration

Now, let's configure the integration to fetch data for a single record view by an id rule input. Appian will automatically create the id rule input we need to return data for a specific launch record.

Let's begin:

  1. In the objects view in Create Single Record Source, click the SpaceX_getOneLaunch integration to open it in a new tab.
  2. In the Rule Inputs panel, change the rule input type for id from type Any Type to type Number (Integer).

    If you don't see the Rule Inputs panel, you may have to click the arrow on the right side of your window to expand the panel.

  3. Set the test value for ri!id to 1.

  4. Edit the Relative Path as an expression and set it to "launches/"&ri!id. This will be appended to the Base URL of the connected system to form a URL of "https://api.spacexdata.com/v3/launches/1, given our test value of 1 for ri!id.

    /xbr-tutorial-url-success-getOne

  5. Click TEST REQUEST. This allows us to run some tests to ensure our integration is behaving as expected. Given our test value of 1 for ri!id, this should return a success message:

    /xbr-tutorial-connected-system

  6. Under the success message, click Convert JSON to Appian value to convert this response body to an Appian dictionary.
  7. Click TEST REQUEST again to ensure the test results successfully converted to JSON.
  8. Click SAVE CHANGES.
  9. Go back to the record type.

Build the single record source expression rule

Now that we've configured an integration to back our record view, we need to create an expression to wrap it. This expression will act as the glue between the integration and the record type, by calling the integration and transforming it into an Appian dictionary.

Like we did for the record data source expression, we'll use SAIL to build an expression for our single record source.

Let's begin:

  1. In the objects view in Create Single Record Source, open the SpaceX_getOneLaunch_recordDataSource expression rule object. The expression will open in a new tab.

  2. Review the SAIL code and verify that it uses a!localVariables to call the SpaceX_getOneLaunch integration.

    1
2
3
4
5

    a!localVariables(

  local!integrationResponse: rule!SpaceX_getOneLaunch1(
    id: ri!id
  ),

  3. Configure the expression rule to to call the integration and return a dictionary.

    1

    rule!SpaceX_GetOneLaunch(id: ri!id).result.body
  4. In the Rule Inputs panel, change the rule input type for id from type Any Type to type Number (Integer).

    If you don't see the Rule Inputs panel, you may have to click the arrow on the right side of your window to expand the panel.

  5. For Test Inputs, set the test value for id (Number (Integer)) to 1.
  6. Click TEST RULE to ensure the expression rule is hooked up to the integration properly.
  7. Click SAVE CHANGES.
  8. Go back to the Create Record Data Source objects list view and click OK.

Now let's enhance our record list by configuring our user filters.

Create a user filter

The user filters we added earlier to our expression are already made for us in the Search and User Filters page of the record type, but we still need to configure them.

To edit a user filter:

  1. In the left pane in the record type, click Search and User Filters.
  2. Click the user filter named Launch Year.
  3. In the Edit User Filter dialog:
    • Do not select Users can select multiple choices. This API only allows a single selection per dropdown.
    • To change the filter choices, copy this expression into the Choices expression editor: 
      1
2
3
4

      a!recordFilterChoices(
    choiceLabels: {2015,2016,2017,2018,2019,2020},
    choiceValues: {2015,2016,2017,2018,2019,2020}
)
    • In the Filter Preview box, click UPDATE FILTER PREVIEW.

    • Test your filter configuration by selecting 2015 in the LAUNCH YEAR dropdown.

      /xbr-tutorial-user-filter-preview

    • Click OK.
  4. Click SAVE CHANGES.

Once again, at this point we can navigate to Tempo to verify that your new filter is interacting with your record list as expected. Incremental testing is a major key to success for serviced-backed records.

For more practice, configure a second User Filter for the launch_success parameter using the ri!launch_success rule input

Test the single record source

Now, let's use the Test Record Source box to verify that the data results returned for our Single Record Source expression returns data

To verify the Single Record Source expression, simply select the Single Record Source view, enter 1 in the Record Identifier field, and click TEST.

Tutorial_XBR_Test_Pane_Single_Record

Configure the list view

Now let's populate our record list with more meaningful data.

  1. In the record type List page, select the Grid option as the list Style option.
  2. Click Edit List to open the Edit Record List dialog.
  3. Add No launches exist with this criteria. in the Empty Grid Message field.
  4. In Rows to Display Per Page, enter 5. This controls the batchSize that is passed into the Paging Info input for your single record source.
  5. In the Columns section of the configuration pane, delete the Details column by hovering over the three dots and clicking the X.
  6. Delete the Rocket and Launch Success columns in the same way.
  7. Click the Mission Name link. The grid configuration pane will show details about that column.
  8. Verify the Sort Field value is set to mission_name. This controls the sortInfo that is passed into pagingInfo input for your record data source.
  9. Click OK to save all changes and return to the record type.

  10. Click SAVE CHANGES.

    You should end up with a list view that looks like this:

    /xbr-tutorial-final-record-list

Create the Summary view

The last step of this tutorial is to create the Summary view. Structurally, a Summary view for a service-backed record is no different from a Summary view for any other record type. What may be different, however, is how you acquire the data.

  1. In the application view of the SpaceX Launch application, click NEW > Interface.
  2. Configure the following properties:
    • For Name, enter: SpaceX_LaunchSummaryView
    • For Description, enter: The Summary View interface for the SpaceX Launch application.
    • For Save In, select the SpaceX Rules & Constants folder.
  3. Select CREATE. The interface will open in a new tab.
  4. Click EXPRESSION MODE.
  5. In the Rule Inputs panel, create a new rule input called launch and set the data type to SpaceX_Launch.

  6. Copy the expression below and paste in the interface definition.

    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
47
48
49
50
51
52
53

    a!boxLayout(
 label: "Flight #"&ri!launch.flight_number&" Launch Info",
 contents: {
   a!sideBySideLayout(
     items: {
       a!sideBySideItem(
         item: a!textField(
           label: "Date",
           labelPosition: "ADJACENT",
           value: ri!launch.launch_date_utc,
           readOnly: true
         )
       ),
       a!sideBySideItem(
         item: a!textField(
           label: "Name",
           labelPosition: "ADJACENT",
           value: ri!launch.rocket.rocket_name,
           readOnly: true
         )
       ),
       a!sideBySideItem(
         item: a!richTextDisplayField(
           label: "Success",
           labelPosition: "ADJACENT",
           value: a!richTextIcon(
             icon:
             if(
               ri!launch.launch_success,
               "check-circle",
               "times-circle"
             ),
             color:
             if(
               ri!launch.launch_success,
               "POSITIVE",
               "NEGATIVE"
             )
           )
         )
       )
     }
   ),
   a!textField(
     label: "Details",
     labelPosition: "ADJACENT",
     value: ri!launch.details,
     showWhen: not(isnull(ri!launch.details)),
     readOnly: true
   )
 },
 iscollapsible: true
)
  7. Click SAVE CHANGES.

The last steps are to get the record's title and Summary view configured.

  1. Go to the SpaceX_Launch record type.
  2. On the left navigation menu, click Views and Header.
  3. In the Views section, click next to Summary.
  4. In the Interface expression editor, copy the expression below to call the interface and pass in rv!identifier. Your expression should look something like the example below.
    • Note that record type field references are unique to each environment and this expression should be used for reference only.
    1
2
3
4
5
6
7
8
9
10
11
12
13

    rule!SpaceX_LaunchSummaryView(
 launch:
 'type!{urn:com:appian:types:launch}SpaceX_Launch'(
   id: rv!identifier,
   flight_number: rv!record[recordType!SpaceX Launch.fields.flight_number],
   mission_name: rv!record[recordType!SpaceX Launch.fields.mission_name],
   launch_year: rv!record[recordType!SpaceX Launch.fields.launch_year],
   launch_date_utc: rv!record[recordType!SpaceX Launch.fields.launch_date_utc],
   rocket: rv!record[recordType!SpaceX Launch.fields.rocket],
   launch_success: rv!record[recordType!SpaceX Launch.fields.launch_success],
   details: rv!record[recordType!SpaceX Launch.fields.details]
 )
)
  5. Click OK.
  6. In the Header section, select Expression.
  7. In the Expression Editor, enter rv!record[recordType!SpaceX Launch.fields.mission_name] to give each record the title of launch mission.
    • Don't copy and paste this example record type field reference. Instead, type in the reference and select the your record type and field as they're suggested.
  8. Click SAVE CHANGES.

Congratulations! Your record is complete. It should look something like:

/xbr-tutorial-summary-view

Considerations when using the record picker component

If you want to use a record picker with your service-backed record, it should work as expected, without the need to change your record definition. But, in case something is not working as desired, here are a few notes on how the record picker works and how you can tweak your record design to optimize for a record picker.

  • When a user types text into the picker field, it is equivalent to a user typing text into the search bar of the record list. The difference is that every new letter in the picker is a new call to the web service, whereas in the record list, the user must hit enter before any calls are made. This means increased load on the web service.
  • Once a record is picked, the component makes one call to the web service for every picked item to get the information displayed in the label. This could be problematic because there is often overhead in web service calls. For that reason, only use the record picker when the number of items you expect users to pick at one time is low.
  • Filters applied in the component are processed in the same way that default filters and user filters are processed. This means that any new filters in the picker needed to be handled accordingly in your source expression and data retrieval rule.

If this picker does not meet your needs, use a custom picker.

For more information about records, see Appian Records.

Open in Github Built: Fri, Sep 29, 2023 (07:12:20 PM)

Service-Backed Record Tutorial

FEEDBACK