SAIL Recipes

Each recipe provides a common user-interface design pattern using SAIL.

Some recipes are applicable to record views, reports, and forms, while most are more relevant to forms, like recipes about form validation and collecting user input for submission. As such, the setup and expressions are catered towards forms, but the same concepts apply to record views and reports. We'll show you how to transfer what you learn to record views and reports.

How to Work Through the Recipes

Most of the recipes on this page define their own local variables using the load() function. This means that you can interact with your dynamic form as soon as you paste the expression into the Interface Designer. When you want to adapt a recipe to your own use case, and save the data captured on the SAIL Form into process, you can do the following:

  1. Create an interface input of the right type for each local variable whose value needs to be saved into the process.
  2. In the expression, find the places that use the local variable, and update them to use the interface input instead.
  3. Delete the corresponding local variables from your rule definition and save your interface.
  4. In your process model, enter the name of your interface and select it
  5. Click Yes when the process modeler asks, "Do you want to import the interface inputs?"
    • If you're using a SAIL task form, this will create node inputs (activity class parameters). Make sure to save the node inputs into process variables if you want to use their values elsewhere in the process.
    • If you're using a SAIL start form, this will create process variables and make them parameters.
  6. Save and publish your process model.
  7. Try it out in Tempo. Use a mobile device in offline mode for testing offline versions of a recipe. Follow the steps in Testing Offline Interfaces to test an offline interface.
  8. Always test each change that you make incrementally. In the process details view, go to the variables tab to confirm that the user's values are saved.

If you are testing multiple recipes, you can continue using the same Interface Designer tab. Make sure you click Test after pasting in a new expression to ensure that any local variables used get updated correctly.

To use these recipes, you must have a basic understanding of SAIL concepts, specifically how to enable user interaction and the difference between load() and with().

See also: Enable User Interaction in SAIL, and SAIL Tutorial

The Interface Designer can be used to see most of the recipes in action. When you use the SAIL interface in process, you need to know how to configure a SAIL task form, how to save the user's input into a node input (aka ACP) from a rule, and subsequently save it into a process variable.

The recipes can be worked on in no particular order. However, make sure to read the first two sections to get yourself set up.

Some recipes have an additional offline version with a modified expression for designing an interface for offline use on mobile devices. Offline functionality is only available for actions, not tasks, records, or reports. See Designing for Offline Mobile for more details on this topic.

How to Adapt a Recipe for Use on a Record View or Report

The recipes are catered for use in process forms, but the same concepts generally apply when used on a record view or report. To use the recipe on a record view or report, you can do the following:

  1. Update the expression to use a!dashboardLayout() instead of a!formLayout().
  2. Remove the label parameter and the buttons parameter configurations.
    • There will be no error if you do not remove these configurations, because these parameters will be ignored by a!dashboardLayout(). However, Appian recommends that you remove them to avoid confusion and to keep your expression more maintainable.
    • If you see an error such as "Invalid lexer symbol found", you most likely forgot to remove a comma when you removed the buttons parameter configuration.

Recipes

Validation Add a Custom Required Message

Instead of the product message that shows up when a required field has no value, show a custom message.

Looping Add and Populate Sections Dynamically

Add and populate a dynamic number of sections, one for each item in a CDT array.

Validation Add Custom Validation Rules

Enforce that the user enters no more than a certain number of characters in their text field, e.g. to match the size constraint on a database column.

Grids, Looping Add, Edit, and Remove Data in an Inline Editable Grid

Allow the user to change data directly in a grid with validation and real-time recalculation.

Looping, Document Management Add Multiple File Upload Components Dynamically

Show a dynamic number of file upload components.

Looping Add Multiple Text Components Dynamically

Show a dynamic number of text components to simulate a multi-text input box. A new text box is shown as soon as the user starts typing into the last input box.

Validation Add Multiple Validation Rules to One Component

Enforce that the user enters at least a certain number of characters in their text field, and also enforce that it contains the "@" character.

Hierarchical Data, Group Management Add, Remove, and Move Group Members Browser

