Integrate Kogito and Business Central projects using Git

About

With the VSCode Kogito Bundle extension, you can author processes, rules, or test scenarios directly in VSCode without the need to run the whole Business Central.

If you would like to know how to create, build and deploy the projects in VSCode, or you would like to integrate the Business Central and VSCode Kogito projects, you are in the right place.

Important note: Although the integration described in this post works for most use cases, it is not supported by Red Hat products.

Prepare the environment

The first thing you will need to do is to prepare the environment. It is recommended to use the latest versions when using any of the following software/tools unless specified otherwise.

Versions used in this post:

• OpenJDK: 1.8+ (e.g. 1.8.0_282 or 11.0.10)
• Maven: 3.6.3
• Git: 2.30.2
• VSCode: 1.46.0+ (e.g. 1.54.3)
• Kogito Bundle extension: 0.8.6
• Business Central: 7.51.0.Final
• KIE server: 7.51.0.Final

Tools

Git

To migrate projects between Business Central and VSCode, you need to have Git installed on your local machine.

Maven

To generate projects in VSCode and build them, ensure you have installed Maven.

Note, you might need to install JDK first if it’s not already pre-installed in your OS. See the system requirements for Maven for more information.

VSCode and Kogito

Install and open VSCode on your machine. You can find installation instructions here: https://code.visualstudio.com/docs/setup/setup-overview.

Kogito Bundle extension

You can install the bundle via UI:

Open Extensions in VSCode, find Kogito Bundle, and click install.

Alternatively, you can use VSCode Quick Open:

1. Launch VSCode Quick Open (by pressing “Ctrl + P“)
2. Paste the following command: ext install kie-group.vscode-extension-kogito-bundle
3. Finally, press enter.

Business Central and KIE server

There are more possibilities for how to prepare the environment to run Business Central and KIE server. You can find information about installation in jbpm getting started guide or Installing and configuring Red Hat Process Automation Manager.

You can download an already prepared and configured Business Central with KIE server here: jbpm-server-7.51.0.Final-dist.zip or here: jbpm-download.htmlto speed up the setting process. 

Once the file is downloaded, unzip it to your working directory (for example, to ~/jbpm-kogito-home/).

To run Business Central, open terminal and execute the following commands:

Wait until deployment is finished. You should see something like this in the terminal:

INFO org.kie.workbench.common.screens.datasource.management.backend.DataSourceManagementBootstrap Initialize deployments task finished successfully.

Login to Business Central:

1. Open the web browser and enter the address: http://localhost:8080/business-central
2. Login with username: wbadmin password: wbadmin

Migrate projects from Business Central to VSCode

If you have properly configured the environment, we can proceed with importing projects from Business Central to VSCode. Note, this workflow should work for the most of the use cases, but if you experience any issues, please report it here: https://issues.redhat.com/projects/KOGITO/summary.

Create or open any project in Business Central:

• Navigate to Menu -> Projects
• You can create a new project by clicking the Add Project button or you can open any Sample project by clicking on Try Samples,select project(s) and click Ok.

Once you have a Business Central project, there are two options how to migrate it to VSCode. The first and preferred one is to clone the repository using git. The second option is to download it using GUI.

Clone the project using Git

To clone the repository, open Business Central, navigate to Project’s Settings, locate URL property, choose either ssh or http from the drop-down menu and copy the link. Alternatively you can use the local git repository that you can find in the “.niogit” folder of your Business Central, but this is not recommended.

Open the terminal in VSCode by clicking on Terminal → New Terminal or use “Ctrl + Shift + `” shortcut and execute these commands:

Download the project using GUI

To download the project using GUI in Business Central, follow the instructions below:

1. Open any asset in the project in Business Central
2. Open Project Explorer
3. Click on the Cogwheel icon
4. Click on Download Project
5. Unzip the project.

Note, there is no Git repository cloned if you downloaded the project using Business Central GUI. If you would like to push/pull changes between Business Central and VSCode, you need to set up a remote repository first by executing the following commands:

Open the project

Now open the cloned/downloaded project in VSCode. There are two options.

The first option is to use the VSCode terminal.

Execute the following commands, hover over the project’s path (the return value of pwd command), and press “Ctrl + Click”. The project will open in a new window.

The second option is to use VSCode GUI.

Click File → Open folder or use “Ctrl + O” shortcut, locate the root folder of the project, and then click OK.

Tip: If you don’t want to close the current project, you can open a new window using the shortcut “Ctrl + Shift + N” before opening the project.

Create a project in VSCode

You can also create your own projects from scratch directly in VSCode, instead of transferring them from Business Central.

You can do that by generating a kjar project skeleton with a Maven archetype command.

If you want to create more projects, use properties with specific GAV when generating projects. If you want to create a Case project, specify it by using caseProject property when generating projects.

Open terminal in VSCode by clicking on Terminal → New Terminal or use “Ctrl + Shift + `” shortcut and execute the following commands:

During the project generation, it will ask you to confirm the configuration. Press y to confirm it and then Enter.

If you are experiencing issues with generating the artifact, ensure you have configured the maven repositories properly. Note, the command might not work properly in PowerShell when trying to execute it on Windows. Use Cmd prompt instead.

Create assets in VSCode

If you have successfully created the project skeleton, it is time to create all assets and necessary files for your project.

Kogito editors

There are currently three different editors provided by Kogito VSCode extension: BPMN, DMN and Test Scenario.

BPMN editor

