Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 3. Intelligent Process Server

The Intelligent Process Server is a standalone, built-in component that can be used to instantiate and execute rules through interfaces available for REST, JMS, or a Java client side application, as well as to manage processes, jobs, and Business Resource Planner functionality through solvers. Created as a web deployable WAR file, this server can be deployed on any web container. The current version of the Intelligent Process Server is included with default extensions for both Red Hat JBoss BRMS and Red Hat JBoss BPM Suite.

This server has a low footprint with minimal memory consumption and therefore can be deployed easily on a cloud instance. Each instance of this server can open and instantiate multiple KIE containers which allows you to execute multiple rule services in parallel.

You can provision the Intelligent Process Server instances through Business Central. In this chapter, the steps required to set up the Intelligent Process Server, provision and connect to the server through Business Central, control what artifacts go in each instance, and go through its lifecycle are provided.

Note

For more information, see the Intelligent Process Server and Realtime Decision Server chapter of the Red Hat JBoss BPM Suite Development Guide.

3.1. Deploying Intelligent Process Server

The Intelligent Process Server is distributed as a web application archive (WAR) file kie-server.war. When you install Red Hat JBoss BPM Suite, the WAR file is installed and deployed in your web container by default.

You can copy the WAR file and deploy it in any other web container, such as Red Hat JBoss Web Server or another Red Hat JBoss EAP install. Note that the WAR file must be compatible with the container.

  1. Once you have deployed the WAR file, create a user with the role kie-server in the web container.
Note

You can change the kie-server user role in the web.xml file or in Keycloak.

  1. Verify that you can access the decision engine: open http://SERVER:PORT/kie-server/services/rest/server/ in a web browser and enter the user name and the password specified in the previous step.

  2. Once authenticated, an XML response in the form of engine status opens: 

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response type="SUCCESS" msg="Kie Server info">
  <kie-server-info>
    <capabilities>BPM</capabilities>
    <capabilities>KieServer</capabilities>
    <capabilities>BRM</capabilities>
    <location>http://localhost:8230/kie-server/services/rest/server</location>
    <name>KieServer@/kie-server</name>
    <id>15ad5bfa-7532-3eea-940a-abbbbc89f1e8</id>
    <version>6.4.0.Final-redhat-5</version>
  </kie-server-info>
</response>

3.2. Installing Intelligent Process Server in Other Containers

3.2.1. Red Hat JBoss Web Server 2.X/3.X, Tomcat 8.X/9.X

Use the following procedure to install the Intelligent Process Server in a Tomcat container.

  1. Follow the steps described in section Generic Deployable Bundle Installation of Red Hat JBoss BPM Suite Installation Guide to download and extract the generic deployable archive containing kie-server.war.

  2. Configure users and roles. Make sure that the TOMCAT_HOME/conf/tomcat-users.xml file contains the following role and user definition. The user name and password should be unique, however, the role must be defined as kie-server: 

    <role rolename="kie-server"/>
<user username="serveruser" password="my.s3cr3t.pass" roles="kie-server"/>

  3. Start the server: run TOMCAT_HOME/bin/startup.sh or in a Windows system TOMCAT_HOME/bin/startup.bat. To make sure that the application was deployed successfully, see Tomcat logs in the TOMCAT_HOME/logs directory. See Section 3.3.1, “Bootstrap Switches” for the list of bootstrap switches that can be used to properly configure the instance. For example: 

    $ ./startup.sh -Dorg.kie.server.id=first-kie-server -Dorg.kie.server.location=http://localhost:8080/kie-server/services/rest/server
  4. To verify that the server is running, open http://SERVER:PORT/kie-server/services/rest/server/ in a web browser and enter the user name and the password specified before. You should see a simple XML message with basic information about the server.
Important

It is not possible to use the JMS interface if the Intelligent Process Server was installed on Tomcat or any other web container. The web container version of the WAR file contains only the REST interface.

3.3. Intelligent Process Server Setup

3.3.1. Bootstrap Switches

The Intelligent Process Server accepts a number of bootstrap switches (system properties) to configure the behavior of the server.

Table 3.1. Bootstrap Switches for Disabling Intelligent Process Server Extensions
PropertyValuesDefaultDescription

