Interface Object

This page describes the features and functionality available when creating interfaces.

Interfaces can be built in design mode by dragging and dropping components from the palette or in expression mode by generating components via expressions.

If you are familiar with these concepts and want help in building your interface, see the pages in the Build section of this collection.

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.

Elements of interface objects

An interface object contains the following elements:

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

#	Section	Description
1	Palette	The palette contains the primary elements you'll use to create interfaces: components, patterns, and the design library. Learn more about the palette.
2	Live view	The live view is the central panel that displays the interface components.
3	AI, design, and expression modes	These icons allow you to switch between AI mode , design mode , and expression mode . Learn more about editing modes.
4	Preview toggle	Turning on the preview toggle allows you to temporarily hide certain developer capabilities, such as component highlighting and empty component placeholders.
5	Preview menus	This allows you to preview your interface in different ways. There are three types of previews: Branding preview : Allows you to preview the branding configurations from a site or portal object. Device width preview: Allows you to see how your interface appears at different screen widths. Locale preview : Allows you to select an Appian-supported locale to instantly preview how your translation strings and other localized content will appear.
6	Interface controls	This section contains controls to undo and redo changes, view performance details, test, reset, and save the interface, search objects, and access settings menu.
7	Rule inputs pane	The rule inputs pane allows you to define a variable for a specific data type and reference it in your expression.
8	Local variables pane	The local variables pane displays the name and value of the local variables defined in your interface.
9	Component configuration pane	The component configuration pane allows you to configure components and see their nested relationships in your interface.

Editing modes

Interface objects have up to three editing modes, each suited to a different workflow:

• AI mode: If Composer is available in your environment, you can chat with it to build and modify your interface and other design objects using natural language.
• Design mode: Drag, drop, and configure components visually using the palette and component configuration pane.
• Expression mode: Write and edit the interface expression directly in the expression editor.

All three modes affect the same interface expression. Changes you make in one mode are reflected when you switch to another.

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.

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 form 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, it is not advised to use these templates as a base that you edit to create your own interface. These examples are configured to use specific test data, and you would have to spend significant time editing the example template to adapt the expressions and inputs to your business case.

