JBoss.orgCommunity Documentation

OptaPlanner Workbench and Execution Server User Guide

The OptaPlanner team

Version 6.4.0.CR2

I. OptaPlanner Engine
II. OptaPlanner Workbench
1. Workbench (General)
1.1. Installation
1.1.1. War installation
1.1.2. Workbench data
1.1.3. System properties
1.1.4. Trouble shooting
1.2. Quick Start
1.2.1. Add repository
1.2.2. Add project
1.2.3. Define Data Model
1.2.4. Define Rule
1.2.5. Build and Deploy
1.3. Administration
1.3.1. Administration overview
1.3.2. Organizational unit
1.3.3. Repositories
1.4. Configuration
1.4.1. User management
1.4.2. Roles
1.4.3. Restricting access to repositories
1.4.4. Command line config tool
1.5. Introduction
1.5.1. Log in and log out
1.5.2. Home screen
1.5.3. Workbench concepts
1.5.4. Initial layout
1.6. Changing the layout
1.6.1. Resizing
1.6.2. Repositioning
1.7. Authoring (General)
1.7.1. Artifact Repository
1.7.2. Asset Editor
1.7.3. Tags Editor
1.7.4. Project Explorer
1.7.5. Project Editor
1.7.6. Validation
1.7.7. Data Modeller
1.7.8. Data Sets
1.8. Embedding Workbench In Your Application
1.9. Asset Management
1.9.1. Asset Management Overview
1.9.2. Managed vs Unmanaged Repositories
1.9.3. Asset Management Processes
1.9.4. Usage Flow
1.9.5. Repository Structure
1.9.6. Managed Repositories Operations
2. Authoring Planning Assets
2.1. Solver Editor
3. Workbench Integration
3.1. REST
3.1.1. Job calls
3.1.2. Repository calls
3.1.3. Organizational unit calls
3.1.4. Maven calls
3.1.5. REST summary
4. Workbench High Availability
4.1.
4.1.1. VFS clustering
4.1.2. jBPM clustering
III. OptaPlanner Execution Server
5. KIE Execution Server
5.1. Overview
5.1.1. Glossary
5.2. Installing the KIE Server
5.2.1. Bootstrap switches
5.2.2. Installation details for different containers
5.3. Kie Server setup
5.3.1. Managed Kie Server
5.3.2. Unmanaged KIE Execution Server
5.4. Creating a Kie Container
5.5. Managing Containers
5.5.1. Starting a Container
5.5.2. Stopping and Deleting a Container
5.5.3. Updating a Container
5.6. Kie Server REST API
5.6.1. [GET] /
5.6.2. [POST] /
5.6.3. [GET] /containers
5.6.4. ⁠[GET] /containers/{id}
5.6.5. [PUT] /containers/{id}
5.6.6. [DELETE] /containers/{id}
5.6.7. [POST] /containers/instances/{id}
5.6.8. [GET] /containers/{id}/release-id
5.6.9. [POST] /containers/{id}/release-id
5.6.10. [GET] /containers/{id}/scanner
5.6.11. [POST] /containers/{id}/scanner
5.6.12. Native REST client for Execution Server
5.7. OptaPlanner REST API
5.7.1. [GET] /containers/{containerId}/solvers
5.7.2. [PUT] /containers/{containerId}/solvers/{solverId}
5.7.3. [GET] /containers/{containerId}/solvers/{solverId}
5.7.4. [POST] /containers/{containerId}/solvers/{solverId}
5.7.5. [GET] /containers/{containerId}/solvers/{solverId}/bestsolution
5.7.6. [DELETE] /containers/{containerId}/solvers/{solverId}
5.8. Controller REST API
5.8.1. [GET] /management/servers
5.8.2. [GET] /management/server/{id}
5.8.3. [PUT] /management/server/{id}
5.8.4. [DELETE] /management/server/{id}
5.8.5. [GET] /management/server/{id}/containers
5.8.6. [GET] /management/server/{id}/containers/{containerId}
5.8.7. [PUT] /management/server/{id}/containers/{containerId}
5.8.8. [DELETE] /management/server/{id}/containers/{containerId}
5.8.9. [POST] /management/server/{id}/containers/{containerId}/status/started
5.8.10. [POST] /management/server/{id}/containers/{containerId}/status/stopped
5.9. Kie Server Java Client API
5.9.1. Maven Configuration
5.9.2. Client Configuration
5.9.3. Server Response
5.9.4. Server Capabilities
5.9.5. Kie Containers
5.9.6. Managing Containers
5.9.7. Available Clients for the Decision Server
5.9.8. Sending commands to the server
5.9.9. Listing available business processes

Part I. OptaPlanner Engine

See the OptaPlanner docs.

The OptaPlanner

Table of Contents

1. Workbench (General)
1.1. Installation
1.1.1. War installation
1.1.2. Workbench data
1.1.3. System properties
1.1.4. Trouble shooting
1.2. Quick Start
1.2.1. Add repository
1.2.2. Add project
1.2.3. Define Data Model
1.2.4. Define Rule
1.2.5. Build and Deploy
1.3. Administration
1.3.1. Administration overview
1.3.2. Organizational unit
1.3.3. Repositories
1.4. Configuration
1.4.1. User management
1.4.2. Roles
1.4.3. Restricting access to repositories
1.4.4. Command line config tool
1.5. Introduction
1.5.1. Log in and log out
1.5.2. Home screen
1.5.3. Workbench concepts
1.5.4. Initial layout
1.6. Changing the layout
1.6.1. Resizing
1.6.2. Repositioning
1.7. Authoring (General)
1.7.1. Artifact Repository
1.7.2. Asset Editor
1.7.3. Tags Editor
1.7.4. Project Explorer
1.7.5. Project Editor
1.7.6. Validation
1.7.7. Data Modeller
1.7.8. Data Sets
1.8. Embedding Workbench In Your Application
1.9. Asset Management
1.9.1. Asset Management Overview
1.9.2. Managed vs Unmanaged Repositories
1.9.3. Asset Management Processes
1.9.4. Usage Flow
1.9.5. Repository Structure
1.9.6. Managed Repositories Operations
2. Authoring Planning Assets
2.1. Solver Editor
3. Workbench Integration
3.1. REST
3.1.1. Job calls
3.1.2. Repository calls
3.1.3. Organizational unit calls
3.1.4. Maven calls
3.1.5. REST summary
4. Workbench High Availability
4.1.
4.1.1. VFS clustering
4.1.2. jBPM clustering
1.1. Installation
1.1.1. War installation
1.1.2. Workbench data
1.1.3. System properties
1.1.4. Trouble shooting
1.2. Quick Start
1.2.1. Add repository
1.2.2. Add project
1.2.3. Define Data Model
1.2.4. Define Rule
1.2.5. Build and Deploy
1.3. Administration
1.3.1. Administration overview
1.3.2. Organizational unit
1.3.3. Repositories
1.4. Configuration
1.4.1. User management
1.4.2. Roles
1.4.3. Restricting access to repositories
1.4.4. Command line config tool
1.5. Introduction
1.5.1. Log in and log out
1.5.2. Home screen
1.5.3. Workbench concepts
1.5.4. Initial layout
1.6. Changing the layout
1.6.1. Resizing
1.6.2. Repositioning
1.7. Authoring (General)
1.7.1. Artifact Repository
1.7.2. Asset Editor
1.7.3. Tags Editor
1.7.4. Project Explorer
1.7.5. Project Editor
1.7.6. Validation
1.7.7. Data Modeller
1.7.8. Data Sets
1.8. Embedding Workbench In Your Application
1.9. Asset Management
1.9.1. Asset Management Overview
1.9.2. Managed vs Unmanaged Repositories
1.9.3. Asset Management Processes
1.9.4. Usage Flow
1.9.5. Repository Structure
1.9.6. Managed Repositories Operations

Use the war from the workbench distribution zip that corrsponds to your application server. The differences between these war files are mainly superficial. For example, some JARs might be excluded if the application server already supplies them.

The workbench stores its data, by default in the directory $WORKING_DIRECTORY/.niogit, for example wildfly-8.0.0.Final/bin/.niogit, but it can be overridden with the system property -Dorg.uberfire.nio.git.dir.

Note

In production, make sure to back up the workbench data directory.

Here's a list of all system properties:

To change one of these system properties in a WildFly or JBoss EAP cluster:

  1. Edit the file $JBOSS_HOME/domain/configuration/host.xml.

  2. Locate the XML elements server that belong to the main-server-group and add a system property, for example:

    <system-properties>
  <property name="org.uberfire.nio.git.dir" value="..." boot-time="false"/>
  ...
</system-properties>

There have been reports that Firewalls in between the server and the browser can interfere with Server Sent Events (SSE) used by the Workbench.

The issue results in the "Loading..." spinner remaining visible and the Workbench failing to materialize.

The workaround is to disable the Workbench's use of Server Sent Events by adding file /WEB-INF/classes/ErraiService.properties to the exploded WAR containing the value errai.bus.enable_sse_support=false. Re-package the WAR and re-deploy.

These steps help you get started with minimum of effort.

They should not be a substitute for reading the documentation in full.

Create a new repository to hold your project by selecting the Administration Perspective.

Figure 1.1. Selecting Administration perspective

Selecting Administration perspective

Select the "New repository" option from the menu.

Figure 1.2. Creating new repository

Creating new repository

Enter the required information.

Figure 1.3. Entering repository information step 1/2

Entering repository information step 1/2

Figure 1.4. Entering repository information step 2/2 (only for managed repositories)

Entering repository information step 2/2 (only for managed repositories)

Select the Authoring Perspective to create a new project.

Figure 1.5. Selecting Authoring perspective

Selecting Authoring perspective

Select "Project" from the "New Item" menu.

Figure 1.6. Creating new project

Creating new project

Enter a project name first.

Figure 1.7. Entering project name

Entering project name

Enter the project details next.

  • Group ID follows Maven conventions.

  • Artifact ID is pre-populated from the project name.

  • Version is set as 1.0 by default.

Figure 1.8. Entering project details

Entering project details

After a project has been created you need to define Types to be used by your rules.

Select "Data Object" from the "New Item" menu.

Note

You can also use types contained in existing JARs.

Please consult the full documentation for details.

Figure 1.9. Creating "Data Object"

Creating "Data Object"

Set the name and select a package for the new type.

Figure 1.10. Creating a new type

Creating a new type

Set field name and type and click on "Create" to create a field for the type.

Figure 1.11. Click "Create" and add the field

Click "Create" and add the field

Click "Save" to update the model.

Figure 1.12. Clicking "Save"

Clicking "Save"

Select "DRL file" (for example) from the "New Item" menu.

Figure 1.13. Selecting "DRL file" from the "New Item" menu

Selecting "DRL file" from the "New Item" menu

Enter a file name for the new rule.

Figure 1.14. Entering file name for rule

Entering file name for rule

Enter a definition for the rule.

The definition process differs from asset type to asset type.

The full documentation has details about the different editors.

Figure 1.15. Defining a rule

Defining a rule

Once the rule has been defined it will need to be saved.

Figure 1.16. Saving the rule

Saving the rule

Once rules have been defined within a project; the project can be built and deployed to the Workbench's Maven Artifact Repository.

To build a project select the "Project Editor" from the "Project" menu.

Figure 1.17. Selecting "Project Editor"

Selecting "Project Editor"

Click "Build and Deploy" to build the project and deploy it to the Workbench's Maven Artifact Repository.

When you select Build & Deploy the workbench will deploy to any repositories defined in the Dependency Management section of the pom in your workbench project. You can edit the pom.xml file associated with your workbench project under the Repository View of the project explorer. Details on dependency management in maven can be found here : http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html

If there are errors during the build process they will be reported in the "Problems Panel".

Figure 1.18. Building and deploying a project

Building and deploying a project

Now the project has been built and deployed; it can be referenced from your own projects as any other Maven Artifact.

The full documentation contains details about integrating projects with your own applications.

A workbench is structured with Organization Units, VFS repositories and projects:

Organization units are useful to model departments and divisions.

An organization unit can hold multiple repositories.

Repositories are the place where assets are stored and each repository is organized by projects and belongs to a single organization unit.

Repositories are in fact a Virtual File System based storage, that by default uses GIT as backend. Such setup allows workbench to work with multiple backends and, in the same time, take full advantage of backend specifics features like in GIT case versioning, branching and even external access.

A new repository can be created from scratch or cloned from an existing repository.

One of the biggest advantage of using GIT as backend is the ability to clone a repository from external and use your preferred tools to edit and build your assets.

Warning

Never clone your repositories directly from .niogit directory. Use always the available protocol(s) displayed in repositories editor.

One additional advantage to use GIT as backend is the possibility to revert your repository to a previous state. You can do it directly from the repository editor by browsing its commit history and clicking the Revert button.

The workbench authenticates its users against the application server's authentication and authorization (JAAS).

On JBoss EAP and WildFly, add a user with the script $JBOSS_HOME/bin/add-user.sh (or .bat):

$ ./add-user.sh
// Type: Application User
// Realm: empty (defaults to ApplicationRealm)
// Role: admin

There is no need to restart the application server.

The Workbench uses the following roles:

Administrates the BPMS system.

Developer can do almost everything admin can do, except clone repositories.

Analyst is a weaker version of developer and does not have access to the asset repository or the ability to deploy projects.

Daily user of the system to take actions on business tasks that are required for the processes to continue forward. Works primarily with the task lists.

Viewer of the system that is interested in statistics around the business processes and their performance, business indicators, and other reporting of the system and people who interact with the system.

It is possible to restrict access to repositories using roles and organizational groups. To let an user access a repository.

The user either has to belong into a role that has access to the repository or to a role that belongs into an orgazinational group that has access to the repository. These restrictions can be managed with the command line config tool.

Provides capabilities to manage the system repository from command line. System repository contains the data about general workbench settings: how editors behave, organizational groups, security and other settings that are not editable by the user. System repository exists in the .niogit folder, next to all the repositories that have been created or cloned into the workbench.

Table 1.1. Available Commands

exitPublishes local changes, cleans up temporary directories and quits the command line tool
discardDiscards local changes without publishing them, cleans up temporary directories and quits the command line tool
helpPrints a list of available commands
list-repoList available repositories
list-org-unitsList available organizational units
list-deploymentList available deployments
create-org-unitCreates new organizational unit
remove-org-unitRemoves existing organizational unit
add-deploymentAdds new deployment unit
remove-deploymentRemoves existing deployment
create-repoCreates new git repository
remove-repoRemoves existing repository ( only from config )
add-repo-org-unitAdds repository to the organizational unit
remove-repo-org-unitRemoves repository from the organizational unit
add-role-repoAdds role(s) to repository
remove-role-repoRemoves role(s) from repository
add-role-org-unitAdds role(s) to organizational unit
remove-role-org-unitRemoves role(s) from organizational unit
add-role-projectAdds role(s) to project
remove-role-projectRemoves role(s) from project
push-changesPushes changes to upstream repository (only in online mode)

