Incremental Updates

Modifying custom providers using a partial OAA payload

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.

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

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:

  "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 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).

{
  "incremental_change": true,
  "applications": [
    {
      "name": "Controller1",
      "application_type": "WebServer",
      "description": "The base web server",
      "local_users": [
        {
          "name": "LUser1",
          "identities": [
            "[e-mail]"
          ],
          "operation": "delete"
        },
        {
          "name": "LUser1",
          "identities": [
            "[e-mail]"
          ],
          "operation": "add"
        }
      ],
      "local_groups": [
        {
          "name": "LGroup1",
          "identities": [
            "[e-mail]"
          ],
          "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": "[e-mail]",
      "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": "[e-mail]",
      "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"
        }
      ]
    }
  ]
}