Interface Tutorial

Overview

This tutorial will teach you how to build an interface in Appian, working in both design mode and expression mode. Completing this tutorial will enable you to move on to the Process Model Tutorial.

The interface we're creating in this tutorial will be a form that lets users add new employee information to the system. We'll create this form in the Appian Tutorial application and use the Employee record type from the Database-Backed Record Type Tutorial to build out the form.

Create the Appian Tutorial application

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

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

To create the Appian Tutorial application:

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

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

   Property	Description
   Name	Enter Appian Tutorial.
   Prefix	Keep the default prefix, AT, which Appian constructs using the initial characters of each word you entered in the Name parameter. We'll be following the recommended naming standard, and using this short, unique prefix whenever we name an object in this application.
   Description	Leave blank. It's normally a best practice to add descriptions to all design objects. However, to save a little time during this tutorial, we'll skip adding descriptions unless the description displays to the end user.
   Generate groups and folders to secure and organize objects	Keep this checkbox selected, so that Appian will automatically generate standard groups and folders and assign default security groups for this application.

4. Click CREATE.

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

   Tip:  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.

6. Click SAVE.

   

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

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

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

Create the Employee record type

To build the interface, you need to create an Employee record type as described in the Use the Write Records Smart Service Function on an Interface pattern. Complete this pattern before continuing.

Create an interface

Now that we've created your 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 Save In, select the AT Rules & Constants folder that Appian generated.
   • 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.

Change 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 new employees in the system.

To change 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, configure the following:

   Tab	Property	Value
   Content	Title	Create New Employee
   Content	Secondary Text	Enter employee details

   

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

Rearrange the sections

The template we selected contains two sections, but we only need the section with two columns. We'll also add some more columns to lay out the other components of the form.

To reorder the section components:

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.

You should be left with nothing but the form layout and the cancel and submit buttons.

Create the record rule input

Before we add new interface components, let's add the rule input needed to store user-entered data for those components. A rule input is a variable that stores inputs from the interface, so those inputs can be successfully passed to a process model.

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.

   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.

Your finished rule inputs should look like this:

Add components

Now, we'll add components to the interface that let users add 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 new 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.

For each component:

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)
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.

Add a validation

You can configure validations on the form's components to ensure the data users enter doesn't contain preventable mistakes. For example, let's 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.

Congratulations!

You did it! You created a records-powered 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