Overview

The leading practice series outlines recommended 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 users improve organization within their 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 would be able to be leveraged across Non-Prod, Dev, and UAT 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 essential to indicate its frequency, particularly if it is scheduled to run automatically. Use 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 the team to effortlessly plan, test, and deploy workflow. This feature streamlines the application of Software Development Lifecycle (SDLC) best practices to the automation processes. When creating Environments, use 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. UAT (User Acceptance Testing) or Sandbox

   • Purpose: Dedicated to testing and QA processes. QA teams can review and test in the User Acceptance Testing (UAT) environment.
   • Example: NON-PROD

3. PROD (Production)

   • Purpose: For processes that have been tested, refined, and are ready for deployment in the Production (PROD) environment. 
   • Example: PROD

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

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.