Macros in Rules
Use a macro when a single rule executes repeatedly on different JSON node paths.
Rule macros let template developers define repeatable, well-tested rule code units that you can call within the context of any JSON transformation. Macros simplify the rule definition source and make it easier to maintain.
You invoke macros using standard function syntax. Reference them anywhere a traditional expression is resolved within a rule action. In template rules, macros can be referenced by an eval action. Macros can include actions and can reference other macros, and macro recursion is supported. Templates support a macro depth of 10. Exceeding that depth results in an overflow error and app creation failure.
For example, consider the following macro for multiplying two numbers:
1{
2 "namespace": "testMacroNamespace",
3 "definitions": [
4 {
5 "name": "multiplyTwoNumbers",
6 "parameters": [
7 "firstNumber",
8 "secondNumber"
9 ],
10 "returns": "${p.firstNumber * p.secondNumber}"
11 },
12 {
13 "name": "shouldExecuteAction",
14 "returns": true
15 }
16 ]
17}It can be invoked in rules actions as follows:
1{
2 "rules": [
3 {
4 "name": "Testing of example macro",
5 "actions": [
6 {
7 "action": "set",
8 "key": "macroResult",
9 "path": "$.path.to.a.number",
10 "value": "${testMacroNamespace:multiplyTwoNumbers(3,3)}"
11 },
12 {
13 "action": "put",
14 "condition": "${testMacroNamespace:shouldExecuteAction()}",
15 "path": "$.my.json.path",
16 "value": {
17 "foo": "bar",
18 "anotherNumber": "${testMacroNamespace:multiplyTwoNumbers(5,5)}"
19 }
20 }
21 ]
22 }
23 ]
24}Macro Object and Macro Definition
A rule macro object contains a collection of macro definition objects. Macro definition objects define the logic of macros and their return values.
Macro object attributes are as follows:
namespace: A unique string identifier (to the template) used to scope the collection of macro definitions.definitions: Array of macro definition objects defined within the rule macro.
Macro definition object attributes are as follows:
name: The name of the macro.description: A string that describes what the macro does.parameters: An array of zero or more parameter names that the macro expects.actions: An array of zero or more rule actions to perform as part of the macro.returns: An expression or literal value to be returned from the macro.
The number of parameters passed in the macro function call must match the number of parameters defined in the macro. They’re passed in the order defined in the macro definition. You can use a maximum of 10 parameters per macro.
Parameters can be referenced in the body of the macro using standard expression syntax: ${p.<parameter_name>}. Parameters can be referenced in any action that accepts expressions. Macros in actions support path statements so that expressions can be used for more dynamic JSON path handling.
Parameters are scoped to the execution of the macro call, and any references to ${p.<parameter_name>} fail outside the scope of the macro.
Macro Examples
An example macro showing multiple definitions including path statements.
1"macros":
2 [
3 {
4 "namespace": "myMacroNamespace",
5 "definitions": [
6 {
7 "name": "multiplyTwoNumbers",
8 "parameters": [
9 "firstNumber",
10 "secondNumber"
11 ],
12 "returns": "${p.firstNumber * p.secondNumber}"
13 },
14 {
15 "name": "deleteWidget",
16 "description": "Deletes a widget and any references to the widget.",
17 "parameters": [
18 "widgetName"
19 ],
20 "actions": [
21 {
22 "action": "eval",
23 "key": "results",
24 "path": "${json:searchPaths(\"$.state.widget['p.widgetName']\")}"
25 },
26 {
27 "condition": "${!empty results}",
28 "action": "delete",
29 "path": "$.state.widgets['${p.widgetName}']"
30 },
31 {
32 "condition": "${!empty results}",
33 "action": "delete",
34 "path": "$.state.gridLayouts..pages..widgets[?(@.name=='${p.widgetName}')]"
35 }
36 ]
37 }
38 ]
39 }
40 ],
41 "constants": [...],
42 "rules": [...]}This example calls a macro with namespace myNS and macro name getSomething defined with no parameters. The results of the macro are stored in the template context, and can be referenced using this expression: ${Rules.Eval.macroResults}.
1{
2 "action": "eval",
3 "key": "macroResults",
4 "value": "${myNS:getSomething()}"
5}This example sets the JSON node at path $.path.to.json.node with the result of macro myNS:getJsonValue defined with no parameters. This action is only called if the macro myNS:shouldExecute (defined with one parameter) returns true.
1{
2 "action": "set",
3 "condition": "${myNS:shouldExecute(true)}",
4 "path": "$.path.to.json.node",
5 "value": "${myNS:getJsonValue()}"
6}See Also
j