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:
- From Chains , click Admin .
- Select Runners
- 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.
- Download the GroundRunner, and unzip
windows_amd64_ground_runner.zip
. - To open the GroundRunner Setup Wizard, run
GroundRunner.msi
, and click Next. - Review and accept the terms in the license agreement, and click Next.
- For Destination Folder, enter the path to where to install the GroundRunner, such as
C:\Program Files\GroundRunner\
, and click Next. - In Platform company token, enter your company ID.
Note: To find your company ID from Chains , click Admin
, and select Runners , Downloads. - 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 North America, enter
- 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.
- To reach the proxy server, in Proxy host, enter its valid URL, including the port if necessary. For example,
- Click Next, Install, and Finish. If prompted for User Account Control, click Yes to enable the installer to make changes to your device.
- 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
- Download the GroundRunner's installation to its own directory within your program files, such as
c:\Program Files (x86)\wdata
. - 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
- 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 asC:\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
.
- If in North America, enter
- For the company token, enter the value generated for your organization.
Note: To find your company ID from Chains , click Admin
, and select Runners , Downloads.
- For the path, create a
- Delete all files from the directory except the
GroundRunner
executable directory. - 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.
- In the CLI, enter the command
- If foreground process, in the CLI, enter the commands:
cd c:\Program Files (x86)\wdata GroundRunner.exe
- If service, do one of the following:
Step 3. Activate the GroundRunner
- From Chains , click Admin, and select Runners.
- Under Pending Registration, enter a short, descriptive name for the runner, such as
<datasource>-GroundRunner
- 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
- Download the GroundRunner's installation file to its own directory—such as
/home/<username>/wdata/
—and unzip the file. - 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
.
- If in North America, enter
- For the company token, enter the value generated for your organization.
Note: To find your company ID from Chains , click Admin
, and select Runners , Downloads.
- For the authorization hostname (AUTH_HOST):
- Delete all files from the directory except the
GroundRunner
executable directory. - In the CLI, enter the commands:
cd Contents ./GroundRunner
Step 2. Activate the GroundRunner
- From Chains, click Admin , and select Runners .
- Under Pending Registration, enter a short, descriptive name for the GroundRunner, such as
<datasource>-GroundRunner
. - 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
, Runners , 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:
- Download the latest GroundRunner for your operating system.
- In Windows Services Manager, stop the GroundRunner service.
- Move the downloaded GroundRunner installation file to its own directory—such as
c:\groundrunner_upgrade
—and unzip its files. - Copy and paste these uncompressed files to the diretory where the GroundRunner binaries are installed:
GroundRunner.exe
GroundRunnerMonitor.exe
- 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
- Download the latest GroundRunner for your operating system.
- On the server hosting the GroundRunner, navigate to the directory where the service runs.
- In a CLI, stop the GroundRunner service.
- Move the downloaded GroundRunner installation file to its own directory—such as
/home/<username>/groundrunner_upgrade/
—and unzip its files. - Copy and paste these uncompressed files to the directory where the GroundRunner binaries are installed:
GroundRunner
GroundRunnerMonitor
- 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:
- 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>
.
- If running as a service, use Windows Service Manager, or, in the CLI, enter the command
- In the CLI, as an administrator, enter the command
installer.exe uninstall
. - 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
- In the CLI, stop the GroundRunner service.
- 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.
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. |
If your network requires a whitelist of outbound domains, these apply to GroundRunners:
Domain | Purpose |
---|---|
|
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 |