Chains 102: Runners
There are two types of Runners for Workiva Chains - CloudRunners and GroundRunners. This article explores the benefits and costs of both as well as discusses information exchange between Runners.
Chains 102: Runners
March 26, 2025
Introduction
Runners are a foundational element of Workiva Chains. They are the agents that perform the data operations defined by the Chain design. For example, when a Chain has a Command to download a file from an SFTP directory, the runner is the Chains component that makes the connection to the SFT Server and retrieves the file.
There are two types of Runners for Workiva Chains - CloudRunners and GroundRunners. Let’s review each.
CloudRunners
A CloudRunner is the agent that is deployed within the Workiva cloud infrastructure. Every Chains deployment has a CloudRunner automatically deployed. No action is required by a customer to use a CloudRunner.
The benefits of a CloudRunner are that there is no hardware required from the customer. All maintenance of the servers to which the CloudRunner is deployed is managed by Workiva. Additionally, Workiva has auto scaling in place to allocate additional system resources to support elastic demand. In layman’s terms, if the CloudRunner hardware is being taxed by a large job, there are mechanisms in place to add additional computing power to ensure maximum performance.
The primary limitation of a CloudRunner is that it is unable to interact with any systems deployed “on-premises” including those that may be deployed in infrastructure as a service offerings such as AWS, Azure, Oracle Cloud Infrastructure (OCI), or Google Cloud. Examples include Oracle Hyperion Financial Management (HFM) as well as relational databases such as those that power legacy data warehouses.
GroundRunners
A GroundRunner is the agent that is deployed within hardware that is managed by a customer. The hardware can be in traditional data centers, 3rd party managed data centers, or Infrastructure as a Service offerings.
This article provides a comprehensive guide for installing a GroundRunner. The article provides system requirements and we strongly recommend that you review the User Account section of the article if deploying a GroundRunner on a Windows machine.
There are two primary benefits of deploying a GroundRunner. First, a GroundRunner enables Workiva Chains to connect to on-premises systems. While connectivity to on-premises systems is supported by a GroundRunner, please note that appropriate network security often needs to be applied to enable communication between the on-prem systems, the GroundRunner, and the rest of Chains which is hosted in Workiva’s infrastructure.
Second, deploying a GroundRunner within your own infrastructure provides additional control over the agent including not only the assigned resources but also providing access to the execution logs that often contain additional troubleshooting detail. The execution logs are not accessible for CloudRunners.
The cost of deploying a GroundRunner is the need to procure and support hardware. While GroundRunners can and often are deployed on virtual environments, there is still a cost associated with using the virtual hardware. Additionally, system maintenance such as operating system patching needs to be considered. The GroundRunner agent itself has an auto updating feature so it requires no maintenance. That said, there have been a handful of occasions where there was a significant upgrade that required manual intervention but those are infrequent and required limited effort.
Multiple GroundRunners can be deployed. It is important to understand that as of this article’s March 2025 publish date, clustering, load balancing, or failover for GroundRunners is not possible. If you wish to discuss these concepts in more detail, we encourage you to contact us.
Runner Data Exchange
The biggest consideration when deploying GroundRunners is understanding how data and information can and cannot be shared across Runners. It is generally considered to be a good practice to use the same Runner for all Commands in a Chain; however, there are instances where multiple runners may be utilized in a single Chain.
Let’s consider an example. An organization has deployed Snowflake and on-premises Oracle Essbase. Snowflake has detailed transactional data and the Essbase cube is loaded nightly with daily sales. In this Chain, a GroundRunner is required to load the data to the Essbase cube. But, the other operations of the Chain could be supported by a CloudRunner, particularly the Snowflake data extraction and any data preparation actions needed. Once the data is transformed and summarized, it could be handed off to the GroundRunner to complete the data load process. This method would distribute the workload and leverage the CloudRunner resources thereby alleviating the workload of the GroundRunner server. This makes the GroundRunner available for additional operations.
In this example, files are being transferred from the CloudRunner to the GroundRunner. This is fully supported. Let’s consider another example. An organization is integrating data from Oracle HFM to Workiva to support their 10K and 10Q SEC filings. A GroundRunner is required to interface directly with HFM. The Command to upload data to Wdata would be required to use a GroundRunner if the output of the HFM extract command was being used as an import to the Workiva create file command. CloudRunners cannot use outputs generated by a GroundRunner. This is an additional security mechanism deployed to ensure that customers can isolate processing sensitive information and prevent inadvertently transferring to the Workiva cloud infrastructure.
If an organization deploys multiple GroundRunners, data can be freely exchanged between those Runners assuming proper configuration of the GroundRunner and network security allows communication between the agents. We encourage you to contact us if you have questions about deploying and using multiple GroundRunners.
It should be noted that the restrictions described in this section apply to file based data only. These are generally noted in the Chains interface by icons such as the paperclip (csv) or a pair of greater than and less than symbols (json). Text, noted by a capital T icon, is able to be exchanged freely between Runners.
This chart summarizes the Runner to Runner information flows.
Summary
The majority of customers leverage a CloudRunner as their primary agent. However, there are instances when a GroundRunner is required or preferred. We encourage you to consider the costs and benefits of each agent type and evaluate the integration requirements for your organization. If your organization deploys a GroundRunner, be mindful of the information flows that are supported when the Chains are being configured.
If you want to discuss Runners and potential architecture in more detail, please feel free to contact us, we’re happy to help you navigate this decision.
