Install the Tools

Prerequisites

You need to install the following software to use Utilihive SDK and its Domain-Specific Language (DSL):

Java 25

The Java Development Kit (JDK) installer from Amazon Corretto automatically sets the necessary Java path variables. If you prefer using the CLI, install the Java 25 JDK using the Software Development Kit Manager (SDKMAN).

sdk install java 25.0.3-amzn

Utilihive SDK versions earlier than 11.764.0 require Java 17, and versions 11.764.0 and later require Java 25. If you upgrade to 11.764.0 or later, install Java 25 and update your IntelliJ project. Uninstall Java 17 only if you no longer maintain projects that use SDK versions earlier than 11.764.0.

To verify your JDK version, run:

java -version

Your default java command must use version 25. If it does not, see Migrate to Java 25 for migration instructions.

Migrate to Java 25

Follow these steps to migrate your project to Java 25.

  1. Close IntelliJ and stop any running Maven processes.

  2. Install Java 25 and set it as the default version.
    Run the following SDKMAN commands:

    sdk install java 25.0.3-amzn
sdk default java 25.0.3-amzn

  3. Verify that the default Java version is 25 by running:

    java -version

  4. Rebase your branches on the latest master branch built with Java 25.
    If any local branches were built with Java 17, rebase them on the new master branch.

  5. Open IntelliJ and configure the project to use Java 25:

    • Go to File  Project Structure  Platform Settings  SDKs. Add the Java 25 SDK. Delete Java 17 SDKs only if you no longer maintain projects that use SDK versions earlier than 11.764.0.

      Add SDK

    • Refresh the Maven projects in IntelliJ.

      Reload all Maven projects

    • Go to File  Project Structure  Project Settings  Project and do the following:

      • Set SDK to corretto-25.

      • Set Language level to SDK default.

        Project Structure Java 25

    • Confirm all modules have their Java language levels set to 25.

    • Set each module’s Kotlin settings with Target platform set to JVM 25, and Kotlin Language version and API version set to 2.4.

      Kotlin settings

  6. Run unit tests to verify that the project is working correctly with Java 25. If you encounter any issues, contact Utilihive Support for assistance.

If multiple JDK versions are installed, make sure your terminal, IntelliJ, and Maven all use Java 25 for this migrated project. Uninstall older Java versions only if you no longer maintain projects that require them (for example, Java 17 for SDK versions earlier than 11.764.0).

IntelliJ IDEA

The IntelliJ code editor comes with built-in support for Kotlin and is the easiest way to work with the Utilihive SDK. The free version is sufficient for developing Utilihive integration flows.

The Linux bundle has the Install-Linux-tar.txt file. Linux users should read this file to learn how to start IntelliJ after downloading it. To install or upgrade IntelliJ, visit the IntelliJ download page.

Git

Start with an example project, which is downloaded as a Git repository.
On Windows and macOS, install Git through IntelliJ during project setup.

Configure the SDK

The Utilihive SDK is installed as a project dependency using Maven. Only licensed users can access and use the SDK. If you need help with your license, contact Utilihive Support.

To configure Maven, you must have access to the GE Vernova Artifactory.

GE Vernova Artifactory Access

All Connect artifacts (Helm charts, Docker images, Maven dependencies, and installation tools) are stored on GE Vernova Artifactory.

Contact your GE Vernova Support representative for more information on how to get access to GE Vernova Artifactory.

Generate an Artifactory token:

  1. Go to: https://gart.software.gevernova.com/ui/user_profile

  2. Once logged in, click on Generate an Identity Token. The description should help you remember its purpose, e.g: GridOS Connect Token.

  3. Click Next. The generated token is used as your password credential, with your SSO as the username.

Configure Maven

You can use the standalone Maven installer or the version embedded in IntelliJ. The next step is to configure Maven to use your licensed credentials.

Create a settings.xml file in the $HOME/.m2 directory. On Windows, this would be: C:\Users\<username>\.m2.

If the .m2 directory does not exist, create it manually. On macOS and Linux, .m2 is hidden. View it using:

ls -a

Add the following configurations to your settings.xml file:

Set the ARTIFACTORY_USR and ARTIFACTORY_PSW environment variables to your Artifactory credentials.

Set Up the Project

Use the Example Project

To use the Utilihive SDK, it is recommended to start with the official example project. It comes preconfigured with dependencies, tests, and sample configurations. Clone the project from the following GitHub URL:

https://github.com/utilihive/flow-developer-example-project-mvn.git

Open IntelliJ, go to File  New  Project from Version Control, enter the GitHub URL, and select Clone.

The Get from Version Control window has the URL field set to the example project’s URL.

Once you have cloned the project, open in IntelliJ and verify that it is using the correct JDK. Go to File  Project Structure, then under Project Settings  Project, select SDK  corretto 25, and select OK.

The Project Structure window displays a Project SDK dropdown with Java 25 selected.

It may take a few minutes for IntelliJ to download the project’s dependencies.

