Install the Tools

Before You Start

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

  • Java 17

    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 17 JDK using the Software Development Kit Manager (SDKMAN).

    Utilihive SDK version 10.x and earlier requires Java 11. If you are upgrading Utilihive SDK from an older version, install Java 17, and update your IntelliJ project to use it. In this case, it is recommended to uninstall Java 11.

    To view the JDK version, run the following command in the terminal:

    java -version

    Your default java command must use version 17. If it does not, set Java 17 as the default or uninstall other Java versions from your machine.

  • 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 IntelliJ Community Edition is sufficient for developing GridOS Connect integration flows.

    Both the Community Edition and Ultimate Linux bundle have 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

    It is recommended to 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

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://dig-grid-artifactory.apps.ge.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  correto 17, and select OK.

The Project Structure window displays a Project SDK dropdown with Java 17 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://dig-grid-artifactory.apps.ge.com/artifactory/gridos-connect-sdk/</url>
    </repository>
</repositories>

Kotlin 2.2

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

When installing or updating the SDK, flow developers must complete the following steps in IntelliJ to ensure the correct Kotlin language level is used.

  1. Set the Kotlin dependency version to 2.2.x, where x is the latest patch version of the Kotlin runtime.

  2. Refresh the Maven project in IntelliJ.

    Maven refresh

  3. Enable the K2 compiler in the IntelliJ Kotlin settings. To do this, select Settings on the right navigation bar, then choose Languages & Frameworks  Kotlin, and turn on Enable K2 mode.

    Kotlin settings

  4. Verify the Kotlin compiler settings are set to 2.2.

    Compiler settings

  5. Ensure the Kotlin module settings in your project are either delegating to the project settings, or explicitly set to Kotlin language level 2.2.

    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.