Interface Tutorial

This tutorial will teach you how to build an interface in Appian, working in both design mode and expression mode.

The interface we're creating in this tutorial will be a form that lets users add or update employee information. Completing this tutorial will enable you to move on to the Process Model Tutorial.

Tutorial prerequisites

To complete this tutorial, you need:

• Appian Tutorial application. Complete the Application Building Tutorial to store the interface used in this tutorial.
• AT Employee record type: Complete the Create the AT Employee record type section of the Record Type Tutorial, including the Generate a database table subsection.
• Designer group membership. You must be a member of the Designer system group. If you're unsure about your group membership, contact your system administrator.

Create the interface

Now that we've created the application and record type, let's get started on the interface.

We're going to create an interface named AT_employeeForm. This interface will show a form for users to input values about new employees.

Create an interface object

To create an interface object:

1. In the Build view, click NEW > Interface.
2. In the Create Interface dialog, configure the following properties:
   • Leave Create from Scratch selected.
   • For Name, enter AT_employeeForm.
   • For Description, enter Form interface for creating or updating employees.
   • For Save In, select the AT Rules & Constants folder that Appian generated.
   • Leave Tags blank.
   • Leave Include in the design library unselected.
3. Click CREATE.

The newly created interface will open in a new tab by default. If you don't see a new tab, make sure you have pop-ups enabled for your browser.

By default, the new interface is in design mode. That's where we want to be for now.

Select a template

Next, let's select an interface template, so we can take advantage of functionality already configured in the template.

In the Select a template panel, under FORMS, click Form with Full header.

The template you selected opens in the live view.

Remove a section

The template we selected contains two sections, but we only need the section with two columns.

To remove a section component:

1. Click the first Section Layout to select it.

2. From the context menu next to Section Layout, click Delete.

   

3. Click the remaining Section Layout to select it.
4. In the Component Configuration pane, delete the default value, Section, from the Label property.

The interface should look like this:

Create rule inputs

Next, we'll create rule inputs. A rule input is a variable that stores inputs from the interface, so those inputs can be successfully passed to a process model.

By default, the form includes a rule input for cancel. We need to create two more rule inputs:

• employee to store the user-entered data in each component.
• isUpdate to indicate if the form is for creating or updating an employee.

To create the rule inputs:

1. In the Rule Inputs pane on the right, click New Rule Input.
2. For Name, enter employee.

3. For Description, keep the blank default.

   Tip:  Adding supplemental information in this field can be useful to guide future development, but for the purposes of this tutorial, we'll keep it blank.

4. For Type, select the AT Employee record type.
5. Leave the Array checkbox unselected. The form only allows users to submit a single employee, so there is no need for the rule input to accept multiple records.
6. Click CREATE AND ADD ANOTHER.
7. For Name, enter isUpdate.
8. For Description, keep the blank default.
9. For Type, select Boolean.
10. Leave the Array checkbox unselected.
11. Click CREATE.

Your finished rule inputs should look like this:

Configure the form title

Now, let's change the form title so that users viewing the published interface know they're in the right place to create a new employee or update an existing employee.

We'll configure the form title to be dynamic so it changes depending on the isUpdate rule input.

To configure the form title:

1. Click on the title Form to select the Full Header Template component. This action opens the Component Configuration pane, which allows you to configure the parameters for the component.
2. In the Component Configuration pane, hover next to Title to click Edit as Expression.

3. In the Title (Text) dialog, copy and paste the following expression.

   This expression uses the rule input isUpdate to determine which text to display as the form title.

   1
   2
   3
   4
   5
    if(
    ri!isUpdate,
    "Update Employee",
    "Create New Employee"
   )
   

4. Click OK. By default, the form title displays as "Create New Employee".
5. Hover next to Secondary Text to click Edit as Expression.

6. In the Secondary Text (Text) dialog, copy and paste the following expression.

   This expression uses the rule input isUpdate to determine which text to display as the secondary text.

   1
   2
   3
   4
   5
    if(
    ri!isUpdate,
    "Update employee details",
    "Enter employee details"
    )
   

7. Click OK. By default, the secondary text displays as "Enter employee details".

Add components

Now, we'll add components to the interface that let users add or update employee data. These components are available in the Palette panel.

To add components to the interface:

1. Drag the following components into the left column, in the following order:
   • TEXT component.
   • DROPDOWN component.
   • TEXT component.
2. Drag the following components into the right column, in the following order:
   • TEXT component.
   • TEXT component.
   • DATE component.

Your interface should look like this:

Configure the components

Next, we'll configure the components so that the form inputs connect to the rule inputs. We'll also specify whether a specific form input is required to submit the form.

By default, the CANCEL button is configured to use the cancel rule input.

To configure the remaining components:

1. Click the component to select it.
2. In the Component Configuration pane, configure the specified parameters:
   • Text (top left)
   • Dropdown (middle left)
   • Text (bottom left)
   • Text (top right)
   • Text (middle right)
   • Date (bottom right)
   • Submit Button (bottom right)
3. Click SAVE.

Once you've configured these parameters, your interface should look like this:

Text (top left)

Configure the following parameters:

Tab	Property	Action
Content	Label	Enter First Name.
Data	Display Value	Select ri!employee > firstName.
Data	Save Input To	Automatically populates with the value selected for Display Value. If not, update it to match.
Behavior	Required	Turn on this toggle.

