---
schema_version: "1"
id: d5ff1458a9bcfbb95fc797743aa8425bffab87fa8ac88a47509cb83133322119
title: Macros in Rules
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/analytics/atf/guides/atf-rules-macros.md
canonical_url: https://developer.salesforce.com/docs/analytics/app-template-framework/guide/atf-rules-macros.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 479ade076323077e2e815db71b7e88570610c6d830a2c838bc1cf5268105309b
products:
  - App Template Framework
  - analytics
---
# 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:

```json
{
    "namespace": "testMacroNamespace",
    "definitions": [
        {
            "name": "multiplyTwoNumbers",
            "parameters": [
                "firstNumber",
                "secondNumber"
            ],
            "returns": "${p.firstNumber * p.secondNumber}"
        },
        {
            "name": "shouldExecuteAction",
            "returns": true
        }
    ]
}
```

It can be invoked in rules actions as follows:

```json
{
    "rules": [
        {
            "name": "Testing of example macro",
            "actions": [
                {
                    "action": "set",
                    "key": "macroResult",
                    "path": "$.path.to.a.number",
                    "value": "${testMacroNamespace:multiplyTwoNumbers(3,3)}"
                },
                {
                    "action": "put",
                    "condition": "${testMacroNamespace:shouldExecuteAction()}",
                    "path": "$.my.json.path",
                    "value": {
                        "foo": "bar",
                        "anotherNumber": "${testMacroNamespace:multiplyTwoNumbers(5,5)}"
                    }
                }
            ]
        }
    ]
}
```

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

```json
  "macros":
  [
      {
          "namespace": "myMacroNamespace",
          "definitions": [
               {
                  "name": "multiplyTwoNumbers",
                  "parameters": [
                      "firstNumber",
                      "secondNumber"
                   ],
                  "returns": "${p.firstNumber * p.secondNumber}"
               },
               {
                  "name": "deleteWidget",
                  "description": "Deletes a widget and any references to the widget.",
                  "parameters": [
                      "widgetName"
                  ],
                  "actions": [
                     {
                       "action": "eval",
                       "key": "results",
                       "path": "${json:searchPaths(\"$.state.widget['p.widgetName']\")}"
                     },
                     {
                        "condition": "${!empty results}",
                        "action": "delete",
                        "path": "$.state.widgets['${p.widgetName}']"
                     },
                     {
                        "condition": "${!empty results}",
                        "action": "delete",
                        "path": "$.state.gridLayouts..pages..widgets[?(@.name=='${p.widgetName}')]"
                     }
                  ]
              }
          ]
      }
   ],
   "constants": [...],
   "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}`.

```json
{
  "action": "eval",
  "key": "macroResults",
  "value": "${myNS:getSomething()}"
}
```

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.

```json
{
  "action": "set",
  "condition": "${myNS:shouldExecute(true)}",
  "path": "$.path.to.json.node",
  "value": "${myNS:getJsonValue()}"
}
```

**See Also**
- [Work with App Template Framework Rules](https://developer.salesforce.com/docs/analytics/app-template-framework/guide/atf-rules-overview.md)