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

Manage GroundRunners for connections

  • Last updated on

To enable the commands within a chain to interact with an on-premise remote data source, IT admins or someone familiar with your organization's network and firewall settings install and set up a GroundRunner on a dedicated server, such as where you host the connected data source. When you add a command to a chain, you assign its connection to a GroundRunner to perform the task within the data source.

Tip: To help ease troubleshooting, you can create a chain to automatically download a GroundRunner's log file to a table.

Prerequisites

GroundRunners support select operating systems and require:

  • Java® version 8
    Note: GroundRunners currently support only Java version 8, not later versions.
  • Limited server resources

To access a shared resource such as a Windows Universal Naming Convention (UNC) path, the GroundRunner also requires a user account with adequate privileges to the resource.

Java

If necessary, download Java from Oracle® or OpenJDK, and install it in the PATH variable to enable global access via the java in a command prompt. After you install Java or edit its configuration, reboot your server.

Note: When installing Java, you may be asked whether to install the Java Development Kit (JDK) or Java Runtime Environment (JRE). For GroundRunners, only the JRE is required.

If using a self-signed certificate or one not issued by Certificate Authority, import it into your Java Keystore to enable Java/SSL security:

  1. Obtain a copy of the certificate used to secure your site from your IT Administrator, or export it from your browser.
  2. Copy the certificate to your GroundRunner's installation.
  3. In your CLI, import the certificate into your Java Keystore. For example: 
    keytool -import -trustcacerts -keystore "C:\Program Files\Java\jre1.8.0_251\lib\security\cacerts" -storepass changeit -noprompt -alias [alias name] -file [path_to_exported_file]

System requirements

GroundRunners support these operating systems, with no external library dependencies:

  • Microsoft Windows® Desktop 10, 32- and 64-bit
  • Microsoft Windows® Server 2012, 2012 R2, 2016, and 2019
  • Linux® Redhat and Ubuntu
  • macOS® Mojave or greater

While GroundRunners require limited server resources, we recommend at least:

  • 512MB of available random access memory (RAM)
  • 100GB of available disk space
Note: To help calculate the required disk space, a chain with five commands that each produce 10MB ephemeral outputs requires 50MB to complete.

The recommended host configuration includes a virtual machine configured with:

  • Two to four processors
  • 8GB of system memory
  • A solid state drive (SSD) storage device
Note: GroundRunners never collect or aggregate data; they retain data only during transmission. An extended validation (EV) certificate always encrypts and protects traffic between a GroundRunner and its data source via DigiCert®.

User account

By default, GroundRunners uses a local administrative account, with inadequate access to remote resources such as shared drives. To access a shared resource such as a Windows UNC path, start the GroundRunner under a user account with adequate privileges to the resource. If using a user account other than the default Local System administrator, grant it permissions to manage the GroundRunner's installation directory to enable automatic updates.

Download GroundRunners

To download a GroundRunner for installation or manual update:

  1. From Wdata, click Chain Builder.
  2. In Chain Builder, select Settings from the sidebar.
    iou.png
  3. Click Downloads at the top.
    2022-07-14_11-41-37.png
  4. Find the GroundRunner for your operating system, and click Download on the right side.

Install GroundRunners

Note: The Microsoft Installer (MSI) requires .NET 3.5 or higher. If you can't meet this requirement, install the GroundRunner via a command line interface (CLI).

Step 1. Install the GroundRunner

