Chain template: Chain Usage Tracker

The Chain Template is designed to provide comprehensive information about Chains and Chain Runs within the Chain Environments. It serves as a valuable complement to the monitor log, offering additional insights into Chain activity.

• Inventory and Tracking: It simplifies the inventory process, allowing users to quickly identify Chains that are underused or in high demand. This aids in better resource allocation and efficiency.
• Detailed Reporting: Users can generate reports detailing essential metadata such as IDs, dates, names, and more, which can be important for documentation and analysis.
• Cleanup Process: The template is invaluable for identifying and removing test Chains or outdated Chains that are cluttering the system, making maintenance easier.
• Optimization for Multiple Chain Builders: In environments with several Chain developers, this template provides a clear view of Chain usage, facilitating coordination and optimization efforts to eliminate unnecessary Chains.

Overall, the template enhances control over monitoring Chains and Chain Runs, enabling users to make informed decisions regarding their management and maintenance.

Introduction

The Chain Template retrieves a list of Chains and Chain Runs (executions) for one or more Chain Environments within the Workspace where it is executed. At runtime, the Reporting Spreadsheet is specified to select the Environments, Chains, and Chain Runs for analysis.

Note: This Template is executable only for Chain Environments present in the deployed Workspace.

The Template gathers data on Chains and loads it into the Chain List Wdata Table for each specified Environment. The information collected for each Chain includes:

• Chain ID
• Chain Name
• Created Date
• Updated Date
• Chain URL
• Workspace ID
• Workspace Name
• Environment ID
• Environment Name

Additionally, it collects data about Chain Runs within the Environment and loads it into the Chain Runs Wdata Table. The information gathered for each Chain Run includes:

• Chain ID
• Workspace ID
• Environment ID
• Executed By
• Start At
• End At
• State
• Launch Type
• Run ID

Once all the Chain data is gathered and loaded into the Wdata Tables, the template proceeds to verify that the Select List in the Days Since Query does not have any new Environments missing since the last run. If any new Environments are identified, the Select List is updated accordingly.

The final step of the template involves executing Refresh Connection to update the Connected Sheets with the most recent information collected by the template. The Connected Sheets are updated with the output produced by the Days Since Use Query.

Requirements

1. The following templates must be enabled and configured in your workspace:
   • Load Data to Wdata
   • Update Status
   • Maintain Wdata Parameters
2. The following connectors must be enabled and configured in your workspace:
   
   • Workiva
   • Workiva Chains
   • JSON
   • Tabular Transformation
   • Handlebars

Deploy the Chain

The Chain Usage Tracker template is located in the Workiva Chains section of the Templates screen.

Here's how to find it:

1. In Chain Builder, go to the Templates dynamic_feed tab
2. Select Workiva Chains from the menu at the top
3. Search for Chain Usage Tracker at the top right and open the template

4. After locating the template, click New Chain to deploy it to your workspace

5. Configure the template by following the steps in the Configure the template section below

Configure the template

1. Download the file Chain User Tracker.cb and import it into your Workspace
   
   • This import will create the necessary Wdata Tables and Query for the template

     Note: The Table IDs of each table for later use when configuring the Chain Variables

     
   • Open Days Since Use Query in Wdata to edit it
   • Click on Parameters menu on the right
   • Click on the Environments parameter
     
     

     Note: See Edit a Query Parameter for more information

   • Modify the List Options to include one or more of your Chain Environments. Ensure that each name is exactly the same as the corresponding Chain Environment, including the case sensitivity
   • Change the Default Value as needed
     
   • Click Apply
   • Click Save
2. Download the file Chain Usage Tracker.tar.gz and import it into your Workspace. This import will create the necessary Chain Usage Tracker Spreadsheet
   • Once the file has been successfully imported, locate and open the Chain Usage Tracker Spreadsheet
   • In the Parameters Sheet, update the Days Since Use threshold as needed in cell B1 to a value that is greater than or equal to -1

     Note: A value of -1 will retrieve all data

     
   • Use the Process Tracking Sheet to monitor the status of the template execution
   • To enable the template to process specific Chain Environments, add one or more child Sheets under the Environments Sheet. Remove or rename the Chain Environment Sheet Placeholder Sheet
   • Ensure that each child Sheet is named exactly the same as the corresponding Chain Environment, including the case sensitivity of the name
     
   • Create an incoming connection from the Days Since Use Wdata Query and configure the Days_Since_Use and Environments parameters
     

     Note: DEV, Demo, and SSC are example Chain Environment names. These Environments may not match your Environment names. Edit the Days Since Use Query Parameter as necessary. The template uses Maintain Wdata Parameters to maintain the values

     

Variables

Note: See Find IDs for Workiva files and items for assistance with locating IDs

Runtime inputs

Note: See Find IDs for Workiva files and items for assistance with locating IDs

Run the Template

1. Click Execute button
2. Click Run With Inputs button
3. Enter in the Chain Usage Tracker Spreadsheet ID into the Reporting Spreadsheet ID runtime input field
   
4. Click Start button
5. As the template runs, navigate to the Chain Usage Tracker Spreadsheet and view the Process Tracking Sheet to monitor run status
6. Allow the template to complete to view data within the Environments child Sheets

Execution Result

Here is an example Output to Chain Usage Tracker Spreadsheet:

Completed Chain:

Troubleshooting

• Ensure the sub chains Update Status, Load Data to Wdata, and Maintain Wdata Parameters are all published
• Verify the correct IDs are specified. For assistance identifying IDs within Workiva, reference Find IDs for Workiva files and items
• Verify that the Chain User Tracker.cb and Chain User Tracker.tar.gz files imported successfully. Reference the Importing Wdata Files and Import a Workiva file help articles
• Verify that the Days Since Use Query has the correct Table IDs for the Chain List and Chain Runs Tables
• Verify the Days Since Use value in the Parameters Sheet is greater than or equal to -1
• Verify that the Environments Sheet exists in the Reporting Spreadsheet and the Chain Environment child Sheets are named correctly
• If you renamed the Environments Sheet, adjust your Days Since Use Query to use your Sheet's custom name
• If you renamed your Status and/or Parameter Sheet names and reference them by their name in you Chain variables, ensure their custom names have been reflected in the values of the Chain variables
• If you renamed the Environments parameter in your Days Since Use Query, ensure the Query Parameter Chain variable has been updated to use your parameter's custom name 
• Verify the Workiva Connector has necessary permissions to execute commands in the selected Environment(s)

Additional Resources

• • Import a Wdata Object
  • Import a Workiva file
  • Chain Template Load Data to Wdata
  • Chain Template Update Status
  • Chain Template Maintain Wdata Parameters
  • Workiva Connector
  • Workiva Chains Connector
  • JSON Connector
  • Tabular Transformation Connector
  • Handlebars Connector