Expression Rules


An expression rule is a stored expression that can be called from other expressions. Like Appian functions, expression rules always return a value that may be influenced by one or more inputs. Expression rules differ in that their return value is dictated by an expression.

Expression rules can be called from any expression, so they can be reused across multiple objects throughout the system.

See also: Expressions

Each time you modify and save an expression rule, a new version is created. All expressions that use the rule use the latest version. All versions are accessible to designers who can view the rule, and a rule can be reverted back to a previous version at any time.


Each expression rule has the following properties:

Property Name Description
Name The name that is used when executing the rule. 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 rule that is displayed in the inline help within the expression editor and the application contents grid.
Save In The folder that the rule is saved into.
Rule Inputs Rule inputs are used to pass data into the expression rule.
  • Name: The name that is used when referencing the input within the rule definition, such as ri!input, or when passing arguments by keyword. Input names are case insensitive and must be unique within a given rule.
  • Type: The type of the rule input.
  • Array: Rule inputs can be either a single value or an array of values.
Test Cases A set of test scenarios used to evaluate the expression rule.
Rule Definition The expression that is evaluated when the rule is called.


Create new expression rules from the context of an application. Use the New menu within an application to create a new expression rule and open it in the expression rule designer. Opening a rule navigates you to the expression rule designer with the rule's properties populated so you can configure and test the rule:

Reserved Names

The following names are reserved for process report metrics, and must not be used.

  • Completion
  • is_process_ontime
  • is_process_overdue
  • is_task_favorite
  • is_task_ontime
  • is_task_overdue
  • Lag
  • NetCompletion
  • NetLag
  • NetWork
  • process_completion_time
  • process_deadline
  • process_ee_id
  • process_start_time
  • process_status
  • pm_avg_completion
  • pm_avg_lag
  • pm_avg_work
  • task_assignee_owner
  • task_assignment_time
  • task_attributed_to
  • task_avg_completion
  • task_avg_lag
  • task_avg_work
  • task_completion_time
  • task_deadline
  • task_ee_id
  • task_status
  • total_completion_time
  • total_lag_time
  • total_work_time
  • Work

Set Rule Properties

To modify the rule properties, click on the name of the rule displayed in the top left corner, as shown below. This opens the Rule Properties dialog, where you can modify the description and folder.


Add Rule Inputs

To create a rule input:

  1. Click the + button in the top right-hand corner of the expression rule designer window.
  2. Configure the name, type, and whether or not it is an array from the grid, as shown below. You can also change the order of rule inputs using the up and down arrows.

Define the Rule

Enter the rule definition in the expression editor in the left-hand side of the expression rule designer. For more information on how to use the expression editor, see the Expression Editor section of the Expressions page.


Testing your expression rule allows you to see what the expression rule outputs based on a given set of inputs. There are two ways to test your expression rule in the expression rule designer: ad hoc testing and test cases.

Ad Hoc Test

When you open the expression rule designer, the middle pane opens to the Ad Hoc Test view. Use the Ad Hoc Test view to quickly test your expression rule while developing it. When you have defined an expression for the rule definition, a Test Rule button is displayed in the middle pane. Clicking the button evaluates the expression and displays the execution time, type, and value of the result.

If you have one or more rule inputs, you can enter values for each input in the Test Inputs grid. These values are used when testing the expression. As you enter an expression for an input, the Value column displays the evaluated result that is used when testing the expression. For many types, you can simply enter a value directly in the Value column.

To save a set of test values as a test case from the Ad Hoc Test view:

  1. Enter values in the Test Inputs grid.
  2. Click the Save as Test Case link below the grid to open the Create Test Case dialog.
  3. Set the test case's name and update any of the test values before adding the test case. Click Save.

Once test cases are added they are saved along with the rule on the next save of the rule.

Test Cases

Test cases can be created and saved with an expression rule. This allows you to run test scenarios in bulk and review the results for all the tests together.

Test values may be expressions or literal values. All expression or literal 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 case.

Each test case has an assertion that determines whether a test case passes or fails. By default, a test case passes if the expression rule evaluates without an error.

In addition to running test cases for an individual rule in expression rule designer, tests for multiple rules can be run in bulk to test an entire application or system at once. See the Automated Testing for Expression Rules page for more details.

Test Case Assertions

The following types of assertions can be defined for each test case:

  • Test will pass when the expression evaluates without errors
  • Test will pass when the test output matches a user-defined output
  • Test will pass when a user-defined expression evaluates to true

Define an output for the assertion when you want to ensure that the test output exactly matches a specific output. A match occurs when output values are exactly the same (including case sensitivity for text) and are of the same type.

To validate other information about the test output, such as its length or the value of specific fields in a CDT, use an assertion expression. The variable test!output can be used in an expression to access the test output and can also be indexed into for targeted validation of CDT or Dictionary outputs.

Test Cases Examples and Recommendations

The following examples demonstrate how to use test case assertions to validate that your expression rules are returning the expected results for a variety of scenarios.

Example 1: Expression rules commonly validate that a value is what is expected in a process or interface. Below is an example of test cases for a rule that checks if an email address is valid.

Test Case Name Rule Input Assertion
Valid email address Output: true
Invalid email address - missing @ Output: false
Invalid email address - missing domain karen.jones@ Output: true
Null is an invalid email address null Output: false
List of email addresses still outputs a scalar boolean
typeof(test!output) = type!Boolean

Example 2: Another common scenario for expression rules is to manipulate a complex data type or Appian object input which could result in varied outputs. Examples of useful assertion expressions in these scenarios are below.

