Manage GroundRunners for Connections

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.

System Requirements

GroundRunners require Java® version 8 or higher.

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. Install Java in the PATH variable so it can be accessed globally via the java command in a command prompt. After you install Java or edit its configuration, reboot your server.

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

• Microsoft Windows® Desktop 7 and 10, 32- and 64-bit
• Microsoft Windows® Server 2008, 2012, 2012 R2, 2016, and 2019
• Linux® Redhat and Ubuntu
• Solaris® 11, 11.1, 11.2, 11.3, and 11.4
• macOS® Sierra, High Sierra, and Ubuntu

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®.

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 Universal Naming Convention (UNC) path, start the GroundRunner under a user account with adequate privileges to the resource.

Download a GroundRunner

To download a GroundRunner for installation or manual update:

1. From Chains , click Admin  settings .
2. Select Runners  computer, Downloads.
   
3. For the GroundRunner for your operating system, click Download.

Install a GroundRunner for Windows via Microsoft Installer

To install a GroundRunner for Microsoft Windows® Desktop 7 and 10, 32- and 64-bit or Microsoft Windows® Server 2008, 2012, 2012 R2, 2016, and 2019 with .NET 3.5 or higher:

Note: The Microsoft Installer (MSI) requires .NET 3.5 or higher. If you can't meet this requirement, use the CLI installation.

1. Download the GroundRunner, and unzip windows_amd64_ground_runner.zip.
2. To open the GroundRunner Setup Wizard, run GroundRunner.msi, and click Next.
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.
5. In Platform company token, enter your company ID.

   Note: To find your company ID from Chains , click Admin settings , and 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.
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.

Install a GroundRunner for Windows via Command Line Interface

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 install a GroundRunner for Microsoft Windows® Desktop 7 and 10, 32- and 64-bit or Microsoft Windows® Server 2008, 2012, 2012 R2, 2016, and 2019:

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.
   • 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 from Chains , click Admin settings , and 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. From Chains , click Admin, and select Runners.
2. Under Pending Registration, enter a short, descriptive name for the runner, such as <datasource>-GroundRunner
3. Click Activate.

Install a GroundRunner as a Foreground Process for Linux or macOS

To install a GroundRunner as a foreground process on:

• Linux® Redhat, Ubuntu, or Solaris® 11, 11.1, 11.2, 11.3, and 11.4
• macOS® Sierra, High Sierra, or Ubuntu:

Step 1. Install the GroundRunner

1. Download the GroundRunner's installation file to its own directory—such as /home/<username>/wdata/—and unzip the file.
2. In a CLI, enter the command ./installer 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 from Chains , click Admin settings , and select Runners computer, Downloads.

3. Delete all files from the directory except the GroundRunner executable directory.
4. In the CLI, enter the commands:

   cd Contents
    ./GroundRunner
   

Step 2. Activate the GroundRunner

1. From Chains, click Admin settings, and select Runners computer.
2. Under Pending Registration, enter a short, descriptive name for the GroundRunner, such as <datasource>-GroundRunner.
3. Click Activate.

Check the Status of a Runner

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, from Chains, click Admin settings, Runners computer, and 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.

For Windows

To update the GroundRunner via CLI:

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
   • GroundRunnerMonitor.exe
5. In Windows Services Manager, restart the GroundRunner service.

To update the GroundRunner via MSI, download and install the latest MSI, and uninstall any previously downloaded versions.

For Linux or macOS

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
   • GroundRunnerMonitor
6. To restart the GroundRunner service, in the CLI, enter the commands:

   cd /home/<username>/wdata/Contents
   ./GroundRunner

Uninstall a GroundRunner

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

For Windows

To uninstall a GroundRunner via CLI:

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.

To uninstall a GroundRunner via MSI, in Apps & features from Windows Settings, select GroundRunner (64 bit), and click Uninstall.

For Linux or macOS

1. In the CLI, stop the GroundRunner service.
2. Delete the GroundRunner executable directory, such as at /home/<username>/wdata/Contents.

GroundRunner Configuration Settings and Whitelist 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.