To use an MSI to install a GroundRunner for Microsoft Windows Desktop or Windows Server with .NET 3.5 or higher:

  1. Download the GroundRunner, and unzip windows_amd64_ground_runner.zip.
  2. To open the GroundRunner Setup Wizard, run GroundRunner.msi, and click Next. groundrunner-msi_1.png
  3. Review and accept the terms in the license agreement, and click Next.
  4. For Destination Folder, enter the path to where to install the GroundRunner, such as C:\Program Files\GroundRunner\, and click Next. groundrunner-msi_2.png
  5. In Platform company token, enter your company token.
    Note: To find your company token in Chain Builder, from Admin settings , select Runners computer, Downloads.
  6. In Platform auth host:
    • If in North America, enter h.app.wdesk.com/s/wdata/oc/app.
    • If in Europe, enter h.eu.wdesk.com/s/wdata/oc/app.
    • If in APAC, enter h.apac.wdesk.com/s/wdata/oc/app.
  7. If using a proxy server, do one of the following:
    • To reach the proxy server, in Proxy host, enter its valid URL, including the port if necessary. For example, http://yourproxy:3000.
    • To bypass the proxy server, in No proxy host, enter a comma-separated list of hosts to reach directly instead.
  8. Click Next, Install, and Finish. If prompted for User Account Control, click Yes to enable the installer to make changes to your device.
  9. From Windows Service Manager, right-click on GroundRunner, and select Start.

Step 2. Activate the GroundRunner

  1. In Chain Builder, select Settings from the sidebar.
    iou.png
  2. Click Runners at the top.
  3. Under Pending Registration, enter a short, descriptive name for the runner, such as <datasource>-GroundRunner
  4. Click Activate.
Note: To ensure the integrity of the GroundRunner executable, the Windows® installer is available for download and cryptographically signed by the Workiva Release Management team as part of the software development lifecycle.

To use a command line interface (CLI) to install a GroundRunner for Microsoft Windows Desktop or Windows Server:

Step 1. Download the GroundRunner

  1. Download the GroundRunner's installation to its own directory within your program files, such as c:\Program Files (x86)\wdata.
  2. Unzip the installation file, and extract its files to the root of the directory:
    • GroundRunner.exe
    • GroundRunnerMonitor.exe
    • installer.exe

Step 2. Install the GroundRunner

  1. From the Windows Command Line interface (cmd.exe) (CLI), as an administrator, run the command c:\Program Files (x86)\wdata\installer.exe install, and accept all defaults. managing-groundrunners-for-connections_1.png
    • For the path, create a Files folder within the new directory, such as C:\Program Files (x86)\Wdata\Files. Select to create it if it doesn't exist.
    • For the authorization hostname (AUTH_HOST):
      • If in North America, enter h.app.wdesk.com/s/wdata/oc/app.
      • If in Europe, enter h.eu.wdesk.com/s/wdata/oc/app.
    • For the company token, enter the value generated for your organization.
      Note: To find your company ID in Chain Builder, from Admin settings , select Runners computer, Downloads.
  2. Delete all files from the directory except the GroundRunner executable directory.
  3. Select whether to run the GroundRunner as a service or a foreground process.
    • If service, do one of the following:
      • In the CLI, enter the command sc start GroundRunner.
      • In Windows Service Manager, start the HostRunner service.
    • If foreground process, in the CLI, enter the commands: 
      cd c:\Program Files (x86)\wdata
GroundRunner.exe

Step 3. Activate the GroundRunner

  1. In Chain Builder, select Settings from the sidebar.
  2. Click Runners at the top.
  3. Under Pending Registration, enter a short, descriptive name for the runner, such as <datasource>-GroundRunner
  4. Click Activate.

To install a GroundRunner on Linux or macOS:

Step 1. Install the GroundRunner

  1. Download the GroundRunner's installation file to its own directory, such as /home/<username>/wdata/.
  2. In a command line interface (CLI), unzip the installation file:
    • For Linux, use the command unzip linux_amd64_ground_runner.zip.
    • For macOS, use the command unzip darwin_amd64_ground_runner.zip.
  3. Enter the details of the GroundRunner.
    • For Windows, use command ./installer install.
    • For Mac OS, use command ./occli install.
    • For the authorization hostname (AUTH_HOST):
      • If in North America, enter h.app.wdesk.com/s/wdata/oc/app.
      • If in Europe, enter h.eu.wdesk.com/s/wdata/oc/app.
    • For the company token, enter the value generated for your organization.
      Note: To find your company ID in Chain Builder, from Admin settings , select Runners computer, Downloads.
  4. Delete all files from the directory except the GroundRunner executable directory.

