There are several major functionality differences between the regular release of Red Hat JBoss Intelligent Process Server and the OpenShift Intelligent Process Server xPaaS image:

As the Intelligent Process Server image is built off the OpenShift JBoss EAP xPaaS image, the JBoss EAP Management CLI is accessible from within the container for troubleshooting purposes.

The Intelligent Process Server xPaaS image requires a service account for deployments. For multiple node deployments, the service account must have the view role enabled so that it can manage the various pods in the cluster. In addition, you will need to configure SSL to enable connections to Intelligent Process Server from outside of the OpenShift instance.

The Intelligent Process Server image requires two keystores:

These keystores are expected by the Intelligent Process Server image, even if the application uses only http on a single-node OpenShift instance. Note that self-signed certificates do not provide secure communication and are intended for internal testing purposes.

See Generate a SSL Encryption Key and Certificate for more information on how to create a keystore with self-signed or purchased SSL certificates.

OpenShift uses objects called Secrets to hold sensitive information, such as passwords or keystores. See the Secrets chapter in the OpenShift documentation for more information.

The Intelligent Process Server image requires a secret that holds the two keystores described earlier. This provides the necessary authorization to applications in the project.

Use the Java and JGroups keystore files to create a secret for the project:

$ oc create secret generic <ips-secret-name> --from-file=<jgroups.jceks> --from-file=<keystore.jks>

After the secret has been generated, it can be associated with a service account.

The service account allows users to associate certain secrets and roles with applications in a project namespace. This provides the application with the necessary authorization to run with all required privileges.

The project must be configured to use a remote repository so that Business Central can push changes and OpenShift can pull the repository to build the application. In the application repository files:

Use the Recreate Update Strategy for the Intelligent Process Server deployment. This update strategy automatically scales down the old deployment to 0 and deploys the new version. After the new version is validated, the new deployment is automatically scaled up to the replica size of the old deployment.

The Recreate update strategy supports Lifecycle Hooks and is set as the default update strategy in the Intelligent Process Server application templates.

The container ID is an md5 sum hash generated from the <alias>=<group_id>:<artifact_id>:<version> of the application, and is used for client communication. In the case of multiple versions, each version of the application will have a unique container ID, but share the deployment alias name.

If an application has already been deployed, use the KIE_CONTAINER_DEPLOYMENT_OVERRIDE variable in the .s2i/environment file, and specify the <alias>=<group_id>:<artifact_id>:<version> for each version of the application to override the KIE_CONTAINER_DEPLOYMENT variable in the json application template. This is useful for preserving older versions of an application that are still in use.

For example, the ApplicationTest application example:

KIE_CONTAINER_DEPLOYMENT=ApplicationTest=com.example.openshift:example_workflow:1.0

To maintain this version of the application, but to add an updated version, update the .s2i/environment file:

KIE_CONTAINER_DEPLOYMENT_OVERRIDE=ApplicationTest=com.example.openshift:example_workflow:1.0|ApplicationTest=com.example.openshift:example_workflow:1.1

See Example Workflow: Deploying an Updated Version Concurrently with Original Application for an example on deploying an updated application alongside the older version.

In most cases, clients must target a particular container by name to execute server-side functions. This can be done by specifying the full deployment name, the container ID hash, or the deployment alias.

For example:

Specifying either the full deployment name or the container ID targets the appropriate container. Specifying the deployment alias, which is used by all the containers in the KIE server, requires a multi-stage resolution process to target the correct version container.

In a multi-version deployment, all applications share the same deployment alias. Requests that use the deployment alias of the application require a resolution process in order to redirect the request to the container of the correct version.

Resolution Process Hierarchy

The multi-stage resolution process depends on the method invoked by the client, and the ID associated with the request:

Process Hierarchy (in descending order):

Clients

Multiple clients can be used to invoke the server, depending on the client interaction type:

Conversation ID

A conversation represents interactions between KIE Services Java clients and the server. When a client initiates a conversation, the response from the server includes an encoded multi-part heading. The client will then use this heading in subsequent requests to the server. This conversation header contains the conversation ID, which is used by the Servlet Filter in the REST interface, or the EJB Interceptor in the JMS interface, to determine the correct version of the application to invoke.

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.jboss.bom.brms</groupId>
        <artifactId>jboss-brms-bpmsuite-platform-bom</artifactId>
          <version>6.3.1.GA-redhat-2</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Default Container ID

