AMDL Reference
ARIC Model Definition Language (AMDL™) is a language used to specify rules and logic within Real-Time Decisioning. For information on how to write business rules and expressions, see Using AMDL. For step-by-step examples, see Tutorial: Defining Rules in Real-Time Decisioning.
Data types
Copy section link
All of the data types that can be used within AMDL can be specified as fixed values. The following are the available data types:
| Method | Description |
|---|---|
Booleans |
Example: |
Strings |
Example: |
Numbers |
Both integer and decimal numbers are permitted by the parser. There is no difference in the way they are handled except when testing strict equality. For more information, see Type coercion in Using AMDL. Examples: |
Durations |
Durations can be specified as a certain number of days (d), hours (h), minutes (m), or seconds (s). Their main use is for comparison. For instance, you may want to check whether the time between two events is less than one hour. Examples: |
Sets |
Unordered collections of unique values. Example: |
Arrays |
Ordered collections of values. Example: |
Operators
Copy section link
This section details the full list of operators within AMDL and their usage.
Mathematical operators
Copy section link
+ - * /
As well as operating on numbers, + and - can also operate on times and durations.
You can add or subtract durations, and add a duration to or subtract a duration from a time.
String concatenation operator
Copy section link
..
This operator concatenates any two strings, numbers, durations, or times as strings. For non-strings this is done in a format so that they can be coerced back to their original types.
Comparison and equality operators
Copy section link
== != < <= > >=
These return a boolean value indicating the result of the comparison. The first two operators can be applied to strings as well as numbers, durations, and times, but the latter four cannot be used for strings.
| Operator | Description |
|---|---|
== |
equals |
!= |
does not equal |
< |
less than |
<= |
less than or equal to |
> |
greater than |
>= |
greater than or equal to |
Boolean operators
Copy section link
! && ||
Use these operators on boolean values.
| Operator | Description |
|---|---|
! |
NOT |
&& |
AND |
| | |
OR |
Collection membership operators
Copy section link
~# !#
Use these operators to test membership in a collection and return a boolean value. The left operand must always be some form of collection, and the right operand must be the element of the collection whose membership is being tested.
| Operator | Description |
|---|---|
~# |
Contains |
!# |
Does not contain |
Collection comparison operators
Copy section link
==# !=# <# <=# ># >=#
These operators perform comparison operations on all elements of a collection and return the boolean combination of the results. The left operand must always be a collection and the right operand that which is to be compared.
Ternary operator
Copy section link
?:
This operator allows one of two operations to be evaluated based on a boolean condition. It is a useful control flow tool to use if, for instance, there are special cases that need action.
Switch case operator
Copy section link
~?
This operator allows one of many operations to be evaluated based on a switch expression. This is useful if you have several special cases for the same variable, each of which needs a different action.
Case labels must be a fixed value or default.
Every switch case must be terminated by a semicolon.
Switching based on variable expressions is not supported.
Default value operator
Copy section link
??
Expression evaluation stops if a referenced variable does not exist.
The ?? operator allows a default value to be specified if an expression cannot be evaluated.
Exists operator
Copy section link
~
This operator checks whether evaluation of a reference returns a non-null value.
Regular expression match operator
Copy section link
~=
This operator checks whether the left string operand matches the regular expression contained in the right operand. This operator can only be applied to strings. For more information, see Regular expressions in Using AMDL.
Regular expression substitution operator
Copy section link
~:
This operator performs a substitution specified in the right operand on the left string operand. This operator can only be applied to strings. For more information, see Regular expressions in Using AMDL.
Operator precedence
Copy section link
In the table below, all operators are listed in precedence order, from highest to lowest, row by row. Operators in the same row of the table have the same precedence. Each operator is left-associative, right-associative, or non-associative:
-
Left-associative operators of the same precedence bind to the left:
e1 op e2 op e3becomes(e1 op e2) op e3. -
Right-associative operators of the same precedence bind to the right:
e1 op e2 op e3becomese1 op (e2 op e3). -
Non-associative operators do not appear in contexts where their binding is ambiguous.
| Operator | Associativity |
|---|---|
+
( ) |
Left |
[ ] |
None |
! |
Right |
* / |
Left |
+ |
Left |
> >= |
Left |
== != |
Left |
Collection operators |
Right |
&& |
Left |
|| |
Left |
~? |
Right |
?? |
Right |
?: |
Right |
Scope
Copy section link
The following is a list of allowed scopes in AMDL, detailing which are supported in business rules and which are supported in analytical workflows.
-
A scope that supports reference allows you to write expressions that reference something within the scope, used as an operand—for example,
event.amount > 100orlists.negativeList ~# event.card. -
A scope that supports definition allows you to write expressions that define variables within that scope—for example,
rules.rule1: event.amount > 100orstate.example: event.amount.
| Scope | Business Rules | Workflows | ||
|---|---|---|---|---|
Definition |
Reference |
Definition |
Reference |
|
|
✓ |
✓ |
||
|
✓ |
✓ |
||
|
✓ |
✓ |
✓ |
✓ |
|
✓ |
✓ |
✓ |
✓ |
|
✓ |
✓ |
✓ |
✓ |
|
✓ |
✓ |
✓ |
✓ |
|
✓ |
✓ |
✓ |
|
|
✓ |
✓ |
||
|
✓ |
|||
|
Only in tests |
✓ |
||
|
Only in tests |
✓ |
||
|
Only in tests |
Note
Scope names are reserved keywords within the relevant AMDL implementation—that is, scopes that can be used in business rule AMDL are reserved keywords in business rule expressions, and scopes that can be used in analytical workflows are reserved keywords in workflows. Thetests scope is a reserved keyword only in the Expectations panel of a unit test (see Testing analytical workflows in Using AMDL).
Reserved keywords cannot be used as the name of a variable of AMDL expression, and references to event data fields with these names must use the square bracket syntax.
For more information, see Event data in Using AMDL.
Annotations
Copy section link
This section provides a complete list and descriptions of allowed annotations in AMDL.
@array()
Copy section link
@array(<duration>)
@array(<length>)
@array(duration=<duration>, size=<length>)
This modifies the type of a state expression such that it captures an array, which in the context of AMDL refers to an ordered collection of objects.
The size of an array must be limited by specifying a duration (in which case elements older than the specified duration expire and are removed) or a fixed length (in which case the oldest element is removed each time a new element is added, once the array reaches that length) or both (using named arguments, duration and size).
If duration and length limits are both specified, the oldest element is removed if the array reaches its size limit when a new element is added, but elements older than the duration are also removed. A default size limit of 1000 elements is applied to all AMDL collections, including arrays. While this can be overridden by specifying a larger length limit, it is not recommended to do so, as this limit prevents performance issues due to large amounts of state data stored in a single collection.
@comment(<comment>)
Copy section link
Note
This annotation is not available in analytical workflows.Use this annotation to add comments to an expression.
@defaultValue(<defaultValue>)
Copy section link
Any single value state expression can have a default value applied in the case in which it is referenced but does not yet exist using this annotation. If the state already exists, the default value is not applied.
@eventType(<eventType>)
Copy section link
Note
This annotation is not available in analytical workflows. Each workflow is mapped to one or more event types, so this annotation is not necessary.A business rule expression accompanied by this annotation is evaluated only for events of the type specified within parentheses.
Multiple such annotations can be used to allow evaluation on multiple defined events.
If no @eventType annotation is provided for a business rule expression, it is evaluated for all event types by default.
@firstValue()
Copy section link
Any state expression with this annotation is updated only if it does not already exist. It effectively captures the first value to which it is ever evaluated.
@histogram()
Copy section link
@histogram(historyLength=<duration>, bucketSize=<bin width>)
@histogram(historyLength=<duration>, bucketSize=<bin width>, timeField=<time field>)
This changes the type of a state expression to a histogram, which in AMDL refers to collection of accumulated values, bucketed by time. For more information, see Histograms in Using AMDL.
@initialContents(<initialContents>)
Copy section link
Any state expression defined as an array or set can have initial contents, which are elements of the collection defined prior to the state expression being updated for the first time. If the state is referenced but does not exist yet, or when the state is updated for the first time, these values are assigned to the collection before the state expression is evaluated or updated.
@mapOptions(keyDuration=<duration>, keySize=<size>)
Copy section link
When using a state or global expression to define a dynamic map, use this optional annotation to set a limit on the number of keys in the map.
Use the keyDuration argument to set a duration limit so that each time the map is updated, keys that were last updated before the specified duration are removed from the map.
Use the keySize argument to specify a fixed size limit so that once the number of keys stored in the map reaches this size, each time a new key is added the key that was last updated longest ago is removed.
If you use both arguments, keys are removed from the map according to whichever limit is reached first.
A default size limit of 1000 keys is applied to all maps. While this can be overridden by specifying a larger size limit, it is not recommended to do so, as this can create performance issues due to large amounts of state data stored in a single map. This is particularly relevant for nested maps that store a collection of values with each key. For more information, see Maps in Using AMDL.
@output( )
Copy section link
@output(<namespace>)
@output(mode=ruleoutput)
Note
This annotation is not available in analytical workflows.This annotation modifies a var expression so that it assigns a tag with the value of that expression for each event for which it is calculated, or outputs the results in the Real-Time Decisioning output.
If outputting as a tag, you can provide an optional namespace argument.
If it is omitted, the tag generated uses the name of the var expression as its namespace.
@rollingAverage(<duration>)
Copy section link
This modifies the type of a state expression to a rolling average, which provides the average of all values it is updated with, weighted so that the weight of each historical value decays with time.
@score(<score>)
Copy section link
Note
This annotation is not available in analytical workflows. For analytical workflows, use an effect to output a risk score.This annotation enables rules to contribute to the overall risk score of a particular event and entity combination. A rule modified with this annotation adds the score specified in the argument to the risk score output by the businessrules model. This model outputs the total of the scores assigned by all triggered rules.
@set( )
Copy section link
@set(<duration>)
@set(<length>)
@set(duration=<duration>, size=<length>)
This annotation modifies the type of a state expression such that it captures a set, which in AMDL is an unordered collection of unique objects. Sets must be limited by specifying either a duration (in which case elements older than the specified duration expire and are removed), or a fixed length (in which case the oldest element is removed each time a new unique element is added, once the set reaches that length). If a value that already exists is added to the set, the expiration timer on that element is reset. If duration and length limits are both specified, the oldest element is removed if the set reaches its size limit when a new element is added, but elements older than the duration are also removed. A default size limit of 1000 elements is applied to all AMDL collections, including sets. Although this can be overridden by specifying a larger length limit, it is not recommended, as this limit prevents performance issues due to large amounts of state data stored in a single collection.
@suppressTag(<namespace>="<tagValue>")
Copy section link
Note
This annotation is not available in analytical workflows. For analytical workflows, use an effect to suppress a tag.This annotation modifies a rule so that when it triggers for a particular event and entity combination, a particular tag value (specified in the argument to this annotation) is suppressed. The namespace is optional. If no namespace is given, this annotation suppresses the tag with the default namespace and the specified value. This is implemented as part of the implicit rules aggregator step, so applies to tags assigned by rules, models (risk thresholds), and aggregators.
@tag(<namespace>="<tagValue>")
Copy section link
Note
This annotation is not available in analytical workflows. For analytical workflows, use an effect to add a tag.This annotation is applicable only to rule expressions.
If a rule triggers, the tag is appended to the response.
The namespace is an optional argument.
If no namespace is given (@tag("<tagValue>")), then it is assigned to the default namespace (_tag).
Multiple tag annotations can form part of any rule.
Methods
Copy section link
Several of the variable types within AMDL have several methods attached to them:
-
String
-
Datetime
-
String similarity
-
Password
-
Compression
-
Number
-
Collection
All of the methods described below are case insensitive (for example, "foo".isblank() and "foo".isBlank() work equivalently).
String
Copy section link
The following methods can be applied to strings.
If applied to a type other than a string, the AMDL expression stops evaluation.
Implementation of these methods mostly follows the Apache StringUtils class (org.apache.commons.lang3.StringUtils).
For details, see StringUtils.
Where details are not given here, refer to the StringUtils documentation.
Conventions such as lowercase and uppercase are follow the definitions given by the Unicode consortium.
For details, see java.lang.Character.
| Method | Description |
|---|---|
|
Abbreviates the string to be of length less than or equal to the provided
|
|
If the first letter is alphabetical, it is capitalized; otherwise, no change.
|
|
Centers a string inside a larger string of size
|
|
Returns the character at position
|
|
Removes one new line from the end of the string if one exists; otherwise, no change.
|
|
Checks whether the substring
|
|
Checks whether the substring
|
|
Checks whether any of the characters in the
|
|
Checks that none of the characters in the
|
|
Counts how many times the substring
|
|
Compares the string with
|
|
Checks whether the string ends with the provided suffix.
|
|
Checks whether the string ends with the provided suffix, irrespective of case.
|
|
Returns the ideal Shannon entropy of the string.
|
|
Compares the string with the argument string, returning true if they represent identical sequences of characters.
|
|
Compares the string with the argument string
|
|
Requires the string the be a valid format string, then uses the arguments If there are more arguments than format specifiers, the extra arguments are ignored. The number of arguments is variable and may be zero.
|
|
Returns the distance (in km) between two points on the Earth’s surface specified by latitude and longitude (in degrees), where
|
|
Checks if the string contains only lowercase letters.
|
|
Checks if the string contains only uppercase letters.
|
|
Checks if the string contains only Unicode letters.
|
|
Checks if the string contains only Unicode letters or digits.
|
|
Checks if the string contains only Unicode letters, digits, or spaces.
|
|
Checks if the string contains only Unicode letters or spaces.
|
|
Checks if the string contains only ASCII printable characters.
|
|
Checks if the string is whitespace or empty.
Unlike
|
|
Checks if the string is empty.
|
|
Checks if the string is not empty and not whitespace only. Opposite of
|
|
Checks if the string is not empty. Opposite of
|
|
Checks if the string contains only Unicode digits.
|
|
Checks if the string contains only Unicode digits or spaces.
|
|
Checks if the string contains only whitespace.
|
|
Returns the leftmost
|
|
Left pads the string with spaces, up to a total length
|
|
Returns the number of characters in the string.
|
|
Converts alphabetical characters in the string to lowercase.
|
|
Returns the MD5 checksum of the string.
|
|
Implicitly normalizes the string as described in
|
|
Converts alphabetical characters in the string to lowercase, then removes any that are not in the argument string
|
|
Removes all appearances of the substring
|
|
Removes substring
|
|
Removes substring
|
|
Removes each substring of the string that matches the given regular expression
|
|
Removes punctuation characters from the string.
|
|
Removes substring
|
|
Removes substring
|
|
Repeats the string
|
|
Replaces all occurrences of string
|
|
Replaces each substring of the string that matches regular expression
|
|
Reverses the order of the characters in the string.
|
|
Reverses a string separated by the
|
|
Returns the rightmost
|
|
Right pads the string with spaces, up to a total length of
|
|
Returns the SHA-256 hash of the string.
|
|
Given a NxN probability matrix (as a 2D array) and an
|
|
Splits the string by the
|
|
Splits the string by any of the specified characters
|
|
Splits the string by character type into an ordered collection of strings.
|
|
Splits the string by character type (including camel-case words) into an ordered collection of strings.
|
|
Checks whether the string starts with the provided prefix.
|
|
Checks whether the string starts with the provided prefix, irrespective of case.
|
|
Removes whitespace from the start and end of the string.
|
|
Removes diacritics from the string.
|
|
Strips any of the provided characters
|
|
Strips any of the provided characters
|
|
Returns the substring after index
|
|
Returns the substring between indices
|
|
Returns the substring after the first occurrence of the separator
|
|
Returns the substring after the last occurrence of the separator
|
|
Returns the substring before the first occurrence of the separator
|
|
Returns the substring before the last occurrence of the separator
|
|
Returns the substring nested between the first two instances of
|
|
Returns the substring nested between the first instances of
|
|
Swaps the case of each string character, changing lowercase characters to uppercase and vice versa.
|
|
Removes start and end characters below ASCII code
|
|
If the first letter of the string is alphabetical, it is changed to lowercase; otherwise, no change.
|
|
Converts alphabetical characters in the string to lowercase.
|
Datetime
Copy section link
These methods can be used on strings that represent a timestamp. All these methods accept an optional format argument, which defines the format of the string the method is acting on (and any datetime arguments) and how it should be parsed, as well as the format of any datetime output. Without this, ISO-8601 format and UTC are assumed. The format argument can be any of the following:
-
A format string using Java’s
DataTimeFormattersyntax. See DateTimeFormatter in the Java documentation for details. -
iso8601 for ISO-8601 format.
-
epoch for a timestamp expressed as the number of milliseconds since the Unix epoch (midnight UTC on 1st Jan 1970).
-
epochsec for a timestamp expressed as the number of seconds since the Unix epoch.
| Method | Description |
|---|---|
|
Returns true if the timestamp string is after the datetime time; otherwise, false.
|
|
Returns true if the timestamp string is before the datetime time; otherwise, false.
|
|
Adds the number of milliseconds, seconds, minutes, hours, or days to the timestamp string.
|
|
Returns the time between the timestamp string and the argument in the units specified, rounded down to the nearest integer.
|
|
Returns the timestamp string, formatted according to the format string specified. This format string has the same possible values as the optional format string that can be added to any of these datetime methods. If a second format string is specified, this represents the format of the timestamp string to be converted.
|
|
Returns the millisecond, second, minute, hour, or day part of the string timestamp.
|
|
Returns any of the standard set of Java temporal fields from the string timestamp. See ChronoField in the Oracle documentation for a list of fields.
|
|
Returns the current time using the format specified by the argument, if an argument is provided, defaulting to ISO-8601. The string operated on has no effect on the return value, so the empty string can be used.
|
|
Returns the timestamp string, but with the time zone changed to the time zone defined by the
|
String similarity
Copy section link
| Method | Description |
|---|---|
|
Returns the cosine distance between the string and
|
|
Returns the cosine distance between the string and
|
|
Returns the Jaccard index distance between the string and
|
|
Returns the Jaccard index distance between the string and
|
|
Returns the Jaro-Winkler distance between the string and
|
|
Returns the Jaro-Winkler distance between the string and
|
|
Returns the Levenshtein distance between the string and
|
|
If
|
|
Returns the Levenshtein distance between the string and
|
|
If
|
|
Returns the Ratcliff/Obershelp distance between the string and
|
|
Returns the Ratcliff/Obershelp distance between the string and
|
|
Returns the Sørensen-Dice distance between the string and
|
|
Returns the Sørensen-Dice distance between the string and
|
Password
Copy section link
| Method | Description |
|---|---|
|
Returns the PBKDF2 hash of the string. Note that the result of this is different every time.
|
|
Validates the supplied password against the hash argument.
|
Compression
Copy section link
| Method | Description |
|---|---|
|
Compresses the string using Java Deflator.
|
|
Decompresses the string using Java Deflator.
|
Number
Copy section link
The following methods apply to numbers. If the method subject is not a number, expression evaluation halts. Implementation of these methods generally follows the Java Math library. For more information, see Java Math Library.
| Method | Description |
|---|---|
|
Returns the absolute value of the number.
|
|
Returns the arc cosine of the value.
The returned angle is in the range
|
|
Returns the arc sine of the value.
The returned angle is in the range
|
|
Returns the arc tangent of a value.
The returned angle is in the range
|
|
Returns the cube root of the number.
|
|
Returns the smallest (closest to negative infinity) integer value that is greater than or equal to the number.
|
|
Returns the trigonometric cosine of the value.
|
|
Returns the hyperbolic cosine of the value.
|
|
Returns Euler’s number
|
|
Returns Euler’s number
|
|
Returns the largest (closest to positive infinity) integer value that is less than or equal to the number.
|
|
Returns the natural logarithm of the number.
|
|
Returns the logarithm (base 10) of the number.
|
|
Returns the greater of the subject number and the argument
|
|
Returns the smaller of the subject number and the argument
|
|
Returns the remainder when the subject number is divided by the argument
|
|
Raises the number to the power of
|
|
Returns a random number greater than or equal to 0.0 and less than the subject number. Subject number must be positive.
ImportantMethods such asrandom() and randomint() that give non-deterministic results should only be used for testing and not in production business rules or workflows.
Non-deterministic methods can result in discrepancies between the real-time and asynchronous responses, as the output from the method is different when the event is processed synchronously to produce the real-time response, and when it is processed asynchronously by Real-Time Decisioning.
|
|
Returns a random integer greater than or equal to 0 and less than the subject number. Subject number must be positive.
ImportantNot recommended for use in production (see important note above). |
|
Rounds the number to
|
|
|
|
Returns the trigonometric sine of the value.
|
|
Returns the hyperbolic sine of the value.
|
|
Returns the square root of the number.
|
|
Returns the trigonometric tangent of the value.
|
|
Returns the hyperbolic tangent of the value.
|
|
Converts the number from radians to degrees.
|
|
Converts the number from degrees to radians.
|
Collection
Copy section link
AMDL supports some common collection and statistical methods:
For additional details, see the following Java documentation: CollectionUtils, SummmaryStatistics, and DescriptiveStatistics.
Statistical methods cause expression execution to stop if the collection contains any non-numerical values. In addition, there are some methods that can only be applied to ordered collections.
Common collections
Copy section link
| Method | Description |
|---|---|
|
Returns an ordered collection consisting of the original collection with all elements of
|
|
Returns an unordered collection consisting of all elements in the first collection not present in
|
|
Returns an unordered collection consisting of all elements present in both collections.
|
|
Checks whether there are any values in the collection.
|
|
Concatenates all values in the collection into a string. If an argument is provided, it uses this as a delimiter. If no argument is provided, no delimiter is used.
|
|
For a collection with one element, returns that element as a scalar value. For a collection with more than one element, execution stops.
|
|
Returns the number of elements in the collection.
|
|
Returns an ordered collection in sorted order. If the values are strings, alphabetical sorting is used. If the values are numbers, numerical sorting is used. For more information, see Ordered collection.
|
|
Returns an unordered collection consisting of all elements present in the collection and not in
|
|
Returns the sum of the values in the collection. If any non-numeric values are present in the collection, expression execution stops.
|
|
Returns an unordered set consisting of all the unique values in either collection.
|
Statistical collections
Copy section link
| Method | Description |
|---|---|
|
Returns the geometric mean of the values in the collection. If any non-number values are present or the collection is empty, returns null. Note that this does not return an exact amount for integer solutions.
|
|
Returns the kurtosis of the values in the collection.
|
|
Returns the maximum value in the collection.
|
|
Returns the arithmetic mean of the values in the collection.
|
|
Returns the median of the values in the collection.
|
|
Returns the minimum value in the collection.
|
|
Returns an estimate for the pth percentile of the values in the collection.
|
|
Returns the population variance of the values in the collection.
|
|
Returns the quadratic mean (also known as root-mean-square) of the values in the collection.
|
|
Returns the second central moment of the values in the collection (the sum of squared deviations from the sample mean).
|
|
|
|
Returns the standard deviation of the values in the collection, based on the sample variance. Example: |
|
Returns the sum of the natural logs of the values in the collection. Example: |
|
Returns the sum of the squares of the values in the collection. Example: |
|
Returns the (sample) variance of the values in the collection. This method returns the bias-corrected sample variance (using Example: |
Ordered collections
Copy section link
| Method | Description |
|---|---|
|
Returns the collection in reverse order. Example: |
|
Randomly permutes the collection using a default source of randomness. Example: |
|
Returns the sublist of all elements with index greater than or equal to the parameter Example: |
|
Returns the sublist of all elements with index greater than or equal to the parameter Example: |