# Identity Aggregation Completed

The platform has introduced an event trigger within the Source Aggregation workflow to provide additional monitoring capabilities. This helps to ensure account aggregations are performing as expected and that identity data always reflects current source account information for better identity governance.

Flow

After the initial collection of accounts in the source system during aggregation completes, this event trigger can:

  • Notify an administrator that IdentityNow was able to successfully connect to the source system and was able to collect source accounts.
  • Notify an administrator when the aggregation is terminated manually during the account collection phase.
  • Notify an administrator or system (e.g. PagerDuty) that IdentityNow failed to collect accounts during aggregation and indicate required remediation for the source system.

# Getting Started

# Prerequisites

  • An oAuth Client configured with Authority as ORG_ADMIN.
  • An org configured with a Source with a Direct Connection.

# In This Topic


# Event Context

Aggregations connect to a source and collect account information from the source to discover the number of accounts that have been added, changed, or removed. For more information about account aggregation see Account Aggregation Data flow (opens new window)

This event trigger does not include entitlement aggregation.

The source account activity is summarized in stats e.g:

"stats": {
            "scanned": 200,
            "unchanged": 190,
            "changed": 6,
            "added": 4,
            "removed": 3
        }

In this example, there are 10 changed accounts (scanned (200) - unchanged - (190)). Changed accounts include accounts that are added (6) and accounts that are changed (4), which equals 10 accounts. Removed accounts may or may not be included in the changed account total depending on the sources. For this example, removed (3) may be considered a changed account in some sources and would show a scanned count of 203 instead of 200.

This event trigger will fire even without changed accounts. The unchanged count will match the scanned accounts in the response.

This event trigger is particularly useful whenever there are issues connecting to the source during aggregation.

started and completed time stamps are in ISO8601 format.

# Aggregation Status

Success Account collection successful and aggregation can move to the next step.

Termination Aggregation was terminated during the account collection phase. Aggregation can be terminated when the account deletion threshold is exceeded. For example, an account delete threshold of 10% is set by default for the source and if the number of removed accounts for the above example is 21 (more than 10% of scanned accounts (200)), the aggregation is cancelled.

Account_Delete_Threshold

Error There is failure in account collection or issues with connecting to the source. errors vary by source.

# View the Trigger

To view the aggregation-accounts-collected event trigger, use the following command:

curl --request GET --url 'https://{tenant}.api.identitynow.com/beta/triggers' --header 'authorization: Bearer {access_token}'

# Trigger Type

This event trigger type is a FIRE_AND_FORGET type. When you subscribe to this event trigger with your HTTP endpoint, a response is not expected to be returned.

# Input Schema

The input schema defines what you will receive to your subscription. Here is input example provided by the trigger:

{
    "stats": {
        "scanned": 200,
        "unchanged": 190,
        "changed": 6,
        "added": 4,
        "removed": 3
    },
    "warnings": [
        "Account skipped"
    ],
    "started": "2020-06-29T22:01:50.474Z",
    "source": {
        "id": "4e4d982dddff4267ab12f0f1e72b5a6d",
        "name": "Corporate Active Directory",
        "type": "SOURCE"
    },
    "completed": "2020-06-29T22:02:04.090Z",
    "errors": [],
    "status": "Success"
}
  • status - The overall status of the aggregation. This is usually "Success", "Failed", or "Terminated".
  • started - The time when the aggregation started.
  • completed - The time when the aggregation completed (either successfully or not).
  • source - A reference to the source which is executing the aggregation. Can be used to get more information (like connector, owner, VA cluster, etc.)
  • errors - A list of error messages accumulated during the aggregation.
  • warnings - A list of warning messages accumulated during the aggregation.
  • stats - These are overall statistics accumulated during the aggregation.
    • scanned - The number of accounts which were scanned / iterated over.
    • unchanged - The number of accounts which existed before, but had no changes.
    • changed - The number of accounts which existed before, but had changes.
    • added - The number of accounts which are new - have not existed before.
    • removed - The number accounts which existed before, but no longer exist (thus getting removed).

# Subscribe to the Trigger

To subscribe to the Identity Aggregation Completed even trigger, make a POST call to /beta/trigger-subscriptions with the following headers and body:

Headers:

  • Authorization: Bearer <access_token>

Body:

{
   "triggerId":"idn:aggregation-accounts-collected",
   "type":"HTTP",
   "httpConfig":{
      "url":"https://urlOfTheExternalService.com",
   }
}

# Filter Example

If you need to only be aware of issues of connecting to a source so that integration can be quickly remediated, try the following filter:

$[?($.status == "Error")]

Filters follow the Goessner JSON Path (opens new window).

# Testing

To test aggregation, manually aggregate using the Admin UI in IdentityNow.

Manual_Aggregation

For testing receiving event triggers, you can try these tools:

  • webhook.site (opens new window) - This tool creates a temporary HTTP endpoint for you to verify that you are able to successfully subscribe to the Event Trigger. You can receive the event after an access request has been submitted. Copy the "unique URL" from webhook.site and use it in the url field of the POST body to /beta/trigger-subscriptions.
  • localhost.run - This tool creates an endpoint for a HTTP server running on your local machine.