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, 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.
|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 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.
Only one designer can edit an interface at any given time. Once you begin editing an interface, other designers are warned when they open or try to update the same interface. You are also warned if you try to edit the same interface in more than one window or browser.
Once warned, designers can open the interface in read-only mode, which allows them to do any action available to a Viewer. They also have the option to edit the interface anyway, although this introduces the risk of losing work. If a designer decides to edit despite the warning, the original editor will be alerted and encouraged to coordinate changes with them.
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:
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:
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|
|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.
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.