1
You need an IDE like IntelliJ IDEA, Eclipse or VSCode. Eclipse is preferred with the BPMN modeler plugin.
2
You need JDK 8 to 11 with JAVA_HOME system property set correctly.

Optionally, get GraalVM 19.1.1+ for native compilation with the GRAALVM_HOME system property set correctly and 'native-image' installed (using 'gu install native-image').
3
You need Apache Maven 3.5.3 or later.

Run the examples

This guide covers Downloading the Kogito examples, Building and running one of the Kogito examples, and Testing the running example with some REST requests.

Download Kogito examples

To download a released version of the Kogito examples, visit this page and select the latest version of the kogito-examples. Simply unzip it. It contains various out-of-the-box examples. We will be focusing on one of the jBPM examples here.

Building and running the jBPM example

Our jBPM example shows how you can build your own order service by leveraging a business process to describe the logic that the service should follow. The example includes a simple process that describes the steps that need to be followed when ordering items: a sequence of a script task (which is writing out some debug info) and a call activity invoking a sub-process, using a custom Order data element.

Kogito Getting Started Demo One Graphic

The sub-process invokes a custom Java service CalculationService.calculateTotal, followed by a user task to verify the order.

Kogito Getting Started Demo Two Graphic

Based on these two processes (defined using BPMN 2.0 format), the custom data object and the custom Java service mentioned earlier, the example shows how a new service is generated that exposes REST operations to create new orders (following the steps as defined in the main and sub-process), or to list and delete active orders.

You can choose to create this service based on either Quarkus or Spring Boot (select appropriate tab below). If you don't have any preference, we recommend you get started with Quarkus since it is a Kubernetes native Java stack (supporting GraalVM) with a lot of capabilities (like hot-reload in dev mode) that we can leverage.

Quarkus

Open your command line and go into the jbpm-quarkus-example folder. First we will build the service. Based on the process definitions, this will generate the necessary code to turn this into a domain-specific order service with REST endpoints to start, list and remove orders.

For local development, you have 3 options to build and start the service:

  • Since the service runs on top of Quarkus, you can take advantage of the development capabilities that Quarkus offers (like live reload etc.), and run the service in Quarkus development mode.
  • You can also run the service as a regular Java service.
  • You can take advantage of native image compilation (requires GraalVM), which will further optimize and minimize the service using native image compilation.
Please pick one of the options (A, B or C) below.

A. Build and run in development mode

mvn clean package quarkus:dev

Your service should be up and running, you can test your service now as described below.

B. Build and run in JVM mode

mvn clean package 
java -jar target/jbpm-quarkus-example-{version}-runner.jar
or on Windows
mvn clean package
java -jar target\jbpm-quarkus-example-{version}-runner.jar

Your service should be up and running, you can test your service now as described below.

C. Build and run in native mode (requires GraalVM)

mvn clean package -Pnative
./target/jbpm-quarkus-example-{version}-runner
Note: This does not yet work on Windows, GraalVM and Quarkus should be rolling out support for Windows soon.

Your service should be up and running, you can test your service now as described below. When running in development mode, Swagger UI can be used to look at or even test the exposed REST endpoints by navigating to http://localhost:8080/swagger-ui.

Spring Boot

Open your command line and go into the jbpm-springboot-example folder. First we will build the service. Based on the process definitions, this will generate the necessary code to turn this into domain-specific order service with REST endpoints to start, list and remove orders.

For local development, you have 2 options to build and start the service:

  • Since the service runs on top of Spring Boot, you can take advantage of the development capabilities that Spring Boot offers and run the service using the Spring Boot maven plugin.
  • You can also run the service as a regular Java service.
Please pick one of the options (A or B) below.

A. Build and run in development mode

mvn clean package spring-boot:run

Your service should be up and running, you can test your service now as described below.

B. Build and run in JVM mode

mvn clean package 
java -jar target/jbpm-springboot-example-{version}.jar
or on Windows
mvn clean package  
java -jar target\jbpm-springboot-example-{version}.jar

Your service should be up and running, you can test your service now as described below.

Test the running service

Once the service is up and running, you can use the following examples to interact with the service. Below are curl command you can run to do the REST calls but feel free to use the tool of your choice as well. For example, when running in Quarkus development mode you can use the Swagger UI by navigating to http://localhost:8080/swagger-ui).

POST /orders

Allows to create a new order with the given data:

curl -d '{"approver" : "john", "order" : {"orderNumber" : "12345", "shipped" : false}}' -H "Content-Type: application/json" -X POST http://localhost:8080/orders
or on Windows
curl -d "{\"approver\" : \"john\", \"order\" : {\"orderNumber\" : \"12345\", \"shipped\" : false}}" -H "Content-Type: application/json" -X POST http://localhost:8080/orders

As response the updated order is returned. Note that the order has an "id" field that now a generated unique id for this order, which should be used as id when trying to retrieve a specific order as shown below.

GET /orders

Returns list of orders currently active:

curl -X GET http://localhost:8080/orders

As response an array of orders is returned.

GET /orders/{id}

Returns order with given id (if active):

curl -X GET http://localhost:8080/orders/{id}