The final stage in the process hierarchy is the default container ID. If a specific container ID cannot be resolved, the default container ID is determined as the application with the latest version (based on <alias>=<group_id>:<artifact_id>:<version>).

Prepare a Git repository for the project configuration files. The repository is used to store the Maven repository and KIE container deployment files. The Git repository has the following file hierarchy:

Preparation of the BPMS project may require some prior knowledge with the Red Hat JBoss BPM Suite. Refer to the Red Hat JBoss BPM Suite User Guide for more information on any of these tasks.

During the build, the Maven repository is downloaded and build into the container so that no additional packages or dependencies are downloaded at runtime.

The application is available once the pod is running.

Clients can use the REST API in various ways:

// LibraryClient.java
KieServicesConfiguration config = KieServicesFactory.newRestConfiguration(
  "http://host/kie-server/services/rest/server", "kieserverUser", "kieserverPassword");
config.setMarshallingFormat(MarshallingFormat.XSTREAM);
ProcessServicesClient client =
  KieServicesFactory.newKieServicesClient(config).getServicesClient(ProcessServicesClient.class);
Map<String,Object> params = new HashMap<String,Object>();
LoanRequest loanRequest = new LoanRequest();
loanRequest.setIsbn("978-0-307-35193-7");
params.put("loanRequest", loanRequest);
Long processInstanceId = client.startProcess("processserver-library", "LibraryProcess", params);

Client can also use the Java Messaging Service, as demonstrated below:

// LibraryClient.java
Properties props = new Properties();
props.setProperty(Context.INITIAL_CONTEXT_FACTORY,
  "org.jboss.naming.remote.client.InitialContextFactory");
props.setProperty(Context.PROVIDER_URL, "remote://host:4447");
props.setProperty(Context.SECURITY_PRINCIPAL, "kieserverUser");
props.setProperty(Context.SECURITY_CREDENTIALS, "kieserverPassword");
InitialContext context = new InitialContext(props);
KieServicesConfiguration config =
  KieServicesFactory.newJMSConfiguration(context, "hornetqUser", "hornetqPassword");
config.setMarshallingFormat(MarshallingFormat.XSTREAM);
ProcessServicesClient client =
  KieServicesFactory.newKieServicesClient(config).getServicesClient(ProcessServicesClient.class);
Map<String,Object> params = new HashMap<String,Object>();
LoanRequest loanRequest = new LoanRequest();
loanRequest.setIsbn("978-0-307-35193-7");
params.put("loanRequest", loanRequest);
Long processInstanceId = client.startProcess("processserver-library", "LibraryProcess", params);

// LibraryClient.java
props.setProperty(Context.INITIAL_CONTEXT_FACTORY,
  "org.apache.activemq.jndi.ActiveMQInitialContextFactory");
props.setProperty(Context.PROVIDER_URL, "tcp://host:61616");
props.setProperty(Context.SECURITY_PRINCIPAL, "kieserverUser");
props.setProperty(Context.SECURITY_CREDENTIALS, "kieserverPassword");
InitialContext context = new InitialContext(props);
ConnectionFactory connectionFactory = (ConnectionFactory)context.lookup("ConnectionFactory");
Queue requestQueue = (Queue)context.lookup("dynamicQueues/queue/KIE.SERVER.REQUEST");
Queue responseQueue = (Queue)context.lookup("dynamicQueues/queue/KIE.SERVER.RESPONSE");
KieServicesConfiguration config = KieServicesFactory.newJMSConfiguration(
  connectionFactory, requestQueue, responseQueue, "activemqUser", "activemqPassword");
config.setMarshallingFormat(MarshallingFormat.XSTREAM);
ProcessServicesClient client =
  KieServicesFactory.newKieServicesClient(config).getServicesClient(ProcessServicesClient.class);
Map<String,Object> params = new HashMap<String,Object>();
LoanRequest loanRequest = new LoanRequest();
loanRequest.setIsbn("978-0-307-35193-7");
params.put("loanRequest", loanRequest);
Long processInstanceId = client.startProcess("processserver-library", "LibraryProcess", params);