org.drools.server.ext.disabled

true, false

false

If set to true, disables the BRM support (for example rules support).

org.jbpm.server.ext.disabled

true, false

false

If set to true, disables the BPM support (for example processes support).

org.optaplanner.server.ext.disabled

true, false

false

If set to true, disables the BRP support (for example planner support).

org.jbpm.ui.server.ext.disabled

true, false

false

If set to true, disables the Intelligent Process Server UI extension.

org.kie.executor.disabled

true, false

false

Disables the Red Hat JBoss BPM Suite executor.

Note

Some controller properties listed below are marked as required. Set these properties when you handle Intelligent Process Server container creation and removal in Business Central. If you use the Intelligent Process Server separately without any interaction with Business Central, the properties do not have to be set.

Table 3.2. Bootstrap Switches Required for Using a Controller
PropertyValuesDefaultDescription

org.kie.server.id

String

N/A

An arbitrary ID to be assigned to the server. If a remote controller is configured, this is the ID under which the server will connect to the controller to fetch the KIE container configurations. If not provided, the ID is automatically generated.

org.kie.server.user

String

kieserver

The user name used to connect with the Intelligent Process Server from the controller, required when running in managed mode. Set this property in Business Central system properties. Setting this property is required when using a controller.

org.kie.server.pwd

String

kieserver1!

The password used to connect with the Intelligent Process Server from the controller, required when running in managed mode. Set this property in Business Central system properties. Setting this property is required when using a controller.

org.kie.server.token

String

N/A

This property enables you to use a token-based authentication between the controller and the Intelligent Process Server instead of the basic user name/password authentication. The controller sends the token as a parameter in the request header. Note that long-lived access tokens are required as the tokens are not refreshed.

org.kie.server.location

URL

N/A

The URL of the Intelligent Process Server instance used by the controller to call back on this server, for example: http://localhost:8230/kie-server/services/rest/server. Setting this property is required when using a controller.

org.kie.server.controller

Comma-separated list

N/A

A comma-separated list of URLs to the controller REST endpoints, for example http://localhost:8080/business-central/rest/controller. Setting this property is required when using a controller.

org.kie.server.controller.user

String

kieserver

The user name to connect to the controller REST API. Setting this property is required when using a controller.

org.kie.server.controller.pwd

String

kieserver1!

The password to connect to the controller REST API. Setting this property is required when using a controller.

org.kie.server.controller.token

String

N/A

This property enables you to use a token-based authentication between the Intelligent Process Server and the controller instead of the basic user name/password authentication. The server sends the token as a parameter in the request header. Note that long-lived access tokens are required as the tokens are not refreshed.

org.kie.server.controller.connect

Long

10000

The waiting time in milliseconds between repeated attempts to connect the Intelligent Process Server to the controller when the server starts.

Table 3.3. Bootstrap Switches for Persistence Properties
PropertyValuesDefaultDescription

org.kie.server.persistence.ds

String

N/A

A data source JNDI name. Set this property when enabling the BPM support.

org.kie.server.persistence.tm

String

N/A

A transaction manager platform for Hibernate properties set. Set this property when enabling the BPM support.

org.kie.server.persistence.dialect

String

N/A

The Hibernate dialect to be used. Set this property when enabling the BPM support.

org.kie.server.persistence.schema

String

N/A

The database schema to be used.

Important

Make sure the new data source for the Intelligent Process Server points to a different database schema than the data source used by Business Central by modifying the org.kie.server.persistence.ds property in order to avoid conflicts. This does not apply if you configured unified execution servers as described in Section 3.3.4, “Unified Execution Servers”.

Table 3.4. Bootstrap Switches for Executor Properties
PropertyValuesDefaultDescription

org.kie.executor.interval

Integer

3

The time between the moment the Red Hat JBoss BPM Suite executor finishes a job and the moment it starts a new one, in a time unit specified in the org.kie.executor.timeunit property.

org.kie.executor.timeunit

java.util.concurrent.TimeUnit constant

SECONDS

The time unit in which the org.kie.executor.interval property is specified.

org.kie.executor.pool.size

Integer

1

The number of threads used by the Red Hat JBoss BPM Suite executor.

org.kie.executor.retry.count

