FunctionCopy link to clipboard
a!customFieldMatch( value, equals, whenTrue, then, default )
Used to create a real-time custom record field, this function evaluates the value parameter against multiple conditions and returns a value based on a match. If no match is found, the default parameter is returned.
ParametersCopy link to clipboard
Keyword | Type | Description |
---|---|---|
|
Any Type |
The value to match. This value can be a record field, related record field, or custom field function. This value can be accessed in other parameters using the function variable |
|
Any Type |
This value is considered a match if it equals the value parameter. This parameter is best to use when evaluating literal values (for example, 1 or "Red"). Text values are case sensitive, so the casing must match that of the value parameter. |
|
Any Type |
The expression considered a match if it evaluates to true. Use a!customFieldCondition(), a!customFieldLogicalExpression(), or both to define your conditional logic. Alternatively, you can provide any custom field function or record field that returns a boolean. |
|
Any Type |
A record field, related record field, custom field function, or literal value to return when the equals or whenTrue parameter matches the value parameter. If you use multiple condition pairs, only the first match will be returned. All then parameters must be the same data type or compatible data types. Compatible data types include Number (Integer)/Number (Decimal) and Date/Date and Time. |
|
Any Type |
A record field, related record field, custom field function, or literal value to return if there are no equals or whenTrue parameters that match the value parameter. This parameter is required. |
Usage considerationsCopy link to clipboard
Where to use this functionCopy link to clipboard
The a!customFieldMatch()
function can only be used to create a custom record field that evaluates in real time. This means you can reference related record fields, constants, and other supported functions in your calculations.
To create a custom record field that evaluates in real-time:
- In your record type, go to Data Model.
- Click NEW CUSTOM RECORD FIELD.
- From SELECT A TEMPLATE, choose Write Your Own Expression.
- Choose Real-time evaluation.
- Click NEXT.
-
Enter an expression using any Custom Field function.
Note: Custom record fields that evaluate in real-time must use at least one Custom Field function.
- Click NEXT.
- Enter a Name for your custom record field.
- Click CREATE.
- Click SAVE CHANGES. The new custom record field appears in your list of fields.
Using the equals or whenTrue parametersCopy link to clipboard
In your a!customFieldMatch()
expression, you can add condition pairs to determine your conditional logic. A condition pair is an instance of the equals/then parameters or the whenTrue/then parameters.
To determine which parameter you should use, consider:
- Using equals when you have simple logic that to evaluates literal values (like static text or numbers) or null values.
- Using whenTrue when your logic is more complex and can be greater than, less than, or an array of values.
You can also use these parameters together, so a single a!customFieldMatch()
expression can contain both equals and whenTrue parameters.
Tip: For optimal performance, Appian recommends having a maximum of five condition pairs in a single a!customFieldMatch()
expression.
Using the equals parameterCopy link to clipboard
For example, let's say you want to create the following logic: If a customer has a support level equal to 3, then display the value "Critical Customer Order". Otherwise, just display "Customer Order". Since the value to compare is an exact value (the number 3), you should use the equals parameter in a!customFieldMatch()
to create this logic. The expression would look like this:
1
2
3
4
5
6
a!customFieldMatch(
value: recordType!Order.relationships.customers.fields.supportLevel,
equals: 3,
then: "Critical Customer Order",
default: "Customer Order"
)
Copy
Using the whenTrue parameterCopy link to clipboard
Now let's say you want create this logic: If a case has been open for 5 or fewer days, then display "Between 1 and 5 days". If a case has been open between 6 and 10 days, then display "Between 6 and 10". If open more than 10, display "Over 10 days".
Since you want to create more complex logic, comparing values greater than or less than other values, you would use the whenTrue parameter to create this logic. Whenever you use the whenTrue parameter, you must also use the a!customFieldCondition() function and/or the a!customFieldLogicalExpression().
The expression for this example would look like this:
Tip: This example also uses the a!customFieldDateDiff() and a!customFieldDefaultValue() functions so the difference is calculated based on the open and closed date; however, if the close date is null, it will subtract from today's date.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
a!customFieldMatch(
/* Get the difference between today's date and the deadline date */
value: a!customFieldDateDiff(
startDate: recordType!Case.fields.submittedDate,
endDate: a!customFieldDefaultValue(
value: recordType!Case.fields.closedDate,
default: today()
),
interval: "DAY"
),
whenTrue: a!customFieldCondition(
field: fv!value,
operator: "<=",
value: 5
),
then: "Between 1 and 5 days",
whenTrue: a!customFieldCondition(
field: fv!value,
operator: "between",
value: {6, 10}
),
then: "Between 6 and 10 days",
default: "Over 10 days"
)
}
Copy
Evaluation orderCopy link to clipboard
The a!customFieldMatch()
function evaluates conditions in order and stops once a condition matches the value parameter. If you use multiple condition pairs, meaning you use multiple instances of equals/then or whenTrue/then in your expression, the then parameter following the first matching condition is evaluated, and any remaining condition pairs will be ignored.
For example, in the function below, there are three condition pairs:
- If a case has a priority of 3, then display "Low"
- If a case has a priority of 2, then display "Medium"
- If a case has a priority of 1, then display "High"
1
2
3
4
5
6
7
8
9
10
a!customFieldMatch(
value: recordType!Case.relationships.priority.fields.Id,
equals: 3,
then: "Low",
equals: 2,
then: "Medium",
equals: 1,
then: "High",
default: "No selected priority"
)
Copy
Since a case can only have one priority level, this function uses the equals parameter to look for a matching value. For example, if a case has a priority value of 2, then the function will evaluate the first and second equals. Because the second equals
is a match, the subsequent then value will be returned. The third condition pair and default parameter will be ignored.
Evaluating multiple condition pairsCopy link to clipboard
In the whenTrue parameter of a!customFieldMatch()
, you can use the a!customFieldLogicalExpression() function to determine how multiple conditions are evaluated.
For example, suppose you want to display an order's delivery status as either on time or late based on when the order was delivered and the status of the order:
- If an order has a status of "Delivered" and it was delivered by the due date or before, display the value "On Time Delivery".
- If an order has a status of "Delivered" and it was delivered after the due date, then display the value "Late Delivery".
- Otherwise, display "Not delivered yet" when there is no delivery date.
The expression would look like this:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
a!customFieldMatch(
/* Get the difference between the delivery date and the due date */
value: a!customFieldDateDiff(
startDate: recordType!Order.fields.deliveryDate,
endDate: recordType!Order.fields.dueDate,
interval: "DAY"
),
whenTrue: a!customFieldLogicalExpression(
operator: "AND",
conditions: {
a!customFieldCondition(fv!value, ">=", 0),
a!customFieldCondition(
recordType!Order.relationships.status.fields.label,
"=",
"Delivered"
)
}
),
then: "On Time Delivery",
whenTrue: a!customFieldLogicalExpression(
operator: "AND",
conditions: {
a!customFieldCondition(fv!value, "<", 0),
a!customFieldCondition(
recordType!Order.relationships.status.fields.label,
"=",
"Delivered"
)
}
),
then: "Late Delivery",
default: "Not delivered yet"
)
Copy
Supported data typesCopy link to clipboard
The value, then, and default parameters can accept any of the following data types:
- Boolean
- Date
- Date and Time
- Number (Integer)
- Number (Decimal)
- Text
The then and default parameters must be the same data type or compatible data types. Compatible data types include Number (Integer)/Number (Decimal) and Date/Date and Time.
For example, if you have a then parameter of type Text, then the default parameters should also be type Text. Or, if you have a then parameter of type Number (Integer), you could have default parameter of type Number (Decimal).
LimitationsCopy link to clipboard
The a!customFieldMatch()
function has the following limitations:
-
You cannot use a custom record field defined using
a!customFieldMatch()
as a filter in a!measure(). This means that you cannot use this type of custom record field to filter measures ina!queryRecordType()
or in any charts. -
You can only use a maximum of five record field references in
a!customFieldMatch()
.
ExamplesCopy link to clipboard
See the Real-time evaluation recipes for another example using a!customFieldMatch()
.
Supported functionsCopy link to clipboard
You can use any of the following supported functions in the parameters of a!customFieldMatch()
:
Note: When you use a supported function in a Custom Field function, you can only pass static values or constants containing static values into the supported function; you cannot pass record field references.
Feature compatibilityCopy link to clipboard
The table below lists this function's compatibility with various features in Appian.
Feature | Compatibility | Note |
---|---|---|
Portals | Partially compatible | Can be used with Appian Portals if it is connected using an integration and web API. |
Offline Mobile | Incompatible | |
Sync-Time Custom Record Fields | Incompatible | |
Real-Time Custom Record Fields | Compatible | Can only be used to create a custom record field that evaluates in real time. It cannot be used anywhere else in your application. |
Process Reports | Incompatible | Cannot be used to configure a process report. |
Process Events | Incompatible | Cannot be used to configure a process event node, such as a start event or timer event. |