Language:
Format:

Red Hat Training

A Red Hat training course is available for Red Hat Decision Manager

Installing and configuring Red Hat Business Optimizer

Red Hat Decision Manager 7.0

Red Hat Customer Content Services

brms-docs@redhat.com

Legal Notice

Abstract

This document describes how to install and configure Red Hat Business Optimizer in Red Hat Decision Manager 7.0.

Preface

As a business rules developer, you can use the Red Hat Business Optimizer to find the optimal solution to planning problems based on a set of limited resources and under specific constraints.

Use this document to set up and configure Red Hat Business Optimizer functionality.

Prerequisite

The Employee Rostering sample project is created in Decision Central to demonstrate Business Optimizer capabilities. To view this project, you must have Red Hat Decision Manager installed. For more information about setting up and installing Red Hat Decision Manager and Decision Central, see Getting started with decision services.

Part I. Solve planning problems using Business Optimizer

Chapter 1. What is Red Hat Business Optimizer

Red Hat Business Optimizer is a lightweight, embeddable planning engine that optimizes planning problems. It helps normal Java programmers solve planning problems efficiently, and it combines optimization heuristics and metaheuristics with very efficient score calculations.

For example, Red Hat Business Optimizer helps solve various use cases:

Employee/Patient Rosters: It helps create timetables for nurses and keeps track of patient bed management.
Educational Timetables: It helps schedule lessons, courses, exams, and conference presentations.
Shop Schedules: It tracks car assembly lines, machine queue planning, and workforce task planning.
Cutting Stock: It minimizes waste by reducing the consumption of resources such as paper and steel.

Every organization faces planning problems; that is, they provide products and services with a limited set of constrained resources (employees, assets, time, and money).

Red Hat Business Optimizer is open source software under the Apache Software License 2.0. It is 100% pure Java and runs on most Java virtual machines.

1.1. A planning problem is NP-complete or NP-hard

The provided use cases are probably NP-complete or NP-hard, which means the following statements apply:

It is easy to verify a given solution to a problem in reasonable time.
There is no simple way to find the optimal solution of a problem in reasonable time.

The implication is that solving your problem is probably harder than you anticipated, because the two common techniques will not suffice:

A brute force algorithm (even a more advanced variant) will take too long.
A quick algorithm, for example in the bin packing problem, putting in the largest items first will return a solution that is far from optimal.

By using advanced optimization algorithms, the Business Optimizer does find a good solution in reasonable time for such planning problems.

Chapter 2. What is a planning problem?

A planning problem has an optimal goal, based on limited resources and under specific constraints. Optimal goals can be any number of things, such as:

Maximized profits - the optimal goal results in the highest possible profit.
Minimized ecological footprint - the optimal goal has the least amount of environmental impact.
Maximized satisfaction for employees or customers - the optimal goal prioritizes the needs of employees or customers.

The ability to achieve these goals relies on the number of resources available. For example, the following resources might be limited:

The number of people
Amount of time
Budget
Physical assets, for example, machinery, vehicles, computers, buildings, and so on

You must also take into account the specific constraints related to these resources, such as the number of hours a person works, their ability to use certain machines, or compatibility between pieces of equipment.

The Business Optimizer helps Java programmers solve constraint satisfaction problems efficiently. It combines optimization heuristics and metaheuristics with efficient score calculation.

2.1. A planning problem has a huge search space

A planning problem has a number of solutions.

There are several categories of solutions:

Possible solution: A possible solution is any solution, whether or not it breaks any number of constraints. Planning problems often have an incredibly large number of possible solutions. Many of those solutions are worthless.
Feasible solution: A feasible solution is a solution that does not break any (negative) hard constraints. The number of feasible solutions tends to be relative to the number of possible solutions. Sometimes there are no feasible solutions. Every feasible solution is a possible solution.
Optimal solution: An optimal solution is a solution with the highest score. Planning problems usually have a few optimal solutions. They always have at least one optimal solution, even in the case that there are no feasible solutions and the optimal solution is not feasible.
Best solution found: The best solution found is the solution with the highest score found by an implementation in a given amount of time. The best solution found is likely to be feasible and, given enough time, it’s an optimal solution.

Counterintuitively, the number of possible solutions is huge (if calculated correctly), even with a small data set.

In the examples provided in the planner-engine distribution folder, most instances have a vast number of possible solutions. As there is no guaranteed way to find the optimal solution, any implementation is forced to evaluate at least a subset of all those possible solutions.

The Business Optimizer supports several optimization algorithms to efficiently wade through that incredibly large number of possible solutions.

Depending on the use case, some optimization algorithms perform better than others, but it is impossible to tell in advance. Using the Business Optimizer, you can switch the optimization algorithm by changing the solver configuration in a few lines of XML or code.

2.2. A planning problem has constraints

Usually, a planning problem has at least two levels of constraints:

A (negative) hard constraint must not be broken.
For example, one teacher can not teach two different lessons at the same time.
A (negative) soft constraint should not be broken if it can be avoided.
For example, Teacher A does not like to teach on Friday afternoons.

Some problems also have positive constraints:

A positive soft constraint (or reward) should be fulfilled if possible.
For example, Teacher B likes to teach on Monday mornings.

Some basic problems only have hard constraints. Some problems have three or more levels of constraints, for example, hard, medium, and soft constraints.

These constraints define the score calculation (otherwise known as the fitness function) of a planning problem. Each solution of a planning problem can be graded with a score. With the Business Optimizer, score constraints are written in an object oriented language, such as Java code or Drools rules.

This type of code is flexible and scalable.

Part II. Download and install Business Optimizer

Chapter 3. Download Red Hat Business Optimizer

Red Hat Business Optimizer can be used to optimize business solutions in Decision Central, in your preferred IDE, or on OpenShift.

Procedure

Download and install Red Hat Decision Manager from the Red Hat Customer Portal. See Installing Red Hat Decision Manager on premise for more information about installing Red Hat Decision Manager.
Download the rhdm-7.0.0.GA-add-ons.zip file from the Red Hat Decision Manager section of the Red Hat Customer Portal.
Extract the Red Hat Business Optimizer engine from the rhdm-7.0.0.GA-planner-engine.zip file to access the complete set of Red Hat Business Optimizer engine JAR files.
Run the examples.

