Before you Begin: Prerequisites and team assembly

To build chains, the following team members may be required: Workiva administrator, source system administrator, network engineer, and infrastructure engineer. Complete the following before starting step 1.

• Understand source system API and/or integration method. Obtain necessary permissions and create an integration user if required. Contact source system vendor for assistance if needed.
• Review Wdata Connectors.
• Complete the following trainings:
  1. Introducing the Data Management Suite
  2. Data Management: Using Wdata
  3. Data Management: Using Chains & Data Prep
  
  If you'd like the complete the full trainings, and not just the three sections above, the full training courses are below:
  4. Data Management
  5. Using the Data Management Suite
  6. Data Management Workshop (instructor led training that can be taken after completion of 5)
• Review all sections within Intro to Wdata, Tables, and Chains.
• Review Connections you will use.
• Become familiar with available Chain Template and Samples as use of these within Chain(s) when possible is leading practice.
• Optional—Review developer documentation for the Workiva API(s) you intend to use within your Chain(s).

Step 1: CloudRunner/GroundRunner

The first step to building a chain is to determine if the source system being connected is cloud-based or on-premises. For cloud-based and systems accessible over the internet, chains can use the CloudRunner agent to execute. For on-premises systems or those not accessible over the internet, chains will need to use a GroundRunner agent to execute.

The security architecture for the runners is here. System requirements, installation, and managing GroundRunners help is here.

Step 2: Allow hosts and emails for Workiva

To ensure that chain processes and GroundRunners can communicate to the necessary endpoints, allowing hosts may need to be applied within your network. The full allow hosts and emails list for Workiva can be found here.

Step 3: Workiva integration user and OAuth2 Grant

Workiva recommends creating Workiva platform user(s) dedicated to integrations. Information on how to create integration users is here. Add necessary read/write permissions for the user to the specific Workiva object(s) in use such as a Wdata Table. Table permission information is here.

Using the integration user or your own username for testing, create an OAuth2 Grant. The client ID and client secret from the grant will be used to authenticate with Workiva APIs. Here is information on how to create an OAuth2 Grant. Here is information on how to generate/view the grant secret. Optional: Here is developer documentation for authentication.

Step 4: Configure a Workiva connection

Within the chain builder, click on “Connections” in the left menu. Here is information for configuring the Workiva connection using the Client ID and Client Secret from the previous step. Additionally, the GroundRunner from step 1 can be selected if in use. Repeat this step to create a connection for the source system as well. If the source system connector is disabled, please work with your Workiva Organization Security Administrator to enable it by following the instructions here.

Step 5: Chain builder

Within the chain builder, click on “Build” in the left menu. Start building a new chain by clicking the “Create” button in the top right corner and select "Create Chain". Complete documentation of all chain connections and commands is here. You may need to reach out to the source system provider for their system’s documentation. Here are some step-by-step instructions for template and sample chains.