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:
-
API Grant
- In order to leverage Workiva API’s, a user must establish an OAuth API Grant within their workspace. Please refer this article for leading practices for managing the OAuth Grant.
- The following Connectors must be enabled and configured in your workspace:
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:
- In Chain Builder, go to the Templates tab.
- Select Workiva Chains from the menu at the top
- 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 IDandwsv-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 NameandSpreadsheetNameacross runs.
Monitor Screen
- Users can diagnose the cause of an error by navigating to their monitor screen.
- 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.
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-KeyandTag-Value) to tag datasets, if needed. Update chain nodes to pass these inputs. -
File Size Management:
Monitor dataset size using thewsv-WdataLoadWarningThresholdvariable. Consider splitting large datasets if warnings are triggered.