Records Tutorial

Overview

The walk-throughs on this page will help you create your first records. They are split up by source type and increase in complexity as you progress.

Use the data provided to understand how the configurations work. Then, try it with your own data. Keep in mind, the final configurations will need to change if your data has different field names.

The content below assumes a basic familiarity with interfaces and focuses more on the specifics of selecting a data source and modifying the list view and related actions for a record. Consider going through the Record Design page before proceeding.

See also: Expression-Backed Record Tutorial

Create the Appian Tutorial Application

The Appian Tutorial application is used to contain the design objects created while working through this tutorial.

The tutorial application only needs to be created once. If you have already created the tutorial application, skip the steps below.

To create the Appian Tutorial application

  1. Log in to Appian Designer (for example, myappiansite.com/suite/design).
  2. Click New Application.
  3. In the Name field, type Appian Tutorial.
  4. Optionally, in the Description field, add a short description.
  5. Click Create.

The application contents view displays. Right now the application is empty. Each design object that you create during the course of this tutorial will appear in this list and be associated with the tutorial application.

Create Entity-Backed Records

The steps below show how to create a simple entity-backed record type for employee information saved to a data store entity.

Before we begin, let's create the data store entity and its data:

  1. Create a custom data type called Employee with the following fields in the associated data types:
    • id (Integer)
    • firstName (Text)
    • lastName (Text)
    • department (Text)
    • title (Text)
    • phoneNumber (Text)
    • startDate (Date)
      See also: Custom Data Type
  2. Designate the id field as the primary key and set to generate value. Only entities that have a defined primary key (and not an automatically generated one) can be a record source.
  3. Save and publish the CDT.
  4. Create a data store entity Employees that references the Employee CDT and publish its data store.
  5. Insert the following values into the table:
id firstName lastName department title phoneNumber startDate
1 John Smith Engineering Director 555-123-4567 2013-01-02
2 Michael Johnson Finance Analyst 555-987-6543 2012-06-15
3 Mary Reed Engineering Software Engineer 555-456-0123 2001-01-02
4 Angela Cooper Sales Manager 555-123-4567 2005-10-15
5 Elizabeth Ward Sales Sales Associate 555-987-6543 2010-01-02
6 Daniel Lewis HR Manager 555-876-5432 2010-01-02
7 Paul Martin Finance Analyst 555-609-3691 2009-12-01
8 Jessica Peterson Finance Analyst 555-987-6543 2004-11-01
9 Mark Hall Professional Services Director 555-012-3456 2009-06-01
10 Rebecca Wood Engineering Manager 555-210-3456 2008-07-27
11 Pamela Sanders Engineering Software Engineer 555-123-4567 2005-04-01
12 Christopher Morris Professional Services Consultant 555-456-7890 2011-03-29
13 Kevin Stewart Professional Services Manager 555-345-6789 2008-02-29
14 Stephen Edwards Sales Sales Associate 555-765-4321 2006-01-02
15 Janet Coleman Finance Director 555-654-3210 1999-12-30
16 Scott Bailey Engineering Software Engineer 555-678-1235 2005-03-15
17 Andrew Nelson Professional Services Consultant 555-789-4560 2005-03-15
18 Michelle Foster HR Director 555-345-6789 2005-03-15
19 Laura Bryant Sales Sales Associate 555-987-6543 2004-11-01
20 William Ross Engineering Software Engineer 555-123-4567 2008-07-27

Now that we have the data, we can create the record type which will generate a record for each of the rows in our Employees data store entity.

  1. Navigate to the application contents view of the Appian Tutorial application (if needed).
  2. Click New, and then click Record Type.
  3. In the Create Record Type dialog, enter the following information:
    • Name: Employee Directory
    • Plural Name: Employees
    • Description: List of current employees
  4. Click Create & Edit.

After the Employee Directory record type opens in the record type designer, we need to add some more information:

  1. Enter the following values into the Data section:
    • Source: Data Store Entity
    • Data Store: Employees
    • Entity: Employee
  2. In the Record View Details section, enter the following for the Record Title field:
rf!firstName & " " & rf!lastName
  1. In the Views grid, click Summary, then paste the following expression into the Interface field:
={
    a!textField(
      label: "Name",
      labelPosition: "ADJACENT",
      value: rf!firstName & " " & rf!lastName,
      readOnly: true
    ),
    a!textField(
      label: "Department",
      labelPosition: "ADJACENT",
      value: rf!department,
      readOnly: true
    ),
    a!textField(
      label: "Title",
      labelPosition: "ADJACENT",
      value: rf!title,
      readOnly: true
    ),
    a!textField(
      label: "Contact Number",
      labelPosition: "ADJACENT",
      value: rf!phoneNumber,
      readOnly: true
    ),
    a!textField(
      label: "Start Date",
      labelPosition: "ADJACENT",
      value: rf!startDate,
      readOnly: true
    )
}
  1. Click Save in the header of the record type designer.

You have just created a record for each of the employees listed in the Employees data store entity.

To view your records, open Tempo in a new browser, select the Records tab, and click Employees. You should see the following:

To view a record, select a name from the list. For Andrew Nelson you should see the following:

The design of the Summary view is based on the expression we added to the Interface field for the Summary view of the record type. Looking back at the expression, you'll notice we used the rf! domain to access our data. This is required for entity-backed records. Other than that, you can change this record view design as you would any other interface.

You can also configure additional record views for users to view more information on the record.

See also: Create a Record View

Since this record type is not backed by a process model with quick tasks and we have not configured a related action yet, selecting the Related Actions view displays an empty list. Later on, we'll add to this list, but for now, let's focus on providing users with more data.

While working through the sections below, keep Tempo open with your record in one browser and the record type designer interface with your record type open in another. This way, when we make changes to the record type, you can just refresh Tempo to see the changes automatically.

Modify the Record List

Currently, our record list is using the defaults. While this provides us with a lot of information, it's not exactly what we want to see.

Let's start by removing the Id column.

  1. With the Employee Directory record type still open, scroll down to the Record List section.
  2. Click Edit Record List. You should see the following:
  3. Remove the Id column.

You should see the following:

Now let's add a new column to display the employee's title.

  1. Go back to the grid by clicking on Grid, as shown below:
  2. Add a new column using the + Add Column link.
  3. Configure the following properties for the new column:
    • Label: Title
    • Sort Field: title
  4. Select the component for the column by clicking the Select Component link and clicking on Text in the dialog.
  5. Configure the following property for the text component:
    • Display Value: rf!title

It should look like the following:

Finally, let's combine the firstName and lastName columns into a single column.

  1. Go back to the grid and remove the lastName column.
  2. Update the following properties of the firstName column:
    • Label: Name
    • Sort Field: lastName
  3. Expand the link definition using the arrow next to the component parameter, as shown below:
  4. Click on Record Link to view the link configuration and update the following property:
    • Label: rf!firstName & " " & rf!lastName

It should look like the following:

  1. Click OK at the bottom of the dialog and save the record.

For more information on the different options available for configuring a record list, see Create a Record List.

Add A User Filter

Now that we have Employee Directory records, let's add a user filter so users can filter the records by Department.

  1. With the Employee Directory record type still open, scroll down to the User Filters section.
  2. Click + New User Filter below the User Filters grid.
  3. Enter the following values for the associated fields exactly as shown (including quotes where present):
    • Filter Name: Department
    • Filter Field: department
    • Filter Label: "Department"
  4. Click + New Filter Option below the Filter Options grid.
  5. Enter the following values for the associated fields exactly as shown (including quotes where present):
    • Option Label: "Engineering"
    • Operator: =
    • Value: "Engineering"
  6. Click Save Filter Option.
    • This creates the first filter option of Engineering for the Department user filter. Now we need to add filter options for the remaining departments.

  7. Following the same steps, create the remaining filter options:

    Option Label Operator Value
    Finance = Finance
    Human Resources = HR
    Professional Services = Professional Services
    Sales = Sales
  8. Click OK in the Create New User Filter modal dialog.
  9. Click Save in the header of the Record Type Designer.

You have just created a Department user filter with the five departments as options.

Refresh the Employees record in Tempo. You should see the following:

To see the full list of options, click the Department filter dropdown. Users can select any one of these options to filter the records down to just those in the selected department(s).

For more information on how to configure user filters, see Create User Filters.

Remember how the Related Actions view for each record was empty? Now let's add an action to it that allows users to update the phone number for the record they are currently viewing.

  1. Create a query rule called getEmployeeById that takes an integer as a parameter and returns the Employee with that id.
  2. Create a process model called Update Phone Number with a process variable named employeeId of type Number (Integer) marked as a parameter and no start form.
  3. Set up an activity chain from the model's start node into a User Input Activity.
  4. For the User Input activity, assign the task to "=pp!initiator", and create a form titled "Update Phone Number" with one text field called "New Phone Number" that has a default value of rule!getEmployeeById(pv!employeeId).phoneNumber and saves into ac!newPhoneNumber. ac!newPhoneNumber should then be saved into a process variable so that it can be accessed by other nodes later in the process.
  5. Use the Write to Data Store Entity Smart Service to update the data store entity that has an id that matches the employeeId process variable.
  6. Publish the process model.
  7. Navigate to the Employee Record Type and open it.
  8. Scroll down to the Related Actions section, and click + New Related Action.
  9. Add a display name and description
  10. For Process Model, select the process model you configured in step 2. You should see the following:

  11. In the Context field, change the value to:

    {
  employeeId: `rp!id` /* Number (Integer) */
}
  12. Click OK.

The Update Phone Number process model is now a related action for your Employee Directory records where users can update the phone number of the record they're viewing.

Refresh the Employees record in Tempo and select an employee from the list. Click Related Actions. You should see the following:

Click Update Phone Number. You should see the following:

Enter a new number, click Submit, and refresh Daniel Lewis' record. You should see the updated number.

