Menu Close

Chapter 17. Migration of a DMN service to a Red Hat build of Kogito microservice

You can migrate DMN-based decision services to Red Hat build of Kogito microservices by moving the DMN resources from KJAR artifacts to the respective Red Hat build of Kogito project. In the Red Hat build of Kogito microservices, some of the KIE v7 features are no longer required.

17.1. Major changes and migration considerations

The following table describes the major changes and features that affect migration from the KIE Server API and KJAR to Red Hat build of Kogito deployments:

Table 17.1. DMN migration considerations

FeatureIn KIE Server APIIn Red Hat build of Kogito artifact

DMN models

stored in src/main/resources of KJAR.

copy as is to src/main/resources.

Object models (POJOs) required for KIE Server generic marshalling

managed using Data Model object editor in Business Central.

object model editing is no longer required.

DMNRuntimeListener

configured using a system property or kmodule.xml file.

must be configured using CDI, by annotating the DMNRuntimeEventListener with CDI’s @ApplicationScope annotation.

Other configuration options

configured using system property or kmodule.xml file.

except DMNRuntimeEventListener, only default values are considered and no override of configuration is supported.

KIE Server Client API

used in conjunction with object models to interact with a KJAR that is deployed on the KIE Server.

for object models, this feature is no longer required.

Note

You can select your own choice of REST library.

REST API

when a KJAR is deployed on KIE Server, the applications interacting with specific DMN model endpoint, use the same API on Red Hat build of Kogito deployment.

advanced support for specific DMN model generation. For more information, see DMN model execution.

Test scenarios

run with a JUnit activator.

analogous JUnit activator is available on Red Hat build of Kogito.

Note

The features that are not mentioned in the previous table are either not supported or not required in a cloud-native Red Hat build of Kogito deployment.

17.2. Migration strategy

When migrating a DMN project to a Red Hat build of Kogito project, first you can migrate external applications that are interacting with decision services on the KIE Server. You can use the REST endpoints that are specific to DMN models. After using the REST endpoints, you can migrate the external applications from the KIE Server to a Red Hat build of Kogito deployment. For more information about specific REST endpoints to DMN models, see REST endpoints for specific DMN models.

The migration strategy includes the following steps:

  1. Migrate existing external applications from the generic KIE Server API to a specific DMN REST endpoint using the KIE Server.
  2. Migrate a KJAR that is deployed on the KIE Server to a Red Hat build of Kogito microservice.
  3. Deploy the Red Hat build of Kogito microservice using Red Hat OpenShift Container Platform.
  4. Reconnect the external application and migrate the REST API consumption from the specific DMN REST endpoint to the Red Hat build of Kogito deployment.

17.3. Migrating external applications to REST endpoints specific to DMN models

To migrate a DMN project to a Red Hat build of Kogito deployment, first you can migrate external applications that use specific DMN REST endpoints to interact with decision services on the KIE Server.

Procedure

  1. If you are using the REST endpoints in your external application, retrieve the Swagger or OAS specification file of the KJAR using GET /server/containers/{containerId}/dmn/openapi.json (|.yaml) endpoint.

    For more information about REST endpoints for specific DMN models, see REST endpoints for specific DMN models.

  2. In your external application, select the Java or JDK library to interact with the decision services. You can interact with the decision services using the REST endpoint for the specific KJAR.
Note

The KIE Server Client Java API is not supported in the migration to a Red Hat build of Kogito deployment.

17.4. Migrating a DMN model KJAR to a Red Hat build of Kogito microservice

After migrating your external application, you need to migrate a KJAR that is specific to a DMN model to a Red Hat build of Kogito microservice.

Procedure

  1. Create a Maven project for your Red Hat build of Kogito microservice.

    For the procedure about creating a Maven project, see Creating a Maven project for a Red Hat build of Kogito microservice.

    The Maven project creates Kogito artifacts.

  2. Copy the DMN models from the src/main/resources folder of the KJAR to the src/main/resources folder of the Kogito artifact.
  3. Copy the test scenarios from the src/test/resources folder of the KJAR to the src/test/resources folder of the Kogito artifact.

    Important

    You need to import the Red Hat build of Kogito dependency of test scenarios in the pom.xml file of your project and create a JUnit activator using the KIE Server REST API. For more information, see Testing a decision service using test scenarios.

  4. Run the following command and ensure that the test scenario is running for the specified non-regression tests.

    mvn clean install

    After running the Red Hat build of Kogito application, you can retrieve the Swagger or OAS specification file. The Swagger or OAS specifications provide the same information as the REST endpoint along with the following implementation details:

    • Base URL of the server where the API is available
    • References Schemas names

    You can use the provided implementation details when your external application is re-routed to the new URL.

