|
Classic file types are no longer available for use as of January 2021. You can transition your classic files or download a PDF. Learn More

Workiva Support Center

Chain Template: Data Dictionary

Chain Template: Data Dictionary

  • Last updated on
Related to chains

Introduction

The Data Dictionary Chain template enables users to capture and export high-level details about specific tables within their workspace to a spreadsheet. Users can specify a keyword to locate tables, define the export spreadsheet's name, and create a table in the workspace to store the schema of each table.

For further details, see the documentation on the Load Data to Wdata Process for a comprehensive overview. Reviewing this documentation before using the Data Dictionary template is recommended.

Prerequisites

This template assumes the following objects are already set up in your Workiva application:

Note: Some variable values may contain sensitive information such as usernames and passwords. We recommend using the "Encrypt" option for information-sensitive variables and setting the appropriate permissions for your spreadsheet.
  • Configure Variables
    • For the Load Data to Wdata sub-chain in the template to function as expected, a workspace variable titled wsv-WdataLoadWarningThreshold must be created. 
Note: It is best practice to set this variable’s default value to 50 (representing 50MB), though this can be adjusted if necessary.
    • Additionally, four other workspace variables must be created before using the Data Dictionary chain.

Below is a breakdown of each variable that needs to be set up and populated:

Variable Value Description
wsv-WdataLoadWarningThreshold Recommended: 50mb Sets the threshold at which the chain will flag datasets that exceed this file size.
wsv-Client ID Derived from the user’s API Grant Populated after creating an API grant.
wsv-Client Secret Derived from the user’s API Grant Populated after creating an API grant.
wsv-IAMBaseURL https://api.app.wdesk.com/iam/v1

Base URL for the Workiva IAM APIs.

Note:The base URL depends on the location of the integration user. 
wsv-PlatformBaseURL https://api.app.wdesk.com/platform/v1

Base URL for the Workiva Platform APIs.

Note: The base URL depends on the location of the integration user. 

Build your Chain

The Data Dictionary | ALL | Primary Chain 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 Data Dictionary | ALL | Primary Chain Template at the top right and open the template

When the Data Dictionary | ALL | Primary chain is deployed into a workspace, it will automatically deploy six additional sub-chains.

Users must ensure that all seven chains have been deployed & published into the same workspace:

  • Data Dictionary | ALL | Primary
  • Data Dictionary | Create Document and Subsections | Spreadsheet Creation
  • Data Dictionary | Create Document and Subsections | Sheet Creation
  • Data Dictionary | Create Table
  • Load Data to Wdata | Primary Chain
  • Load Data to Wdata | Replace Dataset
  • Load Data to Wdata | Add New Dataset

After locating your template, configure it for your workspace using the variables created in the above section.

Note: For detailed instructions on creating a chain from a template, see the Create and manage chains article.

Runtime Inputs

Upon running this Primary Chain (Data Dictionary | ALL | Primary), following Run Time Inputs will need to be populated or passed through a calling Chain:

Runtime Input Description Field Type Required?
SpreadsheetName Specifies the name of the spreadsheet where the table schema will be written. Text Yes
Search Value This input is used to locate tables containing the specified keyword. Text Yes
Wdata Table Name Specifies the name of the data dictionary table created on initial template execution. Text Yes

Wdata Table

To utilize this chain, a Data Dictionary Wdata table must exist within the workspace. The chain will automatically create this table, using the naming convention “Data Dictionary Table,” unless a user specifies a different table name.

The following table schema will be used to build the data dictionary table:

Column Name Column Description Column ID Column Type
Table_Name N/A table_name text
Alias N/A alias text
Mode N/A mode text
Name N/A name text
Type N/A type text
Customized Adjustments Disclaimer: If users experience issues with column headers not matching when importing their data into a Wdata table, they can leverage data prep or other commands to correct this. However, if a user does add any customized adjustments to this template, it is recommended that they make a copy before doing so. Any changes to the template will hinder its reusability. This is also applicable if applying a tag configuration to the template.

Troubleshooting

The following steps can be used to troubleshoot issues with the chain template:

Chain Execution Errors

  • Verify that all chains are published.
  • Ensure the OAuth2 credentials (wsv-Client ID and wsv-Client Secret) are valid and up to date.
  • Check workspace permissions for the user executing the chain.

Data Import Errors

  • Confirm that column headers in your source file match the schema of the Wdata table.
  • For Replace Dataset operations, ensure file names match existing datasets in the table.
  • For Add New Dataset operations, ensure file names are unique within the table.

Duplicate Table or Spreadsheet Creation

  • Use consistent names for Wdata Table Name and SpreadsheetName across runs.

Monitor Screen

  • Users can diagnose the cause of an error by navigating to their monitor screen.

image.png

  • The DCV_Chain Result variable captures the status of the chain based on the final result. If an error occurs, it will apply the reason for the failure to the output text of the chain within the monitor screen.

Data Dictionary Pic 2.png
Users can also use the monitor screen to determine if their file was imported successfully

Best Practices

  • Avoid Customizing the Original Template:
    Create a copy if adjustments are needed. Changes to the template may hinder reusability.

  • Tagging for Enhanced Context:
    Add runtime inputs (Tag-Key and Tag-Value) to tag datasets, if needed. Update chain nodes to pass these inputs.

  • File Size Management:
    Monitor dataset size using the wsv-WdataLoadWarningThreshold variable. Consider splitting large datasets if warnings are triggered.

Additional Resources

Introduction The Data Dictionary Chain template enables users to capture and export high-level details about specific...