Integer

3

The number of retries the Red Hat JBoss BPM Suite executor attempts on a failed job.

Table 3.5. Callback Bootstrap Switches
PropertyValuesDefaultDescription

org.jbpm.ht.callback

mvel

ldap

db

jaas

props

custom

jaas

Specifies the implementation of user group callback to be used:

  • mvel: Default; mostly used for testing.
  • ldap: LDAP; requires additional configuration in the jbpm.usergroup.callback.properties file.
  • db: Database; requires additional configuration in the jbpm.usergroup.callback.properties file.
  • jaas: JAAS; delegates to the container to fetch information about user data.
  • props: A simple property file; requires additional file that will keep all information (users and groups).
  • custom: A custom implementation; specify the fully qualified name of the class in the org.jbpm.ht.custom.callback property.

org.jbpm.ht.custom.callback

Fully qualified name

N/A

A custom implementation of the UserGroupCallback interface in case the org.jbpm.ht.callback property is set to custom.

Table 3.6. Other Bootstrap Switches
PropertyValuesDefaultDescription

kie.maven.settings.custom

Path

N/A

The location of a custom settings.xml file for Maven configuration.

kie.server.jms.queues.response

String

queue/KIE.SERVER.RESPONSE

The response queue JNDI name for JMS.

org.drools.server.filter.classes

true, false

false

When set to true, the Drools Intelligent Process Server extension accepts custom classes annotated by the XmlRootElement or Remotable annotations only.

org.kie.server.bypass.auth.user

true, false

false

Allows to bypass the authenticated user for task-related operations, for example queries.

org.kie.server.domain

String

N/A

The JAAS LoginContext domain used to authenticate users when using JMS.

org.kie.server.repo

Path

.

The location where Intelligent Process Server state files will be stored.

org.kie.server.sync.deploy

true, false

false

Instructs the Intelligent Process Server to hold the deployment until the controller provides the containers deployment configuration. This property affects only the servers running in managed mode. The options are as follows:

  • false; the connection to the controller is asynchronous. The application starts, connects to the controller, and once successful, deploys the containers. The application accepts requests even before the containers are available.
  • true; the deployment of the server application joins the controller connection thread with the main deployment and awaits its completion. This option can lead to a potential deadlock in case more applications are on the same server instance. It is strongly recommended to use only one application (the server) on one server instance.

3.3.2. Managed Intelligent Process Server

A managed instance requires an available controller to start the Intelligent Process Server.

A controller manages the Intelligent Process Server configuration in a centralized way. Each controller can manage multiple configurations at once, and there can be multiple controllers in the environment. Managed Intelligent Process Server can be configured with a list of controllers, but will only connect to one at a time.

Important

Controllers should be synchronized to ensure that the same set of configuration is provided to the server, regardless of the controller to which it connects.

When the Intelligent Process Server is configured with a list of controllers, it will attempt to connect to each of them at startup until a connection is successfully established with one of them. If a connection cannot be established, the server will not start, even if there is a local storage available with configuration. This ensures consistence and prevents the server from running with redundant configuration.

Note

To run the Intelligent Process Server in standalone mode without connecting to controllers, see Section 3.3.3, “Unmanaged Intelligent Process Server”.

Configuring Intelligent Process Server Managed by Business Central

Warning

This section provides a sample setup that you can use for testing purposes. Some of the values are unsuitable for a production environment, and are marked as such.

Configure the Business Central to manage an Intelligent Process Server instance by performing the following steps:

Configuring Intelligent Process Server Managed by Business Central

  1. Make sure users with the following roles exist:

    • In Business Central, a user with the role rest-all.
    • On the Intelligent Process Server, a user with the role kie-server.
    Note

    In production environments, use two distinct users, each with one role. In this sample situation, we use only one user named controllerUser that has both the rest-all and the kie-server roles.

    If such users do not exist, create them.

    • On Red Hat JBoss EAP, go to EAP_HOME/bin/ and execute: 

      $ ./add-user.sh -a --user controllerUser --password controllerUser1234; --role kie-server,rest-all
      Warning

      Plain-text passwords are not secure. For production environments, use a password vault. For more information, see the Password Vault chapter of the Red Hat JBoss Enterprise Application Platform 6.4 How To Configure Server Security guide.

    • On Red Hat JBoss Web Server, see Section 3.2.1, “Red Hat JBoss Web Server 2.X/3.X, Tomcat 8.X/9.X”.
    • On IBM WebSphere Application Server, see the Creating Users and Groups section of the Red Hat JBoss BPM Suite IBM WebSphere Installation and Configuration Guide.
    • On Oracle WebLogic Server, see the Configuring Security Settings section of the Red Hat JBoss BPM Suite Oracle Weblogic Installation and Configuration Guide.

  2. Set the following JVM properties. The location of Business Central and the Intelligent Process Server may be different. In such case, ensure you set the properties on the correct server instances.

    Table 3.7. JVM Properties for Intelligent Process Server Instance
    PropertyValueNote

    org.kie.server.id

    default-kie-server

    The Intelligent Process Server ID.

    org.kie.server.controller

    http://localhost:8080/business-central/rest/controller

    The location of Business Central.

    org.kie.server.controller.user

    controllerUser

    The user name with the role rest-all as mentioned in the previous step.

    org.kie.server.controller.pwd

    controllerUser1234;

    The password of the user mentioned in the previous step.

    org.kie.server.location

    http://localhost:8080/kie-server/services/rest/server

    The location of the Intelligent Process Server.

    Table 3.8. JVM Properties for Business Central Instance
    PropertyValueNote

    org.kie.server.user

    controllerUser

    The user name with the role kie-server as mentioned in the previous step.

    org.kie.server.pwd

    controllerUser1234;

    The password of the user mentioned in the previous step.

  3. Verify the successful start of the Intelligent Process Server by sending a GET request to http://SERVER:PORT/kie-server/services/rest/server/. Once authenticated, you get an XML response similar to this: 

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response type="SUCCESS" msg="Kie Server info">
    <kie-server-info>
        <capabilities>BRM</capabilities>
        <capabilities>BPM-UI</capabilities>
        <capabilities>BPM</capabilities>
        <capabilities>BRP</capabilities>
        <capabilities>KieServer</capabilities>
        <location>http://localhost:8080/kie-server/services/rest/server</location>
        <messages>
            <content>Server KieServerInfo{serverId='local-server-123', version='6.4.0.Final-redhat-3', location='http://localhost:8080/kie-server/services/rest/server'}started successfully at Fri Jun 03 13:48:44 CEST 2016</content>
            <severity>INFO</severity>
            <timestamp>2016-06-03T13:48:44.606+02:00</timestamp>
        </messages>
        <name>local-server-123</name>
        <id>local-server-123</id>
        <version>6.4.0.Final-redhat-3</version>
    </kie-server-info>
</response>
  4. Verify successful registration by logging into Business Central and selecting Deploy Execution Servers. If successful, you can see the registered server ID.

3.3.3. Unmanaged Intelligent Process Server

An unmanaged Intelligent Process Server is a standalone instance, and therefore must be configured individually using REST/JMS API from the Intelligent Process Server itself. There is no controller involved. The configuration is automatically persisted by the server into a file and that is used as the internal server state, in case of restarts.

The configuration is updated during the following operations:

  • Deploy KIE Container
  • Undeploy KIE Container
  • Start KIE Container
  • Stop KIE Container
Note

If the Intelligent Process Server is restarted, it will attempt to re-establish the same state that was persisted before shutdown. Therefore, KIE Containers that were running will be started, but the ones that were stopped will not.

3.3.4. Unified Execution Servers

Since Red Hat JBoss BPM Suite version 6.4, it is possible to configure both Business Central and the Intelligent Process Server to use the same data source. This enables you to work with your processes using both applications. In such a setup, it is recommended to use Business Central for operations that require a graphical user interface and the Intelligent Process Server for all remote calls.

Warning

The following restrictions apply:

  • The Container ID must be the same as the deployment unit ID.
  • The SINGLETON runtime strategy cannot be used.
  • Triggering the execution of a part of a single process instance, between two safe points, on both the execution servers results in a successful execution on the first execution server only. The other execution server will throw an exception and will not modify the process data in the database.

