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

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

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

Specific Information for Microsoft Graph API

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.
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 Path value.
    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 Path value.
    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 Path value.
    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.

Specific Information for Workday API

Field Explanation and Tips
Security context Specify the credentials to communicate with the API. For the Workday API, you only need to provide the appropriate user name (in “user@tenant” format) and password.
URL

Specify the URL to the resource you want to access.

In this case, you need provide the WSDL (Web Services Description Language) URL of the Workday Human Resources web service.

To find the WSDL URL, you need to access your Workday instance and locate the service.

Workday Users Connector Configuration

Configure your Workday Users Data Source, using from the provided template.

  1. In the Setup and Sync Tool, go to Data Model > Data Sources. Click on the Add button in the Data Sources window.


    API Data Source 'Workday-Users-1'

  2. In the Select template window, select the Users template from the Workday API section.


    Select template

  3. On the Properties tab, provide basic data for the new Data Source: the connection name, the URL of the Human Resources Workday web service, the user name, and the password.


    Select template

  4. On the Diagnostics tab, make sure the credentials work and data can be retrieved.


    Preview Data

Columns tab

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

Clicking on the Add button will allow you to select and display additional columns.

Add additional columns

After the Data Source has been configured successfully, you can now set up a People Data Connection. See Configure people data connections.

Filter tab

Optionally, filter out irrelevant data from the Data Source.

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