Connect Workday Adaptive Planning#

Reportworq refreshes Workday Adaptive Planning OfficeConnect reports. An OfficeConnect report is an Excel workbook whose query specifications are stored in hidden properties on each worksheet. Reportworq reads those embedded specifications and queries the Adaptive Planning API to update the workbook - so a report that a finance user built in the OfficeConnect Excel add-in can be refreshed, parameterized, burst, and distributed by Reportworq without anyone reopening it in Excel.

In the connector catalog the tile is Workday Adaptive Planning. This is the planning product on the Adaptive Planning API - it is not the same as the Workday connector, which reaches Workday itself (Financial Management and HCM). Adding the wrong one is the most common mistake here; see the Connector catalog.

The connector supports three authentication types:

• Basic Credentials - a username and password, the same credentials the Workday Adaptive OfficeConnect add-in uses.
• Adaptive Token - a single Adaptive authentication token.
• Workday OAuth - token-based access using a Workday API client. This is the mode this guide focuses on, because it is the one that needs API access set up in Workday and Adaptive first, and it is the mode Reportworq automates the most for you.

How Workday OAuth authentication works#

Reaching the Adaptive Planning API with a Workday API client is a two-step token exchange, and in older setups administrators performed it by hand (for example, in Postman) on every token refresh:

1. Call the Workday token endpoint with the client id, client secret, and a refresh token to get a short-lived Workday access token.
2. Call the Adaptive token endpoint with that access token to get an Adaptive public API token, which authenticates the actual Adaptive Planning API calls.

Reportworq does this exchange for you. In Workday OAuth mode you enter five values once, and at run time Reportworq requests a fresh Workday access token, exchanges it for an Adaptive public API token, and reuses that token for the rest of the operation. You do not paste tokens into Reportworq, and you do not need Postman to keep a token alive - you only supply the durable client id, client secret, and refresh token.

The remaining one-time work - creating the API user, the security group, the API client, and the refresh token in Workday and Adaptive - is done in Workday and Adaptive by a Workday administrator, and is described next.

Before you begin#

• You are a Reportworq administrator. Only administrators can add or configure datasource connections.
• The Reportworq server can reach the Adaptive host over the network. The connection is outbound from the Reportworq server to the Adaptive host on port 443. If your network restricts outbound traffic, allowlist the Adaptive host by hostname (Workday runs Adaptive on AWS and the published IP ranges rotate). See Connect a Workday Adaptive sandbox or non-US environment.
• A Workday administrator can perform the Workday- and Adaptive-side setup below, or has already done it and can give you the five values Reportworq needs. The exact menu labels belong to Workday and can vary by tenant and release; follow Workday's own documentation for the current steps, and treat the outline below as the shape of the task, not a substitute for it.

Set up API access in Workday and Adaptive#

This is the one-time setup that Reportworq does not automate, because it happens inside Workday and Adaptive. The goal is to end up with a dedicated integration user, a Workday API client that can reach the Adaptive Planning API, and a refresh token for that client.

1. Create the public API user in Adaptive#

1. In Adaptive, under Tenant Setup / Public APIs, create a new API user. The API user is added to Adaptive immediately; it does not need to go through the user-sync process.
2. Edit the user in Adaptive Administration and give it the access the integration needs: assign it to the Administrator group with access to all levels. If your Adaptive tenant has child instances, grant the user top-level access in each child instance too, keeping the default instance as the parent.
3. If Access Rules are enabled in your tenant, make sure the API user is covered by a rule that grants access to all levels and all dimensions. A public API token can only ever see what its user is entitled to, so an under-provisioned user is the usual reason data comes back empty or partial.

2. Create an integration security group in Workday#

1. In Workday, create a new Integration System Security Group (Unconstrained) for this integration. Do not reuse a security group created for other integrations.
2. Assign the new API (integration) user to the group.
3. Grant the group the Adaptive Planning API domains it needs - typically Adaptive Planning API Access, Adaptive Planning, and Adaptive Planning Integration - with the get/put and view/modify access your Workday administrator determines, then activate the pending security changes.

3. Register the Workday API client#

1. In Adaptive, under Integrations / Design Integrations / Credentials, create a new Workday Credential and copy its certificate.
2. In Workday, register a new API client with the client grant type set to JWT (JWT bearer). Add an x509 certificate using the certificate you copied from the Adaptive Workday Credential.
3. Set the client's scope to the Adaptive Planning scopes the integration needs (for example, Adaptive Planning, Adaptive Planning for Financial Plans, and Adaptive Planning for the Workforce, plus the system/tenant scopes your administrator requires).
4. Copy the resulting client id back into the Adaptive Workday Credential and add the integration user, then test the connection in Adaptive to confirm the client can reach the tenant.

It is worth validating the new user inside Adaptive before going further - for example, by building a Planning Data Source with the new credential and importing data. Adaptive uses the same API under the hood, so a successful import is a good sign the user and client are provisioned correctly.

4. Generate a refresh token#