Step 2. Select whether to run as a service or foreground process

In the CLI, enter the commands to run the GroundRunner as a background service or foreground process:

  • If executed from the default OS init program, you can run it as a background service. Enter: 
    /home/[username]/wdata/Contents/GroundRunnerMonitor
  • To run it as a foreground process with logs written to console, enter: 
    cd home/[username]/wdata/Contents
sudo ./GroundRunner
  • To run it as a foreground process with logs written to logfile, enter: 
    cd home/[username]/wdata/Contents
sudo ./GroundRunnerMonitor
Tip: To stop a GroundRunner as a foreground process, press CTRL + C.

Step 3. Activate the GroundRunner

  1. In Chain Builder, select Settings from the sidebar.
  2. Click Runners at the top.
  3. Under Pending Registration, enter a short, descriptive name for the GroundRunner, such as <datasource>-GroundRunner.
  4. Click Activate.

Check the status of a GroundRunner

GroundRunners require a constant heartbeat to exchange messages with instructions on how to run jobs and any related information. If a GroundRunner goes offline, it can no longer respond to commands, and administrators receive a warning email.

To view the online/offline status of a GroundRunner, in Chain Builder, from Admin settings, Runners computer, view which runners are Pending Registration, Active, or Inactive.

Note: In the event of a network disruption, GroundRunners automatically try to re-establish communication.

To view the resource status of the host operating system for a runner, select its Show status.

Note: To view all active GroundRunners on a Linux server, enter this command in a CLI: ps -a |grep GroundRunner.

Manually update a GroundRunner

While rare, you may need to manually upgrade a GroundRunner.

Download and install the latest MSI, and uninstall any previously downloaded versions.

  1. Download the latest GroundRunner for your operating system.
  2. In Windows Services Manager, stop the GroundRunner service.
  3. Move the downloaded GroundRunner installation file to its own directory—such as c:\groundrunner_upgrade—and unzip its files.
  4. Copy and paste these uncompressed files to the diretory where the GroundRunner binaries are installed:
    • GroundRunner.exe or ocrunner.exe
    • GroundRunnerMonitor.exe or ocrunnermonitor.exe
  5. In Windows Services Manager, restart the GroundRunner service.
  1. Download the latest GroundRunner for your operating system.
  2. On the server hosting the GroundRunner, navigate to the directory where the service runs.
  3. In a CLI, stop the GroundRunner service.
  4. Move the downloaded GroundRunner installation file to its own directory—such as /home/<username>/groundrunner_upgrade/—and unzip its files.
  5. Copy and paste these uncompressed files to the directory where the GroundRunner binaries are installed:
    • GroundRunner or ocrunner
    • GroundRunnerMonitor or ocrunnermonitor
  6. To restart the GroundRunner service, in the CLI, enter the commands: 
    cd /home/<username>/wdata/Contents
    ./GroundRunner

Set a GroundRunner's environments

By default, GroundRunners are available in all your workspaces and environments. To limit the use of a GroundRunner to only specific environments:

  1. In Chain Builder, go to Settings, and then select Edit from the GroundRunner's menu.
    groundrunner-menu.png
  2. Under Runner Restrictions, uncheck Global, and select the workspaces and environments to use the GroundRunner.
  3. Click Save.

Uninstall a GroundRunner

If you no longer need a GroundRunner, you can uninstall it.

From Windows Settings, in Apps & features, select GroundRunner (64 bit), and click Uninstall.
  1. Stop the GroundRunner service:
    • If running as a service, use Windows Service Manager, or, in the CLI, enter the command sc stop GroundRunner.
    • If running as a foreground process, press the key sequence <ctrl> <c>.
  2. In the CLI, as an administrator, enter the command installer.exe uninstall.
  3. Delete the GroundRunner executable directory.

In the CLI, stop the GroundRunner service, and delete its executable directory, such as at /home/<username>/wdata/Contents.

GroundRunner configuration settings and outbound domains

