Workiva Support Center

GroundRunners enable chain commands to interact with on-premises systems or remote data sources not otherwise accessible over the internet. 

To use a custom certificate, an IT professional or someone otherwise familiar with your organization's network settings must import the certificate to your system's certificate store and disable Workiva's default shared libraries.

Requirements

• An IT professional is recommended when using a custom certificate. Workiva Support will not be able to assist with this installation.
• A supported operating system is required.
• A Java Runtime Environment (JRE) is not installed with the GroundRunner during the initial GroundRunner installation. After setup is completed and the GroundRunner is running, it will automatically download a JRE as needed to run commands that depend on Java. No installation or admin intervention is required, and the retrieved JRE will not affect existing JRE installations if they exist on the host. Learn more about GroundRunner requirements.
• Some connectors are not compatible with Workiva's shared libraries and must use the GroundRunner's system Java installation. See the exclusion list.

Import the custom certificate

When using a self-signed certificate or one not issued by Certificate Authority, your GroundRunners must use the system's certificate store.

To import a certificate:

1. Contact your IT admin to obtain a copy of the certificate used to secure your site, or export it from your browser.
2. Import the certificate into the system's certificate keystore. Valid locations are listed below.

Valid locations

In previous GroundRunner versions, custom certificates were read from the cacerts file in the JRE/JDK installation directory. This functionality has changed so that custom certificates can only be read from the following locations.

Disable Workiva shared libraries

Within chains, a "shared library" is any external library or dependency required for the proper function of a connector. These shared libraries are maintained, updated, and distributed by Workiva directly (with a few exceptions). At this time, Java 21 is our only shared library, but additional dependencies may be added as necessary.

To disable shared libraries and substitute your own self-installed library, add a new configuration option to your GroundRunner.config file:

SHARED_LIBRARY_OVERRIDES=java-21=/path/to/java21/home,java-24=/path/to/java24/home

The path provided in this override must be valid, and it must contain a folder named bin that contains the relevant executables. However, the path itself should not include the bin directory.

Example

Consider the folder structure of a sample Java installation: ~/.asdf/installs/java/corretto-21.0.6.10.1 ❯ tree -L 1

.
├── ADDITIONAL_LICENSE_INFO
├── ASSEMBLY_EXCEPTION
├── LICENSE
├── README.md
├── bin
├── commitId.txt
├── conf
├── include
├── jmods
├── legal
├── lib
├── man
├── release
└── version.txt

You'll notice the bin folder in our file structure. Importantly, this subdirectory is not included in our provided path.

Instead, the override in our GroundRunner.config file looks like this:

 SHARED_LIBRARY_OVERRIDES=java-21=/Users/username/.asdf/installs/java/corretto-21.0.6.10.1

And on a Windows machine, it would look something like this:

SHARED_LIBRARY_OVERRIDES=java-21=C:\Program Files\Java\jre-21

Note: Make sure your Windows install uses backslashes in the provided path.

Troubleshooting

The GroundRunner won't start if:

• Any of the paths provided in your config file do not exist
• The paths do not contain a bin subdirectory

Excluded connectors

These connectors are not compatible with Workiva's shared libraries and must use the GroundRunner's system Java installation:

• Oracle Essbase
• Oracle Hyperion Financial Management (HFM)

These connectors still use custom certificates read from the cacerts file.

Note: When "supported" connectors are executed on the same GroundRunner as an excluded connector, the supported connectors will still use Workiva's shared libraries by default. You can override this by configuring the SHARED_LIBRARY_OVERRIDES option detailed in this article.