Interface Object

Overview

Interfaces can be designed visually, by dragging and dropping components, or programmatically, by generating components via expressions. This topic describes the features and functionality available when creating interfaces. If you are familiar with these concepts and want help in building your interface, please refer to the pages in the Build section of the documentation.

interface_designer_panes.png

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 for editing.

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

Start with a Template

When the interface has not yet been defined, a list of template options are available in design mode (shown below). These options give you a starting point from which to build your interface.

interface_designer_templates.png

There are four categories of templates, (1) forms, (2) pages, (3) examples, and (4) builders.

Forms

All forms come with at least a submit and cancel button. The different options represent different arrangements of components and columns.

The Wizard-based templates each contain a functional, multi-page wizard with a confirmation at the end. To modify this for use in your interface, add your own components to the pre-defined pages and add new pages as necessary following the same pattern.

Outlines generate basic expressions for common layouts and use cases. These templates provide structural skeletons to use as a quick starting point that will be enhanced into a richer interface.

Pages

Pages provide only simple arrangements of columns and sections.

Examples

Examples are fully-formed interfaces that demonstrate the richness, density, and dynamism that Appian interfaces can offer. These templates are a great way to get ideas on how to display data and to learn how to apply best practices. However, as these templates generate complete expressions, inputs, and test data, it is not advised to use these templates as a starting point for a new interface.

  • The Request Form example template demonstrates using validations and validation groups, a "form-in-form" pattern to add a new option to a radio button field, and a working editable grid with calculated columns. This template also contains both a Submit and a Cancel button, where the Cancel button saves true into ri!cancel to indicate that the form was not completed.
  • The Sales Dashboard example template showcases dynamic positive and negative styling of KPIs based on set thresholds and takes advantage of grid row selection to filter the Pipeline chart by specific account executives. This template uses randomly generated data that will change during testing. Press the 'Test' button in the header when using this template to try it out for yourself!
  • The Faculty Record example template showcases the ever-expanding capabilities of Appian components to build beautiful, dense interfaces. This template also demonstrates how to leverage Appian's mobile awareness functions to create a tailored experience for users on mobile devices. Check it out for yourself using the mobile device options on the Preview tab when viewing this example template.
  • The Landing Page example template demonstrates how to use linked cards for navigation and boxes to display detailed information specific to the current user. This template showcases a design paradigm commonly used for Sites.
  • The Sales Pipeline example template demonstrates how to use dynamic information cards with filters. This template also demonstrates a common design paradigm for product catalogues.

Builders

Builders allow you to quickly create an interface using existing data in your system.

Report Builder

The report builder is an interactive builder that leverages an existing data source. For information on the Report Builder, see Use the Report Builder.

Create from Data Type

This option will populate an interface with fields corresponding to the definition in a Custom Data Type (CDT). Simply select a CDT and the builder will do the rest.