See Migrating from Red Hat BRMS 6.4 to Red Hat Decision Manager 7.0 for information about migrating from previous versions of Red Hat Business Optimizer.

Chapter 4. Installing the Red Hat Business Optimizer engine in your application

Red Hat Business Optimizer can be installed using Maven or other applications, such as Gradle, Ivy, or Buildr.

Prerequisite

The Red Hat Decision Manager has been downloaded and installed from the Red Hat Customer Portal. See Getting started with decision services for more information about installing Red Hat Decision Manager.

Procedure

Get the Red Hat Business Optimizer optaplanner-core JARs at the Red Hat JBoss Maven Repository.
Identify the latest version by checking the Red Hat JBoss Maven Repository.

Add a dependency to optaplanner-core in your project’s pom.xml:

  <dependency>
      <groupId>org.optaplanner</groupId>
      <artifactId>optaplanner-core</artifactId>
      <version>{MAVEN_ARTIFACT_VERSION}</version>
  </dependency>

(Optional) Add any other Red Hat Business Optimizer engine modules that you require, such as the optaplanner-persistence-jpa or optaplanner-persistence-xstream integration modules. For more information about how to configure Red Hat Business Optimizer for use with other Java technologies, see the Optaplanner documentation.

Note

The optaplanner-benchmark module is included as part of the engine, however, it is recommended to be used as a separate module, as demonstrated in the this Employee Rostering module. This is to avoid leaking the optaplanner-benchmark into the .war file.

Alternatively, if you are using Ant (without Ivy) you can install the engine by copying all of the JARs from the downloaded ZIP’s binaries directory. Manually verify that your classpath does not contain duplicate JARs.

Note

The downloaded .zip file binaries directory contains far more JARs then optaplanner-core actually uses. It also contains the JARs used by other modules, such as optaplanner-benchmark.

Check the Maven repository pom.xml files to determine the minimal dependency set for a specific version of a specific module.

Part III. Run the examples

Chapter 5. Running the Business Optimizer examples

Red Hat Business Optimizer includes a number of examples to demonstrate a variety of use cases.

Prerequisite

Download and install Red Hat Decision Manager from the Red Hat Customer Portal.

Procedure

Download the rhdm-7.0.0.GA-add-ons.zip file from the Red Hat Decision Manager section of the Red Hat Customer Portal.
Extract the Red Hat Business Optimizer engine from the rhdm-7.0.0.GA-planner-engine.zip file.
In the rhdm-7.0.0.GA-planner-engine folder, open the examples directory and use the appropriate script to run the examples:
Linux or Mac:
```
$ cd examples
$ ./runExamples.sh
```
Windows:
```
$ cd examples
$ runExamples.bat
```

Select and run an example from the GUI application window:

Note

Red Hat Business Optimizer itself has no GUI dependencies. It runs just as well on a server or a mobile JVM as it does on the desktop.

5.1. Running the Red Hat Business Optimizer examples in an IDE (IntelliJ, Eclipse, or Netbeans)

Use the following procedure to run the Red Hat Business Optimizer examples in IntelliJ or Netbeans:

Procedure

Open the file examples/sources/pom.xml as a new project.
The Maven integration will take care of the rest of the installation.

Use the following procedure to run the Red Hat Business Optimizer examples in Eclipse:

Procedure

Open a new project for the directory examples/sources.
Add all the JARs to the classpath from the directory binaries and the directory examples/binaries , except for the file examples/binaries/optaplanner-examples-*.jar.
Add the Java source directory src/main/java and the Java resources directory src/main/resources.
Create a run configuration:
- Main class: org.optaplanner.examples.app.OptaPlannerExamplesApp
- VM parameters (optional): -Xmx512M -server
- Working directory: examples/sources
Run the run configuration.

Part IV. Configure the Decision Server

Chapter 6. Decision Server

The Decision 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, and Red Hat Business Optimizer functionality through solvers. Created as a web deployable WAR file, this server can be deployed on any web container. The current version of the Decision Server is included with default extensions for both Red Hat Decision Manager and Red Hat Business Automation.

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 Decision Server instances through Decision Central.

Chapter 7. Deploying Decision Server

The Decision Server is distributed as a web application archive (WAR) file kie-server.war. When you install Red Hat Decision Manager, deploy the kie-server.war file for full functionality. For information about how to deploy the Decision Server, see Installing Red Hat Decision Manager on premise.

Prerequisite

The Red Hat Decision Manager has been downloaded and deployed with the kie-server.war file.

Procedure

Create a user with the role kie-server in the web container.
Verify that you can access the decision engine.
1. In a web browser, open http://SERVER:PORT/kie-server/services/rest/server/
2. Enter the user name and the password specified in the previous step.

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>KieServer</capabilities>
      <capabilities>BRM</capabilities>
      <capabilities>BPM</capabilities>
      <location>http://localhost:8230/kie-server/services/rest/server</location>
      <name>first-kie-server</name>
      <id>first-kie-server</id>
      <version>7.5.1.Final-redhat-1</version>
  </kie-server-info>
</response>

7.1. Bootstrap Switches

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

Table 7.1. Bootstrap Switches for Disabling Decision Server Extensions

Property	Values	Default	Description
`org.drools.server.ext.disabled`	`true`, `false`	`false`	If set to `true`, disables the Decision Manager support (for example rules support).
`org.jbpm.server.ext.disabled`	`true`, `false`	`false`	If set to `true`, disables the Business Automation support (for example processes support).
`org.optaplanner.server.ext.disabled`	`true`, `false`	`false`	If set to `true`, disables the Business Optimizer support.
`org.jbpm.ui.server.ext.disabled`	`true`, `false`	`false`	If set to `true`, disables the Decision Server UI extension.
`org.kie.executor.disabled`	`true`, `false`	`false`	Disables the Red Hat Decision Manager executor.

Note

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

Table 7.2. Bootstrap Switches Required for Using a Controller

