Workiva Support Center

With the Workiva connector, you can use commands in chains to interact with the Workiva platform, including other Wdata features, Spreadsheets, and GraphDB. For example, with this connector, you can:

• Create and manage tables, queries, and views
• List a table's datasets or import errors
• Create and manage spreadsheets or their sheets
• Manage records and reports

Requirements

To interact with the Workiva platform, the connector uses the Workiva REST APIs. To set up the connector, you'll need:

• A dedicated Workiva integration user with an OAuth2 grant.

  Note: This integration user requires appropriate permissions for the commands the connector performs, such as Owner of the spreadsheets or workspace it interacts with.

• The integration user's OAuth2 grant ID and secret.
• To run the chain in a test environment, the URLs to override the API's hosts and base paths.

Note: While the workspace's 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.

Set up the Workiva connector

1. From Chain Builder, click Connections  compare_arrows, and then Create at the top right.
2. Under Create Connection, select Workiva and the default CloudRunner.
   
3. Under Basic Info, enter a unique name and description to help identify the connector.

4. Under Resources, select the resources to associate with this connection.
   This section provides a secure location for any files (scripts, security tokens, certificates, etc.) that the connector needs to function, such as for authentication or environment requirements. When you save the connection, these files are automatically AES-256 encrypted. For more information, refer to the Workiva Chain Builder security architecture Support page.

   Advantages:

   • Safe storage: Because these files are encrypted upon saving and stored at the connection level, they are ideal for sensitive or static configuration data that shouldn't be hard-coded into the chain itself.
   • Portability: If you move your chain from a "Test" workspace to a "Production" workspace, the resources stay tied to the Connection settings, meaning you don't have to rewrite the file paths in your chain nodes.
   • Accessibility: Storing the files here makes the files available to the Runner (the agent executing the task) without requiring the file to be manually placed on the runner's physical host machine.

   Disadvantages:

   • Because they are encrypted, they cannot be edited directly; you have to delete the file and upload the changed version.

5. Under Properties, enter the connection's details:
   

   Property	Details
   ID	Enter the ID for the integration users' OAuth grant.
   Secret	Enter the secret for the ID property.
   Cerebral host override	To override the URL host and base path for the Wdata endpoints, such as for a test environment, enter the URL to use instead.
   Spreadsheets host override	To override the URL host and base path for the Spreadsheets endpoints, such as for a test environment, enter the URL to use instead.
   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.
   Admin host override	To override the URL host and base path for the Admin endpoints, such as for a test environment, enter the URL to use instead.
   GraphDB host override	To override the URL host and base path for the GraphDB endpoints, such as for a test environment, enter the URL to use instead.
   Platform API host override	To override the URL host and base path for the Workiva platform endpoints, such as for a test environment, enter the URL to use instead.

   Note: All sensitive credentials are automatically encrypted and stored using AES-256 encryption.

6. Select the environments to use the connection, and click Save.
7. To test the connection, create and run a chain with the connector's List Files command, and verify it returns a valid output.

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.

Troubleshooting

If the connection to the Workiva platform fails:

• Verify that the connector's application OAuth credentials are present, correct, and valid. OAuth credentials have defined expiration dates, and the certificate may have expired. If this is the case, you will need to create a new certificate and enter the new client secret in the Connector. 
• Ensure the integration user has appropriate permissions for the command being performed.
• If using a host override, check the that URL entered for the connector is correct.

• Verify that the ID of the Workiva file —such as the table, query, or spreadsheet— being interacted with is correct.

  Note: A file's ID appears in its URL when open in Workiva. For example, a spreadsheet's ID appears after spreadsheet/ in its URL; a table's ID appears after tables/.