GroundRunners enable chain commands to interact with on-premises systems or remote data sources not otherwise accessible over the internet. They're typically installed on a dedicated server, such as the one that hosts your connected data source, by an IT professional or someone otherwise familiar with your organization's network settings.
Before setting up a GroundRunner, we recommend reviewing the Chain Builder security architecture.
Requirements
A compatible operating system is required, and if your GroundRunner will access shared resources such as a Windows Universal Naming Convention (UNC) path, then a user account with sufficient privileges is needed as well.
The Java Runtime Environment (JRE) is licensed under GPL v2 but is covered by the classpath exception.
Note: To use custom certificates with your Java installation, or to simply not use Workiva's shared libraries, see our Using custom certificates with GroundRunners article.
Download the GroundRunner
To download a GroundRunner for installation or manual update:
- In Chain Builder, select Settings
from the sidebar. - Click Downloads at the top.
- Find the GroundRunner for your operating system, and click Download on the right side.
Install the GroundRunner
The Microsoft Installer (MSI) requires .NET 3.5 or higher. If you can't meet this requirement, install the GroundRunner via command line interface instead.
To install the GroundRunner:
- Unzip the windows_amd64_ground_runner.zip file.
- Run GroundRunner.msi to begin the GroundRunner Setup Wizard.
- Click Next.
- Review and accept the terms in the license agreement, and click Next.
- For the Destination Folder, enter the path where the GroundRunner will be installed (such as
C:\Program Files\GroundRunner\
) and click Next. - In Platform company token, enter your company token.
- 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
- If in North America, enter
- If using a proxy server, enter its URL and port in Proxy host. (For example, http://yourproxy:3000.)
- To bypass the proxy server, enter a comma-separated list of hosts under No proxy host.
- Click Next, Install, and Finish.
- Once installed, right-click on the GroundRunner from Windows Service Manager and select Start.
Your GroundRunner has now been installed and is ready for activation.
To install via command line interface, you must download the GroundRunner's installation to its own directory within your program files (such as c:\Program Files (x86)\wdata
). You can then unzip the installation file and extract it to the root of the directory.
You can then install the GroundRunner :
- From the Windows CLI, 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
). - 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 APAC, enter
h.apac.wdesk.com/s/wdata/oc/app
- If in North America, enter
- Enter your company token.
- For the path, create a Files folder within the new directory (such as
- 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 running as a 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 running as a foreground process, enter these commands in the CLI:
cd c:\Program Files (x86)\wdata GroundRunner.exe
- If running as a service, do one of the following:
Step 1. Install the GroundRunner
- Download the GroundRunner's installation file to its own directory, such as
/home/<username>/wdata/
. - In a CLI, unzip the installation file:
- For Linux, use the command
unzip linux_amd64_ground_runner.zip
- For macOS, use the command
unzip GroundRunner.zip
- For Linux, use the command
- Enter the details of the GroundRunner.
- For both Linux and Mac OS, use 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 APAC, enter
h.apac.wdesk.com/s/wdata/oc/app
- If in North America, enter
- Enter your company token.
- For both Linux and Mac OS, use command
- 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 following commands to run the GroundRunner as either a background service or a foreground process.
Background service
If executed from the default OS init program, you can run it as a background service:
/home/[username]/wdata/Contents/GroundRunnerMonitor
Foreground process
To run it as a foreground process with logs written to console:
cd home/[username]/wdata/Contents sudo ./GroundRunner
To run it as a foreground process with logs written to logfile:
cd home/[username]/wdata/Contents sudo ./GroundRunnerMonitor
Activate the GroundRunner
After installing your GroundRunner, you must activate it within Chain Builder.
- In Chain Builder, select Settings
from the sidebar. - Click Runners at the top.
- Under Pending Registration, enter a short, descriptive name for the runner (such as <datasource>-GroundRunner).
- Click Activate.
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.
- 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 GroundRunner.exe and GroundRunnerMonitor.exe to the directory where the GroundRunner binaries are installed.
- In Windows Services Manager, restart the GroundRunner service.
- Download the latest GroundRunner for your operating system.
- On the server hosting the GroundRunner, go 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 GroundRunner.exe and GroundRunnerMonitor.exe to the directory where the GroundRunner binaries are installed.
- To restart the GroundRunner service, enter these commands in the CLI:
cd /home/<username>/wdata/Contents
./GroundRunner
Uninstall a GroundRunner
If you no longer need a GroundRunner, you can uninstall it.
- Stop the GroundRunner service.
- If running as a service, use Windows Service Manager or enter the command
sc stop GroundRunner
in the CLI. - If running as a foreground process, press the key sequence <ctrl> <c>.
- If running as a service, use Windows Service Manager or enter the command
- In the CLI, as an administrator, enter the command
installer.exe uninstall
. - Delete the
GroundRunner
executable directory.
In the CLI, stop the GroundRunner service and delete its executable directory (e.g., /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.
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, enter its URL and port (if necessary). For example, Note: GroundRunners may use proxy servers, but not those authenticated via New Technology LAN Manager (NTLM). Instead, allow the server's IP address. |
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 be used in conjunction 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 in conjunction with PORT. |
DISABLE_WEBSOCKETS | Websockets are required to run transformations. When disabled, any commands using transformations will be skipped entirely. |
Note: 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 |
---|---|
|
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. |
Security
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®.
Note: To secure on-premises data, CloudRunners can share output with GroundRunners, but GroundRunners can't share file outputs with CloudRunner.
Troubleshoot GroundRunner errors
If you receive these errors when a chain runs, check the command's GroundRunners.
Tip: To help ease troubleshooting, you can create a chain to automatically download a GroundRunner's log file to a table.
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:
|
Unable to download resources associated with command. Please contact Support if error persists. |
The runners associated with these chain's commands can't communicate with one another. This often occurs when commands use different runners and the CloudRunner is trying to use a file output from a GroundRunner-based command. |
Use the same runner with all commands in the chain. If 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.
|
Commands are skipped on GroundRunner but succeed on CloudRunner | Websockets are required to run transformations. When websockets are disabled any transformations will be skipped entirely. |
Open your config file and set
|