# Incremental Updates

{% hint style="success" %}
When developing your OAA integration, whether to implement incremental updates depends on your use case. If you don't have a convenient way to track provider-side changes, it is typically easier to do a full extraction and metadata push, to not miss changes within the app or IdP.
{% endhint %}

After the initial metadata push, you can modify, add, or remove OAA entities, permissions, and properties without needing to submit the full payload each time. A first push can't be an incremental update.

An incremental update is specified by setting `"incremental_change": true` in the `json_data` push payload and adding an update `operation` for each entity to change. Most payload objects support incremental update operations:

| Custom Application                                            | Custom Identity Provider |
| ------------------------------------------------------------- | ------------------------ |
| application, user, group, role, permission, role\_assignments | domain, group, user      |

The `operation` field indicates the change to make. Valid `operation`s are:

* `"add"`, `"modify"`, `"delete"` to create, change, or remove an entity.
* `"add_resource"`, `"delete_resource"` to modify resources in applications, permissions and role scopes.
* `"add_tag"`, `"delete_tag"` to update a tag without altering the entity.

The object to update must contain an ID (`name` or `identity`) and the properties to create or modify. An error response will provide more details if an operation is invalid or unavailable.

See the sample payload below for [more examples](#sample-payload).

### Notes

* When modifying dynamic properties, all five properties must be present.
* `add` and `modify` can't be used on the same object. For example, to update both tags and properties on an entity, use:

```json
  "resources": [
    {
      "name": "resource1",
      "resource_type": "type1",
      "tags": [
        {
          "key": "keyDelta1",
          "value": "valDelta1"
        }
      ],
      "operation": "add_tag"
    },
    {
      "name": "resource1",
      "resource_type": "type1",
      "operation": "modify"
    }
  ]
```

#### Sample payload

The following JSON example for [custom application](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/templates/custom-application-template.md) includes a range of update operations. Note that when modifying tags, only include the identity and tags (no other properties such as `manager_id` can be present).

```json
{
  "incremental_change": true,
  "applications": [
    {
      "name": "Controller1",
      "application_type": "WebServer",
      "description": "The base web server",
      "local_users": [
        {
          "name": "LUser1",
          "identities": [
            "localuser1@company.com"
          ],
          "operation": "delete"
        },
        {
          "name": "LUser1",
          "identities": [
            "localuser1Mod@company.com"
          ],
          "operation": "add"
        }
      ],
      "local_groups": [
        {
          "name": "LGroup1",
          "identities": [
            "localgroup1@company.com"
          ],
          "tags": [
            {
              "key": "groupTag2Key",
              "value": "groupTag2Value"
            }
          ],
          "operation": "add_tag"
        }
      ],
      "local_roles": [
        {
          "name": "LRole2",
          "permissions": [
            "FULL"
          ],
          "operation": "delete"
        }
      ],
      "resources": [
        {
          "name": "resource1",
          "sub_resources": [
            {
              "name": "sub1b",
              "operation": "delete"
            }
          ],
          "operation": "modify"
        }
      ]
    }
  ],
  "permissions": [
    {
      "name": "Just Access",
      "operation": "modify"
    },
    {
      "name": "NonData",
      "PermissionType": [
        "NonData"
      ],
      "operation": "add"
    },
    {
      "name": "READ",
      "permission_type": [
        "DataRead"
      ],
      "operation": "delete"
    },
    {
      "name": "READ",
      "permission_type": [
        "DataRead"
      ],
      "operation": "add"
    }
  ],
  "identity_to_permissions": [
    {
      "identity": "testuser1@company.com",
      "identity_type": "IDP",
      "role_assignments": [
        {
          "application": "Controller1",
          "role": "LRole1",
          "apply_to_application": true,
          "operation": "delete"
        },
        {
          "application": "Controller1",
          "role": "LRole2",
          "resources": [
            "resource1",
            "resource1.sub1a.sub2b"
          ],
          "operation": "add"
        }
      ]
    },
    {
      "identity": "testuser3@company.com",
      "identity_type": "IDP",
      "role_assignments": [
        {
          "application": "Controller1",
          "role": "LRole1",
          "resources": [
            "resource1.sub1b",
            "resource1.sub1c"
          ],
          "operation": "delete_resource"
        },
        {
          "application": "Controller1",
          "role": "LRole1",
          "resources": [
            "resource1.sub1a"
          ],
          "operation": "add_resource"
        }
      ],
      "application_permissions": [
        {
          "application": "WebServer2",
          "permission": "Just Access",
          "operation": "delete"
        }
      ]
    }
  ]
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/oaa/best-practices/incremental-updates.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.