Workiva Support Center

Overview

This "leading practice" series outlines recommendes general practices for various artifacts within the Data Management Suite in the Workiva Platform. Keep in mind that these are general guidelines and may need to be adapted based on specific, unique use cases. These recommendations aim to help you improve organization within your Workspaces. Let's begin by exploring these naming conventions.

Naming Conventions for Connections, Chains and Environments

Connections in Chains

When creating Connections in Chains, it's essential to establish optimal naming conventions to ensure clarity and distinction between Environments:

• Name of Connector: Provide a descriptive name for the Connector that clearly indicates its purpose and function.
• Type of Workspace: Specify the workspace or project where the Connector is being utilized.
• Environment of the Connector: Clearly identify the Environment (e.g., Development, Production) to which the Connector corresponds.

Example:

• SFTP Connection | SEC Reporting | NON-PROD
  • Description: Establishes a Connection to the SFTP server for a SEC Reporting workspace solution within a non-prod Environment like Development, QA , Sandbox etc.
• SFTP Connection | SEC Reporting | PROD
  • Description: Establishes a Connection to the SFTP server for SEC reporting workspace solution within the production Environment.

This naming convention facilitates easy identification and management of Connections across different Environments. It ensures that Chains within specific environments interact only with the appropriate sources, enhancing security and reliability. A Non-Prod connection can be leveraged across Non-Prod, Dev, and Test environments.

This naming convention practice should be consistently applied to all Connections, whether they are Core or Premium Connectors. By maintaining uniformity in Connection naming across different Environments, you can streamline the Chain promotion process and enable seamless execution of chains across workspaces.

Chain Builder

When building Chains in the Workiva platform, maintaining a well-organized naming convention is crucial. A clear and consistent naming strategy helps navigate the Chains more efficiently, especially as the number of workflows grow. This section outlines the leading practices for naming Chains based on their Purpose, Source system, Frequency, and Workflow Hierarchy.

Purpose and Source System

Determining the Chain's Purpose

Consider the following questions to define the purpose of a Chain:

• What kind of data is being used within the Chain?
• Can the Chain be utilized across multiple processes (i.e., is it a Utility Chain)?
• What Source System is being used to pull data from?

Frequency

Specifying the Chain's Frequency

When naming the Chain, it is important to indicate its frequency, particularly if it is scheduled to run automatically. We suggest the following guidelines:

• Indicate if the Chain is to be run on an ad-hoc basis.
• Specify if the Chain runs on a daily, weekly, quarterly, or annual basis.

Hierarchy

Organizing Complex Chain Builds

In Chain build consisting of multiple workflows, there is typically a top-level Chain with multiple Sub-Chains executed in a sequence. Organize these Chains by prefixing them with a numbered naming convention.

Example of a Numbered Naming Convention:

• 1.0 Top-Level Chain
• 1.1 Execute Dataset
• 1.2 Load Data to Wdata Table
• 1.3 Refresh Incoming Connections

This approach helps users quickly identify the order of operations within a workflow and automatically organizes the Chains within the Workspace based on the numerical order.

Practical Examples of Chain Naming Conventions

Utility Chains

Utility Chains are common workflows executed by multiple other workflows, such as Loading data into a Wdata Table. To ensure Utility Chains are prominently displayed at the top of the Workspace, consider the following naming conventions::

• 0.0 - [Utility Chain Name] | [Process] | Utility Chain
• 0.1 - [Utility Chain Name] | [Process] | Utility Chain
• 0.2 - [Utility Chain Name] | [Process] | Utility Chain

Source Systems

The term "Source systems" refers to the origin of the data, which can include various systems such as ERP (Enterprise Resource Planning), EPM (Enterprise Performance Management), HR (Human Resources), and accounting systems, or it can be file-based, like data coming from an SFTP /FTP.

The following example demonstrates the organization for three Source Systems as an example:

1. Workday
   • 1.0 - [Chain Name/Process] | Workday | [Frequency]
   • 1.1 - [Chain Name/Process] | Workday | [Frequency]
   • 1.2 - [Chain Name/Process] | Workday | [Frequency]
2. SAP
   • 2.0 - [Chain Name/Process] | SAP | [Frequency]
   • 2.1 - [Chain Name/Process] | SAP | [Frequency]
   • 2.2 - [Chain Name/Process] | SAP | [Frequency]
3. Netsuite
   • 3.0 - [Chain Name/Process] | Netsuite | [Frequency]
   • 3.1 - [Chain Name/Process] | Netsuite | [Frequency]
   • 3.2 - [Chain Name/Process] | Netsuite | [Frequency]

For a Workspace with a large number of Chains, use the following naming convention examples for clarity and organization:

This structure ensures clear, consistent naming conventions and organization, making it easier to identify and manage Utility Chains and Source System Chains based on their process and frequency of execution.

Environment Naming Convention

Environments allow you to effortlessly plan, test, and deploy workflows. This streamlines the application of Software Development Lifecycle (SDLC) best practices to your automation processes. When creating Environments, we suggest using the following simplified naming conventions to clearly identify the purpose of each Environment. This helps users quickly understand the intended use of each Environment.

Environment Types and Naming Conventions

1. DEV (Development)
   • Purpose: Used for developing new chains and processes. Builders can safely create and experiment in the Development (DEV) environment.
   • Example: DEV
2. Test (or Sandbox)
   • Purpose: Dedicated to testing and QA processes. QA teams can review and test in the Testing (Test) environment.
   • Example: TEST
3. PROD (Production)
   • Purpose: For processes that have been tested, refined, and are ready for deployment in the Production environment. 

   • Example: PROD

     

Notes

• Multiple chains can have identical names, but each is distinguished by a unique identifier known as a GUID.

• Each Workspace has a unique ID (see in the URL), so multiple workspaces can have the same name. We recommend against doing that though due to the potential for user confusion.
• Chains, Workspace, and Workspace Environment names all support spaces and the Workiva standard character set.
• Name lengths:
  • Chain names have a maximum length of 100 characters. 
    Caution: when copying chains, the characters "-- Copy" are automatically added. If this results in a name longer than 100 characters, the chain will not be copied.
  • Chain command (node) names have a maximum of 255 characters. 
  • Workspace names have a maximum length of 50 characters.
  • Workspace environment names have a maximum length of 25 characters.

Summary

Using these simplified naming conventions helps maintain a structured and easily navigable environment setup. It ensures that each Environment's purpose is clear, reducing confusion and improving efficiency during the Development, Testing, and Deployment phases.