On Windows, IntelliJ might show a warning about Defender slowing things down. If this occurs, select Exclude directories to avoid unnecessary virus scans on your project and IDE folders. Apply similar exclusions for other antivirus programs and operating systems.

Configure the Repository in pom.xml

Make sure the server ID in your settings.xml file matches the repository entry in the pom.xml file of the example project.

<repositories>
    <repository>
        <id>gev-artifactory</id>
        <url>https://gart.software.gevernova.com/artifactory/gridos-connect-sdk/</url>
    </repository>
</repositories>

Kotlin 2.4

The current versions of the Flow Developer SDK depend on Kotlin 2.4.

When installing or updating the SDK, complete the following steps in IntelliJ to configure the correct Kotlin language level.

  1. Go to File  Project Structure  Project Settings  Project.

  2. Set the SDK to corretto-25 and the Language level to SDK default.

  3. Set the Kotlin dependency version to 2.4.x, where x is the latest patch version of the Kotlin runtime.

  4. Refresh the Maven project in IntelliJ.

    Maven refresh

  5. Enable the K2 compiler in the IntelliJ Kotlin settings. Select Settings on the right navigation bar, then choose Languages & Frameworks  Kotlin, and turn on Enable K2 mode.

    Kotlin settings

  6. Verify the Kotlin compiler settings are set to 2.4.

    Compiler settings

  7. Make sure each module’s Kotlin language level is set to 2.4 or delegating to the project settings.

    Language level

Set Up the Project Manually

If you start from an empty IntelliJ project, add the required dependencies to your pom.xml file, including the Utilihive SDK. Use the example project’s pom.xml as a reference.

Download Source Files

Whether you are using the example project or your own, it is recommended that you download the Maven sources for the SDK dependencies. This enables IntelliJ to display contextual documentation when you hover over processor properties. For example, the following image shows documentation for an id property:

The "id" property displays a pop-up underneath with an explanation of valid characters.

To enable this feature in IntelliJ:

  1. On Windows or Linux, select File  Settings. On macOS, select IntelliJ IDEA  Settings.

  2. Go to Build, Execution, Deployment  Build Tools  Maven  Importing.

  3. In the Automatically download section, make sure the Sources option is selected.

    The Preferences window shows that "Sources" is checked next to "Automatically download".

  4. If you do not want Maven sources to download automatically or if automatic download does not work, you can manually trigger the download. Open Maven tool window on the right and select Download icon  Download Sources.

    The Maven tool window displays an option to download sources and/or documentation.

JSONiq Language Support IntelliJ Plugin

Utilihive data mapping is done using the JSONiq query language. We provide a plugin for IntelliJ that supports syntax highlighting for both JSONiq files and inline JSONiq code.

You can request the installation file from Utilihive Support. The plugin is provided as a ZIP file.

Once the ZIP file is downloaded, to install:

  1. Go to File  Settings  Plugins.

  2. In the tabs section, click the three stacked dots (or the cog wheel icon in newer versions of IntelliJ), select Install Plugin from Disk, and select the ZIP file.

  3. Restart IntelliJ to apply the changes.

    The Install Plugin from Disk window displays the option to select a zip file.

Usage

In JSONiq files (.jq or .jqy file extensions), syntax highlighting is enabled by default. Use the language annotation provided by IntelliJ to highlight the inline code. The following syntax displays inline code:

@Language("JSONiq")
val mapper = """
Your JSONiq code here
""".trimIndent()

// If the @Language annotation is not available, use the following syntax:

//language=JSONiq
val mapper = """
Your JSONiq code here
""".trimIndent()

For more information on language support for IntelliJ, see IntelliJ Language Injection.

Advanced Setup

This setup includes application overrides for port numbers and cleanup tasks.

Application Overrides

The test server that comes with the Utilihive SDK can be configured by editing the file located at $HOME/utilihive/server/application-override.properties on your computer.

The utilihive directory won’t be created until the first time the test server attempts to start. For information on how to start the server from a unit test, check out the flow tutorials.

The initial application-override.properties file comments out every possible configuration option, where each property is set to its default. For example:

# The maximum age a flow can have before it is purged. Default 30 minutes.
# flowDeveloper.serverComponents.flow.timeToLiveMillis=1800000

Ports

The most important properties you might want to change would be the ports that the server runs on. If the default ports are already in use by other processes, uncomment and change the following properties:

server.port=8070
management.server.port=8071

Note that server.port refers to the main test server while management.server.port handles separate endpoints for things like manually shutting down the server.

Make sure the current server is shut down before changing the port. See the Troubleshooting documentation for more information.

Cleanup

The only other property you might want to change would be the following:

flowDeveloper.serverComponents.cleanup.active=true

This defines whether or not to enable cleanup tasks on the test server. Setting this to false will make the server stop purging outdated flow deployments that the unit tests might have left behind. It is highly recommended to leave this on for normal use and should only be switched off after talking to support.

Next Steps

Now, you have set up a project, see flow tutorials for the next steps.