Free cookie consent management tool by TermsFeed

a!customFieldMatch() Function

Function

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.

Parameters

Keyword Type Description

value

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 fv!value. This parameter is required.

equals

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.

whenTrue

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.

then

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.

default

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 considerations

Where to use this function

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:

  1. In your record type, go to Data Model.
  2. Click NEW CUSTOM RECORD FIELD.
  3. From SELECT A TEMPLATE, choose Write Your Own Expression.
  4. Choose Real-time evaluation.
  5. Click NEXT.
  6. 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.

  7. Click NEXT.
  8. Enter a Name for your custom record field.
  9. Click CREATE.
  10. Click SAVE CHANGES. The new custom record field appears in your list of fields.

Using the equals or whenTrue parameters

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 parameter

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 parameter

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 order

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 pairs

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 types

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).

Limitations

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 in a!queryRecordType() or in any charts.

  • You can only use a maximum of five record field references in a!customFieldMatch().

Examples

See the Real-time evaluation recipes for another example using a!customFieldMatch().

Supported functions

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 compatibility

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.

Feedback