The tool can be found from kie-config-cli-${version}-dist.zip. Execute the kie-config-cli.sh script and by default it will start in online mode asking for a Git url to connect to ( the default value is ssh://localhost/system ). To connect to a remote server, replace the host and port with appropriate values, e.g. ssh://kie-wb-host/system.

./kie-config-cli.sh

To operate in offline mode, append the offline parameter to the kie-config-cli.sh command. This will change the behaviour and ask for a folder where the .niogit (system repository) is. If .niogit does not yet exist, the folder value can be left empty and a brand new setup is created. 

./kie-config-cli.sh offline

Create a user with the role admin and log in with those credentials.

After successfully logging in, the account username is displayed at the top right. Click on it to review the roles of the current account.

After logging in, the home screen shows. The actual content of the home screen depends on the workbench variant (Drools, jBPM, ...).

The Workbench is comprised of different logical entities:

The Workbench consists of three main sections to begin; however its layout and content can be changed.

Figure 1.19. The Workbench

The Workbench

The initial Workbench shows the following components:-

  • Project Explorer

    This provides the ability for the user to browse their configuration; of Organizational Units (in the above "example" is the Organizational Unit), Repositories (in the above "uf-playground" is the Repository) and Project (in the above "mortgages" is the Project).

  • Problems

    This provides the user will real-time feedback about errors in the active Project.

  • Empty space

    This empty space will contain an editor for assets selected from the Project Explorer.

    Other screens will also occupy this space by default; such as the Project Editor.

The default layout may not be suitable for a user. Panels can therefore be either resized or repositioned.

This, for example, could be useful when running tests; as the test defintion and rule can be repositioned side-by-side.

The following screenshot shows a Panel being resized.

Move the mouse pointer over the panel splitter (a grey horizontal or vertical line in between panels).

The cursor will changing indicating it is positioned correctly over the splitter. Press and hold the left mouse button and drag the splitter to the required position; then release the left mouse button.

Figure 1.20. Resizing

Resizing

The following screenshot shows a Panel being repositioned.

Move the mouse pointer over the Panel title ("Guided Editor [No bad credit checks]" in this example).

The cursor will change indicating it is positioned correctly over the Panel title. Press and hold the left mouse button. Drag the mouse to the required location. The target position is indicated with a pale blue rectangle. Different positions can be chosen by hovering the mouse pointer over the different blue arrows.

Figure 1.21. Repositioning - dragging

Repositioning - dragging

Figure 1.22. Repositioning - complete

Repositioning - complete

Projects often need external artifacts in their classpath in order to build, for example a domain model JARs. The artifact repository holds those artifacts.

The Artifact Repository is a full blown Maven repository. It follows the semantics of a Maven remote repository: all snapshots are timestamped. But it is often stored on the local hard drive.

By default the artifact repository is stored under $WORKING_DIRECTORY/repositories/kie, but it can be overridden with the system property -Dorg.guvnor.m2repo.dir. There is only 1 Maven repository per installation.

The Artifact Repository screen shows a list of the artifacts in the Maven repository:

To add a new artifact to that Maven repository, either:

  • Use the upload button and select a JAR. If the JAR contains a POM file under META-INF/maven (which every JAR build by Maven has), no further information is needed. Otherwise, a groupId, artifactId and version need be given too.

  • Using Maven, mvn deploy to that Maven repository. Refresh the list to make it show up.

Note

This remote Maven repository is relatively simple. It does not support proxying, mirroring, ... like Nexus or Archiva.

The Asset Editor is the principle component of the workbench User-Interface. It consists of two main views Editor and Overview.

Tags allow assets to be labelled with any number of tags that you define. These tags can be used to filter assets on the Project Explorer enabling "Tag filtering".

To create tags you simply have to write them on the Tags input and press the "Add new Tag/s" button. The Tag Editor allows creating tags one by one or writing more than one separated with a white space.

Figure 1.28. Creating Tags

Creating Tags

Once you created new Tags they will appear over the Editor allowing you to remove them by pressing on them if you want.

Figure 1.29. Existing Tags

Existing Tags

The Project Explorer provides the ability to browse different Organizational Units, Repositories, Projects and their files.

The initial view could be empty when first opened.

Figure 1.30. An empty initial view

An empty initial view

The user may have to select an Organizational Unit, Repository and Project from the drop-down boxes.

Figure 1.31. Selecting a repository

Selecting a repository

The default configuration hides Package details from view.

In order to reveal packages click on the icon as indicated in the following screen-shot.

Figure 1.32. Showing packages

Showing packages

After a suitable combination of Organizational Unit, Repository, Project and Package have been selected the Project Explorer will show the contents. The exact combination of selections depends wholly on the structures defined within the Workbench installation and projects. Each section contains groups of related files. If a file is currently being edited by another user, a lock symbol will be displayed in front of the file name. The symbol is blue in case the lock is owned by the currently authenticated user, otherwise black. Moving the mouse pointer over the lock symbol will display a tooltip providing the name of the user who is currently editing the file (and therefore owning the lock). To learn more about locking see Section 1.7.2, “Asset Editor” for details.

Figure 1.33. Expanded asset group

Expanded asset group

Project Explorer supports multiple views.

Views can be selected by clicking on the icon within the Project Explorer, as shown below.

Both Project and Repository Views can be further refined by selecting either "Show as Folders" or "Show as Links".

Figure 1.34. Switching view

Switching view

Figure 1.35. Project View - Folders

Project View - Folders

Figure 1.36. Project View - Links

Project View - Links

Figure 1.37. Repository View - Folders

Repository View - Folders

Figure 1.38. Repository View - Links

Repository View - Links

Download Download and Download Repository make it possible to download the project or repository as a zip file.

Figure 1.39. Repository and Project Downloads

Repository and Project Downloads

A branch selector will be visible if the repository has more than a single branch.

Figure 1.40. Branch selector

Branch selector

To make easy view the elements on packages that contain a lot of assets, is possible to enabling the Tag filter, whichs allows you to filter the assets by their tags.

To see how to add tags to an asset look at: Section 1.7.3, “Tags Editor”

Figure 1.41. Enabling Filter by Tag

Enabling Filter by Tag

Figure 1.42. Filter by Tag

Filter by Tag

Figure 1.43. Filtering by Tag

Filtering by Tag

Copy, rename and delete actions are available on Links mode, for packages (in of Project View) and for files and directories as well (in Repository View). Download action is available for directories. Download downloads the selected the selected directory as a zip file.

Figure 1.44. Project View - Package actions

Project View - Package actions

Figure 1.45. Repository View - Files and directories actions

Repository View - Files and directories actions

Warning

Workbench roadmap includes a refactoring and an impact analyses tools, but currenctly doesn't have it. Until both tools are provided make sure that your changes (copy/rename/delete) on packages, files or directories doesn't have a major impact on your project.

In cases that your change had an unexcepcted impact, Workbench allows you to restore your repository using the Repository editor.

Important

Files locked by other users as well as directories that contain such files cannot be renamed or deleted until the corresponding locks are released. If that is the case the rename and delete symbols will be deactivated. To learn more about locking see Section 1.7.2, “Asset Editor” for details.

The Project Editor screen can be accessed from Project Explorer. Project Editor shows the settings for the currently active project.

Unlike most of the workbench editors, project editor edits more than one file. Showing everything that is needed for configuring the KIE project in one place.

Figure 1.46. Project Screen and the different views

Project Screen and the different views

Build & Depoy builds the current project and deploys the KJAR into the workbench internal Maven repository.

Project Settings edits the pom.xml file used by Maven.

General settings provide tools for project name and GAV-data (Group, Artifact, Version). GAV values are used as identifiers to differentiate projects and versions of the same project.

Figure 1.47. Project Settings

Project Settings

The project may have any number of either internal or external dependencies. Dependency is a project that has been built and deployed to a Maven repository. Internal dependencies are projects build and deployed in the same workbench as the project. External dependencies are retrieved from repositories outside of the current workbench. Each dependency uses the GAV-values to specify the project name and version that is used by the project.

Figure 1.48. Dependencies

Dependencies

Classes and declared types in white listed packages show up as Data Objects that can be imported in assets. The full list is stored in package-name-white-list file that is stored in each project root.

Package white list has three modes:

Metadata for the pom.xml file.

Knowledge Base Settings edits the kmodule.xml file used by Drools.

Figure 1.49. Knowledge Base Settings

Knowledge Base Settings

Note

For more information about the Knowledge Base properties, check the Drools Expert documentation for kmodule.xml.

Knowledge bases and sessions lists the knowledge bases and the knowledge sessions specified for the project.

Lists all the knowledge bases by name. Only one knowledge base can be set as default.

Knowledge base can include other knowledge bases. The models, rules and any other content in the included knowledge base will be visible and usable by the currently selected knowledge base.

Rules and models are stored in packages. The packages property specifies what packages are included into this knowledge base.

Equals behavior is explained in the Drools Expert part of the documentation.

Event processing mode is explained in the Drools Fusion part of the documentation.

The table lists all the knowledge sessions in the selected knowledge base. There can be only one default of each type. The types are stateless and stateful. Clicking the pen-icon opens a popup that shows more properties for the knowledge session.

Metadata for the kmodule.xml

Settings edits the project.imports file used by the workbench editors.

Figure 1.50. Imports

Imports

Data Objects provided by the Java Runtime environment may need to be registered to be available to rule authoring where such Data Objects are not implicitly available as part of an existing Data Object defined within the Workbench or a Project dependency. For example an Author may want to define a rule that checks for java.util.ArrayList in Working Memory. If a domain Data Object has a field of type java.util.ArrayList there is no need create a registraton.

Metadata for the project.imports file.

When performing any of the following operations a check is now made against all Maven Repositories, resolved for the Project, for whether the Project's GroupId, ArtifactId and Version pre-exist. If a clash is found the operation is prevented; although this can be overridden by Users with the admin role.

Note

The feature can be disabled by setting the System Property org.guvnor.project.gav.check.disabled to true.

Resolved repositories are those discovered in:-

Affected operations:-

Users with the Admin role can override the list of Repositories checked using the "Repositories" settings in the Project Editor.

Figure 1.51. Project Editor - Viewing resolved Repositories

Project Editor - Viewing resolved Repositories

Figure 1.52. Project Editor - The list of resolved Repositories

Project Editor - The list of resolved Repositories

Figure 1.53. Duplicate GAV detected

Duplicate GAV detected

The Workbench provides a common and consistent service for users to understand whether files authored within the environment are valid.

The Problems Panel shows real-time validation results of assets within a Project.

When a Project is selected from the Project Explorer the Problems Panel will refresh with validation results of the chosen Project.

When files are created, saved or deleted the Problems Panel content will update to show either new validation errors, or remove existing if a file was deleted.

Figure 1.54. The Problems Panel

Here an invalid DRL file has been created and saved.

The Problems Panel shows the validation errors.

The Problems Panel

It is not always desirable to save a file in order to determine whether it is in a valid state.

All of the file editors provide the ability to validate the content before it is saved.

Clicking on the 'Validate' button shows validation errors, if any.

By default, a data model is always constrained to the context of a project. For the purpose of this tutorial, we will assume that a correctly configured project already exists and the authoring perspective is open.

To start the creation of a data model inside a project, take the following steps:

  1. From the home panel, select the authoring perspective and use the project explorer to browse to the given project.

    Figure 1.55. Go to authoring perspective and select a project

    Go to authoring perspective and select a project

  2. Open the Data Modeller tool by clicking on a Data Object file, or using the "New Item -> Data Object" menu option.

    Figure 1.56. Click on a Data Object

    Click on a Data Object

This will start up the Data Modeller tool, which has the following general aspect:

Figure 1.57. Data modeller overview

Data modeller overview

The "Editor" tab is divided into the following sections:

The "Source" tab shows an editor that allows the visualization and modification of the generated java code.

The "Overview" tab shows the standard metadata and version information as the other workbench editors.

A data model consists of data objects which are a logical representation of some real-world data. Such data objects have a fixed set of modeller (or application-owned) properties, such as its internal identifier, a label, description, package etc. Besides those, a data object also has a variable set of user-defined fields, which are an abstraction of a real-world property of the type of data that this logical data object represents.

Creating a data object can be achieved using the workbench "New Item - Data Object" menu option.

Figure 1.70. New Data Object menu option

New Data Object menu option

Both resource name and location are mandatory parameters. When the "Ok" button is pressed a new Java file will be created and a new editor instance will be opened for the file edition. The optional "Persistable" attribute will add by default configurations on the data object in order to make it a JPA entity. Use this option if your jBPM project needs to store data object's information in a data base.

Once the data object has been created, it now has to be completed by adding user-defined properties to its definition. This can be achieved by pressing the "add field" button. The "New Field" dialog will be opened and the new field can be created by pressing the "Create" button. The "Create and continue" button will also add the new field to the Data Object, but won't close the dialog. In this way multiple fields can be created avoiding the popup opening multiple times. The following fields can (or must) be filled out:

When finished introducing the initial information for a new field, clicking the 'Create' button will add the newly created field to the end of the data object's fields table below:

Figure 1.74. New field has been created

New field has been created

The new field will also automatically be selected in the data object's field list, and its properties will be shown in the Field general properties editor. Additionally the field properties will be loaded in the different tool windows, in this way the field will be ready for edition in whatever selected tool window.

At any time, any field (without restrictions) can be deleted from a data object definition by clicking on the corresponding 'x' icon in the data object's fields table.

As stated before, both Data Objects as well as Fields require some of their initial properties to be set upon creation. Additionally there are three domains of properties that can be configured for a given Data Object. A domain is basically a set of properties related to a given business area. Current available domains are, "Drools & jJBPM", "Persistence" and the "Advanced" domain. To work on a given domain the user should select the corresponding "Tool window" (see below) on the right side toolbar. Every tool window usually provides two editors, the "Data Object" level editor and the "Field" level editor, that will be shown depending on the last selected item, the Data Object or the Field.

The Drools & jBPM domain editors manages the set of Data Object or Field properties related to drools applications.

The Drools & jBPM object editor manages the object level drools properties

Figure 1.75. The data object's properties

The data object's properties

  • TypeSafe: this property allows to enable/disable the type safe behaviour for current type. By default all type declarations are compiled with type safety enabled. (See Drools for more information on this matter).

  • ClassReactive: this property allows to mark this type to be treated as "Class Reactive" by the Drools engine. (See Drools for more information on this matter).

  • PropertyReactive: this property allows to mark this type to be treated as "Property Reactive" by the Drools engine. (See Drools for more information on this matter).

  • Role: this property allows to configure how the Drools engine should handle instances of this type: either as regular facts or as events. By default all types are handled as a regular fact, so for the time being the only value that can be set is "Event" to declare that this type should be handled as an event. (See Drools Fusion for more information on this matter).

  • Timestamp: this property allows to configure the "timestamp" for an event, by selecting one of his attributes. If set the engine will use the timestamp from the given attribute instead of reading it from the Session Clock. If not, the engine will automatically assign a timestamp to the event. (See Drools Fusion for more information on this matter).

  • Duration: this property allows to configure the "duration" for an event, by selecting one of his attributes. If set the engine will use the duration from the given attribute instead of using the default event duration = 0. (See Drools Fusion for more information on this matter).

  • Expires: this property allows to configure the "time offset" for an event expiration. If set, this value must be a temporal interval in the form: [#d][#h][#m][#s][#[ms]] Where [ ] means an optional parameter and # means a numeric value. e.g.: 1d2h, means one day and two hours. (See Drools Fusion for more information on this matter).

  • Remotable: If checked this property makes the Data Object available to be used with jBPM remote services as REST, JMS and WS. (See jBPM for more information on this matter).

The Drools & jBPM object editor manages the field level drools properties

Figure 1.76. The data object's field properties

The data object's field properties

  • Equals: checking this property for a Data Object field implies that it will be taken into account, at the code generation level, for the creation of both the equals() and hashCode() methods in the generated Java class. We will explain this in more detail in the following section.

  • Position: this field requires a zero or positive integer. When set, this field will be interpreted by the Drools engine as a positional argument (see the section below and also the Drools documentation for more information on this subject).

The Persistence domain editors manages the set of Data Object or Field properties related to persistence.

Persistence domain object editor manages the object level persistence properties

Figure 1.77. The data object's properties

The data object's properties

  • Persistable: this property allows to configure current Data Object as persistable.

  • Table name: this property allows to set a user defined database table name for current Data Object.

The persistence domain field editor manages the field level persistence properties and is divided in three sections.

Figure 1.78. Persistence domain field editor sections

Persistence domain field editor sections

A persistable Data Object should have one and only one field defined as the Data Object identifier. The identifier is typically a unique number that distinguishes a given Data Object instance from all other instances of the same class.

The column properties section enables the customization of some properties of the database column that will store the field value.

When the field's type is a Data Object type, or a list of a Data Object type a relationship type should be set in order to let the persistence provider to manage the relation. Fortunately this relation type is automatically set when such kind of fields are added to an already marked as persistable Data Object. The relationship type is set by the following popup.

Figure 1.79. Relationship configuration popup

Relationship configuration popup

  • Relationship type: sets the type of relation from one of the following options:

    One to one: typically used for 1:1 relations where "A is related to one instance of B", and B exists only when A exists. e.g. PurchaseOrder -> PurchaseOrderHeader (a PurchaseOrderHeader exists only if the PurchaseOrder exists)

    One to many: typically used for 1:N relations where "A is related to N instances of B", and the related instances of B exists only when A exists. e.g. PurchaseOrder -> PurchaseOrderLine (a PurchaseOrderLine exists only if the PurchaseOrder exists)

    Many to one: typically used for 1:1 relations where "A is related to one instance of B", and B can exist even without A. e.g. PurchaseOrder -> Client (a Client can exist in the database even without an associated PurchaseOrder)

    Many to many: typically used for N:N relations where "A can be related to N instances of B, and B can be related to M instances of A at the same time", and both B an A instances can exits in the database independently of the related instances. e.g. Course -> Student. (Course can be related to N Students, and a given Student can attend to M courses)

    When a field of type "Data Object" is added to a given persistable Data Object, the "Many to One" relationship type is generated by default.

    And when a field of type "list of Data Object" is added to a given persistable Data Object , the "One to Many" relationship is generated by default.

  • Cascade mode: Defines the set of cascadable operations that are propagated to the associated entity. The value cascade=ALL is equivalent to cascade={PERSIST, MERGE, REMOVE, REFRESH}. e.g. when A -> B, and cascade "PERSIST or ALL" is set, if A is saved, then B will be also saved.

    The by default cascade mode created by the data modeller is "ALL" and it's strongly recommended to use this mode when Data Objects are being used by jBPM processes and forms.

  • Fetch mode: Defines how related data will be fetched from database at reading time.

    EAGER: related data will be read at the same time. e.g. If A -> B, when A is read from database B will be read at the same time.

    LAZY: reading of related data will be delayed usually to the moment they are required. e.g. If PurchaseOrder -> PurchaseOrderLine the lines reading will be postponed until a method "getLines()" is invoked on a PurchaseOrder instance.

    The default fetch mode created by the data modeller is "EAGER" and it's strongly recommended to use this mode when Data Objects are being used by jBPM processes and forms.

  • Optional: establishes if the right side member of a relationship can be null.

  • Mapped by: used for reverse relations.

The advanced domain enables the configuration of whatever parameter set by the other domains as well as the adding of arbitrary parameters. As it will be shown in the code generation section every "Data Object / Field" parameter is represented by a java annotation. The advanced mode enables the configuration of this annotations.

The advanced domain editor has the same shape for both Data Object and Field.

Figure 1.80. Advanced domain editor.

Advanced domain editor.

The following operations are available

The data model in itself is merely a visual tool that allows the user to define high-level data structures, for them to interact with the Drools Engine on the one hand, and the jBPM platform on the other. In order for this to become possible, these high-level visual structures have to be transformed into low-level artifacts that can effectively be consumed by these platforms. These artifacts are Java POJOs (Plain Old Java Objects), and they are generated every time the data model is saved, by pressing the "Save" button in the top Data Modeller Menu. Additionally when the user round trip between the "Editor" and "Source" tab, the code is auto generated to maintain the consistency with the Editor view and vice versa.

Figure 1.84. Save the data model from the top menu

Save the data model from the top menu

The resulting code is generated according to the following transformation rules:

  • The data object's identifier property will become the Java class's name. It therefore needs to be a valid Java identifier.

  • The data object's package property becomes the Java class's package declaration.

  • The data object's superclass property (if present) becomes the Java class's extension declaration.

  • The data object's label and description properties will translate into the Java annotations "@org.kie.api.definition.type.Label" and "@org.kie.api.definition.type.Description", respectively. These annotations are merely a way of preserving the associated information, and as yet are not processed any further.

  • The data object's role property (if present) will be translated into the "@org.kie.api.definition.type.Role" Java annotation, that IS interpreted by the application platform, in the sense that it marks this Java class as a Drools Event Fact-Type.

  • The data object's type safe property (if present) will be translated into the "@org.kie.api.definition.type.TypeSafe Java annotation. (see Drools)

  • The data object's class reactive property (if present) will be translated into the "@org.kie.api.definition.type.ClassReactive Java annotation. (see Drools)

  • The data object's property reactive property (if present) will be translated into the "@org.kie.api.definition.type.PropertyReactive Java annotation. (see Drools)

  • The data object's timestamp property (if present) will be translated into the "@org.kie.api.definition.type.Timestamp Java annotation. (see Drools)

  • The data object's duration property (if present) will be translated into the "@org.kie.api.definition.type.Duration Java annotation. (see Drools)

  • The data object's expires property (if present) will be translated into the "@org.kie.api.definition.type.Expires Java annotation. (see Drools)

  • The data object's remotable property (if present) will be translated into the "@org.kie.api.remote.Remotable Java annotation. (see jBPM)

A standard Java default (or no parameter) constructor is generated, as well as a full parameter constructor, i.e. a constructor that accepts as parameters a value for each of the data object's user-defined fields.

The data object's user-defined fields are translated into Java class fields, each one of them with its own getter and setter method, according to the following transformation rules:

  • The data object field's identifier will become the Java field identifier. It therefore needs to be a valid Java identifier.

  • The data object field's type is directly translated into the Java class's field type. In case the field was declared to be multiple (i.e. 'List'), then the generated field is of the "java.util.List" type.

  • The equals property: when it is set for a specific field, then this class property will be annotated with the "@org.kie.api.definition.type.Key" annotation, which is interpreted by the Drools Engine, and it will 'participate' in the generated equals() method, which overwrites the equals() method of the Object class. The latter implies that if the field is a 'primitive' type, the equals method will simply compares its value with the value of the corresponding field in another instance of the class. If the field is a sub-entity or a collection type, then the equals method will make a method-call to the equals method of the corresponding data object's Java class, or of the java.util.List standard Java class, respectively.

    If the equals property is checked for ANY of the data object's user defined fields, then this also implies that in addition to the default generated constructors another constructor is generated, accepting as parameters all of the fields that were marked with Equals. Furthermore, generation of the equals() method also implies that also the Object class's hashCode() method is overwritten, in such a manner that it will call the hashCode() methods of the corresponding Java class types (be it 'primitive' or user-defined types) for all the fields that were marked with Equals in the Data Model.

  • The position property: this field property is automatically set for all user-defined fields, starting from 0, and incrementing by 1 for each subsequent new field. However the user can freely changes the position among the fields. At code generation time this property is translated into the "@org.kie.api.definition.type.Position" annotation, which can be interpreted by the Drools Engine. Also, the established property order determines the order of the constructor parameters in the generated Java class.

As an example, the generated Java class code for the Purchase Order data object, corresponding to its definition as shown in the following figure purchase_example.jpg is visualized in the figure at the bottom of this chapter. Note that the two of the data object's fields, namely 'header' and 'lines' were marked with Equals, and have been assigned with the positions 2 and 1, respectively).

Figure 1.85. Purchase Order configuration

Purchase Order configuration



    package org.jbpm.examples.purchases;

    /**
    * This class was automatically generated by the data modeler tool.
    */
    @org.kie.api.definition.type.Label("Purchase Order")
    @org.kie.api.definition.type.TypeSafe(true)
    @org.kie.api.definition.type.Role(org.kie.api.definition.type.Role.Type.EVENT)
    @org.kie.api.definition.type.Expires("2d")
    @org.kie.api.remote.Remotable
    public class PurchaseOrder implements java.io.Serializable
    {

    static final long serialVersionUID = 1L;

    @org.kie.api.definition.type.Label("Total")
    @org.kie.api.definition.type.Position(3)
    private java.lang.Double total;

    @org.kie.api.definition.type.Label("Description")
    @org.kie.api.definition.type.Position(0)
    private java.lang.String description;

    @org.kie.api.definition.type.Label("Lines")
    @org.kie.api.definition.type.Position(2)
    @org.kie.api.definition.type.Key
    private java.util.List<org.jbpm.examples.purchases.PurchaseOrderLine> lines;

    @org.kie.api.definition.type.Label("Header")
    @org.kie.api.definition.type.Position(1)
    @org.kie.api.definition.type.Key
    private org.jbpm.examples.purchases.PurchaseOrderHeader header;

    @org.kie.api.definition.type.Position(4)
    private java.lang.Boolean requiresCFOApproval;

    public PurchaseOrder()
    {
    }

    public java.lang.Double getTotal()
    {
    return this.total;
    }

    public void setTotal(java.lang.Double total)
    {
    this.total = total;
    }

    public java.lang.String getDescription()
    {
    return this.description;
    }

    public void setDescription(java.lang.String description)
    {
    this.description = description;
    }

    public java.util.List<org.jbpm.examples.purchases.PurchaseOrderLine> getLines()
    {
    return this.lines;
    }

    public void setLines(java.util.List<org.jbpm.examples.purchases.PurchaseOrderLine> lines)
    {
    this.lines = lines;
    }

    public org.jbpm.examples.purchases.PurchaseOrderHeader getHeader()
    {
    return this.header;
    }

    public void setHeader(org.jbpm.examples.purchases.PurchaseOrderHeader header)
    {
    this.header = header;
    }

    public java.lang.Boolean getRequiresCFOApproval()
    {
    return this.requiresCFOApproval;
    }

    public void setRequiresCFOApproval(java.lang.Boolean requiresCFOApproval)
    {
    this.requiresCFOApproval = requiresCFOApproval;
    }

    public PurchaseOrder(java.lang.Double total, java.lang.String description,
    java.util.List<org.jbpm.examples.purchases.PurchaseOrderLine> lines,
    org.jbpm.examples.purchases.PurchaseOrderHeader header,
    java.lang.Boolean requiresCFOApproval)
    {
    this.total = total;
    this.description = description;
    this.lines = lines;
    this.header = header;
    this.requiresCFOApproval = requiresCFOApproval;
    }

    public PurchaseOrder(java.lang.String description,
    org.jbpm.examples.purchases.PurchaseOrderHeader header,
    java.util.List<org.jbpm.examples.purchases.PurchaseOrderLine> lines,
    java.lang.Double total, java.lang.Boolean requiresCFOApproval)
    {
    this.description = description;
    this.header = header;
    this.lines = lines;
    this.total = total;
    this.requiresCFOApproval = requiresCFOApproval;
    }

    public PurchaseOrder(
    java.util.List<org.jbpm.examples.purchases.PurchaseOrderLine> lines,
    org.jbpm.examples.purchases.PurchaseOrderHeader header)
    {
    this.lines = lines;
    this.header = header;
    }

    @Override
    public boolean equals(Object o)
    {
    if (this == o)
    return true;
    if (o == null || getClass() != o.getClass())
    return false;
    org.jbpm.examples.purchases.PurchaseOrder that = (org.jbpm.examples.purchases.PurchaseOrder) o;
    if (lines != null ? !lines.equals(that.lines) : that.lines != null)
    return false;
    if (header != null ? !header.equals(that.header) : that.header != null)
    return false;
    return true;
    }

    @Override
    public int hashCode()
    {
    int result = 17;
    result = 31 * result + (lines != null ? lines.hashCode() : 0);
    result = 31 * result + (header != null ? header.hashCode() : 0);
    return result;
    }

    }

Using an external model means the ability to use a set for already defined POJOs in current project context. In order to make those POJOs available a dependency to the given JAR should be added. Once the dependency has been added the external POJOs can be referenced from current project data model.

There are two ways to add a dependency to an external JAR file:

To add a dependency to a JAR file in local M2 repository follow this steps.

Figure 1.86. Project editor.

Project editor.

Figure 1.87. New dependency line.

New dependency line.

Figure 1.88. Dependency line edition.

Dependency line edition.

When project is saved the POJOs defined in the external file will be available.

Figure 1.89. Save project.

Save project.

To add a dependency to a JAR file in current "Guvnor M2 repository" follow this steps.

Figure 1.90. Guvnor M2 Repository editor.

Guvnor M2 Repository editor.

Figure 1.91. File browser.

File browser.

Figure 1.92. File upload success.

File upload success.

Once the file has been loaded it will be displayed in the repository files list.

Figure 1.93. Files list.

Files list.

If the uploaded file is not a valid Maven JAR (don't have a pom.xml file) the system will prompt the user in order to provide a GAV for the file to be installed.

Figure 1.94. Not valid POM.

Not valid POM.

Figure 1.95. Enter GAV manually.

Enter GAV manually.

Open the project editor (see bellow) and click on the "Add from repository" button to open the JAR selector to see all the installed JAR files in current "Guvnor M2 repository". When the desired file is selected the project should be saved in order to make the new dependency available.

Figure 1.96. Select JAR from "Maven Artifact Repository".

Select JAR from "Maven Artifact Repository".

When a dependency to an external JAR has been set, the external POJOs can be used in the context of current project data model in the following ways:

The following screenshot shows how external objects are prefixed with the string " -ext- " in order to be quickly identified.

Figure 1.97. Identifying external objects.

Identifying external objects.

Current version implements roundtrip and code preservation between Data modeller and Java source code. No matter where the Java code was generated (e.g. Eclipse, Data modeller), the data modeller will only create/delete/update the necessary code elements to maintain the model updated, i.e, fields, getter/setters, constructors, equals method and hashCode method. Also whatever Type or Field annotation not managed by the Data Modeler will be preserved when the Java sources are updated by the Data modeller.

Aside from code preservation, like in the other workbench editors, concurrent modification scenarios are still possible. Common scenarios are when two different users are updating the model for the same project, e.g. using the data modeller or executing a 'git push command' that modifies project sources.

From an application context's perspective, we can basically identify two different main scenarios:

In this scenario the application user has basically just been navigating through the data model, without making any changes to it. Meanwhile, another user modifies the data model externally.

In this case, no immediate warning is issued to the application user. However, as soon as the user tries to make any kind of change, such as add or remove data objects or properties, or change any of the existing ones, the following pop-up will be shown:

Figure 1.98. External changes warning

External changes warning

The user can choose to either:

The application user has made changes to the data model. Meanwhile, another user simultaneously modifies the data model from outside the application context.

In this alternative scenario, immediately after the external user commits his changes to the asset repository (or e.g. saves the model with the data modeller in a different session), a warning is issued to the application user:

Figure 1.100. External changes warning

External changes warning

As with the previous scenario, the user can choose to either:

A data set is basically a set of columns populated with some rows, a matrix of data composed of timestamps, texts and numbers. A data set can be stored in different systems: a database, an excel file, in memory or in a lot of other different systems. On the other hand, a data set definition tells the workbench modules how such data can be accessed, read and parsed.

Notice, it's very important to make crystal clear the difference between a data set and its definition since the workbench does not take care of storing any data, it just provides an standard way to define access to those data sets regardless where the data is stored.

Let's take for instance the data stored in a remote database. A valid data set could be, for example, an entire database table or the result of an SQL query. In both cases, the database will return a bunch of columns and rows. Now, imagine we want to get access to such data to feed some charts in a new workbench perspective. First thing is to create and register a data set definition in order to indicate the following:

This chapter introduces the available workbench tools for registering and handling data set definitions and how this definitions can be consumed in other workbench modules like, for instance, the Perspective Editor.

Note

For simplicity sake we will be using the term data set to refer to the actual data set definitions as Data set and Data set definition can be considered synonyms under the data set authoring context.

Everything related to the authoring of data sets can be found under the Data Set Authoring perspective which is accessible from the following top level menu entry: Extensions>Data Sets, as shown in the following screenshot.

Figure 1.102. Data Set Authoring Perspective

Data Set Authoring Perspective

The center panel, shows a welcome screen, whilst the left panel contains the Data Set Explorer listing all the data sets available

Note

This perspective is only intended to Administrator users, since defining data sets can be considered a low level task.

The Data Set Explorer list the data sets present in the system. Every time the user clicks on the data set it shows a brief summary alongside the following information:

Figure 1.103. Data Set Explorer

Data Set Explorer

  • (1) A button for creating a new Data set

  • (2) The list of currently available Data sets

  • (3) An icon that represents the Data set's provider type (Bean, SQL, CSV, etc)

  • (4) Details of current cache and refresh policy status

  • (5) Details of current size on backend (unit as rows) and current size on client side (unit in bytes)

  • (6) The button for editing the Data set. Once clicked the Data set editor screen is opened on the center panel

The next sections explains how to create, edit and fine tune data set definitions.

Clicking on the New Data Set button opens a new screen from which the user is able to create a new data set definition in three steps:

Allows the user's specify the type of data provider of the data set being created.

This screen lists all the current available data provider types and helper popovers with descriptions. Each data provider is represented with a descriptive image:

Figure 1.104. Provider type selection

Provider type selection

Four types are currently supported:

  • Bean (Java class) - To generate a data set directly from Java

  • SQL - For getting data from any ANSI-SQL compliant database

  • CSV - To upload the contents of a remote or local CSV file

  • Elastic Search - To query and get documents stored on Elastic Search nodes as data sets

Once a type is selected, click on Next button to continue with the next workflow step.

The screenshot below shows a CSV data set configuration form. Once all the required settings are filled click on Test button. The system will try to fetch an small amount of data before moving to the next workflow step.

Figure 1.105. CSV Configuration

CSV Configuration

The provider type selected in the previous step will determine which configuration settings the system asks for.

Figure 1.106. Configuration screen per data set type

Configuration screen per data set type

Note

The UUID attribute is a read only field as it's generated by the system. It's only intended for usage in API calls or specific operations.

After clicking on the Test button (see previous step), the system executes a data set lookup test call in order to check if the remote system is up and the data is available. If everything goes ok the user will see the following screen:

Figure 1.107. Data set preview

Data set preview

This screen shows a live data preview along with the columns the user wants to be part of the resulting data set. The user can also navigate through the data and apply some changes to the data set structure. Once finished, we can click on the Save button in order to register the new data set definition.

We can also change the configuration settings at any time just by going back to the configuration tab. We can repeat the Configuration>Test>Preview cycle as may times as needed until we consider it's ready to be saved.

Columns

In the Columns tab area the user can select what columns are part of the resulting data set definition.

Figure 1.108. Data set columns

Data set columns

  • (1) To add or remove columns. Select only those columns you want to be part of the resulting data set

  • (2) Use the drop down image selector to change the column type

A data set may only contain columns of any of the following 4 types:

  • Label - For text values supporting group operations (similar to the SQL "group by" operator) which means you can perform data lookup calls and get one row per distinct value.

  • Text - For text values NOT supporting group operations. Typically for modeling large text columns such as abstracts, descriptions and the like.

  • Number - For numeric values. It does support aggregation functions on data lookup calls: sum, min, max, average, count, disctinct.

  • Date - For date or timestamp values. It does support time based group operations by different time intervals: minute, hour, day, month, year, ...

No matter which remote system you want to retrieve data from, the resulting data set will always return a set of columns of one of the four types above. There exists, by default, a mapping between the remote system column types and the data set types. The user is able to modify the type for some columns, depending on the data provider and the column type of the remote system. The system supports the following changes to column types:

  • Label <> Text - Useful when we want to enable/disable the categorization (grouping) for the target column. For instance, imagine a database table called "document" containing a large text column called "abstract". As we do not want the system to treat such column as a "label" we might change its column type to "text". Doing so, we are optimizing the way the system handles the data set and

  • Number <> Label - Useful when we want to treat numeric columns as labels. This can be used for instance to indicate that a given numeric column is not a numeric value that can be used in aggregation functions. Despite its values are stored as numbers we want to handle the column as a "label". One example of such columns are: an item's code, an appraisal id., ...

Note

BEAN data sets do not support changing column types as it's up to the developer to decide which are the concrete types for each column.

Filter

A data set definition may define a filter. The goal of the filter is to leave out rows the user does not consider necessary. The filter feature works on any data provider type and it lets the user to apply filter operations on any of the data set columns available.

Figure 1.109. Data set filter

Data set filter

While adding or removing filter conditions and operations, the preview table on central area is updated with live data that reflects the current filter status.

There exists two strategies for filtering data sets and it's also important to note that choosing between the two have important implications. Imagine a dashboard with some charts feeding from a expense reports data set where such data set is built on top of an SQL table. Imagine also we only want to retrieve the expense reports from the "London" office. You may define a data set containing the filter "office=London" and then having several charts feeding from such data set. This is the recommended approach. Another option is to define a data set with no initial filter and then let the individual charts to specify their own filter. It's up to the user to decide on the best approach.

Depending on the case it might be better to define the filter at a data set level for reusing across other modules. The decision may also have impact on the performance since a filtered cached data set will have far better performance than a lot of individual non-cached data set lookup requests. (See the next section for more information about caching data sets).

Note

Notice, for SQL data sets, the user can use both the filter feature introduced or, alternatively, just add custom filter criteria to the SQL sentence. Although, the first approach is more appropriated for non technical users since they might not have the required SQL language skills.

To edit an existing data set definition go the data set explorer, expand the desired data set definition and click on the Edit button. This will cause a new editor panel to be opened and placed on the center of the screen, as shown in the next screenshot:

Figure 1.110. Data set definition editor

Data set definition editor

Every time we edit an item its editor is added to the center panel. We can navigate through the list of opened editors just by clicking on the down arrow icon placed at the editor's toolbar in the top right corner.

Figure 1.111. Editor selector

Editor selector

The editor provides all the features described in previous sections. We can change the configuration settings, test our data set definition and modify the resulting data set structure. Additionally, the editor provides some extra buttons in its toolbar:

  • Save - To validate the current changes and store the data set definition.

  • Delete - To remove permanently from storage the data set definition. Any client module referencing the data set may be affected.

  • Validate - To check that all the required parameters exists and are correct, as well as to validate the data set can be retrieved with no issues.

  • Copy - To create a brand new definition as a copy of the current one.

Note

Data set definitions are stored in the underlying GIT repository as JSON files. Any action performed is registered in the repository logs so it is possible to audit the change log later on.

In the Advanced settings tab area the user can specify caching and refresh settings. Those are very important for making the most of the system capabilities thus improving the performance and having better application responsive levels.

Figure 1.112. Advanced settings

Advanced settings

  • (1) To enable or disable the client cache and specify the maximum size (bytes).

  • (2) To enable or disable the backend cache and specify the maximum cache size (number of rows).

  • (3) To enable or disable automatic refresh for the Data set and the refresh period.

  • (4) To enable or disable the refresh on stale data setting.

Let's dig into more details about the meaning of these settings.

The system provides caching mechanisms out-of-the-box for holding data sets and performing data operations using in-memory strategies. The use of these features brings a lot of advantages, like reducing the network traffic, remote system payload, processing times etc. On the other hand, it's up to the user to fine tune properly the caching settings to avoid hitting performance issues.

Two cache levels are supported:

The following diagram shows how caching is involved in any data set operation:

Figure 1.113. Data set caching

Data set caching

Any data look up call produces a resulting data set, so the use of the caching techniques determines where the data lookup calls are executed and where the resulting data set is located.

Client cache

If ON then the data set involved in a look up operation is pushed into the web browser so that all the components that feed from this data set do not need to perform any requests to the backend since data set operations are resolved at a client side:

  • The data set is stored in the web browser's memory

  • The client components feed from the data set stored in the browser

  • Data set operations (grouping, aggregations, filters and sort) are processed within the web browser, by means of a Javascript data set operation engine.

If you know beforehand that your data set will remain small, you can enable the client cache. It will reduce the number of backend requests, including the requests to the storage system. On the other hand, if you consider that your data set will be quite big, disable the client cache so as to not hitting with browser issues such as slow performance or intermittent hangs.

Backend cache

Its goal is to provide a caching mechanism for data sets on backend side.

This feature allows to reduce the number of requests to the remote storage system , by holding the data set in memory and performing group, filter and sort operations using the in-memory engine.

It's useful for data sets that do not change very often and their size can be considered acceptable to be held and processed in memory. It can be also helpful on low latency connectivity issues with the remote storage. On the other hand, if your data set is going to be updated frequently, it's better to disable the backend cache and perform the requests to the remote storage on each look up request, so the storage system is in charge of resolving the data set lookup request.

Note

BEAN and CSV data providers relies by default on the backend cache, as in both cases the data set must be always loaded into memory in order to resolve any data lookup operation using the in-memory engine. This is the reason why the backend settings are not visible in the Advanced settings tab.

The refresh feature allows for the invalidation of any cached data when certain conditions are meet.

Figure 1.114. Refresh settings

Refresh settings

  • (1) To enable or disable the refresh feature.

  • (2) To specify the refresh interval.

  • (3) To enable or disable data set invalidation when the data is outdated.

The data set refresh policy is tightly related to data set caching, detailed in previous section. This invalidation mechanism determines the cache life-cycle.

Depending on the nature of the data there exist three main use cases:

  • Source data changes predictable - Imagine a database being updated every night. In that case, the suggested configuration is to use a "refresh interval = 1 day" and disable "refresh on stale data". That way, the system will always invalidate the cached data set every day. This is the right configuration when we know in advance that the data is going to change.

  • Source data changes unpredictable - On the other hand, if we do not know whether the database is updated every day, the suggested configuration is to use a "refresh interval = 1 day" and enable "refresh on stale data". If so the system, before invalidating any data, will check for modifications. On data modifications, the system will invalidate the current stale data set so that the cache is populated with fresh data on the next data set lookup call.

  • Real time scenarios - In real time scenarios caching makes no sense as data is going to be updated constantly. In this kind of scenarios the data sent to the client has to be constantly updated, so rather than enabling the refresh settings (remember this settings affect the caching, and caching is not enabled) it's up to the clients consuming the data set to decide when to refresh. When the client is a dashboard then it's just a matter of modifying the refresh settings in the Displayer Editor configuration screen and set a proper refresh period, "refresh interval = 1 second" for example.

As we already know, Workbench provides a set of editors to author assets in different formats. According to asset’s format a specialized editor is used.

One additional feature provided by Workbench is the ability to embed it in your own (Web) Applications thru it's standalone mode. So, if you want to edit rules, processes, decision tables, etc... in your own applications without switch to Workbench, you can.

In order to embed Workbench in your application all you'll need is the Workbench application deployed and running in a web/application server and, from within your own web applications, an iframe with proper HTTP query parameters as described in the following table.

Table 1.2. HTTP query parameters for standalone mode

Parameter NameExplanationAllow multiple valuesExample
standaloneWith just the presence of this parameter workbench will switch to standalone mode.no(none)
pathPath to the asset to be edited. Note that asset should already exists.nogit://master@uf-playground/todo.md
perspectiveReference to an existing perspective name.noorg.guvnor.m2repo.client.perspectives.GuvnorM2RepoPerspective
headerDefines the name of the header that should be displayed (useful for context menu headers).yesComplementNavArea

Note

Path and Perspective parameters are mutual exclusive, so can't be used together.

This section of the documentation describes the main features included that contribute to the Asset Management functionality provided in the KIE Workbench and KIE Drools Workbench. All the features described here are entirely optional, but the usage is recommended if you are planning to have multiple projects. All the Asset Management features try to impose good practices on the repository structure that will make the maintainace, versioning and distribution of the projects simple and based on standards. All the Asset Management features are implemented using jBPM Business Processes, which means that the logic can be reused for external applications as well as adapted for domain specific requirements when needed.

Note

You must set the "kiemgmt" role to your user to be able to use the Asset Management Features

Since the creation of the assets management features repositories can be classified into Managed or Unmanaged.

All new assets management features are available for this type of repositories. Additionally a managed repository can be "Single Project" or "Multi Project".

A "Single Project" managed repository will contain just one Project. And a "Multi Project" managed repository can contain multiple Projects. All of them related through the same parent, and they will share the same group and version information.

Assets management features are not available for this type or repositories and they basically behaves the same as the repositories created with previous workbench versions.

There are 4 main processes which represent the stages of the Asset Management feature: Configure Repository, Promote Changes, Build and Release.

The Configure Repository process is in charge of the post initialization of the repository. This process will be automatically triggered if the user selects to create a Managed Repository on the New repository wizzard. If they decide to use the governance feature the process will kick in and as soon as the repository is created. A new development and release branches will be created. Notice that the first time that this process is called, the master branch is picked and both branches (dev and release) will be based on it.

By default the asset management feature is not enabled so make sure to select Managed Repository on the New Repository Wizzard. When we work inside a managed repository, the development branch is selected for the users to work on. If multiple dev branches are created, the user will need to pick one.

When some work is done in the developments branch and the users reach a point where the changes needs to be tested before going into production, they will start a new Promote Changes process so a more technical user can decide and review what needs to be promoted. The users belonging to the "kiemgmt" group will see a new Task in their Group Task List which will contain all the files that had being changed. The user needs to select the assets that will be promoting via the UI. The underlying process will be cherry-picking the commits selected by the user to the release branch. The user can specify that a review is needed by a more technical user.

This process can be repeated multiple times if needed before creating the artifacts for the release.

The Build process can be triggered to build our projects from different branches. This allows us to have a more flexible way to build and deploy our projects to different runtimes.

The release process is triggered at any time when the user decided that it is time to generate a release of the project that he/she is working on. This process will build the project (calling the Build Process) and it will update all the maven artifacts to the next version.

This section describes the common usage flow for the asset management features showing all the screens involved.

The first contact with the Asset Management features starts on the Repository creation.

If the user chooses to create a Managed Respository a new page in the wizzard is enabled:

When a managed repository is created the assets management configuration process is automatically launched in order to create the repository branches, and the corresponding project structure is also created.

Once a repository has been created it can be managed through the Repository Structure Screen.

To open the Repository Structure Screen for a given repository open the Project Authoring Perspective, browse to the given repository and select the "Repository -> Repository Structure" menu option.

Figure 1.115. Repository Structure Menu

Repository Structure Menu

The following picture shows an example of a single project managed repository structure.

Figure 1.116. Single Project Managed Repository

Single Project Managed Repository

The following picture shows an example of a multi project managed repository structure.

Figure 1.117. Multi Project Managed Repository

Multi Project Managed Repository

The following picture shows an example of an unmanaged repository structure.

Figure 1.118. Unmanaged Repository

Unmanaged Repository

The following picture shows the screen areas related to managed repositories operations.

Figure 1.119. Managed Repositories Operations

Managed Repositories Operations

The branch selector lets to switch between the different branches created by the Configure Repository Process.

Figure 1.120. Branch Selector

Branch Selector

From the repository structure screen it's also possible to create, edit or delete projects from current repository.

Figure 1.121. Add Project to current structure

Add Project to current structure

Figure 1.122. Edit/Delete projects from current structure

Edit/Delete projects from current structure

The assets management processes can also be launched from the Project Structure Screen.

Figure 1.123. Launch Assets Management Processes

Launch Assets Management Processes

Filling the parameters bellow a new instance of the Configure Repository can be started. (see Configure Repository Process)

Figure 1.124. Configure Repository Process Parameters

Configure Repository Process Parameters

Filling the parameters bellow a new instance of the Promote Changes Process can be started. (see Promote Changes Process)

Figure 1.125. Promote Changes Process Parameters

Promote Changes Process Parameters

Filling the parameters bellow a new instance of the Release Process can be started. (see Release Process)

Figure 1.126. Release Process Parameters

Release Process Parameters

2.1. Solver Editor

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

Note

To see and use this editor, the user needs to have the role plannermgmt.

Use the Validate button to validate the solver configuration. This will actually build a Solver, so most issues in your project will present itself then, without the need to deploy and run it.

By default, the solver configuration will automatically scan for all planning entities and a planning solution classes. If none are found (or too many), validation will fail.

3.1. REST
3.1.1. Job calls
3.1.2. Repository calls
3.1.3. Organizational unit calls
3.1.4. Maven calls
3.1.5. REST summary

REST API calls to Knowledge Store allow you to manage the Knowledge Store content and manipulate the static data in the repositories of the Knowledge Store. The calls are asynchronous, that is, they continue their execution after the call was performed as a job. The job ID is returned by every calls to allow after the REST API call was performed to request the job status and verify whether the job finished successfully. Parameters of these calls are provided in the form of JSON entities.

When using Java code to interface with the REST API, the classes used in POST operations or otherwise returned by various operations can be found in the (org.kie.workbench.services:)kie-wb-common-services JAR. All of the classes mentioned below can be found in the org.kie.workbench.common.services.shared.rest package in that JAR.

Every Knowledge Store REST call returns its job ID after it was sent. This is necessary as the calls are asynchronous and you need to be able to reference the job to check its status as it goes through its lifecycle. During its lifecycle, a job can have the following statuses:

The following job calls are provided:

[GET] /jobs/{jobID}

Returns the job status

Returns a JobResult instance

Example 3.1. An example (formatted) response body to the get job call on a repository clone request

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

[DELETE] /jobs/{jobID}

Removes the job: If the job is not yet being processed, this will remove the job from the job queue. However, this will not cancel or stop an ongoing job

Returns a JobResult instance

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

The following repositories calls are provided:

[GET] /repositories

Gets information about the repositories in the Knowledge Store

Returns a Collection<Map<String, String>> or Collection<RepositoryRequest> instance, depending on the JSON serialization library being used. The keys used in the Map<String, String> instance match the fields in the RepositoryRequest class

Example 3.2. An example (formatted) response body to the get repositories call

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

[GET] /repositories/{repositoryName}

Gets information about a repository

Returns a Map<String, String> or RepositoryRequest instance, depending on the JSON serialization library being used. The keys used in the Map<String, String> instance match the fields in the RepositoryRequest class

Example 3.3. An example (formatted) response body to the get repository call

{
  "name":"wb-assets",
  "description":"generic assets",
  "userName":null,
  "password":null,
  "requestType":null,
  "gitURL":"git://bpms-assets"
}

[POST] /repositories

Creates a new empty repository or a new repository cloned from an existing (git) repository

Consumes a RepositoryRequest instance

Returns a CreateOrCloneRepositoryRequest instance

Example 3.4. An example (formatted) response body to the create repositories call

{
  "name":"new-project-repo",
  "description":"repo for my new project",
  "userName":null,"password":null,
  "requestType":"new",
  "gitURL":null
}

[DELETE] /repositories/{repositoryName}

Removes the repository from the Knowledge Store

Returns a RemoveRepositoryRequest instance

[POST] /repositories/{repositoryName}/projects/

Creates a project in the repository

Consumes an Entity instance

Returns a CreateProjectRequest instance

Example 3.5. An example (formatted) request body that defines the project to be created

{
  "name":"myProject",
  "description": "my project"
}

[DELETE] /repositories/{repositoryName}/projects/

Deletes the project in the repository

Returns a DeleteProjectRequest instance

[GET] /repositories/{repositoryName}/projects/

Gets information about the projects

Returns a Collection<Map<String, String>> or Collection<ProjectResponse> instance, depending on the JSON serialization library being used. The keys used in the Map<String, String> instance match the fields in the ProjectResponse class

Example 3.6. An example (formatted) response body to the get projects call

[
  {
    "name":"wb-assets",
    "description":"generic assets",
    "groupId":"org.test",
    "version":"1.0"
 },
 {
   "name":"loanProject",
   "description":"Loan processes and rules",
    "groupId":"com.bank",
    "version":"3.7"
 }
]

Organizational unit calls are calls to the Knowledge Store that allow you to manage its organizational units, so as to organize the connected Git repositories.

The following organizationalUnits calls are provided:

[POST] /organizationalunits

Creates an organizational unit in the Knowledge Store

Consumes an OrganizationalUnit instance

Returns a CreateOrganizationalUnitRequest instance

Example 3.7. An example (formatted) request body defining a new organizational unit to be created

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

[GET] /organizationalunits/{orgUnitName}

Creates an organizational unit

Consumes an OrganizationalUnit instance

Returns a CreateOrganizationalUnitRequest instance

Example 3.8. An example (formatted) request body defining a new organizational unit to be created

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

[POST] /organizationalunits/{orgUnitName}

Creates an organizational unit in the Knowledge Store

Consumes an UpdateOrganizationalUnit instance

Returns a UpdateOrganizationalUnitRequest instance

Example 3.9. An example (formatted) request body defining a new organizational unit to be created

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

[DELETE] /organizationalunits/{organizationalUnitName}

Deletes a organizational unit

Returns a RemoveOrganizationalUnitRequest instance

[POST] /organizationalunits/{organizationalUnitName}/repositories/{repositoryName}

Adds the repository to the organizational unit

Returns a AddRepositoryToOrganizationalUnitRequest instance

[DELETE] /organizationalunits/{organizationalUnitName}/repositories/{repositoryName}

Removes the repository from the organizational unit

Returns a RemoveRepositoryFromOrganizationalUnitRequest instance

Maven calls are calls to a Project in the Knowledge Store that allow you compile and deploy the Project resources.

The following maven calls are provided:

[POST] /repositories/{repositoryName}/projects/{projectName}/maven/compile

Compiles the project (equivalent to mvn compile)

Consumes a BuildConfig instance. While this must be supplied, it's not needed for the operation and may be left blank.

Returns a CompileProjectRequest instance

[POST] /repositories/{repositoryName}/projects/{projectName}/maven/install

Installs the project (equivalent to mvn install)

Consumes a BuildConfig instance. While this must be supplied, it's not needed for the operation and may be left blank.

Returns a InstallProjectRequest instance

[POST] /repositories/{repositoryName}/projects/{projectName}/maven/test

Compiles the project runs a test as part of compilation

Consumes a BuildConfig instance

Returns a TestProjectRequest instance

[POST] /repositories/{repositoryName}/projects/{projectName}/maven/deploy

Deploys the project (equivalent to mvn deploy)

Consumes a BuildConfig instance. While this must be supplied, it's not needed for the operation and may be left blank.

Returns a DeployProjectRequest instance

The URL templates in the table below are relative the following URL:

Table 3.1. Knowledge Store REST calls

URL TemplateTypeDescription
/jobs/{jobID}GETreturn the job status
/jobs/{jobID}DELETEremove the job
/organizationalunitsGETreturn a list of organizational units
/organizationalunitsPOST

create an organizational unit in the Knowledge Store described by the JSON OrganizationalUnit entity

/organizationalunits/{organizationalUnitName}/repositories/{repositoryName}POSTadd a repository to an organizational unit
/organizationalunits/{organizationalUnitName}/repositories/{repositoryName}DELETEremove a repository from an organizational unit
/repositories/POST

add the repository to the organizational unit described by the JSON RepositoryReqest entity

/repositoriesGETreturn the repositories in the Knowledge Store
/repositories/{repositoryName}DELETEremove the repository from the Knowledge Store
/repositories/POSTcreate or clone the repository defined by the JSON RepositoryRequest entity
/repositories/{repositoryName}/projects/POSTcreate the project defined by the JSON entity in the repository
/repositories/{repositoryName}/projects/{projectName}/maven/compile/POSTcompile the project
/repositories/{repositoryName}/projects/{projectName}/maven/installPOSTinstall the project
/repositories/{repositoryName}/projects/{projectName}/maven/test/POST

compile the project and run tests as part of compilation

/repositories/{repositoryName}/projects/{projectName}/maven/deploy/POSTdeploy the project

4.1.
4.1.1. VFS clustering
4.1.2. jBPM clustering

The VFS repositories (usually git repositories) stores all the assets (such as rules, decision tables, process definitions, forms, etc). If that VFS resides on each local server, then it must be kept in sync between all servers of a cluster.

Use Apache Zookeeper and Apache Helix to accomplish this. Zookeeper glues all the parts together. Helix is the cluster management component that registers all cluster details (nodes, resources and the cluster itself). Uberfire (on top of which Workbench is build) uses those 2 components to provide VFS clustering.

To create a VFS cluster:

  1. Download Apache Zookeeper and Apache Helix.

  2. Install both:

    1. Unzip Zookeeper into a directory ($ZOOKEEPER_HOME).

    2. In $ZOOKEEPER_HOME, copy zoo_sample.conf to zoo.conf

    3. Edit zoo.conf. Adjust the settings if needed. Usually only these 2 properties are relevant:

      # the directory where the snapshot is stored.
dataDir=/tmp/zookeeper
# the port at which the clients will connect
clientPort=2181

    4. Unzip Helix into a directory ($HELIX_HOME).

  3. Configure the cluster in Zookeeper:

    1. Go to its bin directory:

      $ cd $ZOOKEEPER_HOME/bin

    2. Start the Zookeeper server:

      $ sudo ./zkServer.sh start

      If the server fails to start, verify that the dataDir (as specified in zoo.conf) is accessible.

    3. To review Zookeeper's activities, open zookeeper.out:

      $ cat $ZOOKEEPER_HOME/bin/zookeeper.out

  4. Configure the cluster in Helix:

    1. Go to its bin directory:

      $ cd $HELIX_HOME/bin

    2. Create the cluster:

      $ ./helix-admin.sh --zkSvr localhost:2181 --addCluster kie-cluster

      The zkSvr value must match the used Zookeeper server. The cluster name (kie-cluster) can be changed as needed.

    3. Add nodes to the cluster:

      # Node 1
$ ./helix-admin.sh --zkSvr localhost:2181 --addNode kie-cluster nodeOne:12345
# Node 2
$ ./helix-admin.sh --zkSvr localhost:2181 --addNode kie-cluster nodeTwo:12346
...

      Usually the number of nodes a in cluster equal the number of application servers in the cluster. The node names (nodeOne:12345 , ...) can be changed as needed.

      Note

      nodeOne:12345 is the unique identifier of the node, which will be referenced later on when configuring application servers. It is not a host and port number, but instead it is used to uniquely identify the logical node.

    4. Add resources to the cluster:

      $ ./helix-admin.sh --zkSvr localhost:2181 --addResource kie-cluster vfs-repo 1 LeaderStandby AUTO_REBALANCE

      The resource name (vfs-repo) can be changed as needed.

    5. Rebalance the cluster to initialize it:

      $ ./helix-admin.sh --zkSvr localhost:2181 --rebalance kie-cluster vfs-repo 2

    6. Start the Helix controller to manage the cluster:

      $  ./run-helix-controller.sh --zkSvr localhost:2181 --cluster kie-cluster 2>&1 > /tmp/controller.log &

  5. Configure the security domain correctly on the application server. For example on WildFly and JBoss EAP:

    1. Edit the file $JBOSS_HOME/domain/configuration/domain.xml.

      For simplicity sake, presume we use the default domain configuration which uses the profile full that defines two server nodes as part of main-server-group.

    2. Locate the profile full and add a new security domain by copying the other security domain already defined there by default:

      <security-domain name="kie-ide" cache-type="default">
    <authentication>
         <login-module code="Remoting" flag="optional">
             <module-option name="password-stacking" value="useFirstPass"/>
         </login-module>
         <login-module code="RealmDirect" flag="required">
             <module-option name="password-stacking" value="useFirstPass"/>
         </login-module>
    </authentication>
</security-domain>

      Important

      The security-domain name is a magic value.

  6. Configure the system properties for the cluster on the application server. For example on WildFly and JBoss EAP:

    1. Edit the file $JBOSS_HOME/domain/configuration/host.xml.

    2. Locate the XML elements server that belong to the main-server-group and add the necessary system property.

      For example for nodeOne:

      <system-properties>
  <property name="jboss.node.name" value="nodeOne" boot-time="false"/>
  <property name="org.uberfire.nio.git.dir" value="/tmp/kie/nodeone" boot-time="false"/>
  <property name="org.uberfire.metadata.index.dir" value="/tmp/kie/nodeone" boot-time="false"/>
  <property name="org.uberfire.cluster.id" value="kie-cluster" boot-time="false"/>
  <property name="org.uberfire.cluster.zk" value="localhost:2181" boot-time="false"/>
  <property name="org.uberfire.cluster.local.id" value="nodeOne_12345" boot-time="false"/>
  <property name="org.uberfire.cluster.vfs.lock" value="vfs-repo" boot-time="false"/>
  <!-- If you're running both nodes on the same machine: -->
  <property name="org.uberfire.nio.git.daemon.port" value="9418" boot-time="false"/>
</system-properties>

      And for nodeTwo:

      <system-properties>
  <property name="jboss.node.name" value="nodeTwo" boot-time="false"/>
  <property name="org.uberfire.nio.git.dir" value="/tmp/kie/nodetwo" boot-time="false"/>
  <property name="org.uberfire.metadata.index.dir" value="/tmp/kie/nodetwo" boot-time="false"/>
  <property name="org.uberfire.cluster.id" value="kie-cluster" boot-time="false"/>
  <property name="org.uberfire.cluster.zk" value="localhost:2181" boot-time="false"/>
  <property name="org.uberfire.cluster.local.id" value="nodeTwo_12346" boot-time="false"/>
  <property name="org.uberfire.cluster.vfs.lock" value="vfs-repo" boot-time="false"/>
  <!-- If you're running both nodes on the same machine: -->
  <property name="org.uberfire.nio.git.daemon.port" value="9419" boot-time="false"/>
</system-properties>

      Make sure the cluster, node and resource names match those configured in Helix.

In addition to the information above, jBPM clustering requires additional configuration. See this blog post to configure the database etc correctly.

The KIE Server is a standalone execution server for rules, planning and workflows.

Table of Contents

5. KIE Execution Server
5.1. Overview
5.1.1. Glossary
5.2. Installing the KIE Server
5.2.1. Bootstrap switches
5.2.2. Installation details for different containers
5.3. Kie Server setup
5.3.1. Managed Kie Server
5.3.2. Unmanaged KIE Execution Server
5.4. Creating a Kie Container
5.5. Managing Containers
5.5.1. Starting a Container
5.5.2. Stopping and Deleting a Container
5.5.3. Updating a Container
5.6. Kie Server REST API
5.6.1. [GET] /
5.6.2. [POST] /
5.6.3. [GET] /containers
5.6.4. ⁠[GET] /containers/{id}
5.6.5. [PUT] /containers/{id}
5.6.6. [DELETE] /containers/{id}
5.6.7. [POST] /containers/instances/{id}
5.6.8. [GET] /containers/{id}/release-id
5.6.9. [POST] /containers/{id}/release-id
5.6.10. [GET] /containers/{id}/scanner
5.6.11. [POST] /containers/{id}/scanner
5.6.12. Native REST client for Execution Server
5.7. OptaPlanner REST API
5.7.1. [GET] /containers/{containerId}/solvers
5.7.2. [PUT] /containers/{containerId}/solvers/{solverId}
5.7.3. [GET] /containers/{containerId}/solvers/{solverId}
5.7.4. [POST] /containers/{containerId}/solvers/{solverId}
5.7.5. [GET] /containers/{containerId}/solvers/{solverId}/bestsolution
5.7.6. [DELETE] /containers/{containerId}/solvers/{solverId}
5.8. Controller REST API
5.8.1. [GET] /management/servers
5.8.2. [GET] /management/server/{id}
5.8.3. [PUT] /management/server/{id}
5.8.4. [DELETE] /management/server/{id}
5.8.5. [GET] /management/server/{id}/containers
5.8.6. [GET] /management/server/{id}/containers/{containerId}
5.8.7. [PUT] /management/server/{id}/containers/{containerId}
5.8.8. [DELETE] /management/server/{id}/containers/{containerId}
5.8.9. [POST] /management/server/{id}/containers/{containerId}/status/started
5.8.10. [POST] /management/server/{id}/containers/{containerId}/status/stopped
5.9. Kie Server Java Client API
5.9.1. Maven Configuration
5.9.2. Client Configuration
5.9.3. Server Response
5.9.4. Server Capabilities
5.9.5. Kie Containers
5.9.6. Managing Containers
5.9.7. Available Clients for the Decision Server
5.9.8. Sending commands to the server
5.9.9. Listing available business processes
5.1. Overview
5.1.1. Glossary
5.2. Installing the KIE Server
5.2.1. Bootstrap switches
5.2.2. Installation details for different containers
5.3. Kie Server setup
5.3.1. Managed Kie Server
5.3.2. Unmanaged KIE Execution Server
5.4. Creating a Kie Container
5.5. Managing Containers
5.5.1. Starting a Container
5.5.2. Stopping and Deleting a Container
5.5.3. Updating a Container
5.6. Kie Server REST API
5.6.1. [GET] /
5.6.2. [POST] /
5.6.3. [GET] /containers
5.6.4. ⁠[GET] /containers/{id}
5.6.5. [PUT] /containers/{id}
5.6.6. [DELETE] /containers/{id}
5.6.7. [POST] /containers/instances/{id}
5.6.8. [GET] /containers/{id}/release-id
5.6.9. [POST] /containers/{id}/release-id
5.6.10. [GET] /containers/{id}/scanner
5.6.11. [POST] /containers/{id}/scanner
5.6.12. Native REST client for Execution Server
5.7. OptaPlanner REST API
5.7.1. [GET] /containers/{containerId}/solvers
5.7.2. [PUT] /containers/{containerId}/solvers/{solverId}
5.7.3. [GET] /containers/{containerId}/solvers/{solverId}
5.7.4. [POST] /containers/{containerId}/solvers/{solverId}
5.7.5. [GET] /containers/{containerId}/solvers/{solverId}/bestsolution
5.7.6. [DELETE] /containers/{containerId}/solvers/{solverId}
5.8. Controller REST API
5.8.1. [GET] /management/servers
5.8.2. [GET] /management/server/{id}
5.8.3. [PUT] /management/server/{id}
5.8.4. [DELETE] /management/server/{id}
5.8.5. [GET] /management/server/{id}/containers
5.8.6. [GET] /management/server/{id}/containers/{containerId}
5.8.7. [PUT] /management/server/{id}/containers/{containerId}
5.8.8. [DELETE] /management/server/{id}/containers/{containerId}
5.8.9. [POST] /management/server/{id}/containers/{containerId}/status/started
5.8.10. [POST] /management/server/{id}/containers/{containerId}/status/stopped
5.9. Kie Server Java Client API
5.9.1. Maven Configuration
5.9.2. Client Configuration
5.9.3. Server Response
5.9.4. Server Capabilities
5.9.5. Kie Containers
5.9.6. Managing Containers
5.9.7. Available Clients for the Decision Server
5.9.8. Sending commands to the server
5.9.9. Listing available business processes

The Kie Server is a modular, standalone server component that can be used to instantiate and execute rules and processes. It exposes this functionality via REST, JMS and Java interfaces to client application. It also provides seamless integration with the Kie Workbench.

At its core, the Kie Server is a configurable web application packaged as a WAR file. Distributions are availables for pure web containers (like Tomcat) and for JEE 6 and JEE 7 containers.

Most capabilities on the Kie Server are configurable, and based on the concepts of extensions. Each extension can be enabled/disabled independently, allowing the user to configure the server to its need.

The current version of the Kie Server ships with two default extensions:

Both extensions enabled by default, but can be disabled by setting the corresponding property (see configuration chapter for details).

This server was designed to have a low footprint, with minimal memory consumption, and therefore, to be easily deployable on a cloud environment. Each instance of this server can open and instantiate multiple Kie Containers which allows you to execute multiple services in parallel.

The KIE Server is distributed as a web application archive (WAR) file. The WAR file comes in three different packagings:

To install the KIE Execution Server and verify it is running, complete the following steps:

  1. Deploy the WAR file into your web container.

  2. Create a user with the role of kie-server on the container.

  3. Test that you can access the execution engine by navigating to the endpoint in a browser window: http://SERVER:PORT/CONTEXT/services/rest/server/.

  4. When prompted for username/password, type in the username and password that you created in step 2.

  5. Once authenticated, you will see an XML response in the form of engine status, similar to this:

    Example 5.1. Sample handshaking server response

    <response type="SUCCESS" msg="KIE Server info">
  <kie-server-info>  
    <version>6.4.0.CR2</version>
  </kie-server-info>
</response>

The Kie Server accepts a number of bootstrap switches (system properties) to configure the behaviour of the server. The following is a table of all the supported switches.

Table 5.1. Kie Server bootstrap switches

PropertyValueDescriptionRequired
org.drools.server.ext.disabledboolean (default is "false")If true, disables the BRM support (i.e. rules support).No
org.jbpm.server.ext.disabledboolean (default is "false")If true, disables the BPM support (i.e. processes support)No
org.kie.server.idstringAn arbitrary ID to be assigned to this 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.No. If not provided, an ID is automatically generated.
org.kie.server.userstring (default is "kieserver")User name used to connect with the kieserver from the controller, required when running in managed modeNo
org.kie.server.pwdstring (default is "kieserver1!")Password used to connect with the kieserver from the controller, required when running in managed modeNo
org.kie.server.controllercomma separated list of urlsList of urls to controller REST endpoint. E.g.: http://localhost:8080/kie-wb/restYes when using a controller
org.kie.server.controller.userstring (default is "kieserver")Username used to connect to the controller REST apiYes when using a controller
org.kie.server.controller.pwdstring (default is "kieserver1!")Password used to connect to the controller REST apiYes when using a controller
org.kie.server.locationURL location of kie server instanceThe URL used by the controller to call back on this server. E.g.: http://localhost:8230/kie-server/services/rest/serverYes when using a controller
org.kie.server.domainstringJAAS LoginContext domain that shall be used to authenticate users when using JMSNo
org.kie.server.bypass.auth.userboolean (default is "false")Allows to bypass the authenticated user for task related operations e.g. queriesNo
org.kie.server.repovalid file system path (default is ".")Location on local file system where kie server state files will be storedNo
org.kie.server.persistence.dsstringDatasource JNDI nameYes when BPM support enabled
org.kie.server.persistence.tmstringTransaction manager platform for Hibernate properties setYes when BPM support enabled
org.kie.server.persistence.dialectstringHibernate dialect to be usedYes when BPM support enabled
org.jbpm.ht.callbackstringOne of supported callbacks for Task Service (default jaas)No
org.jbpm.ht.custom.callbackstringCustom implementation of UserGroupCallback in case org.jbpm.ht.callback was set to ‘custom’No
kie.maven.settings.customvalid file system path Location of custom settings.xml for maven configurationNo
org.kie.executor.intervalinteger (default is 3)Number of time units between polls by executorNo
org.kie.executor.pool.sizeinteger (default is 1)Number of threads in the pool for async workNo
org.kie.executor.retry.countinteger (default is 3)Number of retries to handle errorsNo
org.kie.executor.timeunitTimeUnit (default is "SECONDS")TimeUnit representing intervalNo
org.kie.executor.disabledboolean (default is "false")Disables executor completelyNo
kie.server.jms.queues.responsestring (default is "queue/KIE.SERVER.RESPONSE")JNDI name of response queue for JMSNo
org.kie.server.controller.connectlong (default is 10000)Waiting time in milliseconds between repeated attempts to connect kie server to controller when kie server starts upNo
org.drools.server.filter.classesboolean (default is "false")If true, accept only classes which are annotated with @org.kie.api.remote.Remotable or @javax.xml.bind.annotation.XmlRootElement as extra JAXB classesNo
    


Important

If you are running both KIE Server and KIE Workbench you must configure KIE Server to use a different Data Source to KIE Workbench using the org.kie.server.persistence.ds property. KIE Workbench uses a jBPM Executor Service that can conflict with KIE Server if they share the same Data Source.

  1. Download and unzip the Tomcat distribution. Let's call the root of the distribution TOMCAT_HOME. This directory is named after the Tomcat version, so for example apache-tomcat-7.0.55.

  2. Download kie-server-6.4.0.CR2-webc.war and place it into TOMCAT_HOME/webapps.

  3. Configure user(s) and role(s). Make sure that file TOMCAT_HOME/conf/tomcat-users.xml contains the following username and role definition. You can of course choose different username and password, just make sure that the user has role kie-server:

    Example 5.2. Username and role definition for Tomcat

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


  4. Start the server by running TOMCAT_HOME/bin/startup.[sh|bat]. You can check out the Tomcat logs in TOMCAT_HOME/logs to see if the application deployed successfully. Please read the table above for the bootstrap switches that can be used to properly configure the instance. For instance:

    ./startup.sh -Dorg.kie.server.id=first-kie-server 
             -Dorg.kie.server.location=http://localhost:8080/kie-server/services/rest/server

  5. Verify the server is running. Go to http://SERVER:PORT/CONTEXT/services/rest/server/ and type the specified username and password. You should see simple XML message with basic information about the server.

Important

You can not leverage the JMS interface when running on Tomcat, or any other Web container. The Web container version of the WAR contains only the REST interface.

  1. Download and unzip the WildFly distribution. Let's call the root of the distribution WILDFLY_HOME. This directory is named after the WildFly version, so for example wildfly-8.2.0.Final.

  2. Download kie-server-6.4.0.CR2-ee7.war and place it into WILDFLY_HOME/standalone/deployments.

  3. Configure user(s) and role(s). Execute the following command WILDFLY_HOME/bin/add-user.[sh|bat] -a -u 'kieserver' -p 'kieserver1!' -ro 'kie-server'. You can of course choose different username and password, just make sure that the user has role kie-server.

  4. Start the server by running WILDFLY_HOME/bin/standalone.[sh|bat] -c standalone-full.xml <bootstrap_switches>. You can check out the standard output or WildFly logs in WILDFLY_HOME/standalone/logs to see if the application deployed successfully. Please read the table above for the bootstrap switches that can be used to properly configure the instance. For instance:

    ./standalone.sh  --server-config=standalone-full.xml 
                 -Djboss.socket.binding.port-offset=150
                 -Dorg.kie.server.id=first-kie-server 
                 -Dorg.kie.server.location=http://localhost:8230/kie-server/services/rest/server

  5. Verify the server is running. Go to http://SERVER:PORT/CONTEXT/services/rest/server/ and type the specified username and password. You should see simple XML message with basic information about the server.

Important

Server setup and registration changed significantly from versions 6.2 and before. The following applies only to version 6.3 and forward.

A managed instance is one that requires a controller to be available to properly startup the Kie Server instance.

A Controller is a component responsible for keeping and managing a Kie Server Configuration in centralized way. Each controller can manager multiple configurations at once and there can be multiple controllers in the environment. Managed KIE Servers can be configured with a list of controllers but will connect to only one at a time.

Note

It's important to mention that even though there can be multiple controllers they should be kept in sync to make sure that regardless which one of them is contacted by KIE Server instance it will provide same set of configuration.

At startup, if a Kie Server is configured with a list of controllers, it will try succesivelly to connect to each of them until a connection is successfully stablished with one of them. If for any reason a connection can't be stablished, the server will not start, even if there is local storage available with configuration. This happens by design in order to ensure consistency. For instance, if the Kie Server was down and the configuration has changed, this restriction guarantees that it will run with up to date configuration or not at all.

Note

In order to run the Kie Server in standalone mode, without connecting to any controllers, please see "Unmanaged Kie Server".

The configuration sets, among other things:

The Controller, besides providing configuration management, is also responsible for overall management of Kie Servers. It provides a REST api that is divided into two parts:

The controller deals only with the Kie Server configuration or definition to put it differently. It does not handle any runtime components of KIE Execution Server instances. They are always considered remote to controller. The controller is responsible for persisting the configuration to preserve restarts of the controller itself. It should manage the synchronization as well in case multiple controllers are configured to keep all definitions up to date on all instances of the controller.

By default controller is shipped with Kie Workbench and provides a fully featured management interface (both REST api and UI). It uses underlying git repository as persistent store and thus when GIT repositories are clustered (using Apache Zookeeper and Apache Helix) it will cover the controllers synchronization as well.

The diagram above illustrates the single controller (workbench) setup with multiple Kie Server instances managed by it.

The diagram bellow illustrates the clustered setup where there are multiple instances of controller synchronized over Zookeeper.

In the above diagram we can see that the Kie Server instances are capable of connecting to any controllers, but they will connect to only one. Each instance will attempt to connect to controller as long as it can reach one. Once connection is established with one of the controllers it will skip the others.

There are two approaches that users can take when working with managed KIE Server instances:

An unmanaged Kie Server is in turn just a standalone instance, and thus must be configured individually using REST/JMS api from the Kie 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:

Note

if the Kie Server is restarted, it will try to restablish the same state that was persisted before shutdown. That means that Kie Containers that were running, will be started, but the ones that were stopped/disposed before, will not.

In most use cases, the Kie Server should be executed in managed mode as that provides some benefits, like a web user interface (if using the workbench as a controller) and some facilities for clustering.

Once your Execution Server is registered, you can start adding Kie Containers to it.

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

  1. Start by clicking the + icon next to the Execution Server where you want to deploy your Container. This will bring up the New Container screen.

  2. If you know the Group Name, Artifact Id and Version (GAV) of your deployed package, then you can enter those details and click the Ok button to select that instance (and provide a name for the Container);

  3. If you don't know these values, you can search KIE Workbench for all packages that can be deployed. Click the Search button without entering any value in the search field (you can narrow your search by entering any term that you know exists in the package that you want to deploy).

    Important

    INSERT SCREENSHOT HERE

    The figure above shows that there are three deployable packages available to be used as containers on the Execution Server. Select the one that you want by clicking the Select button. This will auto-populate the GAV and you can then click the Ok button to use this deployable as the new Container.

  4. Enter a name for this Container at the top and then press the Ok button.

    Important

    The Container name must be unique inside each execution server and must not contain any spaces.

Note

Just below the GAV row, you will see an uneditable row that shows you the URL for your Container against which you will be able to execute REST commands.

Containers within the Execution Server can be started, stopped and updated from within KIE Workbench.⁠

Once registered, a Container is in the 'Stopped' mode. It can be started by first selecting it and then clicking the Start button. You can also select multiple Containers and start them all at the same time.

Once the Container is in the 'Running' mode, a green arrow appears next to it. If there are any errors starting the Container(s), red icons appear next to Containers and the Execution Server that they are deployed on.

You should check the logs of both the Execution Server and the current Business Central to see what the errors are before redeploying the Containers (and possibly the Execution Server).⁠

Similar to starting a Container, select the Container(s) that you want to stop (or delete) and click the Stop button (which replaces the Start button for that Container once it has entered the 'Running' mode) or the Delete button.⁠

You can update deployed KieContainers without restarting the Execution Server. This is useful in cases where the Business Rules change, creating new versions of packages to be provisioned.

You can have multiple versions of the same package provisioned and deployed, each to a different KieContainer.

To update deployments in a KieContainer dynamically, click on the icon next to the Container. This will open up the Container Info screen. An example of this screen is shown here:

Important

INSERT SCREENSHOT HERE

The Container Info screen is a useful tool because it not only allows you to see the endpoint for this KieContainer, but it also allows you to either manually or automatically refresh the provision if an update is available. The update can be manual or automatic:

Manual Update: To manually update a KieContainer, enter the new Version number in the Version box and click on the Update button. You can of course, update the Group Id or the Artifact Id , if these have changed as well. Once updated, the Execution server updates the container and shows you the resolved GAV attributes at the bottom of the screen in the Resolved Release Id section.

Automatic Update: If you want a deployed Container to always have the latest version of your deployment without manually editing it, you will need to set the Version property to the value of LATEST and start a Scanner. This will ensure that the deployed provision always contains the latest version. The Scanner can be started just once on demand by clicking the Scan Now button or you can start it in the background with scans happening at a specified interval (in seconds).You can also set this value to LATEST when you are first creating this deployment. The Resolved Release Id in this case will show you the actual, latest version number.

The Execution Server supports the following commands via the REST API.

Please note the following before using these commands:

Returns the Execution Server information

Example 5.3. Example Server Response

<response type="SUCCESS" msg="KIE Server info">
  <kie-server-info> 
    <version>6.2.0.redhat-1</version> 
  </kie-server-info> 
</response>

Using POST HTTP method, you can execute various commands on the Execution Server. E.g: create-container, list-containers, dispose-container and call-container.

Following is the full list of commands:

  • CreateContainerCommand

  • GetServerInfoCommand

  • ListContainersCommand

  • CallContainerCommand

  • DisposeContainerCommand

  • GetContainerInfoCommand

  • GetScannerInfoCommand

  • UpdateScannerCommand

  • UpdateReleaseIdCommand

The commands itself can be found in the org.kie.server.api.commands package.

Returns a list of containers that have been created on this Execution Server.

Example 5.4. Example Server Response

<response type="SUCCESS" msg="List of created containers">
  <kie-containers> 
    <kie-container container-id="MyProjectContainer" status="STARTED"> 
      <release-id>
        <artifact-id>Project1</artifact-id> 
        <group-id>com.redhat</group-id>
        <version>1.0</version> 
      </release-id> 
      <resolved-release-id>
        <artifact-id>Project1</artifact-id> 
        <group-id>com.redhat</group-id>
        <version>1.0</version> 
      </resolved-release-id> 
    </kie-container>
  </kie-containers> 
</response>

Returns the status and information about a particular container. For example, executing http://SERVER:PORT/CONTEXT/services/rest/server/containers/MyProjectContainer could return the following example container info.

Example 5.5. Example Server Response

⁠<response type="SUCCESS" msg="Info for container MyProjectContainer">
  <kie-container container-id="MyProjectContainer" status="STARTED"> 
    <release-id>
      <artifact-id>Project1</artifact-id> 
      <group-id>com.redhat</group-id>
      <version>1.0</version> 
    </release-id> 
    <resolved-release-id>
      <artifact-id>Project1</artifact-id> 
      <group-id>com.redhat</group-id>
      <version>1.0</version> 
    </resolved-release-id> 
  </kie-container>
</response>

Allows you to create a new Container in the Execution Server. For example, to create a Container with the id of MyRESTContainer the complete endpoint will be: http://SERVER:PORT/CONTEXT/services/rest/server/containers/MyRESTContainer. An example of request is:⁠

Example 5.6. Example Request to create a container

<kie-container container-id="MyRESTContainer">
  <release-id>
    <artifact-id>Project1</artifact-id> 
    <group-id>com.redhat</group-id>
    <version>1.0</version> 
  </release-id> 
</kie-container>

And the response from the server, if successful, would be be:

Example 5.7. Example Server Response when creating a container

<response type="SUCCESS" msg="Container MyRESTContainer successfully deployed with module com.redhat:Project1:1.0">
  <kie-container container-id="MyProjectContainer" status="STARTED"> 
    <release-id>
      <artifact-id>Project1</artifact-id> 
      <group-id>com.redhat</group-id>
      <version>1.0</version> 
    </release-id> 
    <resolved-release-id>
      <artifact-id>Project1</artifact-id> 
      <group-id>com.redhat</group-id>
      <version>1.0</version> 
    </resolved-release-id> 
  </kie-container>
</response>

⁠Disposes the Container specified by the id. For example, executing http://SERVER:PORT/CONTEXT/services/rest/server/containers/MyProjectContainer using the DELETE HTTP method will return the following server response:⁠

Example 5.8. Example Server Response disposing a container

<response type="SUCCESS" msg="Container MyProjectContainer successfully disposed."/>

Executes operations and commands against the specified Container. You can send commands to this Container in the body of the POST request. For example, to fire all rules for Container with id MyRESTContainer (http://SERVER:PORT/CONTEXT/services/rest/server/containers/instances/MyRESTContainer), you would send the fire-all-rules command to it as shown below (in the body of the POST request):

Example 5.9. Example Server Request to fire all rules

<fire-all-rules/>

Following is the list of supported commands:

  • AgendaGroupSetFocusCommand

  • ClearActivationGroupCommand

  • ClearAgendaCommand

  • ClearAgendaGroupCommand

  • ClearRuleFlowGroupCommand

  • DeleteCommand

  • InsertObjectCommand

  • ModifyCommand

  • GetObjectCommand

  • InsertElementsCommand

  • FireAllRulesCommand

  • QueryCommand

  • SetGlobalCommand

  • GetGlobalCommand

  • GetObjectsCommand

  • BatchExecutionCommand

These commands can be found in the org.drools.core.command.runtime package.

Returns the full release id for the Container specified by the id.

Example 5.10. Example Server Response

⁠<response type="SUCCESS" msg="ReleaseId for container MyProjectContainer">
  <release-id>
    <artifact-id>Project1</artifact-id> 
    <group-id>com.redhat</group-id>
    <version>1.0</version> 
  </release-id> 
</response>

Allows you to update the release id of the container deployment. Send the new complete release id to the Server.

Example 5.11. Example Server Request

<release-id>
  <artifact-id>Project1</artifact-id>
  <group-id>com.redhat</group-id>    
  <version>1.1</version>
</release-id>

The Server will respond with a success or error message, similar to the one below:⁠

Example 5.12. Example Server Response

<response type="SUCCESS" msg="Release id successfully updated.">
  <release-id>
    <artifact-id>Project1</artifact-id> 
    <group-id>com.redhat</group-id>
    <version>1.0</version> 
  </release-id> 
</response>

Returns information about the scanner for this Container's automatic updates.⁠

Example 5.13. Example Server Response

<response type="SUCCESS" msg="Scanner info successfully retrieved">
  <kie-scanner status="DISPOSED"/> 
</response>

Allows you to start or stop a scanner that controls polling for updated Container deployments. To start the scanner, send a request similar to: http://SERVER:PORT/CONTEXT/services/rest/server/containers/{container-id}/scanner with the following POST data.⁠

Example 5.14. Example Server Request to start the scanner

<kie-scanner status="STARTED" poll-interval="20"/>

⁠The poll-interval attribute is in seconds. The response from the server will be similar to:⁠

Example 5.15. Example Server Response

<response type="SUCCESS" msg="Kie scanner successfully created.">
  <kie-scanner status="STARTED"/> 
</response>

To stop the Scanner, replace the status with DISPOSED and remove the poll-interval attribute.

Commands outlined in this section can be sent with any REST client, whether it is curl, RESTEasy or .NET based application. However, when sending requests from Java based application, users can utilize out of the box native client for remote communication with Execution Server. This client is part of the org.kie:kie-server-client project. It doesn't allow creating XML request, therefore it is necessary generate them before, for example, using Drools API.

Example 5.16. Generate XML request

 
import java.util.ArrayList;
import java.util.List;

import org.drools.core.command.impl.GenericCommand;
import org.drools.core.command.runtime.BatchExecutionCommandImpl;
import org.drools.core.command.runtime.rule.FireAllRulesCommand;
import org.drools.core.command.runtime.rule.InsertObjectCommand;
import org.kie.api.command.BatchExecutionCommand;
import org.kie.internal.runtime.helper.BatchExecutionHelper;

public class DecisionClient {

public static void main(String args[]) {
        Bean1 bean1 = new Bean1();
        bean1.setName("Robert");

        InsertObjectCommand insertObjectCommand = new InsertObjectCommand(bean1, "f1");
        FireAllRulesCommand fireAllRulesCommand = new FireAllRulesCommand("myFireCommand");

        List<GenericCommand<?>> commands = new ArrayList<GenericCommand<?>>();
        commands.add(insertObjectCommand);
        commands.add(fireAllRulesCommand);
        BatchExecutionCommand command = new BatchExecutionCommandImpl(commands);

        String xStreamXml = BatchExecutionHelper.newXStreamMarshaller().toXML(command); // actual XML request
	}
}

Once the request is generated it can be sent using kie-server-client as follows:

Example 5.17. Sending XML request with kie-server-client

 
import org.kie.server.api.model.ServiceResponse;
import org.kie.server.client.KieServicesClient;
import org.kie.server.client.KieServicesConfiguration;
import org.kie.server.client.KieServicesFactory;

//user "anton" must have role "kie-server" assigned
KieServicesConfiguration config =  KieServicesFactory.
        newRestConfiguration("http://localhost:8080/kie-server/services/rest/server",
        "anton",
        "password1!");
 KieServicesClient client = KieServicesFactory.newKieServicesClient(config);
// the request "xStreamXml" we generated in previous step
// "ListenerReproducer" is the name of the Container
ServiceResponse<String> response = client.executeCommands("ListenerReproducer", xStreamXml); 
System.out.println(response.getResult());

When the Planner capability is enabled, the Kie Server supports the following additional REST APIs. As usual, all these APIs are also available through JMS and the Java client API. Please also note:

The example requests and responses used below presume that a kie container is build using the optacloud example of OptaPlanner Workbench, by calling a PUT on /services/rest/server/containers/optacloud-kiecontainer-1 with this content:

<kie-container container-id="optacloud-kiecontainer-1">
  <release-id>
    <group-id>opta</group-id>
    <artifact-id>optacloud</artifact-id> 
    <version>1.0.0</version> 
  </release-id> 
</kie-container>

Returns the list of solvers created in the container.

Example 5.18. Example Server Response (XStream)

<org.kie.server.api.model.ServiceResponse>
  <type>SUCCESS</type>
  <msg>Solvers list successfully retrieved from container 'optacloud-kiecontainer-1'</msg>
  <result class="org.kie.server.api.model.instance.SolverInstanceList">
    <solvers>
      <solver-instance>
        <container-id>optacloud-kiecontainer-1</container-id>
        <solver-id>solver1</solver-id>
        <solver-config-file>opta/optacloud/cloudSolverConfig.solver.xml</solver-config-file>
        <status>NOT_SOLVING</status>
      </solver-instance>
      <solver-instance>
        <container-id>optacloud-kiecontainer-1</container-id>
        <solver-id>solver2</solver-id>
        <solver-config-file>opta/optacloud/cloudSolverConfig.solver.xml</solver-config-file>
        <status>NOT_SOLVING</status>
      </solver-instance>
    </solvers>
  </result>
</org.kie.server.api.model.ServiceResponse>

Example 5.19. Example Server Response (JSON)

{
  "type" : "SUCCESS",
  "msg" : "Solvers list successfully retrieved from container 'optacloud-kiecontainer-1'",
  "result" : {
    "solver-instance-list" : {
      "solver" : [ {
        "status" : "NOT_SOLVING",
        "container-id" : "optacloud-kiecontainer-1",
        "solver-id" : "solver1",
        "solver-config-file" : "opta/optacloud/cloudSolverConfig.solver.xml"
      }, {
        "status" : "NOT_SOLVING",
        "container-id" : "optacloud-kiecontainer-1",
        "solver-id" : "solver2",
        "solver-config-file" : "opta/optacloud/cloudSolverConfig.solver.xml"
      } ]
    }
  }
}

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 5.20. Example Server Request (XStream)

<solver-instance>
  <solver-config-file>opta/optacloud/cloudSolverConfig.solver.xml</solver-config-file>
</solver-instance>

Example 5.21. Example Server Response (XStream)

<org.kie.server.api.model.ServiceResponse>
  <type>SUCCESS</type>
  <msg>Solver 'solver1' successfully created in container 'optacloud-kiecontainer-1'</msg>
  <result class="solver-instance">
    <container-id>optacloud-kiecontainer-1</container-id>
    <solver-id>solver1</solver-id>
    <solver-config-file>opta/optacloud/cloudSolverConfig.solver.xml</solver-config-file>
    <status>NOT_SOLVING</status>
  </result>
</org.kie.server.api.model.ServiceResponse>

Example 5.22. Example Server Request (JSON)

{
  "solver-config-file" : "opta/optacloud/cloudSolverConfig.solver.xml"
}

Example 5.23. Example Server Response (JSON)

{
  "type" : "SUCCESS",
  "msg" : "Solver 'solver1' successfully created in container 'optacloud-kiecontainer-1'",
  "result" : {
    "solver-instance" : {
      "container-id" : "optacloud-kiecontainer-1",
      "solver-id" : "solver1",
      "solver-config-file" : "opta/optacloud/cloudSolverConfig.solver.xml",
      "status" : "NOT_SOLVING"
    }
  }
}

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

Example 5.24. Example Server Response (XStream)

<org.kie.server.api.model.ServiceResponse>
  <type>SUCCESS</type>
  <msg>Solver 'solver1' state successfully retrieved from container 'optacloud-kiecontainer-1'</msg>
  <result class="solver-instance">
    <container-id>optacloud-kiecontainer-1</container-id>
    <solver-id>solver1</solver-id>
    <solver-config-file>opta/optacloud/cloudSolverConfig.solver.xml</solver-config-file>
    <status>NOT_SOLVING</status>
  </result>
</org.kie.server.api.model.ServiceResponse>

Example 5.25. Example Server Response (JSON)

{
  "type" : "SUCCESS",
  "msg" : "Solver 'solver1' state successfully retrieved from container 'optacloud-kiecontainer-1'",
  "result" : {
    "solver-instance" : {
      "container-id" : "optacloud-kiecontainer-1",
      "solver-id" : "solver1",
      "solver-config-file" : "opta/optacloud/cloudSolverConfig.solver.xml",
      "status" : "NOT_SOLVING"
    }
  }
}

Updates the state of the {solverId} in container {containerId}, most notably to start solving. The request's body is a marshalled SolverInstance and can either request the solver to solve a planning problem or to stop solving one. The SolverInstance state determines which operation should be executed and can be set one of two possible values:

For example, to solve an optacloud problem with 2 computers and 1 process:

Example 5.26. Example Server Request (XStream)

<solver-instance>
  <status>SOLVING</status>
  <planning-problem class="opta.optacloud.CloudSolution">
    <computerList>
      <opta.optacloud.Computer>
        <cpuPower>10</cpuPower>
        <memory>4</memory>
        <networkBandwidth>100</networkBandwidth>
        <cost>1000</cost>
      </opta.optacloud.Computer>
      <opta.optacloud.Computer>
        <cpuPower>20</cpuPower>
        <memory>8</memory>
        <networkBandwidth>100</networkBandwidth>
        <cost>3000</cost>
      </opta.optacloud.Computer>
    </computerList>
    <processList>
      <opta.optacloud.Process>
        <requiredCpuPower>1</requiredCpuPower>
        <requiredMemory>7</requiredMemory>
        <requiredNetworkBandwidth>1</requiredNetworkBandwidth>
      </opta.optacloud.Process>
    </processList>
  </planning-problem>
</solver-instance>

Notice that the response does not contain the best solution yet, because solving can take seconds, minutes, hours or days and this would time out the HTTP request:

Example 5.27. Example Server Response (XStream)

<org.kie.server.api.model.ServiceResponse>
  <type>SUCCESS</type>
  <msg>Solver 'solver1' from container 'optacloud-kiecontainer-1' successfully updated.</msg>
  <result class="solver-instance">
    <container-id>optacloud-kiecontainer-1</container-id>
    <solver-id>solver1</solver-id>
    <solver-config-file>opta/optacloud/cloudSolverConfig.solver.xml</solver-config-file>
    <status>SOLVING</status>
  </result>
</org.kie.server.api.model.ServiceResponse>

Instead, it's solving asynchronously and you need to call the bestsolution URL to get the best solution.

For example, to terminate solving:

Example 5.28. Example Server Request (XStream)

<solver-instance>
  <status>NOT_SOLVING</status>
</solver-instance>

Example 5.29. Example Server Response (XStream)

<org.kie.server.api.model.ServiceResponse>
  <type>SUCCESS</type>
  <msg>Solver 'solver1' from container 'optacloud-kiecontainer-1' successfully updated.</msg>
  <result class="solver-instance">
    <container-id>optacloud-kiecontainer-1</container-id>
    <solver-id>solver1</solver-id>
    <solver-config-file>opta/optacloud/cloudSolverConfig.solver.xml</solver-config-file>
    <status>TERMINATING_EARLY</status>
    <score class="org.optaplanner.core.api.score.buildin.hardsoft.HardSoftScore">
      <hardScore>0</hardScore>
      <softScore>-3000</softScore>
    </score>
  </result>
</org.kie.server.api.model.ServiceResponse>

This doesn't delete the solver, the best solution can still be retrieved.

Returns the best solution found at the time the request is made. If the solver hasn't 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.⁠

For example, the problem submitted above would return this solution, with the process assigned to the second computer (because the first one doesn't have enough memory).

Example 5.30. Example Server Response (XStream)

<org.kie.server.api.model.ServiceResponse>
  <type>SUCCESS</type>
  <msg>Best computed solution for 'solver1' successfully retrieved from container 'optacloud-kiecontainer-1'</msg>
   <result class="solver-instance">
    <container-id>optacloud-kiecontainer-1</container-id>
    <solver-id>solver1</solver-id>
    <solver-config-file>opta/optacloud/cloudSolverConfig.solver.xml</solver-config-file>
    <status>SOLVING</status>
    <score class="org.optaplanner.core.api.score.buildin.hardsoft.HardSoftScore">
      <hardScore>0</hardScore>
      <softScore>-3000</softScore>
    </score>
    <best-solution class="opta.optacloud.CloudSolution">
      <score class="org.optaplanner.core.api.score.buildin.hardsoft.HardSoftScore" reference="../../score" />
      <computerList>
        <opta.optacloud.Computer>
          <cpuPower>10</cpuPower>
          <memory>4</memory>
          <networkBandwidth>100</networkBandwidth>
          <cost>1000</cost>
        </opta.optacloud.Computer>
        <opta.optacloud.Computer>
          <cpuPower>20</cpuPower>
          <memory>8</memory>
          <networkBandwidth>100</networkBandwidth>
          <cost>3000</cost>
        </opta.optacloud.Computer>
      </computerList>
      <processList>
        <opta.optacloud.Process>
          <requiredCpuPower>1</requiredCpuPower>
          <requiredMemory>7</requiredMemory>
          <requiredNetworkBandwidth>1</requiredNetworkBandwidth>
          <computer reference="../../../computerList/opta.optacloud.Computer[2]" />
        </opta.optacloud.Process>
      </processList>
    </best-solution>
  </result>
</org.kie.server.api.model.ServiceResponse>

⁠Disposes the solver {solverId} in container {containerId}. If it hasn't terminated yet, it terminates it first.

Example 5.31. Example Server Response (XStream)

<org.kie.server.api.model.ServiceResponse>
  <type>SUCCESS</type>
  <msg>Solver 'solver1' successfully disposed from container 'optacloud-kiecontainer-1'</msg>
</org.kie.server.api.model.ServiceResponse>

Example 5.32. Example Server Response (JSON)

{
  "type" : "SUCCESS",
  "msg" : "Solver 'solver1' successfully disposed from container 'optacloud-kiecontainer-1'"
}

When you have Managed Kie Server setup, you need to manage Kie Servers and Containers via a Controller. Generally, it's done by workbench UI but you may also use Controller REST API.

Returns a list of Kie Server templates

Example 5.33. Example Server Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<server-template-list>
    <server-template>
        <server-id>demo</server-id>
        <server-name>demo</server-name>
        <container-specs>
            <container-id>hr</container-id>
            <container-name>hr</container-name>
            <server-template-key>
                <server-id>demo</server-id>
            </server-template-key>
            <release-id>
                <artifact-id>HR</artifact-id>
                <group-id>org.jbpm</group-id>
                <version>1.0</version>
            </release-id>
            <configs>
                <entry>
                    <key>RULE</key>
                    <value xsi:type="ruleConfig" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                        <scanner-status>STOPPED</scanner-status>
                    </value>
                </entry>
                <entry>
                    <key>PROCESS</key>
                    <value xsi:type="processConfig" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                        <strategy>Singleton</strategy>
                        <kie-base-name></kie-base-name>
                        <kie-session-name></kie-session-name>
                        <merge-mode>Merge Collections</merge-mode>
                    </value>
                </entry>
            </configs>
            <status>STARTED</status>
        </container-specs>
        <configs/>
        <server-instances>
            <server-instance-id>demo@localhost:8230</server-instance-id>
            <server-name>demo@localhost:8230</server-name>
            <server-template-id>demo</server-template-id>
            <server-url>http://localhost:8230/kie-server/services/rest/server</server-url>
        </server-instances>
        <capabilities>RULE</capabilities>
        <capabilities>PROCESS</capabilities>
        <capabilities>PLANNING</capabilities>
    </server-template>
</server-template-list>

Returns a Kie Server template

Example 5.34. Example Server Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<server-template-details>
    <server-id>product-demo</server-id>
    <server-name>product-demo</server-name>
    <container-specs>
        <container-id>hr</container-id>
        <container-name>hr</container-name>
        <server-template-key>
            <server-id>demo</server-id>
        </server-template-key>
        <release-id>
            <artifact-id>HR</artifact-id>
            <group-id>org.jbpm</group-id>
            <version>1.0</version>
        </release-id>
        <configs>
            <entry>
                <key>RULE</key>
                <value xsi:type="ruleConfig" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                    <scanner-status>STOPPED</scanner-status>
                </value>
            </entry>
            <entry>
                <key>PROCESS</key>
                <value xsi:type="processConfig" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                    <strategy>Singleton</strategy>
                    <kie-base-name></kie-base-name>
                    <kie-session-name></kie-session-name>
                    <merge-mode>Merge Collections</merge-mode>
                </value>
            </entry>
        </configs>
        <status>STARTED</status>
    </container-specs>
    <configs/>
    <server-instances>
        <server-instance-id>demo@localhost:8230</server-instance-id>
        <server-name>demo@localhost:8230</server-name>
        <server-template-id>demo</server-template-id>
        <server-url>http://localhost:8230/kie-server/services/rest/server</server-url>
    </server-instances>
    <capabilities>RULE</capabilities>
    <capabilities>PROCESS</capabilities>
    <capabilities>PLANNING</capabilities>
</server-template-details>

Creates a new Kie Server template with the specified id

Example 5.35. Example Request to create a new Kie Server template

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<server-template-details>
    <server-id>test-demo</server-id>
    <server-name>test-demo</server-name>    
    <configs/>
    <capabilities>RULE</capabilities>
    <capabilities>PROCESS</capabilities>
    <capabilities>PLANNING</capabilities>
</server-template-details>

Deletes a Kie Server template with the specified id

Returns all containers on given server

Example 5.36. Example Server Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<container-spec-list>
    <container-spec>
        <container-id>hr</container-id>
        <container-name>hr</container-name>
        <server-template-key>
            <server-id>demo</server-id>
        </server-template-key>
        <release-id>
            <artifact-id>HR</artifact-id>
            <group-id>org.jbpm</group-id>
            <version>1.0</version>
        </release-id>
        <configs>
            <entry>
                <key>RULE</key>
                <value xsi:type="ruleConfig" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                    <scanner-status>STOPPED</scanner-status>
                </value>
            </entry>
            <entry>
                <key>PROCESS</key>
                <value xsi:type="processConfig" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                    <strategy>Singleton</strategy>
                    <kie-base-name></kie-base-name>
                    <kie-session-name></kie-session-name>
                    <merge-mode>Merge Collections</merge-mode>
                </value>
            </entry>
        </configs>
        <status>STARTED</status>
    </container-spec>
</container-spec-list>

Returns the Container information including its release id and configuration

Example 5.37. Example Server Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<container-spec-details>
    <container-id>hr</container-id>
    <container-name>hr</container-name>
    <server-template-key>
        <server-id>demo</server-id>
    </server-template-key>
    <release-id>
        <artifact-id>HR</artifact-id>
        <group-id>org.jbpm</group-id>
        <version>1.0</version>
    </release-id>
    <configs>
        <entry>
            <key>PROCESS</key>
            <value xsi:type="processConfig" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                <strategy>Singleton</strategy>
                <kie-base-name></kie-base-name>
                <kie-session-name></kie-session-name>
                <merge-mode>Merge Collections</merge-mode>
            </value>
        </entry>
        <entry>
            <key>RULE</key>
            <value xsi:type="ruleConfig" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                <scanner-status>STOPPED</scanner-status>
            </value>
        </entry>
    </configs>
    <status>STARTED</status>
</container-spec-details>

Creates a new Container with the specified containerId and the given release id and optionally configuration

Example 5.38. Example Server Request

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<container-spec-details>
    <container-id>hr</container-id>
    <container-name>hr</container-name>
    <server-template-key>
        <server-id>demo</server-id>
    </server-template-key>
    <release-id>
        <artifact-id>HR</artifact-id>
        <group-id>org.jbpm</group-id>
        <version>1.0</version>
    </release-id>
    <configs>
        <entry>
            <key>PROCESS</key>
            <value xsi:type="processConfig" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                <strategy>Singleton</strategy>
                <kie-base-name></kie-base-name>
                <kie-session-name></kie-session-name>
                <merge-mode>Merge Collections</merge-mode>
            </value>
        </entry>
        <entry>
            <key>RULE</key>
            <value xsi:type="ruleConfig" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                <scanner-status>STOPPED</scanner-status>
            </value>
        </entry>
    </configs>
    <status>STARTED</status>
</container-spec-details

Disposes a Container with the specified containerId

Starts the Container. No request body required

Stops the Container. No request body required

The Kie Server has a great Java API to wrap REST or JMS requests to be sent to the server. In this section we will explore some of the possibilities of this API.

if you are a Maven user, make sure you have at least the following dependencies in the project's pom.xml

Example 5.39. Maven Dependencies

<dependency>
  <groupId>org.kie.server</groupId>
  <artifactId>kie-server-client</artifactId>
  <version>${kie.api.version}</version>
</dependency>
<!-- Logging -->
<dependency>
  <groupId>ch.qos.logback</groupId>
  <artifactId>logback-classic</artifactId>
  <version>1.1.2</version>
</dependency>
<!-- Drools Commands -->
<dependency>
  <groupId>org.drools</groupId>
  <artifactId>drools-compiler</artifactId>
  <scope>runtime</scope>
  <version>${kie.api.version}</version>
</dependency>

The version kie.api.version depends on the Kie Server version you are using. For jBPM 6.3, for example, you can use 6.3.1-SNAPSHOT.

The client requires a configuration object where you set most of the server communication aspects, such as the protocol (REST and JMS) credentials and the payload format (XStream, JAXB and JSON are the supported formats at the moment). The first thing to do is create your configuration then create the KieServicesClient object, the entry point for starting the server communication. See the source below where we use a REST client configuration:

Example 5.40. Client Configuration Example

import org.kie.server.api.marshalling.MarshallingFormat;  
import org.kie.server.client.KieServicesClient;  
import org.kie.server.client.KieServicesConfiguration;  
import org.kie.server.client.KieServicesFactory;  
  
public class DecisionServerTest {  
  
    private static final String URL = "http://localhost:8080/kie-server/services/rest/server";  
    private static final String USER = "kieserver";  
    private static final String PASSWORD = "kieserver1!";  
  
    private static final MarshallingFormat FORMAT = MarshallingFormat.JSON;  
  
    private KieServicesConfiguration conf;  
    private KieServicesClient kieServicesClient;  
  
    public void initialize() {  
        conf = KieServicesFactory.newRestConfiguration(URL, USER, PASSWORD);  
        conf.setMarshallingFormat(FORMAT);  
        kieServicesClient = KieServicesFactory.newKieServicesClient(conf);  
    }


All the service responses are represented by the object org.kie.server.api.model.ServiceResponse<T> where T is the type of the payload. It has the following attributes:

String msg: The response message;

org.kie.server.api.model.ServiceResponse.ResponseType type: the response type enum, which can be SUCCESS or FAILURE;

T result: The actual payload of the response, the requested object.

Notice that this is the same object returned if you are using REST or JMS, in another words it is agnostic to protocol.

Decision Server initially only supported rules execution, starting in version 6.3 it started supporting business process execution. To know what exactly your server support, you can list the server capabilities by accessing the object org.kie.server.api.model.KieServerInfo using the client:

Example 5.41. Listing Server capabilities

public void listCapabilities() {  
    KieServerInfo serverInfo = kieServicesClient.getServerInfo().getResult();  
    System.out.print("Server capabilities:");  
    for(String capability: serverInfo.getCapabilities()) {  
        System.out.print(" " + capability);  
    }  
    System.out.println();  
}


If the server supports rules and process, the following should be printed when you run the code above:

Server capabilities: BRM KieServer BPM

If you want to publish a kjar to receive requests, you must publish it in a container. The container is represented in the client by the object org.kie.server.api.model.KieContainerResource, and a list of resources is org.kie.server.api.model.KieContainerResourceList. Here's an example of how to print a list of containers:

Example 5.42. Listing Kie Containers

public void listContainers() {  
    KieContainerResourceList containersList = kieServicesClient.listContainers().getResult();  
    List<KieContainerResource> kieContainers = containersList.getContainers();  
    System.out.println("Available containers: ");  
    for (KieContainerResource container : kieContainers) {  
        System.out.println("\t" + container.getContainerId() + " (" + container.getReleaseId() + ")");  
    }  
}


You can use the client to dispose and create containers. If you dispose a containers, a ServiceResponse will be returned with Void payload(no payload) and if you create it, the KieContainerResource object itself will be returned in the response. Sample code:

Example 5.43. Disposing and creating containers

public void disposeAndCreateContainer() {  
    System.out.println("== Disposing and creating containers ==");  
    List<KieContainerResource> kieContainers = kieServicesClient.listContainers().getResult().getContainers();  
    if (kieContainers.size() == 0) {  
        System.out.println("No containers available...");  
        return;  
    }  
    KieContainerResource container = kieContainers.get(0);  
    String containerId = container.getContainerId();  
    ServiceResponse<Void> responseDispose = kieServicesClient.disposeContainer(containerId);  
    if (responseDispose.getType() == ResponseType.FAILURE) {  
        System.out.println("Error disposing " + containerId + ". Message: ");  
        System.out.println(responseDispose.getMsg());  
        return;  
    }  
    System.out.println("Success Disposing container " + containerId);  
    System.out.println("Trying to recreate the container...");  
    ServiceResponse<KieContainerResource> createResponse = kieServicesClient.createContainer(containerId, container);  
    if(createResponse.getType() == ResponseType.FAILURE) {  
        System.out.println("Error creating " + containerId + ". Message: ");  
        System.out.println(responseDispose.getMsg());  
        return;  
    }  
     System.out.println("Container recreated with success!");  
}


The KieServicesClient is also the entry point for others clients to perform specific operations, such as send BRMS commands and manage processes. Currently from the KieServicesClient you can have access to the following services available in org.kie.server.client package:

For further information about these interfaces check github: https://github.com/droolsjbpm/droolsjbpm-integration/tree/master/kie-server-parent/kie-server-remote/kie-server-client/src/main/java/org/kie/server/client

You can have access to any of these clients using the method getServicesClient in the KieServicesClient class. For example: RuleServicesClient rulesClient = kieServicesClient.getServicesClient(RuleServicesClient.class);

To build commands to the server you must use the class org.kie.api.command.KieCommands, that can be created using org.kie.api.KieServices.get().getCommands(). The command to be send must be a BatchExecutionCommand or a single command(if a single command is sent, the server wraps it into a BatchExecutionCommand):

Example 5.44. Sending commands to a container

public void executeCommands() {  
    System.out.println("== Sending commands to the server ==");  
    RuleServicesClient rulesClient = kieServicesClient.getServicesClient(RuleServicesClient.class);  
    KieCommands commandsFactory = KieServices.Factory.get().getCommands();  
    Command<?> insert = commandsFactory.newInsert("Some String OBJ");  
    Command<?> fireAllRules = commandsFactory.newFireAllRules();  
    Command<?> batchCommand = commandsFactory.newBatchExecution(Arrays.asList(insert, fireAllRules));  
    ServiceResponse<String> executeResponse = rulesClient.executeCommands("hello", batchCommand);  
    if(executeResponse.getType() == ResponseType.SUCCESS) {  
        System.out.println("Commands executed with success! Response: ");  
        System.out.println(executeResponse.getResult());  
    }  
    else {  
        System.out.println("Error executing rules. Message: ");  
        System.out.println(executeResponse.getMsg());  
    }  
}

The result in this case is a String with the command execution result. In our case it will print the following:

    == Sending commands to the server ==  
    Commands executed with success! Response:   
    {  
      "results" : [ ],  
      "facts" : [ ]  
    }

* You must add org.drools:drools-compiler dependency to have this part working


To list process definitions we use the QueryClient. The methods of the QueryClient usually uses pagination, which means that besides the query you are making, you must also provide the current page and the number of results per page. In the code below the query for process definitions from the given container starts on page 0 and list 1000 results, in another words, the 1000 first results.

Example 5.45. Listing Business Processes Definitions Example

public void listProcesses() {  
    System.out.println("== Listing Business Processes ==");  
    QueryServicesClient queryClient = kieServicesClient.getServicesClient(QueryServicesClient.class);  
    List<ProcessDefinition> findProcessesByContainerId = queryClient.findProcessesByContainerId("rewards", 0, 1000);  
    for (ProcessDefinition def : findProcessesByContainerId) {  
        System.out.println(def.getName() + " - " + def.getId() + " v" + def.getVersion());  
    }  
}