In addition to the Related Actions view, you can configure specific related actions to be available from specific record views. Let's try this by making the Update Phone Number related action available from the Summary view.

  1. In the Views section, click on the Summary view to edit it.
  2. In the Related Actions Shortcut field, check the Update Phone Number related action and click OK
  3. Click Save in the header of the Record Type Designer.

Refresh the Employees record in Tempo and select an employee from the list. From the Summary view, you should see that the Update Phone Number related action is available as a button on the top right.

For more information about configuring related actions, see Add a Related Action.

Export Record List to Excel

Designers can allow record viewers to export record lists to Excel. This setting displays an Export to Excel button on a record list that record viewers can click to download a copy of their filtered record lists in Excel.

To enable this option, check the checkbox next to Show Export to Excel Button in the Record List section of your Record Type object.

Note: This functionality is only available for data store entity backed record lists using a grid list style. The button will be disabled if the filtered record list contains more than 100,000 rows or 50 columns.

Give Users Access to View the Records

Since we didn't add any users or groups to the record type security, only system administrators can view the records in Tempo. By adding groups and giving them Viewer, Auditor, Editor, or Administrator permissions, you can open up the records to other users.

  1. Open the Employee Directory record type in the record type designer.
  2. Open the Settings menu and click on Security.
  3. Click the link to add Users or Groups.
  4. Pick the groups containing the users to whom you want the record to be visible. Set their permission level to Viewer
  5. Click Add and then Save Changes.

All members of the specified groups can now see the Employee record. You can repeat these steps for the other roles.

For more information on security for record types, see Configuring Security for a Record Type.

Create Process-Backed Records

Now that we've created an entity-backed record, let's move on to process-backed records.

Before we start, though, we'll need a process model. For our example, let's use the process model from the Process Model Tutorial. If you haven't already created the Submit Expenses process model, do so now by completing the first five sections of the tutorial, then follow the steps below to create your record type.

  1. Navigate to the application contents view of the Appian Tutorial application (if needed).
  2. Click New, and then click Record Type.
  3. In the Create Record Type dialog, enter the following information:
    • Name: Expense Report
    • Plural Name: Expense Reports
    • Description: List of expense reports
  4. Click Create & Edit.

After the Expense Report record type opens in the record type designer, we need to add some more information:

  1. Enter the following values into the Data section:
    • Source: Process Model
    • Process Model: Submit Expenses
  2. In the Record List section, select Feed in the List Style field.
  3. Click on the Edit Record List link and enter the following:

    • List View Item Template:

       =a!listViewItem(
  title: rf!expenseItem
 )
    • Sort Field: expenseDate
    • Sort Order: Descending
  4. Click OK to close the dialog and save the record list settings.

  5. Click on the Summary view in the Views grid and enter the following into the Interface field:

    ={
    a!textField(
      label: "Requester",
      labelPosition: "ADJACENT",
      value: user(touser(rf!pp.initiator), "firstName") & " " & user(touser(rf!pp.initiator), "lastName"),
      readOnly: true
    ),
    a!textField(
      label: "Amount",
      labelPosition: "ADJACENT",
      value: rf!expenseAmount,
      readOnly: true
    ),
    a!textField(
      label: "Date",
      labelPosition: "ADJACENT",
      value: rf!expenseDate,
      readOnly: true
    )
 }
    • Your form should look like the following:

  6. Click Save in the header of the Record Type Designer.

You have just created a record for each of the processes of the Submit Expenses process model.

If you go the record list view in Tempo, however, you might not see any expense reports listed. This is because you don't have any instances of the process. Let's add one and take a look at the result.

Start an instance of the Submit Expenses process with the following values:

  • Expense Item: Plane ticket to St. Louis
  • Expense Amount: 200
  • Expense Date: 4/16/2013
  • Comments: Flights are expensive.

In Tempo, select the Records tab, and click Expense Reports.

You should see the following:

Select the "Plane ticket to St. Louis" record.

You should see the following:

Just like the entity-backed records, the design of the record view is based on the expression we added to the Interface field of the Summary view of the record type. You'll notice we used the rf! domain again, but this time it was to access process variables of the process model. This is required for process-backed records. Along with the process variables, you can also access certain process and process model properties using the same domain.

Only certain process and process model properties are available for use in interfaces.

For the full list, see also: Record List

Other than that, you can change this record view design as you would any other interface.

Similarity to Entity-backed Records

Notice that both the record list and summary view for process-backed records look the same as for entity-backed records. The same advanced configurations you did in the entity-backed record example are also applicable to process-backed records. The process for implementing these configurations is exactly the same as well. See the sections in the entity-backed records example for the step-by-step process.

The only new concept for process-backed records that we did not cover with entity-backed records is exposing quick tasks as related actions. This is because entities can't have quick tasks; only processes can. However, exposing your processes quick tasks as related actions on the record is easy.

If the process model you used as the source for the record had any quick tasks (the example we used did not), the quick tasks that are available to the user would automatically appear in the list of related actions for those records. You don't have to take any further action to get them to appear in the list. However, you cannot make quick tasks available to end users as related actions from record views. You are also able to configure other related actions following the same example we saw for entity-backed records.

18.3

On This Page

FEEDBACK