GroundRunners enable chain commands to interact with on-premises systems or remote data sources not otherwise accessible over the internet. Java 17 is automatically included with your default GroundRunner installation.
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. 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:
- Contact your IT admin to obtain a copy of the certificate used to secure your site, or export it from your browser.
- 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.
Valid locations:
- Windows-ROOT
- Windows-ROOT-LOCALMACHINE
- Windows-ROOT-CURRENTUSER
- Windows-MY
- Windows-MY-CURRENTUSER
- Windows-MY-LOCALMACHINE
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 17 is our only shared library, but additional dependencies will 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-17=/path/to/java/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-17.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-17=/Users/username/.asdf/installs/java/corretto-17.0.6.10.1
And on a Windows machine, it would look something like this:
SHARED_LIBRARY_OVERRIDES=java-17=C:\Program Files\Java\jre-17
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:
These connectors still use custom certificates read from the cacerts file.