Property	Values	Default	Description
`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 Decision Server from the controller, required when running in managed mode. Set this property in Decision Central system properties. Set this property when using a controller.
`org.kie.server.pwd`	String	`kieserver1!`	The password used to connect with the Decision Server from the controller, required when running in managed mode. Set this property in Decision Central system properties. Set this property when using a controller.
`org.kie.server.token`	String	N/A	A property that enables you to use token-based authentication between the controller and the Decision Server instead of the basic user name/password authentication. The controller sends the token as a parameter in the request header. The server requires long-lived access tokens as the tokens are not refreshed.
`org.kie.server.location`	URL	N/A	The URL of the Decision 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/decision-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	A property that enables you to use token-based authentication between the Decision 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 Decision Server to the controller when the server starts.

Table 7.3. Bootstrap Switches for Executor Properties

Property	Values	Default	Description
`org.kie.executor.interval`	Integer	`3`	The time between the moment the Red Hat Decision Manager 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 Decision Manager executor.
`org.kie.executor.retry.count`	Integer	`3`	The number of retries the Red Hat Decision Manager executor attempts on a failed job.

Table 7.4. Other Bootstrap Switches

Property	Values	Default	Description
`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 Decision Server extension accepts custom classes annotated by the `XmlRootElement` or `Remotable` annotations only.
`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 Decision Server state files will be stored.
`org.kie.server.sync.deploy`	`true`, `false`	`false`	A property that instructs the Decision Server to hold the deployment until the controller provides the containers deployment configuration. This property only affects 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 recommended that you use only one application (the server) on one server instance.

Chapter 8. Managed Decision Server

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

A controller manages the Decision Server configuration in a centralized way. Each controller can manage multiple configurations at once, and there can be multiple controllers in the environment. Managed Decision 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 Decision 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 Decision Server in standalone mode without connecting to controllers, see Section 8.2, “Unmanaged Decision Server”.

8.1. Configuring Decision Server Managed by Decision 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.

Use this procedure to configure Decision Central to manage a Decision Server instance.

Prerequisite

Users with the following roles exist:

In Decision Central, a user with the role rest-all.
On the Decision 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.

Procedure

Set the following JVM properties.

The location of Decision Central and the Decision Server may be different. In such case, ensure you set the properties on the correct server instances.

On Red Hat JBoss EAP, modify the <system-properties> section in:
- EAP_HOME/standalone/configuration/standalone*.xml for standalone mode.
- EAP_HOME/domain/configuration/domain.xml for domain mode.

Table 8.1. JVM Properties for Managed Decision Server Instance

Property	Value	Note
`org.kie.server.id`	`default-kie-server`	The Decision Server ID.
`org.kie.server.controller`	`http://localhost:8080/decision-central/rest/controller`	The location of Decision 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 Decision Server.

Table 8.2. JVM Properties for Decision Central Instance