Files with bpmn extension $BPMN_FILE_NAME.bpmn are handled by the BPMN, respectively Business Process editor. You can design processes with this modeler.

DMN editor

Files with dmn extension $DMN_FILE_NAME.dmn are handled by the DMN editor. You can design decisions with this modeler.

SCESIM editor

Files with scesim extension $SCESIM_FILE_NAME.scesim are handled by the Test Scenario editor. You can design test scenarios for testing your DMN assets with this modeler.

Note, the pop-up dialog will ask you to select the DMN asset when creating Test Scenario. Therefore make sure you create it in advance.

Create assets

If you create/open any of the listed assets above, an editor will open.

To use VSCode GUI, follow the instructions below:

1. Open the project (click on Explorer in upper left corner)
2. Create the missing folders by right click on the location → New folder.
   • src/main/resources/$PACKAGE(e.g. src/main/resources/org/kie/businessapp)
     Use this location for BPMN and DMN assets.
   • src/test/resources/$PACKAGE (e.g. src/test/resources/org/kie/businessapp)
     Use this location for SCESIM assets.
3. Select the location, click on New File, and input file name with the desired extension (e.g.process.bpmn, dmn.dmn or test-scenario.scesim).

The other option is to use a terminal. Execute following commands:

The created file can be opened by listing the files in the folder with lscommand, hovering over the file name and then “ctrl + click”. Alternatively, you can open the file using GUI by locating the file and clicking on it.

After creating a few assets and modeling simple BPMN process, your project may look like this:

Other file formats

We don’t provide custom editors in Kogito for any other assets not mentioned above, including work item handlers. However, you can find useful tips on how to create some of them below.

Data Objects

The Data Object in Business Central is no more than a POJO, so you can create/use it manually:

1. Create a file $CLASS_NAME.java (e.g. Person.java) insrc/main/java/$PACKAGE(e.g. src/main/java/org/kie/businessapp)
2. Create a java class in the file. For example:
   package org.kie.businessapp; public class Person {/*...*/}

Forms

You can create it in Business Central and copy the source code or download the file to your local project, usually to src/main/resources/$PACKAGE (e.g. src/main/resources/org/kie/businessapp).

Other assets

You can create any other assets that you need for your project in Business Central and copy the file/source code to VSCode. Another option is obviously to create them from scratch by creating a file with specific extension $FILE_NAME.$EXTENSION (e.g. rules.drl) in desired location (e.g. src/main/resources/org/kie/businessapp).

Migrate a project from VSCode to Business Central

Once you have your project created, you can migrate it to Business Central.

You need to create a repository from the project first. Open the terminal and execute these commands:

Once you created the repository, import the project to Business Central:

1. Open or Create a space in Business Central
2. Click on the arrow drop-down menu next to the Add Project and click Import Project
3. Paste the URL to your repository and click Ok
   file://$WORKING_DIRECTORY/$PROJECTS/$PROJECT_NAME/.git(e.g. file:///home/user/jbpm-kogito-home/projects/mybusinessapp/.git)
4. Select the project and click Ok

Synchronize changes between VScode and Business Central

Whether you migrated your projects from Business Central or you created a new one in VSCode from scratch, you might want to synchronize the changes between VSCode and Business Central. You can do it manually using Git since there is no automated way to do that.

The first thing you need to do is to set up a remote repository if you haven’t done so:

After that, pull or push the changes between Business Central and VSCode. Note, currently VSCode Kogito extension is under alpha release, hence some corner case issues may arise with complex round-trip synchronization. Also, if any conflicts occur, you will need to handle them manually.

Build and Deploy the project

To be able to visualize the process in the runtime monitoring tools, ensure that all processes have their SVGs generated. If you created the project from scratch, you have to generate them manually:

1. Open process in VScode and click SVG icon in the upper right corner.
2. Rename the generated SVG file to the format ${process id}-svg.svg (e.g. process-svg.svg)
   You can find the process id in the Properties panel in the Business Process editor.

Build the project

Go to your project home (where pom.xml file is located) and execute the command:

If you are experiencing issues with not resolved dependencies, ensure you have set the right maven repositories. You can also add necessary repositories to the project’s pom.xml file.

Deploy the project using Swagger

You can deploy your project to any KIE server you want. For demonstration purposes, we will use KIE server which comes alongside with Business Central.

First, ensure the KIE server is running. See “Business Central and KIE server” section above for more information.

Open http://localhost:8080/kie-server/services/rest/server and login with credentials:

username: kieserver password: kieserver1!

You should get a response: “<response type="SUCCESS" msg="Kie Server info"> …”

Open http://localhost:8080/kie-server/docs/ and follow the instructions:

1. under “KIE Server and KIE containers” category find:
   PUT/server/containers/{containerId} Creates a new KIE container in the KIE Server with a specified KIE container ID
   
2. Click PUT and then Try it out
3. Input{containerId}(e.g. containerMyBusinessApp)
4. Update container-id and GAV in body (you can find it in pom.xml of your project)
   For example: containerMyBusinessApp, org.kie.businessapp:mybusinessapp:1.0
   
5. Click Execute
   You should get a successful response with code 201

You can check your containers at http://localhost:8080/kie-server/services/rest/server/containers

Conclusion

I hope this article helped you better understand how to integrate Kogito and Business Central projects. You can seamlessly migrate the existing projects or create a completely new one directly in VSCode. You can now easily start using the Kogito Bundle extension and utilize it to its full potential.