Connector for Workday

The Workday connector imports user attributes from Workday using the Reports-as-a-Service API. This integration allows you to import specific user attributes to enhance targeting capabilities in Nexthink Adopt. While Adopt is the primary use case, the imported data can also be leveraged by any Nexthink feature that supports custom fields. The connector only supports Basic authorizations.

Prerequisites

Before configuring the Workday connector, ensure you complete the following:

  • Create a custom report in Workday.

  • Configure connector credentials in Nexthink. Refer to the Connector credentials documentation for more information.

Creating a report in Workday

  1. Navigate to the Create Custom Report page in Workday.

  2. Configure the report:

    • Choose Advanced as the report type.

    • Provide a meaningful Report Name.

  3. To ensure the report returns data quickly, select the Web Service and Optimized for Performance options. The data source depends on the data being collected, but the standard recommendation is to use Indexed All Worker.

  4. Add required report fields that include user identifiers such as email or UPN.

  5. After creating the report, generate a URL for Nexthink to use. The URL format is: https://<tenant>.workday.com/ccx/service/customreport2/<tenant>/<report_path>

  • Split the URL into two parts for configuration:

    • Base URL for connector credentials: https://<tenant>.workday.com

    • Resource path: /ccx/service/customreport2/<tenant>/<report_path>

Refer to the official Workday community documentation for more information.

Configuring the Workday connector

From the Nexthink web interface:

  1. Go to Administration > Inbound connectors.

  2. Click the New connector button in the top-right corner of the page.

  3. Select Workday: User Attributes from the connector list.

The General tab includes:

  • Name: A meaningful name for the connector. This name appears on the administration page.

  • NQL ID: A unique identifier for the connector used when referencing the Workday connector in NQL queries. You can initially modify the suggested NQL ID, but once you save the workflow, you can no longer change the NQL ID.

  • Description: A short description of the purpose and behavior of the connector.

  • Scheduling:

    • Recurrence: Set the execution time and recurrence. Executions start at the scheduled time and distribute over the hour.

  • Connection:

    • Credentials: Select preconfigured credentials from the Connector credentials page. Only BasicAuth is supported. Refer to the Connector credentials documentation for more information.

    • URL: This URL is automatically populated when you select credentials.

The Parameters tab includes:

  • Report resource: Enter the full path to the Workday report. For example, /ccx/service/customreport2//<report_path>

The Data mapping tab includes:

  • Identification: Select a field from the API response to be used to identify users.

    • Source identifier (JSONata): Enter the field name returned by the API response that identifies users. Use JSONata if needed to transform the value.

    • Nexthink identifier: Select either UPN (requires UPN collection via Collector) or Email address (requires the Entra ID connector).

  • Field Mapping: Click Add mapping to match custom fields defined on the user object.

    • Source identifier (JSONata): Enter the field name returned by the API response that identifies users. Use JSONata if needed to transform the value.

    • Nexthink field: Select the custom field to import the value.

Known limitations

  • If employees share the same UPN, the UPN-based identification only processes the first 1,000 user records.

  • User Principal Name (UPN) requires configuration in Collector.

  • Email address requires the Entra ID (Azure AD) connector.

  • The Workday API imposes the following restrictions:

    • A report can contain between 1 million and 3 million records, depending on post-processing, 1 million if grouping is enabled.

    • The report output cannot exceed 2 GB in size.

Refer to the official Workday community documentation for more information.

Querying execution logs with NQL

Using NQL, retrieve detailed insights into the execution of Workday connector instances by querying the following table:

Field
Type
Description

time

datetime

Timestamp of the connector execution log entry.

status

enumeration

Execution status: • success: All rows received and processed. • partial: Some rows ignored due to row limit. • failure: Connector could not receive or process data.

details.name

string

Name of the connector instance.

details.description

string

Description of the error(s), if any. Includes descriptions such as: • Too many rows received...Invalid JSONata expression for field

details.connector

string

Name of the connector template used.

details.credentials

string

Label of the credentials used in the instance.

details.credentials_id

string

Unique identifier of the credentials.

details.nql_id

string

NQL ID of the connector instance.

details.number_of_received_rows

number

Total number of rows received from the source.

details.number_of_processed_rows

number

Total number of rows processed by the connector—may differ from imported rows.

Run the platform.inbound_connector_logs query to retrieve comprehensive logging information about all inbound connector executions.

NQL examples

Retrieve failed imports for the last 24h
platform.inbound_connector_logs during past 24h | where status == failure | list time, details.connector, details.name, details.error_description | sort time desc
Retrieve imports for the last 24h (including status and number of processed rows)
platform.inbound_connector_logs during past 24h | list time, details.connector, details.name, details.number_of_processed_rows | sort time desc

Last updated

Was this helpful?