Display the membership tree for a given group and provide users with the ability to add, remove, and move user members from a single interface.

Validation, Grids, Looping Add Validations to an Inline Editable Grid

Allow the user to change data directly in a grid, and validate number of rows added and new total.

Reports, Charts, Query Data, Grids Aggregate Data from a Data Store Entity and Conditionally Display in a Chart or Grid

Aggregate data from a data store entity, specifically the total number of employees in each department, to display in a pie chart.

Reports, Charts, Query Data Aggregate Data from a Data Store Entity and Display in a Chart

Aggregate data from a data store entity, specifically the total number of employees in a given department, to display in a pie chart.

Reports, Charts, Query Data Aggregate Data from a Data Store Entity by Multiple Fields and Display in a Chart

Aggregate data from a data store entity by multiple fields, specifically the total number of employees for each title in each department, to display in a stacked column chart.

Reports, Charts, Query Data, Filtering Aggregate Data from a Data Store Entity using a Filter and Display in a Chart

Aggregate data from a data store entity, specifically the total number of employees for each title in the Engineering department, to display in a bar chart.

Validation Approve/Reject Buttons with Conditional Requiredness

Present two buttons to the end user called "Approve" and "Reject" and only make the comments field required if the user clicks "Reject."

Validation Approve/Reject Buttons with Multiple Validation Rules

Present two buttons to the end user called "Approve" and "Reject."

Wizards Build a Wizard in SAIL

Divide a big form into sections presented one step at a time with validation.

Wizards Build a Wizard with Milestone Navigation

Use the milestone component to show steps in a wizard.

Grids, Conditional Display Conditionally Hide a Column in a Grid

Conditionally hide a column in a read-only paging grid when all data for that column is a specific value.

Choice Components Configure a Boolean Checkbox

Configure a checkbox that saves a boolean (true/false) value, and validate that the user selects the checkbox before submitting a form.

Validation Configure a Button that Skips Validation (a Cancel Button)

Display a button that submits the form even if the form contains validation errors such as a blank required field or an invalid text.

Charts, Grids, Query Data Configure a Chart Drilldown to a Grid

Display a pie chart with aggregate data from a data store entity that the user can interact with to display related chart data.

Charts, Grids Configure a Chart to Grid Toggle

Display a column chart with a toggle to display an alternate grid view of the data.

Hierarchical Data Browse Hierarchical Data

Display a hierarchical data browser.

Choice Components Configure a Dropdown Field to Save a CDT

When using a dropdown to select values from the database, or generally from an array of CDT values, configure it to save the entire CDT value rather than just a single field.

Choice Components Configure a Dropdown with an Extra Option for Other

Show a dropdown that has an "Other" option at the end of the list of choices. If the user selects "Other", show a required text field.

Pickers, Records, Filtering Configure a Record Picker that Filters Suggestions

Allow users to choose from a filtered list of records using an autocompleting picker.

Pickers Configure an Array Picker

Allow users to choose from a long text array using an autocompleting picker.

Pickers Configure an Array Picker that Ignores Duplicates

Allow users to choose from a long text array using an autocompleting picker and prevent any choice from being picked multiple times.

Pickers Configure an Array Picker with a Show All Option

Allow users to choose from a long text array using an autocompleting picker, but also allow them to see the entire choice set using a dropdown.

Conditional Display, Choice Components Configure Cascading Dropdowns

Show different dropdown options depending on the user selection.

Formatting Define a Simple Currency Component

Show a text field that allows the user to enter dollar amounts including the dollar symbol and thousand separators, but save the value as a decimal rather than text. Additionally, always show the dollar amount with the dollar symbol.

Grids Delete Rows in a Grid

Delete one or more rows of data in a read-only paging grid.

Grids, Reports, Looping Display a User's Tasks in a Grid With Task Links

Display the tasks for a user in a paging grid and allow them to click on a task to navigate to the task itself.

Images, Document Management Display an Array of Images Stored in Document Management

Display a set of images stored in Appian's document management system.

Grids, Formatting Display Array of Data in a Grid

Display an array of CDT data in a read-only paging grid.