1. In Workday, register (or open) the API client for integrations for this integration and copy its client id and client secret.
2. From that API client, choose the action to manage refresh tokens for integrations, select the integration user, and generate a new refresh token. Copy and store it securely - this is the refresh token Reportworq will use.
3. Note the token endpoint for the API client (Workday shows it on the View API Client task). This is the Workday Token Url you give Reportworq.

Gather the five values Reportworq needs#

For Workday OAuth mode, collect these five values from the setup above:

In both URLs, <gateway> is your Workday gateway host and <tenant> is your Workday tenant. Treat the client secret and refresh token like passwords: do not paste them into email, chat, or a screenshot. Reportworq stores them encrypted on the connection.

Add the connection in Reportworq#

1. Sign in to Reportworq as an administrator and go to Settings > Integrations. Datasource connectors live under the DATASOURCES heading.

2. Select Add integration, find Workday Adaptive Planning in the catalog, and add it. The connection editor opens.

   Screenshot coming soonThe Reportworq Workday Adaptive Planning connection editor, showing Datasource Settings and Authentication Settings

3. Select Enable datasource connection and give the connection a Datasource Name (for example, Adaptive). This name is how parameters and formulas refer to the datasource, so it must be unique across the instance and is awkward to change later.

4. Under Authentication Settings, set Authentication Type to Workday OAuth.

5. Set the API URL for your environment. Leave it blank for US production. For a sandbox, a preview environment, or a non-US region, use the examples menu on the field or enter the host by hand - for example https://api.sbox.adaptiveplanning.com. Enter only the host; Reportworq appends the API path and version itself. See Connect a Workday Adaptive sandbox or non-US environment.

6. Set the Instance Code if you need a specific Adaptive instance. Leave it blank to use the default instance.

7. Enter the five Workday OAuth values you gathered: Workday Token Url, Adaptive Token Url, Workday ClientId, Workday Secret, and Workday Refresh Token.

   Screenshot coming soonThe Workday OAuth fields in the Reportworq connection editor: Workday Token Url, Adaptive Token Url, Workday ClientId, and the masked Workday Secret and Workday Refresh Token

8. If your Reportworq instance is licensed for Data Collection and you want data collection (writeback) to authenticate as a different user, select Use different credentials for data collection and fill in the Data Collection Credentials. Otherwise the connection's credentials are used for both.

9. Select Test connection. A reachable, correctly configured connection returns "Success." If it fails, re-check the URLs, the client id, secret, and refresh token, the API user's Adaptive access, and the Reportworq server's outbound network access to the Adaptive host, then test again.

10. Select Save.

Refresh OfficeConnect reports in a job#

Once the connection tests, Reportworq can refresh OfficeConnect workbooks that were built against this Adaptive tenant:

• Add the OfficeConnect workbook as a source report in a Distribution Job. Reportworq reads the query specifications embedded in the worksheets and refreshes the data from Adaptive at run time.
• Use Reportworq Parameters to copy sheets and adjust the filter elements in the report specifications. The connector adds a Workday Adaptive Planning Dimension parameter type, driven by Adaptive dimension or attribute values, for manual lists or attribute-sourced lists, and for choosing whether leaf, consolidated, or both kinds of members are used. See Parameterize a report and Burst with parameters.
• Reportworq also provides Adaptive-specific worksheet formulas for reading and writing Adaptive data. See Workday Adaptive functions.

Behavior and limits#

• Reportworq handles the token exchange. In Workday OAuth mode you supply only the client id, client secret, and refresh token; Reportworq requests a Workday access token and exchanges it for an Adaptive public API token at run time and reuses it for the operation. Keep the refresh token current - if it is revoked or expires, refreshes fail until you generate a new one and re-enter it.
• Metadata is cached. Reportworq keeps a local cache of the Adaptive dimensional structure so a job fetches only data values, not the whole structure. The cache defaults to 24-hour freshness. After a structure change in Adaptive, use Refresh Metadata on the connection (save any edits first).
• Access is set by the API user, not by Reportworq. The public API token can see only what its Adaptive user is entitled to. If levels, dimensions, or instances are missing, widen the API user's access in Adaptive rather than changing anything in Reportworq.
• A sandbox is a different host, not a flag. Point API URL at the environment's host; blank means US production. The version segment stays managed by Reportworq.
• Advanced options. The connection's Timeout (seconds) defaults to 600, and Allow multi-threaded sheet processing is available for large workbooks.
• Only administrators can add or configure the connection, and editing, disabling, renaming, or deleting a live datasource breaks every job and form that refreshes from it. See Connect a data source.

Troubleshooting#

Related#

• Connect a data source for the general add, test, and manage flow.
• Connector catalog for the environment hosts, network allowlisting, and the per-connector traps.
• Workday Adaptive functions for the Adaptive-specific worksheet formulas.
• Data models for building curated, reusable Adaptive data for report authors.
• Workday: Authentication URLs and IP addresses for the authoritative list of environment hosts and IP ranges.