# `rules.json` Syntax

This page describes the JSON syntax for defining rule objects used in `template-to-app-rules.json` and `app-to-template-rules.json`. For background on how rules fit into the App Template Framework, see [Work with App Template Framework Rules](/docs/analytics/app-template-framework/guide/atf-rules-overview.md).

The `rules` object can contain any number of `rule` objects. A `rule` object is made up of:

| Attribute     | Type   | Example                                                | Required | Notes                                                                                                                                                                                                                                                                                 |
| ------------- | ------ | ------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | String | `"name": "ruleName"`                                   | Yes      | An identifier for the rule.                                                                                                                                                                                                                                                           |
| `condition`   | String | `"condition": "${Variables.foo == 'Yes'}"`             | No       | Use Freemarker conditions to apply the rules. Use the same syntax as `conditions` used in `template-info.json`.                                                                                                                                                                       |
| `appliesTo`   | Array  | `"appliesTo": [{"type": "dashboard", "name": "*"}]`    | Yes      | Use `"type": "*"` to apply to all JSON assets. Other valid values are `dashboard`, `lens`, `workflow`, `schema`, and `xmd`. Use the `name` string to reference specific JSON assets. The `name` can take `*` as well, to apply to all of one asset type or a group of one asset type. |
| `description` | String | `"description": "This rule adds strings to an array."` | No       | Use this to explain what the rule is doing.                                                                                                                                                                                                                                           |
| `actions`     | Array  | `"action": "set"`                                      | Yes      | There are six supported action types: `add`, `put`, `set`, `delete`, `eval`, and `replace`. Define as many actions as needed in the array.                                                                                                                                            |

## Rule Example with `appliesTo` Value

```json
{
    "name": "myRuleForWorkflowNodeDelete",
    "appliesTo": [
      {
        "type": "workflow",
        "name": "*"
      }
    ],
    "actions": [
      {
        "action": "delete",
        "description": "delete node from workflow",
        "path": "$.workflowDefinition.nodeName"
      }
    ]
}
```

## Actions Syntax for Rules

| Action    | Notes                                                                                                                                                                                                                                                                                                                                                                    |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `add`     | Adds an entry to an existing array. Needs `index` and `value`. `index` is 0 for the first element in the array, any number after that for the middle of the array. If `index` is larger than the array size, this action adds the `value` to the end of the array.                                                                                                       |
| `put`     | Add an attribute and value to an existing JSON value. Needs `key` and `value`. `value` can be a string or an array.                                                                                                                                                                                                                                                      |
| `set`     | Set a value on an existing JSON attribute. Needs `value`.                                                                                                                                                                                                                                                                                                                |
| `delete`  | Remove a node in the existing JSON tree.                                                                                                                                                                                                                                                                                                                                 |
| `eval`    | Evaluate the expression specified in `value` and assign results to the context variable specified by `key` (if set). Context attribute can be referenced using the expression: `${Rules.Eval.<variable_name>}`. The scope of the `eval` variable is the entire document if performed in a rule, or the macro if performed within a macro.                                |
| `replace` | Replace any text string throughout the entire document. Use when regular expressions are not an option. Can still use expressions. Instead of using the `replace` action, you can perform targeted search and replace (JSON Path) with `${string:replace(...)}`. In cases requiring regular expressions, use `${string:replaceFirst(...)}`, `${string:replaceAll(...)}`. |

### Example `add` Action

```json
{ 
    "action": "add",
    "description" : "Add desc",
    "path": "$.json.path.to.existing.json,array",
    "index": 0,
    "value": "value to add"
}
```

### Example `put` Action

```json
{ 
    "action": "put",
    "description" : "Put desc",
    "path": "$.json.path.to.existing.json",
    "key": "jsonAttributeName",
    "value": "new value"
}
```

### Example `set` Action

```json
{ 
    "action": "set",
    "description" : "Set desc",
    "path": "$.json.path.to.attribute",
    "value": "setValue"
}
```

### Example `delete` Action

```json
{ 
    "action": "delete",
    "description" : "Delete desc",
    "path": "$.json.path.to.delete"
}
```

### Example `eval` Action

The `eval` action retrieves the `sayHello` macro result and then the `set` action uses the result to set a value in a JSON path.

```json
[
    {
        "action": "eval",
        "description": "Evaluate the sayHello macro",
        "key": "helloResult",
        "value": "${myMacros:sayHello('Hello')}"
    },
    {
        "action": "set",
        "path": "$.path.json.node",
        "value": "${Rules.Eval.helloResult}"
    }
]
```

### Example `replace` Action

```json
{
    "action": "replace",
    "description": "Replace the amount field value",
    "key": "RPLCM_Opportunity_Amount_Field",
    "value": "${Variables.Opportunity_Amount.fieldName}"
}
```

**See Also**

- [Work with App Template Framework Rules](/docs/analytics/app-template-framework/guide/atf-rules-overview.md)
- [`rules.json` Attributes](/docs/analytics/app-template-framework/guide/atf-rules-json-attributes.md)