Interfaces

Overview

An interface returns one or more SAIL components to display on a record view, Tempo report, or process form. This is the primary object that designers use to show user interfaces to application users.

Interfaces are defined using expressions, which enable dynamic behavior and reuse of common logic and components across multiple objects throughout the system. They are called and evaluated in the same way as expression rules or query rules.

Each time you modify and save an interface, a new version is created. All objects that use the interface will use the latest version. All versions are accessible to designers who can view the interface, and an interface can be reverted back to a previous version at any time.

For detailed information about how to design SAIL interfaces, including how to enable user interactions, how to save and validate user inputs, and how to submit user inputs to process, see the SAIL Design page.

For functional examples of different design patterns, see the SAIL Recipes page. These examples will help you learn key SAIL concepts and can be used as a starting point for your implementation.

For step-by-step guidance on how to build your first interface, see the SAIL Tutorial.

Properties

Each interface has the following properties.

Property Name Description
Name The name that will be used when executing an interface. Names are case-insensitive and must be unique across interfaces, integrations, expression rules, query rules, constants, and functions. Names cannot be changed after creation.
Description Supplemental information about the interface that is displayed in the inline help within the expression editor and the application contents grid.
Save Into Folder The rule folder that the interface is saved into.
Make Available Offline Makes an interface available for offline mobile. This property is only available if offline mobile is enabled for the environment in the Appian Administration Console.
Interface Inputs Interface inputs are used to pass data in and out of an interface.
  • Name: The name that will be used when referencing the input within the interface definition, such as ri!input, or when passing arguments by keyword. Input names are case insensitive and must be unique within a given interface.
  • Type: Interface inputs can be either a system or custom data type.
  • Array: Interface inputs can be either a single value or an array of values.
Default Test Values A common test scenario that can be used when modifying or testing an interface.
Interface Definition The interface is defined using an expression that returns one or more SAIL components. The definition can be configured using either the design view or expression view located in the left pane of the interface designer.

Create

New interfaces are created from the context of an application. Use the New menu within an application to create a new interface and open it in the interface designer. For instructions on how to create a new interface from an application, see Create an Interface in the SAIL Tutorial.

Interfaces are created and modified using the interface designer, an interactive tool that lets designers create, display, and immediately test interfaces as if they were live in Tempo. See the Interface Designer page for more information.

Default Test Values

Designers have an option to save a set of default test values with the interface. This allows you to save a common test scenario that can be used by any designer who modifies or tests the interface.

Test values may be expressions or literal values. All expression or text values have a 4,000 character limit. Additionally, the designer must have access to all selected users, groups, documents, or folders to save as a test value.

See also: Save Default Test Values

Exporting and Importing Default Test Values

Default test values are always exported with the interface, but can only imported if the destination environment has the Allow Test Values to Be Imported with Design Objects setting enabled. For more about this configuration, see the Deployment section of the Appian Administration Console page.

Calling an Interface From an Expression

Interfaces are called using the rule! domain, just like expression rules or query rules. When calling an interface, values or variables can be passed to the inputs by position or by keyword, as shown below.

rule!newPurchaseRequestForm(
  pr: pv!purchaseRequest,
  items: pv!prItems,
  cancel: pv!cancel
)

Save Interface as Report or Action

The interface designer allows you to save an interface as a report or action and automatically creates the corresponding objects for you. See the Save Interface As section of the interface designer page for more information.

Edit

When you save a new version of an interface, the latest version will be available immediately. This means that record views, reports, and process tasks that use this interface will immediately use the new version. It is therefore important to carefully consider the impact on running processes when changing SAIL form definitions. Appian recommends that you follow these best practices to facilitate the change management of SAIL forms:

  • When calling rules in your SAIL form definition, pass rule inputs by keyword.
  • Take advantage of entity-backed records and design short-lived processes. See the Record Design page for more information.
  • If the version of your SAIL form must remain in sync with the version of your process, create new rules for your SAIL forms.

All versions are accessible to designers who can view the interface, and a interface can be reverted back to a previous version at any time. Previous versions of an interface can be viewed in the Interface Designer.

Move

Users with Administrator permission to an interface or folder can move it to another folder within the root folder.

To move an interface or interfaces folder:

  1. In the /designer interface, open the folder from the Rules tab that contains the interface or folder.
  2. Select the checkbox next to the interface or folder.
  • You can select more than one.

    1. Click the Move button on the toolbar.
  • The Choose Folder dialog box is displayed listing all top-level folders directly beneath the root folder (Rules and Constants).

    1. Locate the target folder and click the Select link.
  • You can also create a new folder if you have Administrator rights to its parent folder and select it.

    1. Click OK to complete the move.

NOTE: Any objects that are configured to inherit the security of the parent folder assume the security rights of the target folder.

Delete

Deleting an interface prevents users from further viewing or editing it. However, the last version of the interface is still available to be used in processes, record views, and reports.

Interfaces can be deleted by users with Administrator rights to it. To delete an interface, go to an application that contains the interface. Select it in the grid and then click the Delete button in the grid toolbar.

Appian does not recommend deleting interfaces that are in use because the interface can no longer be exported.

Security

Interface Object Security

The security rolemap of the interface object itself controls who can see or modify the interface definition and properties.

The following actions can be completed by each role:

Actions Administrator Editor Viewer Deny
Evaluate the interface Yes Yes Yes Yes
View the interface definition Yes Yes Yes No
Update the interface definition Yes Yes No No
Delete the interface Yes Yes No No
View the security in the application designer Yes Yes No No
Update the security Yes No No No

By default, interfaces inherit the security of the folder that they are saved in. To view or modify the security of an interface, go to an application that contains the interface. Select it in the grid and then click the Security button in the grid toolbar. Unchecking the Inherit security from parent box will allow you to add new items to the rolemap or modify existing items.

End User Interface Security

The security of the interface that is viewed by the end user is controlled by the Appian object that uses that interface. For example, to view the interface for a Tempo report, users need to have at least viewer rights to the Tempo report.

For more information on how to secure Appian objects that can display interfaces to end users, see Tempo Report Security, Configuring Security for a Record Type, and Process Model Security.

Data Security

Security for the data displayed on a SAIL interface is based on the security of the underlying data source. Users must have at least view rights to the data to view it within an interface. If a user does not have view rights to part of the data on an interface, the interface may fail to load.

Note: Hiding data through SAIL interface expression configurations does not secure the underlying data. It only determines what does not display on the interface.

For more information on how to configure the security for the underlying data source, see Configuring Data Store Security and Configuring Process Security.

Expression Evaluation Context

In general, the SAIL interface expression runs under the context of the user viewing the interface. In the specific case where a user is viewing a process task that has been accepted by another user, the SAIL interface expression runs under the context of the task owner (the user who accepted the task).

See the User Contexts for Expressions page for more information on what user context is used when evaluating activity class parameters.

FEEDBACK