Once the builder is done (it's really fast), you should see a basic form with CANCEL and SUBMIT buttons, and all fields defined in the CDT as components in the interface. The component type will be a best-match based on the data-type of the corresponding field. For example, a text field will be represented with a Text Component in the interface; a date field will be a Date Time Component, etc.

Your form will also come with 3 rule inputs:

  1. The selected CDT name (of the same type).
    • All fields defined in the CDT are already connected to the pre-populated components.
  2. cancel (Boolean)
    • This rule input is connected to the CANCEL button.
  3. readOnly (Boolean)
    • This rule input is referenced by every component's readOnly parameter. When true, the components will not be editable. This is a common design pattern for reusing the same interface as both the input form and the display form.

Design Guidance

While editing your interfaces you may encounter design guidance. Appian design guidance reinforces best practice design patterns that should be implemented in your objects. Design guidance for interfaces is calculated while editing expressions within the interface or when a precedent of the interface is updated.

When a recommendation or warning is triggered you'll see an indicator icon in the header (A) and next to the corresponding line in the expression editor (B).

Click on the icon in the header to learn more about the suggested guidance (C) and how it can be addressed.

If a recommendation is not applicable to your use case, you can Dismiss (D) that individual recommendation for that interface. Learn more about recommendation dismissal. Warnings cannot be dismissed and should always be addressed to avoid complications when the logic in the object is executed.

Interface guidance is also visible outside of interfaces on the Health Dashboard.

See design guidance for the full list of possible guidance. Note that guidance is only calculated for and displayed on an interface's saved default test values.

Set Interface Properties

To modify the interface properties, go to Properties in the Settings menu, as shown below.

This opens the Interface Properties dialog, where you can modify the description, folder, and make the interface available for offline use. For more information about offline interfaces, see designing interfaces for offline use.

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. Interfaces can be renamed in Appian Designer, see Renaming Design Objects for more information.
Description Supplemental information about the interface that is displayed in the inline help within the expression editor and the application contents grid.
Save In 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. Rule inputs are configured within the interface object.
  • 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: Rule inputs can be either a system or custom data type.
  • Array: Rule 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. Default test values are configured within the interface object.
Interface Definition The interface is defined using an expression that returns one or more interface components. The definition is configured within the interface object, using either design mode or expression mode.

Interface Object Security

Any user can invoke any interface that is used by a process, record view, report, or site page they can access. For example, if a user is a member of a group that has Viewer permissions to a Tempo report, they will, by default, be able to view the report's interfaces.

For more information on how to secure Appian objects that can display interfaces to users, see Tempo Report Security, and Appian Records Security.

The security role map of an interface controls which developers can see or modify it and its properties. By default, interfaces inherit the security of the folder that they are saved in. See Editing Object Security to modify an interface's security.

The following table outlines the actions that can be completed for each permission level in an interface's security role map:

Actions Administrator Editor Viewer Deny
Evaluate the interface Yes Yes Yes Yes
View the interface definition Yes Yes Yes No
Duplicate the interface Yes Yes Yes No
Update the interface definition Yes Yes No No
View the security Yes Yes No No
Rename the interface Yes Yes No No
Delete the interface Yes No No No
Update the security Yes No No No

Data Security

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

Note: Hiding data through 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 of the underlying data source, see Data Store Security and Process Security.

Expression Evaluation Context

In general, the 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 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.

Duplicate

Developers with Viewer permissions to this object can duplicate it. There are two ways to duplicate an object with a designer:

  1. From any view within an application's context, you can select the object you wish to duplicate and use the toolbar option to launch the duplication dialog. The duplicated object will be added to the application you're working in. This capability is only available for single object selections from the grid.
  2. If you are in the designer for an object you want to duplicate then you can select Duplicate from the object's Settings menu. From there, you can specify the target application for the new object.

Once you select the Duplicate option, you will see the following dialog:

NOTE: You can only duplicate the most recent version of an object. If you have unsaved changes and attempt to duplicate the object from within the designer, the most recent saved version of the object will be duplicated without the unsaved changes. A banner appears when there are unsaved changes to remind you before duplicating.

Duplication from within an object is available for interfaces, expression rules, integrations, and decisions. Constants, in addition to the previously mentioned object types, can be duplicated from the toolbar button from anywhere within an application's context.

Versions

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 information on how to manage object versions, see Managing Object Versions.

Editing an Interface

When you save a new version of an interface, the latest version will be available immediately. This means that record views, reports, process tasks and other interfaces that use this interface will immediately use the new version. It is therefore important to carefully consider the impact on running processes when changing interface definitions.

Appian recommends that you follow these best practices to facilitate the change management of interfaces:

  • When calling rules in your interface definition, pass rule inputs by keyword.
  • Take advantage of entity-backed records and design short-lived processes. See the Records Tutorial page for more information.
  • If the version of your interface must remain in sync with the version of your process, create new interfaces rather than a new version, or use conditional logic to invoke the new behavior in the new version of your interface. Either approach will let older process instances continue to use the old behavior of the interface.

Keyboard Shortcuts

Adept designers can leverage several keyboard shortcuts to build interfaces more fluidly. There are general keyboard shortcuts that can be used for overall interface design, as well as keyboard shortcuts that enhance functionality specific to design mode and expression mode respectively.

The following keyboard shortcuts can be used in both design mode and expression mode:

  • Toggle between design mode and expression mode (Ctrl+M for Windows and Mac)
  • Add new rule input (Ctrl+I for Windows, Cmd+I for Mac)
  • Test interface (Ctrl+Enter for Windows, Cmd+Enter for Mac)
  • Undo (Ctrl+Z for Windows, Cmd+Z for Mac)
  • Redo (Ctrl+Shift+Z for Windows, Cmd+Shift+Z for Mac) Note: Undo/Redo in design mode will undo/redo changes to last interface state; in expression mode, this action will only undo/redo changes to text within the interface definition. Therefore, Undo/Redo can only be used to undo/redo changes within the same mode. For example, you cannot undo an action taken in expression mode by using the Undo function in design mode.

The following keyboard shortcuts are for component-level actions in design mode:

  • Duplicate the selected component (Ctrl+D for Windows, Cmd+D for Mac)
  • Delete the selected component (Ctrl+Del for Windows, Cmd+Del for Mac)

The following keyboard shortcuts are available when interacting with the expression editor in an interface:

Action Windows Mac
Close find/replace dialog ESC ESC
Collapse/Expand code block ALT+L COMMAND+OPTION+L
Comment code block CTRL+/ COMMAND+/
Copy CTRL+C COMMAND+C
Create constant CTRL+Click on new constant name COMMAND+Click on new constant name
Create constant dialog ALT+O COMMAND+OPTION+O
Cut CTRL+X COMMAND+X
Delete group before cursor CTRL+Backspace OPTION+Backspace
Decrease indent CTRL+[ COMMAND+[
Delete line CTRL+D COMMAND+D
Format expression CTRL+SHIFT+F CTRL+SHIFT+F
Highlight all occurrences Double click word Double click word
Highlight all text inside Double click parenthesis Double click parenthesis
Increase indent CTRL+] COMMAND+]
Launch the Query Editor ALT+V COMMAND+OPTION+V
Move cursor before group CTRL+Left OPTION+Left
Move cursor after group CTRL+Right OPTION+Right
Move cursor to line start Home COMMAND+Left
Move cursor to line end End COMMAND+Right
Open find dialog CTRL+F COMMAND+F
Open find and replace dialog CTRL+H COMMAND+H
Open object definition CTRL+Click on object name COMMAND+Click on object name
Paste CTRL+V COMMAND+V
Redo CTRL+Y COMMAND+Y, COMMAND+SHIFT+Z
Select all CTRL+A COMMAND+A
Save Selected Expression As… ALT+SHIFT+E COMMAND+SHIFT+E
Select group before cursor CTRL+SHIFT+Left OPTION+SHIFT+Left
Select group after cursor CTRL+SHIFT+Right OPTION+SHIFT+Right
Select previous occurrence SHIFT+ALT+Left CTRL+OPTION+Left
Select next occurrence SHIFT+ALT+Right CTRL+OPTION+Right
Show/Hide indent guide CTRL+G COMMAND+G
Undo CTRL+Z COMMAND+Z
View domains SHIFT+ALT+D COMMAND+SHIFT+D
View functions SHIFT+ALT+F COMMAND+SHIFT+F

Note: For a quick reference of these shortcuts as you are working, hover over the ? icon in the top right of the expression editor.

Save Interface As

If your interface is intended to be used as a report or an application action, you can configure that within the interface using Save as… in the Settings menu.

Some fields in the Save As form may be pre-populated with information based on your interface definition and the application that contains the interface.

Save as Report

You can create a report directly from within the interface object. This automatically creates a report that calls the interface and makes it available from the Reports tab in Tempo.

To save an interface as a report, use the Report option in the Save Interface As dialog.

/interface object save interface as report

After clicking Save, you will be prompted to set security on your new report. The report will automatically be added to the selected application.

Save as Application Action

You can create an application action directly from within the interface object. This automatically creates a process model with a start form that calls the interface, including a process parameter for each input, and creates an action on the selected application, making it available from the Actions tab in Tempo.

To save an interface as an action, use the Application Action option in the Save Interface As dialog.

/interface object save interface as application action

After clicking Save, you will be prompted to set security on your new process model. The process model will automatically be added to the selected application and the application will be published.

Open in Github Built: Tue, May 23, 2023 (06:12:33 PM)

On This Page

FEEDBACK