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.
    • Enter SpaceX Launch in the Name field.
    • Enter Container for components of the SpaceX Launch application. in the Description field.
  3. Click Create. The Review Application Security dialog will open.
  4. From the Permission Level dropdown, select the Viewer permission level for the Default (All Other Users) group.
  5. Click Add Users or Groups.
  6. Click to open the Create Group dialog.
    • Enter SpaceX Managers in the Name field.
    • Enter Manager group for the Launch application. in the Description field.
    • Enter AT Administrators in the Parent Group field.
    • Enter your user name in Group Members.
    • Leave the default settings for Group Type, Visibility, and Privacy Policy as is.
    • Click CREATE to return to the Review Application Security dialog.
    • From the Permission Level dropdown, select the Administrator permission level for the SpaceX Managers group.
  7. Click SAVE.

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. From the SpaceX Launch application in Appian Designer, click the New dropdown and select Data Type to open the Create Data Type dialog.
    • Select Create from scratch.
    • Append :launch to the end of the default namespace.
    • Enter SpaceX_Rocket in the Name field.
    • Enter This custom data type defines the data fields associated with each rocket. in the Description field.
    • Click Create. The SpaceX_Rocket data type will open in a new tab.
  2. Under the Fields section, 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)

  3. Click Save.

    /Tutorial_XBR_CDT_Rocket

Now let's create the SpaceX_Launch data type:

  1. From the SpaceX Launch application, click the New dropdown and select Data Type.
  2. Select Create from scratch
  3. Append :launch to the end of the default namespace.
  4. In Name, enter SpaceX_Launch.
  5. In Description, enter This custom data type defines the data fields associated with each launch..
  6. Click Create. The SpaceX_Launch data type will open in a new tab.
  7. Under the Fields section, 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)

  8. Click Save.

    /Tutorial_XBR_CDT_Launch

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 SpaceX Launch application, click the New dropdown, and select Record Type.
  2. In Name, enter SpaceX Launch. SpaceX Launches will automatically populate in the Plural Name field.
  3. In Description, enter Record type for the SpaceX Launch application..
  4. Click Create. The Review Record Type Security dialog will open.
    • From the Permission Level dropdown, select the Viewer permission level for the Default (All Other Users) group.
    • Add the SpaceX Managers group and select Administrators as the permission level.
  5. 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. By default, the Create a new integration option is selected. Click the icon next to the Connected System field.
  2. Select HTTP for your connected system to open the Create Connected System dialog.
    • Note: For more information about a specific connected system option, including a detailed description, hover over the connected system button to access the tool tip.
  3. In Name, enter r/SpaceX API.
  4. In Description, enter An API that returns data about SpaceX launches..
  5. For System Logo, upload a system logo image.
  6. In Base URL, enter https://api.spacexdata.com/v3/.
  7. Set the Authentication dropdown to None since this is an unauthenticated API.

  8. 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. In Name, enter SpaceX_getAllLaunches.
  2. In Description, enter The integration that calls in data for the record data source.
  3. Under Save In, click the Browse Folder icon.
  4. From the Pick a Rule Folder dialog, click NEW FOLDER.
    • For Name, enter SpaceX Rules.
    • For Description, enter This folder con expression rules, interfaces, and integrations for the SpaceX Launch applications.
    • Click CREATE.
  5. In Save In, begin typing SpaceX Rules. This will allow you to select the SpaceX Rules folder we just created.
  6. Click OK, then clickNext.

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.

From 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

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 following rules inputs are configured and enabled by checking the checkboxes under Paging and Search.
    • pagingInfo of type PagingInfo
    • searchText of type Text
  2. 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
  3. Click CREATE. Tutorial_XBR_RDS_Objects_List
  4. Click OK. The Choose Record Data Source dialog now opens so that we can finish setting up our data source and data type.
  5. For Record Data Source, select SpaceX_source_getAllLaunches_recordDataSource. Click Search to see this automatically selected.
  6. Click NEXT.
  7. For Data Type, select the SpaceX_Launch CDT that we created earlier.
  8. Click FINISH.
  9. 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. From the application view, select the SpaceX_getAllLaunches integration object. If you don't see your new objects, refresh the page.

  2. In 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. Open the Query Parameters section and 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

  2. Click TEST REQUEST. This allows us to run some tests to ensure the integration is behaving as expected.
  3. 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. From 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'),
  )  
)
  10. Go back to the record type.

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. From the Test Record Source box, select the Record Data Source view.
  2. Click TEST.

  3. 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. From 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. In Connected System, enter r/SpaceX API.
  3. In Name, enter SpaceX_getOneLaunch.
  4. In Description, enter The single record source integration for the SpaceX Launch application..
  5. For Save In, select the SpaceX Rules 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. From 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).
    • Note: 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. From 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).
    • Note: 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.1. 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 User Filters page of the record type, but we still need to configure them.

To edit a User Filter:

  1. From the left pane in the record type, click the User Filters page.
  2. Click the user filter named Launch Year.
  3. From 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}
)
    • From 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. From 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.
    • 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.
  8. Click OK to save all changes and return to the record type.

  9. 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. From the SpaceX Launch application, click the New dropdown and select Interface.
  2. Enter SpaceX_LaunchSummaryView in the Name field. and choose a rule folder to save into.
    • In Description, enter The Summary View interface for the SpaceX Launch application..
    • Select SpaceX Rules as the Save In folder.
  3. Select Create. The interface will pop-up 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 and select the Views page.
  2. In the Record Title 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.
  3. In the Views grid, click Summary to open the Edit View dialog.
  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 and save the record.

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: Wed, Aug 16, 2023 (04:37:39 PM)

On This Page

FEEDBACK