Dropdown (middle left)

Configure the following parameters:

Tab	Property	Action
Content	Label	Enter Department.
Data	Data Source	Select Record Type, then search for and select the AT Employee record type.
Data	Selected Value	Select ri!employee > departmentId.
Data	Save Selection To	Automatically populates with the value selected for Selected Value. If not, update it to match.
Data	Choice Labels	Remove the default selection. An error appears. Select department > value and the error will disappear.
Data	Choice Values	Remove the default selection. An error appears. Select department > id. The error disappears.

Now, the department names from the AT Department record type will display as the selectable values in the dropdown list.

Because of the relationship between AT Employee and AT Department, the user selects the department name (for example, "Engineering"), but the app saves the selected value as the ID to which the selected value maps. This follows data modeling best practices.

You can test the configuration of this component by clicking the dropdown and selecting a department. If the component is configured correctly, you should see the following list of department names and be able to select a department without an error.

Text (bottom left)

Configure the following parameters:

Tab	Property	Action
Content	Label	Enter Phone Number.
Data	Display Value	Select ri!employee > phoneNumber.
Data	Save Input To	Automatically populates with the value selected for Display Value. If not, update it to match.

Text (top right)

Configure the following parameters:

Tab	Property	Action
Content	Label	Enter Last Name.
Data	Display Value	Select ri!employee > lastName.
Data	Save Input To	Automatically populates with the value selected for Display Value. If not, update it to match.
Behavior	Required	Turn on this toggle.

Text (middle right)

Configure the following parameters:

Tab	Property	Action
Content	Label	Enter Title.
Data	Display Value	Select ri!employee > title.
Data	Save Input To	Automatically populates with the value selected for Display Value. If not, update it to match.

Date (bottom right)

Configure the following parameters:

Tab	Property	Action
Content	Label	Enter Start Date.
Data	Display Value	Select ri!employee > startDate.
Data	Save Input To	Automatically populates with the value selected for Display Value. If not, update it to match.
Behavior	Required	Turn on this toggle.

Submit button (bottom right)

Configure the following parameters:

Tab	Property	Action
Content	Label	Hover and click Edit as Expression. Then, copy and paste the following expression to dynamically change the button label: if(ri!isUpdate, "Save", "Create"). Click OK.

Add a validation

Next, we'll add a custom validation to our form so users are limited to a maximum of 15 characters in the Phone Number field.

To add a custom validation:

1. Select the Phone Number text component.
2. In the Component Configuration pane, go to the Behavior tab.
3. Hover over the Validations property, then click Edit as Expression.

4. Copy and paste the following expression in the Validations (List of Text String) expression box:

   1
   2
   3
   4
   5
   if(
    len(tostring(ri!employee[recordType!AT Employee.fields.phoneNumber]))<=15,
    null,
    "Enter a phone number with 15 digits or fewer"
    )
   

5. In the expression, change the record type reference to use the record type reference in your environment.
6. Click OK to close the expression box.
7. To test the validation:
   • For Phone Number, enter 1234567890123456.
   • Click outside the text field. You should see the validation message.
   • For Phone Number, delete the 6 at the end of the string. The validation message should no longer appear.

   

8. Click SAVE.

Create test scenarios

Finally, we'll create test scenarios to display sample data in our interface. Since this interface is for creating and updating employees, we'll create two different test scenarios.

To create the test scenarios:

1. In the interface header, click the dropdown arrow next to the TEST button and click MANAGE TEST SCENARIOS.
2. In the Manage Test Scenarios dialog, click CREATE.
3. Configure the following test scenario:
   • For Name, enter Create action.
   • For Description, enter Tests the user flow of creating a new employee.
   • For the isUpdate (Boolean) rule input, select False.
   • Leave all other rule inputs as null.
4. Click CREATE to create the test scenario.
5. In the Manage Test Scenarios dialog, click CREATE.
6. Configure the following test scenario:
   • For Name, enter Update action.
   • For Description, enter Tests the user flow of updating an existing employee.
   • For the employee (AT Employee) rule input, enter the following expression. Replace any record type references with references to record types in your environment.

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
    a!queryRecordByIdentifier(
     recordType: recordType!AT Employee,
     identifier: 1,
     fields: {
      recordType!AT Employee.fields.id,
      recordType!AT Employee.fields.firstName,
      recordType!AT Employee.fields.lastName,
      recordType!AT Employee.fields.departmentId,
      recordType!AT Employee.fields.phoneNumber,
      recordType!AT Employee.fields.title,
      recordType!AT Employee.fields.startDate
     }
    )
   

   • For the isUpdate (Boolean) rule input, select True.
   • Leave the cancel (Boolean) rule input as null.
7. Click CREATE AND TEST. Since you loaded the "Update action" test scenario, the form displays data for the employee with an identifier of 1.
8. Switch between test scenarios to see how the form changes:
   1. In the interface header, click the dropdown arrow next to the TEST button.
   2. Select Create action to load the rule input values from that test scenario.
9. Click SAVE.

Success!

You did it! You created an interface to meet a business use case. You're ready to move on to other tutorials.

• To connect your interface to a process model that saves new employee data, check out the Process Modeling Tutorial.

See also: Interface Recipes to create different interfaces with specific layouts and dynamic behavior.

Feedback