This article provides guidance on what interfaces are and how to manage them in your application.
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.
Each interface has the following properties.
|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.|
|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.|
|Rule Inputs||Rule inputs are used to pass data in and out of an interface.
|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.|
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.
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
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.
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 )
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.
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:
All versions of an object are saved and designers can view the definitions of old versions; however, when invoked, it is always the latest version that executes.
Versions of a single object can be accessed by users with Viewer permissions, by doing one of the following:
This option opens the Versions dialog with a list of versions:
If you wish to revert to an older version, open that version by clicking on it and save it. This will create a new version of the object with the definition that is currently loaded in the designer. Modifying a previous version and saving it as the latest version does not affect the old version. To avoid confusion, you should close the tab from which you opened the Versions dialog, since it now contains an old version.
Versions can be deleted by users with Editor permissions and if there are multiple versions. A single version can be deleted by clicking the corresponding red X in the rightmost column of the versions grid.
Bulk deletion can be done by selecting filter criteria that returns multiple versions, which causes a message to appear that prompts you to delete the filtered versions. If the latest version is included in the filtered results, it will not be affected by the bulk deletion. This allows for easier and faster cleanup of object versions, in order to maintain useful versions and prevent version buildup that may affect engine memory.
Users with Administrator permission to this object or rule folder can move it to another folder:
NOTE: Any objects that are configured to inherit the security of the parent folder assume the security rights of the target folder.
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 them. Appian does not recommend deleting interfaces that are in use because the interface can no longer be exported.
To delete an interface:
System Administrators have the ability to delete interfaces (and other objects) in bulk by selecting them and clicking Delete in the toolbar.
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:
|Evaluate the interface||Yes||Yes||Yes||Yes|
|View the interface definition||Yes||Yes||Yes||No|
|Update the interface definition||Yes||Yes||No||No|
|View the security in the application designer||Yes||Yes||No||No|
|Delete the interface||Yes||No||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.
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.
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.
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.