Setting up IntelliJ to Test Groovy Code in Boomi

(Updated on )
~boomi ~groovy ~intellij

Boomi is a low code environment for integrations, which means that most situations do not require coding but occasionally it is necessary. This article reviews how to setup a Groovy testing environment within Windows and code that you want to implement within Boomi. While Boomi can be helpful with testing, having an IDE (integrated development environment) provides a substantially faster way to debug your Groovy code.

Step 1 - Installing IntelliJ Community Edition

IntelliJ has a free and a paid version. Downloading the free community version provides all the required features. You can find the Community Edition at the bottom of the page. Install IntelliJ after downloading the install file. Use the defaults during the installation, but change any settings that you feel are necessary. Once the install is complete, go ahead and open IntelliJ.

https://www.jetbrains.com/idea/download

JetBrains has an installation guide to installing IntelliJ. The installation guide also includes JetBrains Toolbox, which is a tool to manage all JetBrains products. The installation guide is at the link below.

https://www.jetbrains.com/help/idea/installation-guide.html

Figure 1. IntelliJ Installation Link.

Step 2 - Creating an IntelliJ Project

Once IntelliJ is open, select the New Project option.

Figure 2. New Project Option.

Give a name to the project, the desired Location, and select Maven as the Build system. A suggested project name is ‘boomi-groovy’. You can use other build systems, but this article covers Maven.

Next, select the Groovy option under New Project on the left. Select the dropdown next to [JDK](Java Development Kit) to download Java 11. Boomi currently uses Amazon Corretto Java 11, and this project aligns with that. Next to Groovy SDK, select download and then select the Groovy version 2.4.21.

Figure 3. New Project with all fields populated.

Figure 4. Download Java 11

Once complete, click on Finish. Java 11 and Groovy automatically downloads and the project created.

Step 3 - Set up Folder Structure

The project uses the following directories to store Groovy scripts and sample data files for use within those scripts.

Create the input_files directory within the project to store sample data files for use in the Groovy scripts.

  • ./input_files

Create new scripts within ./src/main/groovy. Create new scripts by right clicking on the groovy directory and selecting New -> Groovy Script.

Figure 5. Folder Structure.

Step 4 - Adding External Libraries

Open the pom.xml file that is within the project’s main directory. Replace the project/dependencies section of the XML and add the following dependencies. The groovy-all dependency should already be present, but the update removes the type=pom section. The boomi-groovy-debugger dependency mocks the Boomi libraries used within the Data Process step and the map function.

    <dependencies>
        <dependency>
            <groupId>org.codehaus.groovy</groupId>
            <artifactId>groovy-all</artifactId>
            <version>2.4.21</version>
        </dependency>
        <dependency>
            <groupId>tech.adambedenbaugh</groupId>
            <artifactId>boomi-groovy-debugger</artifactId>
            <version>1.0.0</version>
        </dependency>
    </dependencies>

After you update the pom file, you can download the external libraries by clicking the Maven icon on the right side of the screen and then clicking the refresh icon.

Figure 6. Maven Refresh Dependencies.

When you require new dependencies, add them to the pom.xml file and click the Maven refresh icon to download the new dependencies.

You can find more information on the boomi-groovy-debugger library at the links below.

Step 5 - Define Groovy Run Templates

You need to set the default configurations for Groovy, which runs within a JVM (Java Virtual Machine). Select Run (top of the screen) -> Edit Configurations. Within the bottom left, click on “Edit configuration templates”. Select Groovy and then add the following to the VM options. Set the options below in the template. Update the PROJECT_DIR environment variable to the project’s base directory. Use this variable within the Data Process step to define the base directory for locating files to treat as inbound documents. Set the illegal-access option to deny to avoid the illegal access warning that displays when running a Groovy 2.4 script with Java 11.

Figure 7.: Edit Run Configurations.

Figure 8.: Edit Run Configuration.

VM options:
  --illegal-access=deny
Environment Variables:
  PROJECT_DIR=<add-your-base-directory>/IdeaProjects/boomi-groovy
Module
  boomi-groovy
JRE
  corretto-11 (select from dropdown)

Step 6 - Testing Scripts within IntelliJ

Boomi uses Groovy in two locations. The first location is within a map using the custom script function. The second location is inline within the process using a Data Process step. The Data Process step instantiates a dataContext class on the back end before executing any Groovy code. You need to either escape the dataContext object or use mock classes from an external library. You can escape the dataContext object by adding \\ before a line, but this may introduce possible errors when translated to Boomi’s context. The method below shows how to use test classes to better test your Groovy code.