Do not deploy both Business Central and Intelligent Process Server in the same application server in a production environment. Deploying both Business Central and Intelligent Process Server in the same application server is only applicable for development environments. Furthermore, unified execution settings require the exact same configurations (such as database, scheduler, executor, KJAR deployments, and so on) regardless of whether the deployment uses a single application server or not.

When configuring unified execution servers, the Intelligent Process Server must be managed by Business Central according to Section 3.3.2, “Managed Intelligent Process Server”, and the following system properties need to be set:

3.4. Creating Containers

Once the Intelligent Process Server is registered, you can start adding containers. Containers are self-contained environments that have been provisioned to hold instances of your packaged and deployed rule instances.

To create a container:

  1. Log in to Business Central.
  2. In the main menu on the top, click Deploy Execution Servers.
  3. Select your server from the SERVER TEMPLATES section on the left side of the page.

  4. Click Add Container in the KIE CONTAINERS section.

    The New Container dialog window opens.

  5. Enter a name of your container and search for the project you want to deploy in the container. Click Select next to the project to automatically enter the project’s details.

    Alternatively, you can enter Group Name, Artifact Id, and Version manually.

    Warning

    When entering the container’s version number, do not use the LATEST or RELEASE keywords. This feature has been deprecated and can cause deployment issues.

  6. Click Next to configure the runtime strategy, KieBase, KieSession, and merge mode for your container. You can skip this step.
  7. Click Finish.

After the container is successfully created, click Start at the upper right hand corner to start it.

Figure 3.1. Container in Started Mode

Container in Started Mode

To verify that the container is running, send a [GET] request to the endpoint.

Example 3.1. Server Response

<response type="SUCCESS" msg="Info for container myContainer">
  <kie-container container-id="myContainer" status="STARTED">
    <messages>
      <content>Container myContainer successfully created with module org.jbpm:CustomersRelationship:1.0.</content>
      <severity>INFO</severity>
      <timestamp>2016-03-02T11:43:40.806+01:00</timestamp>
    </messages>
    <release-id>
      <artifact-id>CustomersRelationship</artifact-id>
      <group-id>org.jbpm</group-id>
      <version>1.0</version>
    </release-id>
    <resolved-release-id>
      <artifact-id>CustomersRelationship</artifact-id>
      <group-id>org.jbpm</group-id>
      <version>1.0</version>
    </resolved-release-id>
    <scanner status="DISPOSED"/>
  </kie-container>
</response>

3.5. Managing Containers

Containers within the Intelligent Process Server can be started, stopped, and updated from Business Central.

3.5.1. Starting, Stopping, and Deleting Containers

A container is stopped by default. To start the container:

  1. Log in to Business Central.
  2. In the main menu on the top, click Deploy Execution Servers.
  3. Select your server from the SERVER TEMPLATES section on the left side of the page.
  4. Find the container you want to start under the KIE CONTAINERS section on the left.

  5. Click Start at the upper right hand corner.

    Alternatively, click Stop to stop a running container. Once a container is stopped, you can click Remove to remove it.

3.5.2. Upgrading Containers

It is possible to update deployed containers without restarting the Intelligent Process Server, which can be used in cases where business rule changes cause new versions of packages to be provisioned. You can have multiple versions of the same package provisioned and deployed.

To upgrade a container:

  1. Log in to Business Central.
  2. In the main menu on the top, click Deploy Execution Servers.
  3. Select your server from the SERVER TEMPLATES section on the left side of the page.
  4. Find the container you want to upgrade under the KIE CONTAINERS section on the left.
  5. Click on the Version Configuration tab at the top.

  6. Enter a new version and click Upgrade.

    Optionally, if you want a deployed container to always have the latest version of your deployment without manually editing it, set the Version value to LATEST and click Scan Now. If a newer version of a container deployment is found in the repository during the scanning, the container is automatically upgraded to this newer version. To start the scanner in the background, click Start Scanner and specify a scan interval in milliseconds.

    The Version value can be set to LATEST if you are creating a deployment for the first time.

3.5.3. Managing Multiple Containers

The Intelligent Process Server allows you to create and provision multiple containers.

Select your server under the REMOTE SERVERS section to view all containers and their statuses.

Figure 3.2. Managing Multiple Containers

Managing Multiple Containers
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.