Grids, Filtering, Records Display Data from a Record in a Grid

Display data from a record type in a read-only paging grid.

Grids, Records Display Data with CDT Fields from a Record in a Grid

Display data that contains CDT fields from a record type in a read-only paging grid.

Images, Grids Display Images in a Grid

Display a set of images in a read-only paging grid. The images are stored in Appian's document management system.

Grids, Images, Reports Display Processes by Process Model with Status Icons

Use SAIL to display information about instances of a specific process model.

Hierarchical Data, Grids Expand/Collapse Rows in a Tree Grid

Create a grid that shows hierarchical data and allows users to dynamically expand and collapse rows within the grid.

Formatting, Grids, Records, Looping Filter Data from a Record in a Grid

Display data from a record type in a read-only paging grid and a dropdown to allow the user to filter the data that is displayed.

Grids, Filtering Filter the Data in a Grid

Filter the data in a read-only paging grid using a dropdown. When the user selects a value to filter by, update the grid to show the result.

Charts, Grids, Filtering Filter the Data in a Grid Using a Chart

Display an interactive chart with aggregate data from a data store entity that allows the user to filter results in a grid.

Formatting, Data, Grids Format Data from a Record in a Grid

Format the data from a record type to display in a read-only paging grid, specifically a decimal number as a dollar amount and a username as a user's display name.

Formatting Format the User's Input

Format the user's input as a telephone number in the US and save the formatted value, not the user's input.

Encryption Gather Sensitive Data from a User and Encrypt It

Create a form that gathers sensitive information from a user and store it securely in an Encrypted Text variable.

Validation, Grids Limit the Number of Rows in a Grid That Can Be Selected

If you want to limit how many rows users can select in a read-only paging grid, you can constrain the number of selections by using validation.

Validation Make a Component Required Based on a User Selection

Make a paragraph component conditionally required based on the user selection.

Barcodes Retrieve Data by Scanning a Barcode

Use the barcode component with a barcode scanner to scan an item's barcode and invoke a call to a REST API to retrieve information about the item.

Grids, Smart Services, Filtering, Reports Save a User's Report Filters to a Data Store Entity

Allow a user to save their preferred filter on a report and automatically load it when they revisit the report later.

Grids, Filtering, Reports Searching on Multiple Fields

Display a grid populated based on search criteria specified by end users.

Grids Select Rows in a Grid

Display checkboxes on a read-only paging grid to allow users to select multiple rows of data.

Default Value Set the Default Value Based on a User Input

Set the default value of a variable based on what the user enters in another component.

Default Value Set the Default Value of an Input on a Start Form

Display a default value in some form inputs on a start form, and save the value into the process when submitting.

Default Value Set the Default Value of an Input on a Task Form

Display a default value in some form inputs on a task form, and save the value to process when submitting.

Default Value Set the Default Value of CDT Fields Based on a User Input

Set the value of a CDT field based on a user input.

Formatting, Grids Show Calculated Columns in a Grid

Display and sort on an additional column for total price that is not a field in the CDT, but calculated based on the unit price and quantity fields.

Validation Showing Validation Errors that Aren't Specific to One Component

Alert the user about form problems that aren't specific to one component, showing the message only when the user clicks "Submit".

Grids Track Adds and Deletes in Inline Editable Grid

In an inline editable grid, track the items that are added for further processing in the next process steps.

Records, Smart Services Update an Entity-Backed Record from its Summary View

Enable users to make quick changes to a record by updating it right from a record view

Grids Use Links in a Grid to Show More Details About an Object

Display more of an object's data than can fit in a single row in a read-only paging grid.

Grids Use Links in a Grid to Show More Details and Edit Data

Allow end users to click a link in a read-only paging grid to view the details for the row, and make changes to the data.

Grids, Web Services Use Links in a Grid to Show More Details and Edit Data in External System

Allow end users to click a link in a read-only paging grid to view the details for the row, and make changes to the data.

Grids Use Selection For Bulk Actions in an Inline Editable Grid

Allow the user to edit data inline in a grid one field at a time, or in bulk using selection.

FEEDBACK