Variables Introduction

When I first started at Workiva working on the Connected Center of Excellence team, I was met with quite a hurdle. That hurdle being to grasp the concept of chains and learn how to build them. A very important part of learning chains and building them with leading practices is to avoid hard coding as much as possible. To avoid hard coding, you will want to use variables. There are a few types of variables that can be used in chain builder, so to help you with implementing your chains in the most efficient way, I have broken down the concept of variables and the different types of variables! I hope you find this helpful for understanding and implementing chains as you start your journey using chains. 

To start us off - at the most basic level, a variable is a value that is used multiple times across a single chain (chain variables) or across multiple chains (workspace variables). Common examples of variables include: Spreadsheet and Sheet IDs, Table IDs, Query IDs, API base URLs and access tokens. The biggest advantage of using variables is that you can manage a repeated value in a single location. This removes the need to copy and paste repetitively and lowers the chances for human error.

Chain Variables

Chain variables are used to store values that are used in a single chain across multiple commands. For instance - if you know you will be adding a dataset to a table and removing the prior data sets from the same table, you will want to create the Table ID as a variable so that you can use the Table ID variable in each command necessary to upload a dataset and delete an existing dataset. 

Other common examples of chain variables include: Spreadsheet IDs, Sheet IDs, Document IDs, Query IDs and more. 

Here is a step by step walkthrough on how to create a chain variable. Once the variable has been created, you can use the variable as an input for a chain command by selecting the field you would like to add the variable to and then expanding the chain variables pane in the left panel.  

Workspace Variables

Workspace variables are used to store values that are used across multiple chains in the same Workspace. Common examples of Workspace variables include: API base URLs and access tokens (Client ID and Client Secrets that are generated after creating the OAuth2 Grant). Using Workspace Variables is helpful when you’re needing to connect to an API in order to retrieve source data and you need to create multiple chains that use the same API.

To create a Workspace variable you will follow these steps. Keep in mind that you will need  Workspace Owner role to create Workspace Variables. You will want to give the Workspace variable a name that makes it easy to identify the variable across all chains and all teams that will be building chains. It is recommended to give the variable a description to provide as much detail as possible. If this variable is storing sensitive information, for instance - a Client Secret generated from an OAuth2 Grant, then you will want to check the “encrypted” box to hide the value.

Whenever you need to use this value during chain creation, you will select the field where you need to use the value and you will see the variables panel appear on the left. To use a Workspace variable, you will expand the “Workspace” area and then select the appropriate variable. This will populate the variable in the selected field. Now, whenever the chain is run, the value that is populated in the Workspace variable will be applied wherever the variable has been placed.

Environment Overrides

Once a Workspace variable has been created, you can specify values for the variable based on the environment, meaning when a chain is run, the variable value passed through to the chain can be different for a chain run in the Dev environment vs the Production environment. 

Environment level overrides are most useful when going through chain development. When creating chains, you may want to test using development artifacts and systems, therefore, you will want the environment you are building in to have values that point to those test systems. 

Imagine you are creating a chain that pulls data from your ERP system and pushes that data into a table in Wdata. You may want to use a test or development ERP system while developing your chains to ensure that the data in your production ERP system and production Wdata tables do not get affected. If this is the case, you will want to have one environment in your chain builder dedicated to development (where you will build and test the chains) and one dedicated to production (where your tested and deployed chains are promoted to). Since connecting to your ERP system will occur across multiple chains, you will want to create the variables necessary to connect to your ERP system at the Workspace level. Once those have been created, you will want to populate the environment level variable values to connect to your test ERP system in the Dev environment. You will do the same to connect to your production ERP system by applying the variable values in your Production environment. Then, when a chain is promoted from your dev environment to your production environment, you do not need to update the variable values in each chain. The chain will use the variable values applied at the environment level. 

To update the environment level override value - navigate to chain builder - Environments - and update the Environment variables for the environment you would like to manage outside of the default Workspace variables. Once you set the appropriate value, be sure to save your changes!

Runtime Inputs

Runtime inputs are a type of variable where the value of that variable is determined at the execution of the chain. 

Let’s say you have a similar process that can be run across multiple artifacts. That’s where Runtime inputs come in handy! For instance - if you have spreadsheets with multiple connections and you want to automatically refresh all connections in a given spreadsheet, you can use Runtime Inputs to specify the Spreadsheet ID when the chain is kicked off. This allows you to use the same process without being tied to only refreshing a single spreadsheet. 

Here’s a step by step guide on how to create and use runtime inputs. 

You can take runtime inputs a step further by passing variables from one chain into another chain by using a Run Chain event and setting the runtime variables as values that were passed through the chain that runs prior.