Note that you should fill in the id of the order you are trying to retrieve, which is returned when creating the order, as shown above. As response a single order is returned if found, otherwise no content (204) is returned.

DELETE /orders/{id}

Cancels order with given id

curl -X DELETE http://localhost:8080/orders/1

You have now successfully tested your service. You can now also try one of the other options of how you can build and run your service if you want to. You can try out other examples as well, all of them are equipped with a Readme file describing how to use them.

Create your first application

After running (one of) the out-of-the-box examples, you can also create your own application from scratch. This guide covers:

  • Configuring your IDE
  • Generating a new project
  • Building the project
  • Testing the project

Configuring your IDE

Currently the Eclipse IDE is the only IDE that has complete tooling support for both process and rule modeling, however Kogito Tooling provides a Visual Studio Code BPMN extension and the team is working on bringing in web-based embeddable editors (BPMN2, DMN and Scenario Simulation) to Eclipse Che or Red Hat CodeReady Workspaces.

Install Visual Studio Code Kogito Tooling

Kogito Tooling provides BPMN support (Alpha) for Visual Studio Code (VSCode). At the moment it is not available in VSCode marketplace, so download the BPMN VSIX file from Kogito Tooling releases page, in VSCode select Extensions (View -> Extensions or use the shortcut in Linux/Windows systems Ctrl + Shift + X), then select the 'More Options' (three dots) icon and load the downloaded VSIX file.

Install Eclipse with modeling plugins

Download and install Eclipse IDE for Java Developers. After starting Eclipse, also install the Eclipse BPMN2 Modeler from the Marketplace (Help -> Eclipse Marketplace... -> Search for 'BPMN2' to find Eclipse BPMN2 Modeler -> Click Install button -> also check 'BPMN2 Modeler - jBPM Runtime Extension Feature' and click Confirm etc. and restart Eclipse).

To build your own service that is powered by Kogito, the easiest way to get started is by generating a sample project using Maven Archetype. You can choose to create this service based on either Quarkus or Spring Boot (select appropriate tab below). If you don't have any preference, we recommend you get started with Quarkus since it is a Kubernetes native Java stack (supporting GraalVM) with a lot of capabilities (like hot-reload in dev mode) that we can leverage.

Generate project

Create an empty folder where you would like to generate your project, open your command line, go into the newly created folder and execute the following command to generate the project there:

mvn io.quarkus:quarkus-maven-plugin:create -DprojectGroupId=com.company -DprojectArtifactId=sample-kogito -Dextensions="kogito"

This command generates a Maven project, importing the kogito extension that comes with all needed dependencies and configuration to equip your application with business automation. Once the project is generated, import it into your Eclipse IDE (File -> Import... -> Select Maven > Existing Maven Projects, click Next, select the folder where you created your project and click Finish).

Implement your application logic

You are now ready to implement your business logic that can be composed of business processes, rules, decision tables, java services and more. For example, create a new process (*.bpmn2) in folder 'src/main/resources' that you can edit to encode your business logic.

Start your application

Open your command line and go into project folder you created. Same as when running the pre-built examples, you can build and run your project in Quarkus development mode, in JVM mode or in native mode. Please pick one of the options (A, B or C) below.

A. Build and run in development mode

mvn clean package quarkus:dev

B. Build and run in JVM mode

mvn clean package
java -jar target/sample-kogito-1.0-SNAPSHOT-runner.jar
or on Windows
mvn clean package
java -jar target\sample-kogito-1.0-SNAPSHOT-runner.jar

C. Build and run in native mode (requires GraalVM)

mvn clean package -Pnative
./target/sample-kogito-1.0-SNAPSHOT-runner
Note: Have a look at the complete quarkus kogito guide here.

Generate project

Open your command line, go to a folder where you would like to generate the project and execute the following command to generate the project (inside a new sample-kogito folder):

mvn archetype:generate -DarchetypeGroupId=org.kie.kogito -DarchetypeArtifactId=kogito-springboot-archetype -DgroupId=com.company -DartifactId=sample-kogito

Once the project is generated, import it into your Eclipse IDE (File -> Import... -> Select Maven > Existing Maven Projects, click Next, select the folder where you created your project and click Finish).

Implement your application logic

You are now ready to implement your business logic that can be composed of business processes, rules, decision tables, java services and more. Included in the project out-of-the-box is a process that you can edit to encode your business logic ('test-process.bpmn2' in folder 'src/main/resources').

Start your application

Open your command line and go into the newly created sample-kogito folder. Same as when running the pre-built examples, you can build and run your project in Spring Boot development mode or in JVM mode. Please pick one of the options (A or B) below.

A. Build and run in development mode

mvn clean package spring-boot:run

B. Build and run in JVM mode

mvn clean package
java -jar target/sample-kogito-1.0-SNAPSHOT-runner.jar
or on Windows
mvn clean package
java -jar target\sample-kogito-1.0-SNAPSHOT-runner.jar

Test your application

Once the service is up and running, you can use REST commands to interact with the service. For example, if you haven't changed the process included out-of-the-box, you start your process using:

POST /orders

Allows to create a new order with the given data:

curl -d "{}" -H "Content-Type: application/json" -X POST http://localhost:8080/tests