Step 7 - Testing Scripts within IntelliJ within a Map

Testing a script designed for a map is straightforward because the map function sets the input and output variables with the script in the middle. You must declare the variables set under input and output within the script in IntelliJ, but you should remove them when adding them to the script map function in Boomi. Also, use println() to write the output to the console for testing. Remove the println() method when running it in Boomi, as it has no effect.

Here is an example script that outputs the first initial and last name, designed for use within a map function in Boomi. First create a new script within the ./src/main/groovy directory by right clicking on that directory and selecting Groovy script. Populate the script below within the new script. Next, click on Run (top of the screen) -> Run. The console displays the output. The green play symbol on the upper-right side of the screen also runs the script.

import java.util.Properties
import java.io.InputStream

// fullName needs to be set within IntelliJ but would be the input variable within Boomi
String fullName = “joe smith” 
int idx = fullName.lastIndexOf(' ')
// This will print the results to the Console but should be removed in Boomi.
println("idx: " + idx);

String firstName = fullName.substring(0,1);
String lastName = fullName.substring(idx + 1);

// This will print the results to the Console but should be removed within Boomi.
println ("firstName: " + firstName);
println("lastName: " + lastName);

// truncatedName would not need to be declared within Boomi because it will be set as an output variable.
String truncatedName = firstName + lastName + "@boomi.com"

// This will print the results to the Console but should be removed in Boomi.
println(truncatedName)

Step 8 - Inline Script with Data Process Steps

The inline Groovy script within the Data Process Steps is more involved because there are some parts of the script that need to use mock classes within IntelliJ. These mock classes mimic the code executed within the Data Process step before the script in the Data Process step runs. They added them as an external library when they included the boomi-groovy-debugger library in the project.

Step 9 - Test Script for Data Process Steps

Now that we have IntelliJ prepared, we can write a Groovy script to precisely mimic what you can input within Boomi. The real power in using this external library lies in your ability to create a script within IntelliJ that also runs in Boomi. Within the Groovy script below there are two parts. The first part is specific only to IntelliJ and does not get copied to Boomi, while the second part is the part that you directly copy from IntelliJ and paste into Boomi.

Before running the script, create a new file called emptyfile.txt within the input_files directory.

// Use for testing. Remove when adding to the Data Process step.
import com.boomi.execution.ContextCreator

// Place directory for multiple files and file name for single file
String pathFiles = "${System.getenv("PROJECT_DIR")}/input_files/emptyfile.txt"
println pathFiles
dataContext = new ContextCreator()
dataContext.AddFiles(pathFiles)
ExecutionUtil ExecutionUtil = new ExecutionUtil()

/* Add any Dynamic Process Properties or Dynamic Document Properties. If
   setting DDPs for multiple files, then index needs to be set for each and
   the index range starts at 0. */
ExecutionUtil.setDynamicProcessProperty("DPP_name", "DPP_value", false)
dataContext.addDynamicDocumentPropertyValues(0, "DDP_name", "DDP_value")


// Place script after this line.
//----------------------------------------------------------------------------------------------------


import java.util.Properties
import java.io.InputStream
import com.boomi.execution.ExecutionUtil

logger = ExecutionUtil.getBaseLogger();

// Example of how to use logger.info() to print to console for testing and to logs within Boomi.
logger.info("Number of documents: " + dataContext.getDataCount())

for (int i = 0; i < dataContext.getDataCount(); i++) {
    InputStream is = dataContext.getStream(i)
    Properties props = dataContext.getProperties(i)
    BufferedReader reader = new BufferedReader(new InputStreamReader(is));
    int lineNum = 0
    while ((line = reader.readLine()) != null) {
        lineNum++
    }
    println lineNum

    // Set properties
    props.setProperty("document.dynamic.userdefined.lineCount", lineNum.toString())

    // Reset the InputStream data
    is.reset()
    dataContext.storeStream(is, props)
}

The code in the first section of the script, before the dashes, mimics the code executed within the Data Process step before any more code runs. A dataContext class is instantiated, mimicking Boomi and setting any process properties or dynamic document properties used within the script. You can set the pathFile variable to a specific file or a directory if you want to call more than one file files. Then the AddFiles() method adds files into dataContext. Once you prep everything, you can create the script after the long line of dashes using exactly the same script found within Boomi’s Data Process step. The script above brings in a flat file, counts the number of lines, and then sets the Dynamic Document Property lineCount with the number of lines within the document.

While writing code within IntelliJ, you want to use println() to write to the console and see the output of your script. Writing to the console can be helpful for both the map and inline scripts.

The article was originally posted at Boomi Community.