After migrating a DMN model KJAR to a Red Hat build of Kogito microservice, you need to deploy the microservice using Red Hat OpenShift Container Platform. For deployment options with Openshift, see OpenShift deployment options with the RHPAM Kogito Operator.

17.4.1. Example of migrating a DMN model KJAR to a Red Hat build of Kogito microservice

The following is an example of migrating a DMN model KJAR to a Red Hat build of Kogito microservice:

Figure 17.1. Example decision service implemented using DMN model

Example of a DMN decision service

Figure 17.2. Example DMN model using specific ItemDefinition structure

Example of a DMN decision service using ItemDefinition structure

You need to define the object model (POJO) as a DTO in an existing KJAR that is developed in Business Central.

Example of an object model defined as DTO in a KJAR

package com.myspace.demo20210321;

/**
 * This class was automatically generated by the data modeler tool.
 */

public class Reservation implements java.io.Serializable {

	static final long serialVersionUID = 1L;
	@com.fasterxml.jackson.annotation.JsonFormat(shape = com.fasterxml.jackson.annotation.JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd")
    @com.fasterxml.jackson.databind.annotation.JsonSerialize(using = com.fasterxml.jackson.datatype.jsr310.ser.LocalDateSerializer.class)
	private java.time.LocalDate checkin;
	@com.fasterxml.jackson.annotation.JsonFormat(shape = com.fasterxml.jackson.annotation.JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd")
    @com.fasterxml.jackson.databind.annotation.JsonSerialize(using = com.fasterxml.jackson.datatype.jsr310.ser.LocalDateSerializer.class)
	private java.time.LocalDate checkout;

	private java.util.List<java.lang.String> guests;

	public Reservation() {
	}

	public java.time.LocalDate getCheckin() {
		return this.checkin;
	}

	public void setCheckin(java.time.LocalDate checkin) {
		this.checkin = checkin;
	}

	public java.time.LocalDate getCheckout() {
		return this.checkout;
	}

	public void setCheckout(java.time.LocalDate checkout) {
		this.checkout = checkout;
	}

	public java.util.List<java.lang.String> getGuests() {
		return this.guests;
	}

	public void setGuests(java.util.List<java.lang.String> guests) {
		this.guests = guests;
	}

	public Reservation(java.time.LocalDate checkin,
			java.time.LocalDate checkout,
			java.util.List<java.lang.String> guests) {
		this.checkin = checkin;
		this.checkout = checkout;
		this.guests = guests;
	}

}

In the previous example, the defined DTO is used in conjunction with the KIE Server client Java API. Alternatively, you can specify the DTO in the payload, when a non-Java external application is interacting with the KJAR that is deployed on the KIE Server.

Example of using KIE Server client Java API

DMNServicesClient dmnClient = kieServicesClient.getServicesClient(DMNServicesClient.class);
 DMNContext dmnContext = dmnClient.newContext();
 dmnContext.set("reservation", new com.myspace.demo20210321.Reservation(LocalDate.of(2021, 3, 1),
                                                                         LocalDate.of(2021, 3, 8),
                                                                         Arrays.asList("John", "Alice")));
 run(dmnClient, dmnContext);

Figure 17.3. Example of manually specifying DTO in the payload

Example of KJAR deployed manually
Note

In the previous example, the FQCN of the object model in the REST API is used for the generic KIE Server marshalling.

17.5. Example of binding an external application to a Red Hat build of Kogito deployment

After deploying the Red Hat build of Kogito microservice, you need to bind your external application to the Red Hat build of Kogito microservice deployment.

Binding your external application includes re-routing the external application and binding the application to a new base URL of the server that is associated with the Red Hat build of Kogito application. For more information, see the following example:

Figure 17.4. Example /discount REST endpoint of KJAR on KIE Server

Example of a DMN model specific REST endpoint of KJAR on KIE Server

Figure 17.5. Example /discount REST endpoint on local Red Hat build of Kogito

Example of a DMN model specific REST endpoint running on local Kogito application

Figure 17.6. Example /discount REST endpoint bound to new base URL of Red Hat build of Kogito

Example of a DMN model specific REST endpoint with new base URL