Builders

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

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 choose whether you want the interface to be editable, read-only, or both—then the builder will do the rest. Once the builder is done (it's really fast), Appian displays the generated interface.

All fields defined in the CDT appear 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.

To create an interface based on a CDT:

1. In the Builders section of the templates pane, click Create from Data Type.
2. In the Data Type field, start entering the name of the CDT you want to use, then select the CDT from the dropdown list that displays.
3. Specify what type of action you want users to perform in the interface:
   • Editing Data: Users can edit the CDT data in the interface.
   • Displaying Data: Users can view CDT data in the interface.
   • Both: Users can either view or edit CDT data in the interface, based on whether or not the interface is in read-only mode.
4. Click Generate. Appian displays the generated interface.

This generated interface contains the following components:

Component	Editing Data	Displaying Data	Both
Layout	Form	Columns	Form
Title	The CDT name with prefix and underscores removed.	none	The CDT name with prefix and underscores removed.
Inputs	An editable input component for each field in the selected CDT.	A read-only input component for each field in the selected CDT.	An input component for each field in the selected CDT. These input components are configured to be editable or read-only based on the readOnly rule input.
Buttons	Cancel and Submit	none	Cancel and Submit
Rule Inputs	selected CDT and cancel	selected CDT	selected CDT, cancel, and readOnly

These rule inputs and interface components are connected as follows:

• selected CDT (CDT): All fields defined in the CDT are already connected to the pre-populated components, including the Submit button.
• cancel (Boolean): This rule input is connected to the Cancel button.
• readOnly (Boolean): This rule input is referenced by every component's Read Only 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. See Reusing Interfaces for more information.

Add components

Once you've defined your interface with a layout, add components to build out your interface functionality.

For a list of components, see the Interface Components page. For more information about using the palette to drag and drop components, see Add components to a layout.

Define rule inputs and local variables

Rule inputs and local variables help you manage data flow in your interface:

• Rule inputs: Define the data that gets passed into your interface from external sources.
• Local variables: Store and manipulate data within the interface itself.

Together, they provide the foundation for creating dynamic, data-driven interfaces.

Rule inputs

Rule Inputs allow you to define a variable for a specific data type and reference it in the interface. For more information on testing your interface with different values, see Testing interfaces.

Create rule inputs

To create a rule input:

1. In the Rule Inputs pane, click New Rule Input .

2. In the New Rule Inpute dialog, configure the following properties:

   Property	Action
   Name	Enter a name that will be used to reference the rule input using the ri! domain prefix. Rule input names aren't case sensitive and must be unique in the interface.
   Description	(Optional) Enter a description for the rule input.
   Type	Choose a data type. This can be either a custom data type or a primitive system data type of text, integer, decimal, date and time, date, or boolean.
   Array	(Optional) If the rule input value can be a list, select this checkbox.

3. Click CREATE or CREATE AND ADD ANOTHER.

Edit rule input names

As naming conventions and requirements evolve, you may need to update the names of your inputs to certain objects. Over time, rules and interfaces can gather many dependents. This can make manual changes to update any keyword references to rules and interfaces difficult and prone to human error.

If you update the name of an input while editing an expression rule or interface, Appian will update any keyword references to that rule input in dependent objects.

There are certain cases when Appian cannot update the dependent object(s):

1. The design object is locked.
2. The design object is not an expression rule or interface.
3. The design object does not use keyword syntax.
4. There are more than 20 direct dependents.

If there is a blue banner in the rule inputs pane, Appian is going to attempt an automatic update of the keyword references.

After you save your changes, a dialog will appear with a summary of what dependent objects were updated and any that you may need to update manually.

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

If you accidentally exit the rename dialog before you've completed all manual updates, use design guidance to find the remaining objects to update. Any object using the wrong keyword reference will be flagged with the invalid keyword syntax design guidance on the health dashboard.

All objects that are updated automatically as a result of the rename will show the developer who renamed the input as the last modifier for the dependent objects.

Setting rule input values

When you add a rule input to an interface, its value is null or empty. You can set rule input values in four ways:

• Interact with components: In the live view, interact with a component that saves into the rule input.
• Edit directly: Click the value in the Rule Inputs pane to edit it directly.
• Test scenarios: Create and switch between named sets of rule input values.
• Configure temporary test values: Click TEST to quickly test values without having to create a test scenario.

Local variables

You may need to define a specific type of variable that is only available within a particular expression and function. Local variables allow you to define and store data for this specific use case. To avoid confusion, we recommend giving each local variable in your interface a unique name. See Defining Local Variables for examples.

The Local Variables grid displays local variables defined in your interface, except for any local variables defined in looping functions like a!forEach(). The Local Variables grid appears between the Rule Input pane and the Component Configuration pane. This grid displays both the name and the value of each local variable. In design mode, you can click + in the grid header to create a new local variable.

By default, all local variables are flattened in a list and ordered according to their definition in the expression rule. Similar to rule inputs, a local variable defined as a list, dictionary, or CDT is initially collapsed in the grid. You can click next to the variable name to expand the local variable and view the values.

Click the link in the Name column to rename a local variable, which also updates any references to that variable. Click the link in the Value column to open a dialog with more details, including the local variable name, the line number of the variable definition, the variable type, and the full variable value.

Preview your interface

Previewing your interface is a vital part of the creation and testing process in application development. The following preview options allow you to view your interfaces as close as possible to how your users will view them.

Typeface

Interface objects use the default typeface configured in the Admin Console.

If CSS profiles are available in your environment, the interface object uses the typeface configured in the site or portal selected in the branding preview.

Preview toggle

In the interface header, you can turn on the Preview toggle to temporarily hide certain developer capabilities, such as component highlighting and empty component placeholders.

The table below summarizes the key differences when the preview toggle is on or off.

Feature	Preview off (Design mode)	Preview off (Expression mode)	Preview on (Both modes)
Component highlighting and selection	Visible, allowing you to click a component to configure it in the component configuration pane.	Visible, allowing you to click a component to navigate to the first line of the component in the expression.	Hidden
Palette	Visible, allowing you to drag and drop components, patterns, and design library interfaces onto the interface.	Hidden	Hidden
Empty component placeholders	Visible, allowing you to view drop targets and quickly add things for certain components like columns.	Hidden	Hidden

Branding preview

The following branding configurations can only be configured in a site or portal object:

• The shape of inputs, which includes input, selection, and picker components, as well as tooltips.
• The shape of dialogs and buttons.
• The accent color, which is used anytime "ACCENT" is selected for a color or style parameter.
• Whether or not buttons use uppercase capitalization.

The branding preview allows you to see what your interface will look like with these branding configurations applied. Simply go to Branding preview and select a site or portal. The site or portal you last selected will be used by default whenever you open an interface object.

You will probably want to view the branding for the site or portal that uses the interface object. This is easy to find from the interface object by going to Settings > Dependents to view all objects that depend on the interface.

When no site or portal is selected, the default branding is applied, which uses the following values:

• Input shape: Squared
• Dialog shape: Squared
• Button shape: Squared
• Use uppercase capitalization for button labels: Turned on
• Accent color: #2322F0
  • Note that this is a different accent color than the default used for sites, which use #1d659c.

Device width preview

Selecting one of the device width preview options allows you to test your interface's responsiveness and see how your design appears at different screen widths.

You can select from the following device widths:

• Fit
• Wide Desktop
• Desktop
• Narrow Desktop
• Tablet (Portrait)
• Tablet (Landscape)
• Phone (Portrait)
• Phone (Landscape)

Keep in mind that even when you select a tablet or phone width, the preview may display your interface differently than it will appear in the Appian Mobile app. If you expect your users to access the interface in Appian Mobile, test it directly in the app.

Locale preview

Selecting a locale from the Locale preview allows you to preview how your interface is translated or localized into different Appian supported locales. You can use the localization preview to see how your translation strings and any localization functions, such as a!currency and date time functions, appear in the selected locale.

To learn more about testing translation strings, see Testing translation strings in an interface.

Testing interfaces

You can test an interface by setting values for its rule inputs. For a quick test where you don't need to keep the values, configure test values. To reuse the same values later, save them as test scenarios.

What are test scenarios?

Test scenarios are named sets of rule input values that you save and reuse when testing an interface. Each scenario defines specific values for rule inputs, so you can quickly switch between different testing conditions. You can create multiple scenarios to represent different use cases and mark one as the default to load automatically when you open or reset the interface.

Why should I use test scenarios?

Test scenarios offer the following benefits:

• Edge cases: Save values that are tedious to enter and reuse them each time you test.
• Multiple use cases: Ensure your interface works correctly across different testing conditions.
• Collaboration: Share common test values with other developers working on the same interface.

Configure test values

The TEST button in the interface header lets you configure test values and optionally save them as a test scenario.

To configure test values:

1. In the interface header, click TEST.
2. In the Configure Test Values dialog, enter values for your rule inputs:
   • Type values directly in the Value column. Use the dropdown list next to the value field to select different options for entering a value.
   • Click LOAD CURRENT VALUES to load values you've already entered in the interface.
   • If you have one or more test scenarios created, select one from the Load a saved scenario list.
3. To apply the values without saving them, click TEST. To keep the values, save them as a new or existing test scenario.

Create a test scenario

You can create a test scenario when configuring test values, or when managing your scenarios.

To create a test scenario when configuring test values:

1. Configure the test values you want to save.
2. In the Configure Test Values dialog, click SAVE AS.
3. In the Save as Test Scenario dialog, select Create new.
4. Enter a Name.
5. (Optional) Enter a Description.
6. (Optional) Select Set as default to load this scenario automatically when the interface opens or resets.
7. Click CREATE AND TEST to close the dialog and load the scenario.
8. In the interface header, click SAVE to save the scenario and the interface.

To create a test scenario when managing scenarios:

1. In the interface header, click the dropdown arrow next to the TEST button and click MANAGE TEST SCENARIOS.
2. In the Manage Test Scenarios dialog, click CREATE.
3. Enter a Name.
4. (Optional) Enter a Description.

5. (Optional) Select Set as default to make this the default scenario that loads when the interface opens or resets. The first scenario you create will automatically be the default.

   Tip:  When upgrading from Appian 25.4 or below to Appian 26.1 or higher, the saved default test values in interfaces will be saved as a test scenario named "Initial Scenario".

6. In the Value column, configure rule input values for the scenario. Use the dropdown list next to the value field to select different options for entering the value.
7. Click CREATE or CREATE AND TEST.
   • CREATE returns to the list of saved scenarios.
   • CREATE AND TEST closes the dialog and loads the scenario.
8. In the interface header, click SAVE to save the scenario and the interface.

Update a test scenario

You can update a test scenario when configuring test values, or when managing your scenarios.

To update a test scenario when configuring test values:

1. Configure the test values you want to save.
2. In the Configure Test Values dialog, click SAVE AS.
3. In the Save as Test Scenario dialog, select Update existing.
4. From the Existing Scenario dropdown, select the scenario to update.
5. Click UPDATE AND TEST to load the scenario.
6. In the interface header, click SAVE to save the scenario and the interface.

To update a test scenario when managing scenarios:

1. In the interface header, click the dropdown arrow next to the TEST button and click MANAGE TEST SCENARIOS.
2. Click the name of the scenario you want to update.
3. Make your changes and click UPDATE or UPDATE AND TEST.
   • UPDATE returns to the list of saved scenarios.
   • UPDATE AND TEST closes the dialog and loads the scenario.
4. In the interface header, click SAVE to save the scenario and the interface.

Load test scenario values

Test scenarios let you quickly load different sets of rule input values into the interface.

To load the interface using values from a test scenario:

1. In the interface header, click the dropdown arrow next to the TEST button.
2. Select a scenario from the list.

The interface loads with the rule input values from the selected scenario. In the test scenario list, a Last scenario loaded indicator displays next to the most recently loaded scenario.

Run test scenarios

You can run one or more test scenarios to view load times for each scenario and check if any of them cause an error. The load time is the amount of time it takes the interface expression to evaluate, in milliseconds.

To run test scenarios:

1. In the interface header, click the dropdown arrow next to the TEST button and click MANAGE TEST SCENARIOS.
2. Do one of the following:
   • Click RUN ALL to run all test scenarios.
   • Select the checkboxes next to specific scenarios, then click RUN SELECTED to run only those scenarios.
3. Review the results in the Load Time (ms) column:
   • A numeric value indicates the interface loaded successfully and shows the load time in milliseconds.
   • An error icon indicates the scenario caused an expression or syntax error.
4. (Optional) Click the column header to sort scenarios by load time.

Duplicate, set as default, or delete a test scenario

To duplicate a scenario, set it as the default, or delete it:

1. In the interface header, click the dropdown arrow next to the TEST button and click MANAGE TEST SCENARIOS.
2. Select the checkbox next to one or more scenarios.
3. Choose to duplicate, set as default, or delete the selected scenarios.
4. In the interface header, click SAVE to save your changes to the scenarios and the interface.

Exporting and importing test scenarios

Test scenarios are always exported with the interface, but will only be 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 Admin Console page.

Resetting the interface

As you build and test an interface, interacting with components changes the state of your local variables, rule inputs, and components. Resetting returns the interface to a clean starting state so you can test again from the beginning.

In the interface header, click the reset button to reset the interface to its default state. This will:

• Reset local variables to their initial value.
• Reset rule inputs to their default test scenario or to null if there is no default scenario.
• Reset components to their default state, such as expanding or collapsing section layouts.

Managing an interface object

Create an interface object

To create an interface object:

1. In your application, go to the Build view.
2. Click NEW > Interface.

3. In the Create Interface dialog, configure the following properties:

   Property	Description
   Name	The name that will be used when executing an interface. Names are case-insensitive, but we recommend following the recommended naming standard. Interfaces can be renamed in the Objects view, Build view, and the interface object; see Renaming Design Objects for more information.
   Description	Supplemental information about the interface that is displayed in the expression editor and the objects grid of some Designer views.
   Save In	The rule folder that the interface is saved into.
   Tags	The tags applied to the object. If the tag you need doesn't exist yet, click Create New Tag to create a new tag without leaving the dialog.
   Include in the design library	Makes an interface available in the Design Library tab of the design mode palette for easy access.
   Display Name	The name that displays for an interface you included in the Design Library tab of the design mode palette.

4. Click CREATE.
5. Review the security and update as needed, then click SAVE.

Duplicate an interface

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

• From any view in an application, 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.
• If you are in an interface, expression rule, integration or decision object, 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:

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.

Edit the interface properties

To edit the interface object properties:

1. In the Build view, click the name of the interface object. The object will open in a new tab.
2. In the settings menu, click Properties.

3. In the Interface Properties dialog, configure the following properties:

   Property	Description
   Name	The name that will be used when executing an interface. Names are case-insensitive, but we recommend following the recommended naming standard. Interfaces can be renamed in the Objects view, Build view, and the interface object; see Renaming Design Objects for more information.
   Description	Supplemental information about the interface that is displayed in the expression editor and the objects grid of some Designer views.
   Save In	The rule folder that the interface is saved into.
   Make Available Offline	Makes an interface available for offline use in the Appian Mobile or Appian for Windows app. Only applicable if offline access is enabled for the environment in the Admin Console. Only enable if you have users who need to use the interface offline. In the mobile or Windows app, offline-enabled forms function as if they aren't connected to the server, even when online. This may affect your interface design and functionality, so fully test offline interfaces in the mobile or Windows app. To learn about offline experiences and how they impact interface design, see About Offline Experiences and Design Interfaces for Offline Use.
   Include in the design library	Makes an interface available in the Design Library tab of the design mode palette for easy access.
   Display Name	The name that displays for an interface you included in the Design Library tab of the design mode palette.

4. Click OK.

Managing interface changes

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

Appian recommends the following best practices to help you manage changes to interfaces:

• When calling rules in your interface definition, pass rule inputs by keyword.
• Take advantage of database-backed records and design short-lived processes. See the Database-Backed Record Type Tutorial page for more information.
• If you need the version of your interface to remain in sync with the version of your process, create new interfaces instead of new versions. If you need to create a new version of the interface, create conditional logic to execute the new behavior in the new version. Either approach will let older process instances continue to use the old interface behavior.

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 developers that can view the interface can edit it, and interfaces can be reverted to a previous version at any time.

For information on how to manage object versions, see Managing Object Versions.

Design guidance

While editing your interfaces, you may encounter design guidance. Appian design guidance reinforces best practice design patterns that you should use in your objects. You'll see design guidance for interfaces while editing expressions within the interface or when updating an interface precedent.

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 to address it.

If a recommendation isn't relevant, you can Dismiss (D) the recommendation. 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.

You can also find interface guidance on the Health Dashboard.

See design guidance for the full list of possible guidance.

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

Save an interface as a Tempo report or application action

If your interface is intended to be used as a Tempo report or an application action, you can configure that within the interface by going to Settings > Save as….

Save as Tempo report

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

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

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

Save as application action

You can create an application action directly from within the interface object. When you do, Appian automatically creates a process model with a start form that calls the interface. The start form includes a process parameter for each input. Then, Appian 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.

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.

Security

Interface object 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.

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.

Feedback