To enable communication with its data source, you may need to open firewall ports on the server where the GroundRunner is installed. To change the configuration settings of some GroundRunners, you can edit the GroundRunner.config file in the directory where the binaries are installed.

Note: GroundRunners may use proxy servers, just not those authenticated via New Technology LAN Manager (NTLM). Instead, whitelist the server's IP address.
Configuration Settings
PORT 0 to 65535. By default, GroundRunners use port 8821 to communicate with one another. However, a port is required only if GroundRunners on different servers share command outputs inside your network.
COMPANY_TOKEN Leave as default, unless the GroundRunner is configured for a different tenant
LOG_LEVEL info or debug
PROTOCOL Leave as default
HTTP_PROXY_URL If using a proxy server, its valid URL, including the port if necessary. For example, http://yourproxy:3000
LONG_POLL If using a proxy server, set to true to instruct the runner to use long-polling to retrieve commands. To ensure performance, use long-polling only if web sockets aren't supported by your proxy server or firewall.
NO_PROXY To bypass the proxy server, provide a comma-separated list of hosts to reach directly instead. To include multiple hosts based on a common pattern, use the * wildcard.
GROUNDRUNNER_CERT Needed if using more than one GroundRunner and wishing to send encrypted information to the second GroundRunner.  Must also be used inconjunction with PORT.  You must also specify the PROTOCOL field as HTTPS when activating the runner.
GROUNDRUNNER_CERT_KEY Needed if using more than one GroundRunner and wishing to receive encrypted information from a second GroundRunner.  Must also be used inconjunction with PORT.
Please note that your self-signed certificate must have a Subject Alternative Name (SAN). If it does not, when your GroundRunner attempts to download files, it will show an error message referencing the missing SAN.

 

If your network must allow outbound domains, these apply to GroundRunners:

Domain Purpose

h.app.wdesk.com

h.eu.wdesk.com

h.apac.wdesk.com

 The main subdomains for common Workiva services, including Wdata
*.wdesk.com The main domain for the production Workiva platform
*.*.wdesk.com The subdomains for supporting components in the Workiva platform

Troubleshoot GroundRunner errors

If you receive these errors when a chain runs, check the commands' GroundRunners:

Error message Cause Resolution
Failed to communicate with agent—this command was not executed The command couldn't communicate with its GroundRunner. If this happens, the GroundRunner didn't start, or a network disruption occurred between the GroundRunner and Chain Builder. Verify:
  • The GroundRunner's service is working.
  • The GroundRunner's server is connected to the internet.
Unable to download resources associated with command. Please contact Support if error persists. The chain's commands' runners can't communicate with one another. This often happens when commands use different runners, and the CloudRunner tries to use a file output from a command with a GroundRunner.
Note: To secure on-premises data, the CloudRunner can share any output with GroundRunners, but GroundRunners can't share file outputs with the CloudRunner.
 Use the same runner with all commands in the chain, or—the chain's commands require multiple runners—verify no commands with GroundRunners pass file outputs to commands that use the CloudRunner.
Error starting command: exec: \"\\[connector].exe\": file does not exist" commandExecutorId=[ID] A malware- or antivirus-application incorrectly identified the connector and intercepted its communication with the GroundRunner.  Exclude the GroundRunner installation directory from the application's scans.
Certificate Errors Using Self Signed Certificates In many cases, it will be convenient to use self-signed certificates to encrypt GroundRunner communication. If you are using a self-signed certificate, be sure that the Common Name of the certificate matches the URL at which the server can be accessed. For example, if your GroundRunner is listening on port 8821 and you can access the server from your network localhost, the certificate's Common Name would be localhost.
Intermittent chain failure with error:
"Connection reset by peer"		 When multiple runners are installed on the same machine, they must each have a unique GUID.

If the same GUID is used, the runners may overlap and enter into an update loop -- causing occasional chain failures.

We recommend a complete reinstall of the GroundRunner.

 

 

 
Was this article helpful?
4 out of 10 found this helpful
To enable the commands within a chain to interact with an on-premise remote data source, IT admins or someone fami...