Scenario Assertion
The output is not null
Specific field in CDT equals some value
exact(index(test!output,"someCDTfield",{}), cons!someConstantValue)
List contains certain value(s)
contains(test!output, {"A", "B"})
Has # items in list
count(test!output) = 4
The output is no longer than a max length limited by a Smart Service
len(test!output) < 4000

Test case recommendations:

  • Expression rules should have enough test cases to accurately describe the behavior of the rule. This increases confidence that the rule works properly for runtime scenarios and helps with maintenance of the rule as it changes over time.
    Note: It is not necessary to have an exhaustive list of all possible permutations for your test cases.
  • Avoid using the and() function to group assertions together when making an assertion expression since this will make debugging the rule's failed tests more difficult. Duplicate test cases and update their assertion expressions when you want to assert multiple things about the same output.
  • When it is necessary to reference an Appian object in an assertion, use the Output matches the asserted output option to select the object. Objects selected from this option will be identified as precedents to the expression rule. It is also acceptable to create test objects and rules to use in test case assertions when necessary.

Test Cases View

The Test Cases view displays all the test cases associated with the rule as shown below:

From the Test Cases view, you can do the following:

  • Create new test cases
  • Edit test cases
  • Run all test cases
  • Duplicate test cases
  • Update test case assertions in bulk
  • Delete test cases

Run Test Cases

Clicking the Run All Tests button evaluates the expression rule with each test case's test inputs to determine whether the test passes or fails. The results of these tests are displayed in the Test Cases grid which includes the evaluated output of the rule for each test case and the test's status. All test inputs and assertions that were defined by an expression are reevaluated when using the run all tests functionality.

Test Status and Results

When a test is run, it can have one of the following resulting statuses:

  • Passed Test passed - the test's assertion passed
  • Failed Test failed: test output did not match asserted output - the test output was not identical to the user specified output
  • Failed Test failed: assertion expression returned false - the user specified assertion expression did not evaluate to true
  • Failed Test failed to run - the test could not be run because either one of its test inputs or the defined assertion failed to evaluate. When the test input failed, an error message is displayed in the cell for the corresponding input.
  • Failed Test returned an error - the rule encountered an expression error during evaluation. An error message is displayed in the output column for that test case.

The most recent test results for a test case definition are shown in the grid. The results continue to show even if the rule definition has changed and the test statuses indicate when the result may no longer be accurate because of the definition change.

Test results are not persisted with the expression rule on save, so tests must be run each time the rule is opened to view the results.

Export and Import of Test Values

Test cases are always exported with the expression rule, 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.

Call an Expression Rule From Another Expression

Expression rules are called using the rule! domain. When calling a rule, values or variables can be passed to the rule inputs by position or by keyword, as shown below.



When you save a new version of an expression rule, the latest version is available immediately. This means that any object that uses this rule immediately uses the new version. It is therefore important to carefully consider the impact on running processes when changing expression rule definitions. Appian recommends that you follow these best practices to facilitate the change management of expression rules:

  • When calling rules in process nodes, pass rule inputs by keyword.
  • Take advantage of entity-backed records and design short-lived processes. See the Record Design page for more information.
  • If the version of your expression rule must remain in sync with the version of your process, create a new rule and call it from the new version of your process model.

All versions are accessible to designers who can view the rule, and a rule can be reverted back to a previous version at any time. In order to access previous versions, select Versions in the Settings menu.

This option will open the Versions dialog, which displays basic information about all other versions of the rule and includes a link to each version. The version description is also shown here and can act as designer notes for descriptions that are not exposed to end users.

If you wish to revert your rule to an older version, open the version and click the Save button. This will create a new version of the rule 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.


Users with Administrator permission to an expression rule or folder can move it to another folder within the root folder.

To move an expression rule or rules folder:

  1. In the /designer interface, open the folder from the Rules tab that contains the expression rule or rules folder.
  2. Select the checkbox next to the expression rule or folder. You can select more than one.
  3. Click the Move button on the toolbar. The Choose Folder dialog box is displayed listing all top-level folders directly beneath the root folder (Rules and Constants).
  4. Locate the target folder and click the Select link. You can also create a new folder if you have Editor rights to its parent folder and select it.
  5. Click OK to complete the move.

NOTE: Any objects that are configured to inherit the security of the parent folder assume the security rights of the target folder.


Deleting an expression rule prevents users from further viewing or editing it. However, the last version of the rule is still available to be used in processes, record views, and reports. Rules can be deleted by users with Administrator rights to it. Appian does not recommend deleting rules that are in use because the rule can no longer be exported. To delete a rule:

  1. Go to an application that contains the rule.
  2. Use the Delete option in the application contents grid toolbar.


The security rolemap of the expression rule controls who can see or modify the rule definition and properties. However, expression rules can be evaluated by any user regardless of their defined role in the security rolemap.

The following actions can be completed by each role:

Actions Administrator Editor Viewer Deny
Evaluate the rule Yes Yes Yes Yes
View the rule definition Yes Yes Yes No
View and run test cases Yes Yes Yes No
Update the rule definition Yes Yes No No
Create, update, and delete test cases Yes Yes No No
Delete the rule Yes Yes No No
View the security in the application designer Yes Yes No No
Update the security Yes No No No

By default, rules inherit the security of the folder that they are saved in. To view or modify the security of a rule, go to an application that contains the rule and use the Security option in the application contents grid toolbar.

You can also restrict users from creating any rules or constants. See the Designer Role section on the User Roles page for more information.

Expression Evaluation Context

Expressions can be evaluated under different user contexts, depending on how the object is configured. Objects like records or reports evaluate the expression in the context of the user viewing the object. Process nodes can be configured to run as different users, including the process initiator or the process model designer, using the Assignment Tab.

See the User Contexts for Expressions page for more information on what user context is used when evaluating expressions in process.


On This Page