The Workiva Chains connector provides common commands for workspaces, environments, and chains. This includes list and get commands used for retrieving properties, details of chain runs, login activity events, and more.
For a full list of compatible commands, see the Workiva Chains commands article.
Requirements
Before using the connector:
- An org security administrator must enable the Workiva Chains connector through the Configurations screen.
- To run the chain in a test environment, you'll need the URLs to override the API's hosts and base paths.
- You must create a dedicated integration user with an OAuth2 grant within your software.
- To find your chain IDs, view this article on finding IDs in Workiva.
Additional requirements for the integration user
While all workspace owners can access chains that use the connector, the connector itself requires a dedicated integration user to perform its commands. Using a dedicated integration user—instead of a collaborator's user account—enables to you track the connector's activity and limit its access to only what it needs to perform its commands.
The following is required when setting up the integration user:
- You must know the integration user's OAuth2 grant ID and secret.
- You must provide the integration user with appropriate permissions for each command the connector will perform; for example, they might be the Owner of the spreadsheet or workspace the connector interacts with.
- The integration user must log in to Chain Builder before they can execute any commands. This is necessary to establish the user's account.
Connection Setup
To set up the Workiva Chains connector:
- From Chain Builder, click Connections , and then Create at the top right.
- Under BizApp Connection, select Workiva Chains and the default CloudRunner.
- Under Basic Info, enter a unique name and description to help identify the connector.
- Under Properties, enter the connection's details:
Property Details Base URL The Base URL; defaults to https://h.app.wdesk.com/s/wdata/oc/api/ ID Enter the ID for the integration users' OAuth grant. Secret Enter the secret for the ID property. IAM host override To override the URL host and base path for the Identify and Access Management (IAM) endpoints, such as for a test environment, enter the URL to use instead. - Select the environments to use the connection, and click Save.
URL Overrides
Depending on the region of your production environment an override URL may apply. You can verify this by comparing against the URL used to log into Wdesk. If the URL contains EU or APAC an override is required.
Note: US region information is listed for reference.
| Field | Value |
|---|---|
| Cerebral Host Override | https://h.app.wdesk.com/s/cerebral |
| Spreadsheets Host Override | https://api.app.wdesk.com/spreadsheets/v1/ |
| IAM Host Override | https://api.app.wdesk.com/iam/v1/oauth2/token |
| Admin Host Override | https://api.app.wdesk.com/admin/v1 |
| Graph DB Host Override | https://api.app.wdesk.com/graphdb/v1/ |
| Platform API Host Override | https://api.app.wdesk.com/platform/v1 |
| Field | Value |
|---|---|
| Cerebral Host Override | https://h.eu.wdesk.com/s/cerebral |
| Spreadsheets Host Override | https://api.eu.wdesk.com/spreadsheets/v1/ |
| IAM Host Override | https://api.eu.wdesk.com/iam/v1/oauth2/token |
| Admin Host Override | https://api.eu.wdesk.com/admin/v1 |
| Graph DB Host Override | https://api.eu.wdesk.com/graphdb/v1/ |
| Platform API Host Override | https://api.eu.wdesk.com/platform/v1 |
| Field | Value |
|---|---|
| Cerebral Host Override | https://h.apac.wdesk.com/s/cerebral |
| Spreadsheets Host Override | https://api.apac.wdesk.com/spreadsheets/v1/ |
| IAM Host Override | https://api.apac.wdesk.com/iam/v1/oauth2/token |
| Admin Host Override | https://api.apac.wdesk.com/admin/v1 |
| Graph DB Host Override | https://api.apac.wdesk.com/graphdb/v1/ |
| Platform API Host Override | https://api.apac.wdesk.com/platform/v1 |