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:
|Name||The name that is used when executing the rule. This property is case-insensitive, but we recommend that you follow the naming standard.|
|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.
|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:
The following names are reserved for process report metrics, and must not be used.
To modify the rule properties, click on the gear menu displayed in the top right corner, as shown below, then click Properties. This opens the Rule Properties dialog, where you can modify the description and folder.
To create a rule input:
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.
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.
While editing your expression rules you may encounter guidance. Appian design guidance reinforces best practice design patterns that should be implemented in your objects. Design guidance for expression rules is calculated while editing the rule or when a precedent of the rule 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 rule. 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.
Expression rule guidance is also visible outside of rules on the Health Dashboard.
See design guidance for the full list of possible guidance.
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.
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. You can also trigger the Test Rule button using the Ctrl+Enter or Command+Enter keyboard shortcut on Windows or Mac, respectively.
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:
Once test cases are added they are saved along with the rule on the next save of the rule.
When using local varaibles in your expression, the values of your local variables will be displayed in the section labeled "Local Variables" between the "Test Input" and "Test Output" sections.
The grid displays the name, type, and value of each local variable in your expression. Clicking on the value will open a dialog with more details and an expanded view of the value.
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.
The following types of assertions can be defined for each test case:
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. The values of your test inputs can be used in your assertion expression too; test inputs are referenced by using the
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 email@example.com||Output: true|
|Invalid email address - missing @||karen.jonesexample.com||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||
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.
|The output is not null||
|Specific field in CDT equals some value||
|List contains certain value(s)||
|Has # items in list||
|The output is no longer than a max length limited by a Smart Service||
Test case recommendations:
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.
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:
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.
When a test is run, it can have one of the following resulting statuses:
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.
To run test cases for multiple expression rules at once, use the Manage Test Cases view. See Test Case Management for more information on executing test cases in bulk and managing test cases at the application level.
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.
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:
Each time you modify and save an expression rule, a new version is created. All objects that use the expression rule will use the latest version. All versions are accessible to designers who can view the expression rule, and an expression rule can be reverted back to a previous version at any time.
For information on how to manage object versions, see Managing Object Versions.
Users with Administrator permission to this object or rule folder can move it to another 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 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 an expression rule:
System administrators have the ability to delete expression rules (and other objects) in bulk by selecting them and clicking Delete in the toolbar.
Renaming an expression rule will automatically update references to it in all objects.
To rename an expression rule:
Learn more on Renaming Design Objects.
Any user can invoke any expression rule that is used by an interface or process they can access.
The security role map of an expression rule controls which developers can see or modify it and its properties. By default, expression rules inherit the security of the folder that they are saved in. However, after creating the expression rule, you can disable that inheritance and modify the rule's security. See Editing Object Security to modify an expression rule's security.
The following table outlines the actions that can be completed for each permission level in an expression rule's security role map:
|Evaluate the rule||Yes||Yes||Yes||Yes|
|View the rule definition||Yes||Yes||Yes||No|
|Duplicate the rule||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|
|View the security||Yes||Yes||No||No|
|Rename the rule||Yes||Yes||No||No|
|Delete the rule||Yes||No||No||No|
|Update the security||Yes||No||No||No|
Expressions can be evaluated under different user contexts, depending on how the object is configured. Record type objects or report objects 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.
Developers with Viewer permissions to this object can duplicate it. There are two ways to duplicate an object with a designer:
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.