Property	Value	Note
`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.

Verify the successful start of the Decision 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:

<response type="SUCCESS" msg="Kie Server info">
    <kie-server-info>
        <capabilities>KieServer</capabilities>
        <capabilities>BRM</capabilities>
        <capabilities>BPM</capabilities>
        <capabilities>CaseMgmt</capabilities>
        <capabilities>BPM-UI</capabilities>
        <capabilities>BRP</capabilities>
        <capabilities>DMN</capabilities>
        <capabilities>Swagger</capabilities>
        <location>http://localhost:8230/kie-server/services/rest/server</location>
        <messages>
            <content>Server KieServerInfo{serverId='first-kie-server', version='7.5.1.Final-redhat-1', location='http://localhost:8230/kie-server/services/rest/server', capabilities=[KieServer, BRM, BPM, CaseMgmt, BPM-UI, BRP, DMN, Swagger]}started successfully at Mon Feb 05 15:44:35 AEST 2018</content>
            <severity>INFO</severity>
            <timestamp>2018-02-05T15:44:35.355+10:00</timestamp>
        </messages>
        <name>first-kie-server</name>
        <id>first-kie-server</id>
        <version>7.5.1.Final-redhat-1</version>
    </kie-server-info>
</response>

Verify successful registration:
1. Log in to Decision Central.
2. Click Menu → Deploy → Execution Servers.
  If registration is successful, you can see the registered server ID.

8.2. Unmanaged Decision Server

An unmanaged Decision Server is a standalone instance, and therefore must be configured individually using REST/JMS API from the Decision 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 Decision 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.

Chapter 9. Creating Containers

Containers are self-contained environments that have been provisioned to hold instances of your packaged and deployed rule instances.

Prerequisite

Once the Decision Server is registered, you can start adding containers.

Procedure

Log in to Decision Central.
In the main menu, click Menu → Deploy → Execution Servers.
Click SERVER TEMPLATES → + New Server Template.
In the New Server Template window, click Container.
Enter the Group Name, Artifact Id, and Version manually.
Alternatively, enter the 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 details of the project.
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.
To deploy the container automatically, select the Start Container? box.
Click Finish.

After the container is successfully created, select the container from the list and click Start at the upper right hand corner to start it

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

Example 9.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>TIMESTAMP</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>

Chapter 10. Managing Containers in Decision Central

Containers within the Decision Server can be started, stopped, and updated from Decision Central.

10.1. Starting, Stopping, and Deleting Containers in Decision Central

When a container is created in Decision Central, it is stopped by default.

Use the following procedure to start the container:

Prerequisite

A container has been created and configured in Decision Central.

Procedure

Log in to Decision Central.
In the main menu, click Menu → Deploy → Execution Servers.
Select your server from the SERVER TEMPLATES section on the left side of the page.
Select the container you want to start under the KIE CONTAINERS section on the left.
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.

10.2. Upgrading Containers in Decision Central

Deployed containers can be updated without restarting the Decision Server. This might be required 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.

Use the following procedure to upgrade a container:

Prerequisite

The Decision Server is configured with a container running in Decision Central.

Procedure

Log in to Decision Central.
In the main menu, click Menu → Deploy → Execution Servers.
Select your server from the SERVER TEMPLATES section on the left side of the page.
Select the container you want to upgrade under the KIE CONTAINERS section on the left.
Click on the Version Configuration tab at the top.
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.

10.3. Managing Multiple Containers

The Decision Server allows you to create and provision multiple containers. Use the following procedure to create and interact with multiple containers:

Prerequisite

The Decision Server has been registered and you are logged in to Decision Central.

Procedure

In the main menu, click Menu → Deploy → Execution Servers.
Select your server from the SERVER TEMPLATES section on the left side of the page.
Select your server under the REMOTE SERVERS section to view all containers and their statuses.

Part V. Configure the Red Hat Business Optimizer REST API

Note

All REST API calls use the following URL with the endpoint base URL: http://SERVER:PORT/decision-central/rest/REQUEST_BODY.

Chapter 11. Knowledge Store REST API

REST API calls to the Knowledge Store REST API allow you to manage the organization units, repositories, and projects.

All POST and DELETE calls return details about the request as well as a job ID that can be used to request the job status and verify whether the job finished successfully. The GET calls return information about repositories, projects, and organizational units.

Parameters and results of these calls are provided in the form of JSON entities. Java classes for different entities are available in the org.guvnor.rest.client package and are referenced in the following text.

11.1. Job Calls

Most Knowledge Store REST calls return a job ID after they are issued. This is necessary as the calls are asynchronous and it is required to be able to reference the job later to check its status as it goes through a job lifecycle.

During its lifecycle, a job can have the following statuses:

Table 11.1. Job Statuses

Status	Description
`ACCEPTED`	The job was accepted and is being processed.
`BAD_REQUEST`	The request was not accepted as it contained incorrect content.
`RESOURCE_NOT_EXIST`	The requested resource (path) does not exist.
`DUPLICATE_RESOURCE`	The resource already exists.
`SERVER_ERROR`	An error on the server side occurred.
`SUCCESS`	The job finished successfully.
`FAIL`	The job failed.
`APPROVED`	The job was approved.
`DENIED`	The job was denied.
`GONE`	The job ID could not be found. A job can be `GONE` in the following cases: The job was explicitly removed. The job finished and has been deleted from a status cache. A job is removed from a status cache after the cache has reached its maximum capacity. The job never existed.

The following job calls are provided:

[GET] /jobs/JOB_ID

Returns a status of the given JOB_ID.

Example 11.1. Formatted Response to GET Job Call on Repository Clone Request

{
  "status" : "SUCCESS",
  "jobId" : "1377770574783-27",
  "result" : "Alias: testInstallAndDeployProject, Scheme: git, Uri: git://testInstallAndDeployProject",
  "lastModified" : 1377770578194,
  "detailedResult" : null
}

[DELETE] /jobs/JOB_ID

Removes a job with the given JOB_ID. If the job is not being processed yet, the call will remove the job from the job queue. However, this call will not cancel or stop an ongoing job.

Both of these job calls return a JobResult instance.

11.2. Organizational Unit Calls

Organizational unit calls are calls to the Knowledge Store that allow you to manage its organizational units which are useful to model departments and divisions. An organization unit can hold multiple repositories.

The following organizational unit calls are provided:

[GET] /organizationalunits/

Returns a list of all organizational units.

Example 11.2. Organizational Unit List in JSON Format

[ {
  "name" : "EmployeeWage",
  "description" : null,
  "owner" : "Employee",
  "defaultGroupId" : "org.bpms",
  "repositories" : [ "EmployeeRepo", "OtherRepo" ]
}, {
  "name" : "OrgUnitName",
  "description" : null,
  "owner" : "OrgUnitOwner",
  "defaultGroupId" : "org.group.id",
  "repositories" : [ "repository-name-1", "repository-name-2" ]
} ]

[GET] /organizationalunits/ORGANIZATIONAL_UNIT_NAME

Returns information about a specific organizational unit.

[POST] /organizationalunits/

Creates an organizational unit in the Knowledge Store. The organizational unit is defined as a JSON entity. The call requires an OrganizationalUnit instance and returns a CreateOrganizationalUnitRequest instance.

Example 11.3. Organizational Unit in JSON Format

{
  "name" : "testgroup",
  "description" : "",
  "owner" : "tester",
  "repositories" : ["testGroupRepository"]
}

[POST] /organizationalunits/ORGANIZATIONAL_UNIT_NAME

Updates the details of an existing organizational unit.

Both the name and owner fields in the required UpdateOrganizationalUnit instance can be left empty. Neither the description field nor the repository association can be updated using this operation.

Example 11.4. Update Organizational Unit Input in JSON Format

{
  "owner" : "NewOwner",
  "defaultGroupId" : "org.new.default.group.id"
}

[DELETE] /organizationalunits/ORGANIZATIONAL_UNIT_NAME

Removes a specified organizational unit.

[POST] /organizationalunits/ORGANIZATIONAL_UNIT_NAME/repositories/REPOSITORY_NAME

Adds a repository to an organizational unit.

[DELETE] /organizationalunits/ORGANIZATIONAL_UNIT_NAME/repositories/REPOSITORY_NAME

Removes a repository from an organizational unit.

11.3. Repository Calls

Repository calls are calls to the Knowledge Store that allow you to manage its Git repositories and their projects.

The following repository calls are provided:

[GET] /repositories

Returns a list of repositories in the Knowledge Store.

Example 11.5. Response of Repository Call

[
  {
    "name": "bpms-assets",
    "description": "generic assets",
    "userName": null,
    "password": null,
    "requestType": null,
    "gitURL": "git://brms-assets"
  },
  {
    "name": "loanProject",
    "description": "Loan processes and rules",
    "userName": null,
    "password": null,
    "requestType": null,
    "gitURL": "git://loansProject"
  }
]

[GET] /repositories/REPOSITORY_NAME

Returns information about a specific repository.

[DELETE] /repositories/REPOSITORY_NAME

Removes a repository.

[POST] /repositories/

Creates or clones a repository defined by a JSON entity.

Example 11.6. JSON Entity with Details about Repository to Be Cloned

{
  "name": "myClonedRepository",
  "organizationalUnitName": "example",
  "description": "",
  "userName": "",
  "password": "",
  "requestType": "clone",
  "gitURL": "git://localhost/example-repository"
}

Example 11.7. JSON Entity with Details about Repository to Be Created

{
  "name": "myCreatedRepository",
  "organizationalUnitName": "example",
  "description": "",
  "userName": "",
  "password": "",
  "requestType": "create",
  "gitURL": "git://localhost/example-repository"
}

Important

Make sure you always include the organizationalUnitName key-value pair in your query and that the specified organization unit exists before you create or clone the repository.

[GET] /repositories/REPOSITORY_NAME/projects/

Returns a list of projects in a specific repository as a JSON entity.

Example 11.8. JSON Entity with Details about Existing Projects

[ {
  "name" : "my-project-name",
  "description" : "A project to illustrate a REST output.",
  "groupId" : "com.acme",
  "version" : "1.0"
}, {
  "name" : "yet-another-project-name",
  "description" : "Yet another project to illustrate a REST output.",
  "groupId" : "com.acme",
  "version" : "2.2.1"
} ]

[POST] /repositories/REPOSITORY_NAME/projects/

Creates a project in a repository.

Example 11.9. Request Body That Defines Project to Be Created

{
  "name" : "NewProject",
  "description" : "Description of the new project.",
  "groupId" : "org.redhat.test",
  "version" : "1.0.0"
}

[DELETE] /repositories/REPOSITORY_NAME/projects/PROJECT_NAME

Removes a project in a repository.

Part VI. The REST API for Decision Server Execution

Chapter 12. The REST API for Decision Server

You can communicate with the Decision Server through the REST API.

The base URL for sending requests is the endpoint defined earlier, for example http://SERVER:PORT/kie-server/services/rest/server/.
All requests require basic HTTP Authentication or token-based authentication for the role kie-server.

Following methods support three formats of the requests: JSON, JAXB, and XSTREAM. You must provide following HTTP headers:

Accept: set to application/json or application/xml.
When specifying more than one accepted content type in the Accept header, be sure to include the qualifiers of preference (qvalues as defined in the HTML 1.1 standard). If you do not, unexpected behavior can occur. This is an example of a well-formed header with multiple accepted content types:
```
Accept: application/xml; q=0.5, application/json; q=0.9
```
X-KIE-ContentType is required when using the XSTREAM marshaller. In such case, set the header to XSTREAM. Values JSON and JAXB are allowed, but not required. When you set the Content-type to application/xml, the JAXB value is used by default.
Content-type: set to application/json or application/xml. This header corresponds with the format of your payload.
--data: your payload. If the payload is in a file, start the name with an ampersand @. For example:
```
--data @commandsRequest.json
```

To ensure both the request and the response are in the same format, always specify both the Content-Type and Accept HTTP headers in your application’s requests. Otherwise, you can receive a marshalling-related error from the server.

The examples use the Curl utility. You can use any REST client. Curl commands use the following parameters:

-u: specifies username:password for the Decision Server authentication.
-H: specifies HTTP headers.
-X: specifies the HTTP method of the request, that is [GET], [POST], [PUT], or [DELETE].

Note

Red Hat Decision Manager commands will work only if your Decision Server has Red Hat Decision Manager capability. The rest of the endpoints will work only if your Decision Server has Red Hat Business Automation capabilities. Check the following URI for capabilities of your Decision Server : http://SERVER:PORT/kie-server/services/rest/server.

12.1. Red Hat Decision Manager commands

[POST] /containers/instances/CONTAINER_ID

Request Type: A single org.kie.api.command.Command command or multiples commands in BatchExecutionCommand wrapper.
Response Type: org.kie.server.api.model.ServiceResponse<String>
Description: Executes the commands sent to the specified CONTAINER_ID and returns the commands execution results. For more information, see the supported commands below.

List of supported commands:

AgendaGroupSetFocusCommand
ClearActivationGroupCommand
ClearAgendaCommand
ClearAgendaGroupCommand
ClearRuleFlowGroupCommand
DeleteCommand
InsertObjectCommand
ModifyCommand
GetObjectCommand
InsertElementsCommand
FireAllRulesCommand
QueryCommand
SetGlobalCommand
GetGlobalCommand
GetObjectsCommand
BatchExecutionCommand
DisposeCommand

For more information about the commands, see the org.drools.core.command.runtime package.

[POST] Drools Commands Execution

Change into a directory of your choice and create commandsRequest.json :

{
      "lookup" : null,
      "commands" : [ {
        "insert" : {
          "object" : "testing",
          "disconnected" : false,
          "out-identifier" : null,
          "return-object" : true,
          "entry-point" : "DEFAULT"
        }

      }, {
        "fire-all-rules" : { }
      } ]
    }

Execute the following command:
```
$ curl -X POST -H 'X-KIE-ContentType: JSON' -H 'Content-type: application/json' -u 'kieserver:kieserver1!' --data @commandsRequest.json http://localhost:8080/kie-server/services/rest/server/containers/instances/myContainer
```
The command generates a request that sends the Insert Object and Fire All Rules commands to the server. Lookup specifies a ksession configured in your kjar. If you use a null lookup value, the default KIE session will be used.

An example response:

    {
      "type" : "SUCCESS",
      "msg" : "Container hello successfully called.",
      "result" : "{\n  \"results\" : [ ],\n  \"facts\" : [ ]\n}"
    }

Chapter 13. Configure the Red Hat Business Optimizer REST API

The Decision Server supports the following Red Hat Business Optimizer REST APIs. These APIs are also available through JMS and the Java client API.

Prerequisite

Red Hat Decision Manager has been installed and configured with basic HTTP Authentication for the kie-server role. You have identified the server endpoint base URL, for example, http://SERVER:PORT/CONTEXT/services/rest/server/.

To get a specific marshalling format, add the HTTP headers Content-Type and optional X-KIE-ContentType in the HTTP request. For example:

Content-Type: application/xml
X-KIE-ContentType: xstream

Note

X-KIE-ContentType supports the following values: xstream, xml, json.

The requests and responses in the example below assume that a KIE container is built using the Employee Rostering example in Decision Central, by calling a PUT on /services/rest/server/containers/employee-rostering with this content:

<kie-container container-id="employee-rostering">
  <release-id>
    <group-id>employeerostering</group-id>
    <artifact-id>employeerostering</artifact-id>
    <version>1.0.0-SNAPSHOT</version>
  </release-id>
</kie-container>

13.1. [GET] /containers

Returns the list of created containers.

Example 13.1. Example Server Response (XStream)

<response type="SUCCESS" msg="List of created containers">
  <result class="kie-containers">
    <kie-container>
      <container-id>employee-rostering</container-id>
        <release-id>
          <group-id>employeerostering</group-id>
          <artifact-id>employeerostering</artifact-id>
          <version>1.0.0-SNAPSHOT</version>
        </release-id>
        <resolved-release-id>
          <group-id>employeerostering</group-id>
          <artifact-id>employeerostering</artifact-id>
          <version>1.0.0-SNAPSHOT</version>
        </resolved-release-id>
        <status>STARTED</status>
        <scanner>
          <status>DISPOSED</status>
        </scanner>
    </kie-container>
  </result>
</response>

13.2. [PUT] /containers/{containerId}/solvers/{solverId}

Creates a new solver with the given {solverId} in the container {containerId}. The request’s body is a marshalled SolverInstance entity that must specify the solver configuration file.

The following is an example of the request and the corresponding response.

Example 13.2. Example Server Request (XStream)

<solver-instance>
  <solver-config-file>employeerostering/employeerostering/EmployeeRosteringSolverConfig.solver.xml</solver-config-file>
</solver-instance>

Example 13.3. Example Server Response (XStream)

<solver-instance>
  <container-id>employee-rostering</container-id>
  <solver-id>solver1</solver-id>
  <solver-config-file>employeerostering/employeerostering/EmployeeRosteringSolverConfig.solver.xml</solver-config-file>
  <status>NOT_SOLVING</status>
  <score/>
</solver-instance>

13.3. [GET] /containers/{containerId}/solvers

Returns the list of solvers created in the container.

Example 13.4. Example Server Response (XStream)

<org.kie.server.api.model.instance.SolverInstanceList>
  <solvers>
    <solver-instance>
      <container-id>employee-rostering</container-id>
      <solver-id>solver1</solver-id>
      <solver-config-file>employeerostering/employeerostering/EmployeeRosteringSolverConfig.solver.xml</solver-config-file>
      <status>NOT_SOLVING</status>
      <score/>
    </solver-instance>
  </solvers>
</org.kie.server.api.model.instance.SolverInstanceList>

13.4. [GET] /containers/{containerId}/solvers/{solverId}

Returns the current state of the solver {solverId} in container {containerId}.

Example 13.5. Example Server Response (XStream)

<solver-instance>
  <container-id>employee-rostering</container-id>
  <solver-id>solver1</solver-id>
  <solver-config-file>employeerostering/employeerostering/EmployeeRosteringSolverConfig.solver.xml</solver-config-file>
  <status>NOT_SOLVING</status>
  <score/>
</solver-instance>

13.5. [POST] /containers/{containerId}/solvers/{solverId}/state/solving

Starts the solver {solverId} in container {containerId} if it is not executing yet. The request’s body is a marshalled PlanningSolution to be optimized.

The following is an example to solve the OptaCloud problem with 2 computers and 6 processes. The solver runs asynchronously. Send a request to the bestsolution URL to get the best solution.

Example 13.6. Example Server Request (XStream)

<employeerostering.employeerostering.EmployeeRoster>
  <employeeList>
    <employeerostering.employeerostering.Employee>
      <name>John</name>
      <skills>
        <employeerostering.employeerostering.Skill>
          <name>reading</name>
        </employeerostering.employeerostering.Skill>
      </skills>
    </employeerostering.employeerostering.Employee>
    <employeerostering.employeerostering.Employee>
      <name>Mary</name>
      <skills>
        <employeerostering.employeerostering.Skill>
          <name>writing</name>
        </employeerostering.employeerostering.Skill>
      </skills>
    </employeerostering.employeerostering.Employee>
    <employeerostering.employeerostering.Employee>
      <name>Petr</name>
      <skills>
        <employeerostering.employeerostering.Skill>
          <name>speaking</name>
        </employeerostering.employeerostering.Skill>
      </skills>
    </employeerostering.employeerostering.Employee>
  </employeeList>
  <shiftList>
    <employeerostering.employeerostering.Shift>
      <timeslot>
        <startTime>2017-01-01T00:00:00</startTime>
        <endTime>2017-01-01T01:00:00</endTime>
      </timeslot>
      <requiredSkill reference="../../../employeeList/employeerostering.employeerostering.Employee/skills/employeerostering.employeerostering.Skill"/>
    </employeerostering.employeerostering.Shift>
    <employeerostering.employeerostering.Shift>
      <timeslot reference="../../employeerostering.employeerostering.Shift/timeslot"/>
      <requiredSkill reference="../../../employeeList/employeerostering.employeerostering.Employee[3]/skills/employeerostering.employeerostering.Skill"/>
    </employeerostering.employeerostering.Shift>
    <employeerostering.employeerostering.Shift>
      <timeslot reference="../../employeerostering.employeerostering.Shift/timeslot"/>
      <requiredSkill reference="../../../employeeList/employeerostering.employeerostering.Employee[2]/skills/employeerostering.employeerostering.Skill"/>
    </employeerostering.employeerostering.Shift>
  </shiftList>
  <skillList>
    <employeerostering.employeerostering.Skill reference="../../employeeList/employeerostering.employeerostering.Employee/skills/employeerostering.employeerostering.Skill"/>
    <employeerostering.employeerostering.Skill reference="../../employeeList/employeerostering.employeerostering.Employee[3]/skills/employeerostering.employeerostering.Skill"/>
    <employeerostering.employeerostering.Skill reference="../../employeeList/employeerostering.employeerostering.Employee[2]/skills/employeerostering.employeerostering.Skill"/>
  </skillList>
  <timeslotList>
    <employeerostering.employeerostering.Timeslot reference="../../shiftList/employeerostering.employeerostering.Shift/timeslot"/>
  </timeslotList>
  <dayOffRequestList/>
  <shiftAssignmentList/>
</employeerostering.employeerostering.EmployeeRoster>

13.6. [POST] /containers/{containerId}/solvers/{solverId}/state/terminating-early

Requests the solver to terminate early, if it is running. This does not delete the solver, the best solution can still be retrieved.

13.7. [GET] /containers/{containerId}/solvers/{solverId}/bestsolution

Returns the best solution found at the time the request is made. If the solver has not terminated yet (so the status field is still SOLVING), it will return the best solution found up to then, but later calls can return a better solution.⁠

Example 13.7. Example Server Response (XStream)

<solver-instance>
  <container-id>employee-rostering</container-id>
  <solver-id>solver1</solver-id>
  <solver-config-file>employeerostering/employeerostering/EmployeeRosteringSolverConfig.solver.xml</solver-config-file>
  <status>NOT_SOLVING</status>
  <score scoreClass="org.optaplanner.core.api.score.buildin.hardsoft.HardSoftScore">0hard/0soft</score>
  <best-solution class="employeerostering.employeerostering.EmployeeRoster">
    <employeeList>
      <employeerostering.employeerostering.Employee>
        <name>John</name>
        <skills>
          <employeerostering.employeerostering.Skill>
            <name>reading</name>
          </employeerostering.employeerostering.Skill>
        </skills>
      </employeerostering.employeerostering.Employee>
      <employeerostering.employeerostering.Employee>
        <name>Mary</name>
        <skills>
          <employeerostering.employeerostering.Skill>
            <name>writing</name>
          </employeerostering.employeerostering.Skill>
        </skills>
      </employeerostering.employeerostering.Employee>
      <employeerostering.employeerostering.Employee>
        <name>Petr</name>
        <skills>
          <employeerostering.employeerostering.Skill>
            <name>speaking</name>
          </employeerostering.employeerostering.Skill>
        </skills>
      </employeerostering.employeerostering.Employee>
    </employeeList>
    <shiftList>
      <employeerostering.employeerostering.Shift>
        <timeslot>
          <startTime>2017-01-01T00:00:00</startTime>
          <endTime>2017-01-01T01:00:00</endTime>
        </timeslot>
        <requiredSkill reference="../../../employeeList/employeerostering.employeerostering.Employee/skills/employeerostering.employeerostering.Skill"/>
      </employeerostering.employeerostering.Shift>
      <employeerostering.employeerostering.Shift>
        <timeslot reference="../../employeerostering.employeerostering.Shift/timeslot"/>
        <requiredSkill reference="../../../employeeList/employeerostering.employeerostering.Employee[3]/skills/employeerostering.employeerostering.Skill"/>
      </employeerostering.employeerostering.Shift>
      <employeerostering.employeerostering.Shift>
        <timeslot reference="../../employeerostering.employeerostering.Shift/timeslot"/>
        <requiredSkill reference="../../../employeeList/employeerostering.employeerostering.Employee[2]/skills/employeerostering.employeerostering.Skill"/>
      </employeerostering.employeerostering.Shift>
    </shiftList>
    <skillList>
      <employeerostering.employeerostering.Skill reference="../../employeeList/employeerostering.employeerostering.Employee/skills/employeerostering.employeerostering.Skill"/>
      <employeerostering.employeerostering.Skill reference="../../employeeList/employeerostering.employeerostering.Employee[3]/skills/employeerostering.employeerostering.Skill"/>
      <employeerostering.employeerostering.Skill reference="../../employeeList/employeerostering.employeerostering.Employee[2]/skills/employeerostering.employeerostering.Skill"/>
    </skillList>
    <timeslotList>
      <employeerostering.employeerostering.Timeslot reference="../../shiftList/employeerostering.employeerostering.Shift/timeslot"/>
    </timeslotList>
    <dayOffRequestList/>
    <shiftAssignmentList/>
    <score>0hard/0soft</score>
  </best-solution>
</solver-instance>

13.8. [POST] /containers/{containerId}/solvers/{solverId}/problemfactchanges

Real-time planning feature. Submits one or multiple ProblemFactChanges to update the dataset the solver currently optimizes.

13.9. [GET] /containers/{containerId}/solvers/{solverId}/problemfactchanges/processed

Real-time planning feature. Returns true if the solver processed all ProblemFactChanges that had been submitted. Returns false otherwise.

13.10. [DELETE] /containers/{containerId}/solvers/{solverId}

⁠Disposes the solver {solverId} in container {containerId}. If it has not terminated yet, it terminates it first.

Part VII. Author planning assets and create solvers

Chapter 14. Create a Solver in Decision Central

The Solver editor creates a solver configuration that can be run in the Execution Solver or plain Java code after the KJAR is deployed.

You can edit and create Solver configurations in Decision Central.

Prerequisite

Red Hat Decision Manager has been downloaded and installed. Your project has been designed and deployed with all relevant assets configured.

This example uses the provided Employee Rostering sample project to demonstrate Solver features.

Procedure

In Decision Central, click Menu → Projects, and click on your project to open it.
In the Assets perspective, click Create New Asset → Solver configuration
In the Create new Solver configuration window, type a name for your Solver and click Ok.
This opens the Solver configuration editor.
In the Score Director Factory configuration section, define a knowledge base that contains scoring rule definitions.
1. Select one of the knowledge sessions defined within the knowledge base.
  The sessions can be managed in the Project perspective in Decision Central by clicking Menu → Projects.
  Note
  Red Hat Business Optimizer uses a default knowledge session if none is specified.
Click the Validate button to validate the Solver configuration. This will actually build a Solver, which will notify you of most issues in your project without the need to deploy and run it.

By default, the Solver configuration automatically scans for all planning entities and planning solution classes. If none are found (or too many), validation fails.

14.1. Configure Solver termination

By default, the planning engine is given an unlimited time period to solve a problem instance.

This might be enforced by some scenarios (for example, real time planning), it is useful to have a mechanism to control total duration of the solving process.

Refer to OptaPlanner documentation for more information on supported termination types.

Note

The Solver can be terminated manually using the Decision Server REST API.

Prerequisite

You have deployed a project and created a Solver in Decision Central.

Procedure

Open the Solver editor,
In the Termination section, click Add to create new termination element within the selected logical group.
Select a termination type from the drop-down list. This is added as an input field in the termination configuration.
Termination elements are organized into a tree structure.

The editor supports definition of logical groups (represented by termination type Nested termination), which join multiple termination elements using logical operators (And/Or). The scope of the operator is limited by the logical group in which it is defined.

Click Remove to remove the termination element from the termination tree.

Note

Removing the root element of a logical group removes its child elements.

Chapter 15. Author planning assets with the Red Hat Business Optimizer domain editor

Red Hat Business Optimizer leverages the data modeller to create a domain model for constraint satisfaction problems.

In addition to its basic functionality (creating data objects and their properties), you can also use the Data Objects editor perspective in Decision Central to enhance the data model with Red Hat Business Optimizer-specific data object roles. The Planning Entity and Planning Solution roles are available in the Red Hat Business Optimizer dock, accessed by clicking the on the right side of the Data Objects perspective.

These options are available in the Red Hat Business Optimizer domain editor.

The content of the domain editor varies depending on the current selection:

Selecting a data object displays settings defined on the data object level (Planning Solution, Planning Entity).
Selecting properties of the data object displays settings defined on the property level of the data object.

The overview of the Red Hat Business Optimizer domain editor capabilities is shown in the following division:

Data object level

Property level

Chapter 16. Configure a planning entity difficulty comparator

Specified on Planning Entity level, a difficulty comparator provides a way to determine which planning entities are more difficult to plan. This helps optimization algorithms to work in an efficient manner. Refer to OptaPlanner documentation for more details.

Prerequisite

You have selected Planning Entity on a data object in the Data Object editor and the difficulty comparator definition tool is available in the Red Hat Business Optimizer Domain editor in the Data Object perspective.

Procedure

Click Add condition to add new sorting criteria for given planning entity.
Once the condition is added, click Add field to select fields that will be used for difficulty comparison.
There are two types of fields:
- Basic - value types (for example, number, String)
- Data object - complex types having nested attributes
  Data object types allow nesting deep into object hierarchy until a basic type is encountered. When this occurs, the Add field button is no longer displayed.
  Sorting criteria are ordered. The ones defined first are prioritized when Red Hat Business Optimizer engine resolves planning entity difficulty.
To remove a field from the sorting criteria, click the x icon within the label. If the field is of type Data object, removing it will remove all its children as well.
- Click Arrow up, Arrow down to change the priority of the criterion by moving it up/down.
- Select Sort order icon to define whether the planning entity criteria is sorted in ascending or descending order.

Chapter 17. Define score constraints using the guided rules designer

To solve an optimization problem, you need to define score constraints that evaluate your solution. Red Hat Business Optimizer integrates with the guided rules designer and provides score modifiers, which are used by the engine during the solving process.

Score modifiers can be accessed in the action selector ( 5686 ) of the THEN (right-hand side) section of a rule, provided the planning solution is defined within the project.

Use the following procedure to create a new score constraint using the guided rules designer.

Prerequisite

You have defined a Planning Solution by creating a class in the domain editor and selecting Planning Solution. See Chapter 15, Author planning assets with the Red Hat Business Optimizer domain editor for more information.

Procedure

Open the project Assets screen by clicking Menu → Projects, and clicking on your project to open it.
Click Create New Asset in the upper-right corner.
Select Guided Rule from the drop-down menu.
In the Create new Guided Rule window, enter a name for the rule and click Ok.
If you want to extend a score constraint you have already created, click the drop-down box next to EXTEND and select the rule from the list.
Click the plus icon ( ) on the right side of the WHEN section to add a condition.
Once the action is selected, Business Optimizer score input appears on the THEN (right-hand side) section of the rule.
The following Red Hat Business Optimizer actions are available in the guided rules designer:
- Modify a single score level - use the action to modify only one score component (e.g. hard score)
- Modify multiple score levels - use the action to modify multiple score components at the same time (e.g. hard and soft score)
Insert the value of a constraint into the text input.
Click Validate to verify the correctness of the inserted value.

For more information about using the guided rule designer, see Designing a decision service using guided rules.

Appendix A. Versioning information

Documentation last updated on: Monday, October 1, 2018.

Legal Notice

The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

Java® is a registered trademark of Oracle and/or its affiliates.

XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.

MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.

Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.

The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.

Language and Page Formatting Options

Red Hat Training

Installing and configuring Red Hat Business Optimizer

Red Hat Customer Content Services

Preface

Part I. Solve planning problems using Business Optimizer

Chapter 1. What is Red Hat Business Optimizer

1.1. A planning problem is NP-complete or NP-hard

Chapter 2. What is a planning problem?

2.1. A planning problem has a huge search space

2.2. A planning problem has constraints

Part II. Download and install Business Optimizer

Chapter 3. Download Red Hat Business Optimizer

Chapter 4. Installing the Red Hat Business Optimizer engine in your application

Part III. Run the examples

Chapter 5. Running the Business Optimizer examples

5.1. Running the Red Hat Business Optimizer examples in an IDE (IntelliJ, Eclipse, or Netbeans)

Part IV. Configure the Decision Server

Chapter 6. Decision Server

Chapter 7. Deploying Decision Server

7.1. Bootstrap Switches

Chapter 8. Managed Decision Server

8.1. Configuring Decision Server Managed by Decision Central

8.2. Unmanaged Decision Server

Chapter 9. Creating Containers

Chapter 10. Managing Containers in Decision Central

10.1. Starting, Stopping, and Deleting Containers in Decision Central

10.2. Upgrading Containers in Decision Central

10.3. Managing Multiple Containers

Part V. Configure the Red Hat Business Optimizer REST API

Chapter 11. Knowledge Store REST API

11.1. Job Calls

11.2. Organizational Unit Calls

11.3. Repository Calls

Part VI. The REST API for Decision Server Execution

Chapter 12. The REST API for Decision Server

12.1. Red Hat Decision Manager commands

Chapter 13. Configure the Red Hat Business Optimizer REST API

13.1. [GET] /containers

13.2. [PUT] /containers/{containerId}/solvers/{solverId}

13.3. [GET] /containers/{containerId}/solvers

13.4. [GET] /containers/{containerId}/solvers/{solverId}

13.5. [POST] /containers/{containerId}/solvers/{solverId}/state/solving

13.6. [POST] /containers/{containerId}/solvers/{solverId}/state/terminating-early

13.7. [GET] /containers/{containerId}/solvers/{solverId}/bestsolution

13.8. [POST] /containers/{containerId}/solvers/{solverId}/problemfactchanges

13.9. [GET] /containers/{containerId}/solvers/{solverId}/problemfactchanges/processed

13.10. [DELETE] /containers/{containerId}/solvers/{solverId}

Part VII. Author planning assets and create solvers

Chapter 14. Create a Solver in Decision Central

14.1. Configure Solver termination

Chapter 15. Author planning assets with the Red Hat Business Optimizer domain editor

Chapter 16. Configure a planning entity difficulty comparator

Chapter 17. Define score constraints using the guided rules designer

Appendix A. Versioning information

Legal Notice

Quick Links

Help

Site Info

Related Sites

Systems Status

About

Red Hat legal and privacy links

Red Hat legal and privacy links