Get started with chains

With Chains, you can automate routine tasks, with easy integration to retrieve or send data across multiple systems of record. For example, you can create a chain to automatically pull financial information from a data source into a table, and then push that data to another system to generate a report. In Chain Builder, you arrange and link the tasks—or commands—a chain should perform.

Note: Only Workspace Owners or Chain Owners can access Chain Builder. From Wdata, click Chains, and then click Open Chain Builder. 

With the exercises in Get started with tables and Get started with queries, you create tables and queries like those used for financial reporting. In this exercise, let's create a chain to run that query and export its results to Spreadsheets. 

Step 1. Get the query's ID and parameters

If you haven't already, download the sample data and perform the Get started with tables and Get started with queries exercises, as you'll use the query in the chain. Note the query's ID, which is how you'll identify the query in the chain.

Note: When you open a query in Wdata, its ID appears after /queries/ in its URL.

If you created the query's filters with parameters instead of static values, note the parameters' names as well. For example:

• PY or Previous_Year
• CY or Current_Year
• Current_Period

Step 2. Create the spreadsheet

Before you create the chain, create a spreadsheet to export the query results to.

To avoid misuse of the spreadsheet, clearly identify its educational intent in its name.

After you create the spreadsheet, note its URL; you'll use it to identify where to export the query results. 

Step 3. Create the chain

Now it's time to build the chain! In the end, it'll include commands to run the query and export its latest results to Spreadsheets.

Before you create a chain, verify you've set up the core Workiva connector used to perform its commands. While this chain requires only the one connector, chains can use multiple connectors to prepare and transfer data across your various systems of record.

With the connector set up, you can add the chain in Chain Builder:

1. In Wdata, click Chains , Chain Builder.
2. Click Build, Chains, and then click Add, Create Chain in the lower right corner.
   
3. Enter a unique name and description to help identify the chain.

   Note: Chains appear in Chain Builder for everyone in the workspace; name them so members clearly understand their intent.

4. Click Save.

Step 4. Start with a Runtime Inputs trigger event

To have the chain start by asking for the variables it needs for its commands, add a Runtime Inputs trigger event.

Tip: In addition to runtime inputs, you can add variables for the chain or workspace. With variables, you can extend the use of a chain, such as with any query or spreadsheet instead of only a specific query or spreadsheet.

1. Click Trigger events  play_for_work, move Runtime inputs  touch_app to Start, and click Edit  create.
2. Under Basic info, enter a unique name and description to help identify the event.
   
3. Under Variables, add variables for:
   • The query ID
   • Any query parameter values
   • The spreadsheet URL

   Tip: For each variable, click Add Input, select TextField, and enter its name, description, and default value.

4. Click Save.

Step 5. Add a command to run the query

Next, add a Run query command to have the chain get the latest results each time it runs. You'll use the runtime inputs to identify the query's ID and parameter values.

1. Under Available BizApps, select Workiva, and drag Run query to the canvas.
2. Drag a link from Start to Run query, and click the command's Edit.

   Note: Be sure to link the command to Start so it can use the runtime inputs.

   
3. Under Basic info, enter a unique name and description to identify the command.
4. Under Command properties, select the Workiva connector to perform the command.
5. For Query ID, select the query ID's runtime input under Trigger.
6. If the query's filters use parameter values, click Add (+) under Parameters, and enter their key/value pairs:

   Key	Value
   PY or Previous_Year	Under Trigger, select the runtime input for the previous year.
   CY or Current_Year	Under Trigger, select the runtime input for the current year.
   Current_Period	Under Trigger, select the runtime input for the current period.

7. Click Save.

Step 6. Add a command to export the results

Now, add a command to export the query's results to Spreadsheets:

1. Under Available BizApps, select Workiva, and drag Export query result to the canvas.
2. Drag a link from Run query to Export query result, and click Edit for the latter.
   
3. Under Basic info, enter a unique name and description to identify the command.
4. Under Command properties, select the same Workiva connector as Run query.
5. For Query result ID, select ID for the Query result output under Run query.
6. For Spreadsheet URL, select the runtime input for the spreadsheet's URL under Trigger.
7. Click Save.

Step 7. Run the chain

To run the chain:

1. Click Publish, Publish.
2. Click Execute and Run with inputs.
3. Enter the values for the runtime inputs, and click Start.
4. To verify the chain succeeds, check the spreadsheet for the query results.

If the chain fails, click the commands in the run history to review their logs for messages to help troubleshoot the error.