This is not the latest version of Identity Director documentation.
View available documentation.

Feature preview: Configure API Data Sources

Use API Data Source to synchronize data from an API Data Source, for example cloud based sources. Templates are available for Microsoft Graph API (5 templates) and Workday API (2 templates).

The feature is in the preview stage. Compatibility and templates for additional APIs may be added.

Prerequisites

Microsoft Graph API

  • Access to your Azure Active Directory
    • A Registered app with permission to Read directory data on the Microsoft Graph API

For more information on how to configure a registered app, please refer to Microsoft Azure documentation.

Workday API

  • Access to your Workday instance

Templates

Templates are available.

  • For the Microsoft Graph API, some fields are pre-filled (for example URL and Array Path, see below).
  • For the Workday API, a default set of columns to be returned is pre-filled for each template.

Properties tab

General

Field Explanation and Tips
Security context Specify the credentials to communicate with the API. For the Microsoft Graph API, the fields map as follows:
  • Client ID: Specify the Azure Application ID for the registered app.
  • Client secret: Specify the value of the Key you generated for Identity Director, in the Settings of the Registered app in Azure.
  • Tenant ID: The tenant ID for your Azure Active Directory

In Building Blocks of Data Sources, credentials of the Security context fields are not included. You have to set these credentials again after you import the Building Block.
URL Specify the URL to the resource you want to access.
Example: https://graph.microsoft.com/v1.0/users

Specific for Microsoft Graph API

Field Explanation and Tips
Array Path Specify the path to the array of data for the resource you want to access.

Combine Results

Select this option to combine data from two resources. Additional choices are:

  • (Combine results) to one:
    For each entry that is returned from the URL, a single value is returned from the Second URL.

    URL: https://graph.microsoft.com/v1.0/users
    Second URL: https://graph.microsoft.com/v1.0/users/{identifier}?$select=department
    Result:

    1. All users are retrieved from the URL, using the Array Pathvalue.
    2. To each user that was retrieved, the corresponding department is added from the Second URL.
    'Combine to one' as configured in the 'Users (with details)' template

  • (Combine results) to many from current URL:
    For each entry that is returned from the URL, a list of values is returned using the Second Array Path within the current URL.

    URL: https://graph.microsoft.com/v1.0/groups?$expand=members
    Array Path: value
    Second Array Path: members
    Result:

    1. All groups are retrieved from the URL using the Array Pathvalue.
    2. To each group that was retrieved, the corresponding members are added, using the Second Array Path members.
    'Combine to many using another URL' as configured in the 'Classification (single URL)' template

  • (Combine results) to many from another URL:
    For each entry that is returned from the URL, a list of values is returned from the Second URL.

    URL: https://graph.microsoft.com/v1.0/groups
    Array Path: value
    Second URL: https://graph.microsoft.com/v1.0/groups/{identifier}/members?$select=id,userPrincipalName
    Second Array Path: value
    Result:

    1. All groups are retrieved using the URL using the Array Pathvalue.
    2. To each group that was retrieved, the corresponding members are added from the Second URL, using the Second Array Path value.
    'Combine to many from another URL' as configured in the 'Classification (two URLs)' template

Property to combine by*

Specify the property that can be used to match data from the two resources (URL and Second URL).

Second URL*

Specify the URL to the second resource you want to access.
Example: https://graph.microsoft.com/v1.0/users

Second Array Path*

Specify the path to the array of data for the resource you want to access using the second URL.

* Availability of these fields depends on your configuration of Combine results.

Columns tab

Configure the columns that should be returned by the Data Source.

Filter tab

Optionally, filter out irrelevant data from the external data.

Using filters can have a significant impact on the performance of retrieving data from the Data Source. In these cases, consider including filter parameters in the URL field (on the Properties tab) instead.
For more information about using filters and other query parameters, see:

Diagnostics tab

  • The Preview Data tab shows a preview of the data.
  • The Data Connections tab shows which data connections currently use the Data Source.
See also