Chapter 2. Project deployment in Business Central
You can use Business Central to develop your business assets and services and to manage KIE Server instances configured for project deployment. When your project is developed, you can build the project in Business Central and deploy it automatically to KIE Server. To enable automatic deployment, Business Central includes a built-in Maven repository. From Business Central, you can start, stop, or remove the deployment units (KIE containers) that contain the services and their project versions that you have built and deployed.
You can also connect several KIE Servers to the same Business Central instance and group them into different server configurations (in Menu
For example, you could have test servers in the Test
configuration and production servers in a Production
configuration. As you develop business assets and services in a project, you deploy the project on the Test
server configuration and then, when a version of the project is sufficiently tested, you can deploy it on the Production
server configuration. In this case, to keep developing the project, change the version in the project settings. Then the new version and the old version are seen as different artifacts in the built-in Maven repository. You can deploy the new version on the Test
server configuration and keep running the old version on the Production
server configuration. This deployment process is simple but has significant limitations. Notably, there is not enough access control: a developer can deploy a project directly into a production environment.
You cannot move a KIE Server into a different server configuration using Business Central. You must change the configuration file of the server to change the server configuration name for it.
2.1. Configuring KIE Server to connect to Business Central
This section provides a sample setup that you can use for testing purposes. Some of the values are unsuitable for a production environment, and are marked as such.
If a KIE Server is not configured in your Red Hat Process Automation Manager environment, or if you require additional KIE Servers in your Red Hat Process Automation Manager environment, you must configure a KIE Server to connect to Business Central.
If you are deploying KIE Server on Red Hat OpenShift Container Platform, see the Deploying an Red Hat Decision Manager environment on Red Hat OpenShift Container Platform 4 using Operators document for instructions about configuring it to connect to Business Central.
Prerequisites
-
Business Central and KIE Server are installed in the base directory of the Red Hat JBoss EAP installation (
EAP_HOME
).
You must install Business Central and KIE Server on different servers in production environments. In this sample situation, we use only one user named controllerUser
, containing both rest-all
and the kie-server
roles. However, if you install KIE Server and Business Central on the same server, for example in a development environment, make the changes in the shared standalone-full.xml
file as described in this section.
Users with the following roles exist:
-
In Business Central, a user with the role
rest-all
-
On KIE Server, a user with the role
kie-server
-
In Business Central, a user with the role
Procedure
-
In your Red Hat Process Automation Manager installation directory, navigate to the
standalone-full.xml
file. For example, if you use a Red Hat JBoss EAP installation for Red Hat Process Automation Manager, go to$EAP_HOME/standalone/configuration/standalone-full.xml
. Open the
standalone-full.xml
file and under the<system-properties>
tag, set the following JVM properties:Table 2.1. JVM Properties for the managed KIE Server instance Property Value Note org.kie.server.id
default-kie-server
The KIE Server ID.
org.kie.server.controller
http://localhost:8080/business-central/rest/controller
The location of Business Central. The URL for connecting to the API of Business Central.
org.kie.server.controller.user
controllerUser
The user name with the role
rest-all
who can log in to the Business Central.org.kie.server.controller.pwd
controllerUser1234;
The password of the user who can log in to the Business Central.
org.kie.server.location
http://localhost:8080/kie-server/services/rest/server
The location of KIE Server. The URL for connecting to the API of KIE Server.
Table 2.2. JVM Properties for the Business Central instance Property Value Note org.kie.server.user
controllerUser
The user name with the role
kie-server
.org.kie.server.pwd
controllerUser1234;
The password of the user.
The following example shows how to configure a KIE Server instance:
<property name="org.kie.server.id" value="default-kie-server"/> <property name="org.kie.server.controller" value="http://localhost:8080/business-central/rest/controller"/> <property name="org.kie.server.controller.user" value="controllerUser"/> <property name="org.kie.server.controller.pwd" value="controllerUser1234;"/> <property name="org.kie.server.location" value="http://localhost:8080/kie-server/services/rest/server"/>
The following example shows how to configure a for Business Central instance:
<property name="org.kie.server.user" value="controllerUser"/> <property name="org.kie.server.pwd" value="controllerUser1234;"/>
To verify that KIE Server starts successfully, send a GET request to
http://SERVER:PORT/kie-server/services/rest/server/
when KIE Server is running. For more information about running Red Hat Process Automation Manager on KIE Server, see Running Red Hat Process Automation Manager.After successful authentication, you receive an XML response similar to the following example:
<response type="SUCCESS" msg="Kie Server info"> <kie-server-info> <capabilities>KieServer</capabilities> <capabilities>BRM</capabilities> <capabilities>BPM</capabilities> <capabilities>CaseMgmt</capabilities> <capabilities>BPM-UI</capabilities> <capabilities>BRP</capabilities> <capabilities>DMN</capabilities> <capabilities>Swagger</capabilities> <location>http://localhost:8230/kie-server/services/rest/server</location> <messages> <content>Server KieServerInfo{serverId='first-kie-server', version='7.5.1.Final-redhat-1', location='http://localhost:8230/kie-server/services/rest/server', capabilities=[KieServer, BRM, BPM, CaseMgmt, BPM-UI, BRP, DMN, Swagger]}started successfully at Mon Feb 05 15:44:35 AEST 2018</content> <severity>INFO</severity> <timestamp>2018-02-05T15:44:35.355+10:00</timestamp> </messages> <name>first-kie-server</name> <id>first-kie-server</id> <version>7.5.1.Final-redhat-1</version> </kie-server-info> </response>
Verify successful registration:
- Log in to Business Central.
Click Menu
Deploy Execution Servers. If registration is successful, you will see the registered server ID.
2.2. Configuring the environment mode in KIE Server and Business Central
You can set KIE Server to run in production
mode or in development
mode. Development mode provides a flexible deployment policy that enables you to update existing deployment units (KIE containers) while maintaining active process instances for small changes. It also enables you to reset the deployment unit state before updating active process instances for larger changes. Production mode is optimal for production environments, where each deployment creates a new deployment unit.
In a development environment, you can click Deploy in Business Central to deploy the built KJAR file to a KIE Server without stopping any running instances (if applicable), or click Redeploy to deploy the built KJAR file and replace all instances. The next time you deploy or redeploy the built KJAR, the previous deployment unit (KIE container) is automatically updated in the same target KIE Server.
In a production environment, the Redeploy option in Business Central is disabled and you can click only Deploy to deploy the built KJAR file to a new deployment unit (KIE container) on a KIE Server.
Procedure
-
To configure the KIE Server environment mode, set the
org.kie.server.mode
system property toorg.kie.server.mode=development
ororg.kie.server.mode=production
. To configure the deployment behavior for a project in Business Central, go to project Settings
General Settings Version and toggle the Development Mode option. NoteBy default, KIE Server and all new projects in Business Central are in development mode.
You cannot deploy a project with Development Mode turned on or with a manually added
SNAPSHOT
version suffix to a KIE Server that is in production mode.
2.3. Configuring an external Maven repository for Business Central and KIE Server
You can configure Business Central and KIE Server to use an external Maven repository, such as Nexus or Artifactory, instead of the built-in repository. This enables Business Central and KIE Server to access and download artifacts that are maintained in the external Maven repository.
Artifacts in the repository do not receive automated security patches because Maven requires that artifacts be immutable. As a result, artifacts that are missing patches for known security flaws will remain in the repository to avoid breaking builds that depend on them. The version numbers of patched artifacts are incremented. For more information, see JBoss Enterprise Maven Repository.
For information about configuring an external Maven repository for an authoring environment on Red Hat OpenShift Container Platform, see the following documents:
Prerequisites
- Business Central and KIE Server are installed. For installation options, see Planning a Red Hat Decision Manager installation.
Procedure
-
Create a Maven
settings.xml
file with connection and access details for your external repository. For details about thesettings.xml
file, see the Maven Settings Reference. -
Save the file in a known location, for example,
/opt/custom-config/settings.xml
. -
In your Red Hat Process Automation Manager installation directory, navigate to the
standalone-full.xml
file. For example, if you use a Red Hat JBoss EAP installation for Red Hat Process Automation Manager go to$EAP_HOME/standalone/configuration/standalone-full.xml
. Open
standalone-full.xml
and under the<system-properties>
tag, set thekie.maven.settings.custom
property to the full path name of thesettings.xml
file.For example:
<property name="kie.maven.settings.custom" value="/opt/custom-config/settings.xml"/>
- Start or restart Business Central and KIE Server.
Next steps
For each Business Central project that you want to export or push as a KJAR artifact to the external Maven repository, you must add the repository information in the project pom.xml
file. For instructions, see Section 2.4, “Exporting a Business Central project to an external Maven repository”.
2.4. Exporting a Business Central project to an external Maven repository
If you configured an external Maven repository for Business Central and KIE Server, you must add the repository information in the pom.xml
file for each Business Central project that you want to export or push as a KJAR artifact to that external repository. You can then progress the project KJAR files through the repository as necessary to implement your integration process, and deploy the KJAR files using Business Central or the KIE Server REST API.
Prerequisites
You configured Business Central and KIE Server to use an external Maven repository. If you deployed Business Central on-premise, for more information about configuring an external Maven repository, see Section 2.3, “Configuring an external Maven repository for Business Central and KIE Server”. If you deployed your authoring environment on Red Hat OpenShift Container Platform, for more information, see the following documents:
Procedure
-
In Business Central, go to Menu
Design Projects, click the project name, and select any asset in the project. -
In the Project Explorer menu on the left side of the screen, click the Customize View gear icon and select Repository View
pom.xml. Add the following settings at the end of the project
pom.xml
file (before the</project>
closing tag). The values must correspond to the settings that you defined in yoursettings.xml
file.<distributionManagement> <repository> <id>${maven-repo-id}</id> <url>${maven-repo-url}</url> <layout>default</layout> </repository> </distributionManagement>
-
Click Save to save the
pom.xml
file changes.
Repeat this procedure for each Business Central project that you want to export or push as a KJAR artifact to the external Maven repository.
2.5. Building and deploying a project in Business Central
After your project is developed, you can build the project in Business Central and deploy it to the configured KIE Server. Projects in Business Central are packaged automatically as KJARs with all necessary components when you build and deploy the projects.
Procedure
-
In Business Central, go to Menu
Design Projects and click the project name. In the upper-right corner, click Deploy to build the project and deploy it to a KIE Server. To compile the project without deploying it to KIE Server, click Build.
NoteYou can also select the Build & Install option to build the project and publish the KJAR file to the configured Maven repository without deploying to a KIE Server. In a development environment, you can click Deploy to deploy the built KJAR file to a KIE Server without stopping any running instances (if applicable), or click Redeploy to deploy the built KJAR file and replace all instances. The next time you deploy or redeploy the built KJAR, the previous deployment unit (KIE container) is automatically updated in the same target KIE Server. In a production environment, the Redeploy option is disabled and you can click Deploy only to deploy the built KJAR file to a new deployment unit (KIE container) on a KIE Server.
To configure the KIE Server environment mode, set the
org.kie.server.mode
system property toorg.kie.server.mode=development
ororg.kie.server.mode=production
. To configure the deployment behavior for a corresponding project in Business Central, go to project SettingsGeneral Settings Version and toggle the Development Mode option. By default, KIE Server and all new projects in Business Central are in development mode. You cannot deploy a project with Development Mode turned on or with a manually added SNAPSHOT
version suffix to a KIE Server that is in production mode.If only one KIE Server is connected to Business Central, or if all connected KIE Servers are in the same server configuration, the services in the project are started automatically in a deployment unit (KIE container).
If multiple server configurations are available, a deployment dialog is displayed in Business Central, prompting you to specify server and deployment details.
If the deployment dialog appears, verify or set the following values:
- Deployment Unit Id / Deployment Unit Alias: Verify the name and alias of the deployment unit (KIE container) running the service within KIE Server. You normally do not need to change these settings. For more information about KIE container aliases, see Section 2.6.3, “KIE container aliases”.
- Server Configuration: Select the server configuration for deploying this project. You can later deploy it to other configured servers without rebuilding the project.
- Start Deployment Unit?: Verify that this box is selected to start the deployment unit (KIE container). If you clear this box, the service is deployed onto the server but not started.
To review project deployment details, click View deployment details in the deployment banner at the top of the screen or in the Deploy drop-down menu. This option directs you to the Menu
Deploy Execution Servers page.
2.6. Deployment units in Business Central
The services in a project are consumed at run time through an instantiated KIE container, or deployment unit, on a configured KIE Server. When you build and deploy a project in Business Central, the deployment unit is created automatically in the configured server. You can start, stop, or remove deployment units in Business Central as needed. You can also create additional deployment units from previously built projects and start them on existing or new KIE Servers configured in Business Central.
2.6.1. Creating a deployment unit in Business Central
One or more deployment units should already exist as part of your Red Hat Decision Manager configuration, but if not, you can create a deployment unit from a project that was previously built in Business Central.
Prerequisites
- The project for which you are creating the new deployment unit has been built in Business Central.
Procedure
-
In Business Central, go to Menu
Deploy Execution servers. - Under Server Configurations, select an existing configuration or click New Server Configuration to create a configuration.
- Under Deployment Units, click Add Deployment Unit.
- Add an alias in the Alias field if required.
- In the table within the window, select a GAV and click Select next to the GAV to populate the deployment unit data fields.
- Select the Start Deployment Unit? box to start the service immediately, or clear the box to start it later.
Click Finish.
The new deployment unit for the service is created and placed on the KIE Servers that are configured for this server configuration. If you have selected Start Deployment Unit?, the service is started.
2.6.2. Starting, stopping, and removing deployment units in Business Central
When a deployment unit is started, the services in the deployment unit are available for use. If only one KIE Server is connected to Business Central, or if all connected KIE Servers are in the same server configuration, services are started in a deployment unit automatically when a project is deployed. If multiple server configurations are available, you are prompted upon deployment to specify server and deployment details and to start the deployment unit. However, at any time you can manually start, stop, or remove deployment units in Business Central to manage your deployed services as needed.
Procedure
-
In Business Central, go to Menu
Deploy Execution servers. - Under Server Configurations, select a configuration.
- Under Deployment Units, select a deployment unit.
- Click Start, Stop, or Remove in the upper-right corner. To remove a running deployment unit, stop it and then remove it.
2.6.3. KIE container aliases
An alias for a KIE container (deployment unit) is a proxy in the KIE Server instance that helps in handling different versions of the same container deployment. You can link a single alias to different versions of a container. When a container is upgraded, the linked alias automatically points to the new version of the container. For information about creating a KIE container alias, see Section 2.6.1, “Creating a deployment unit in Business Central”.
For example, if a client application is changing every time a new version of a container is deployed, then the client application can point to the container alias. When a new container version is deployed, the associated alias is updated and all the requests are routed automatically to the new container without changing the client application.
Consider an example project that contains a single process and uses the following properties:
-
GroupId
: org.jbpm -
ArtifactId
: my-project -
Version
: 1.0 -
containerID
: my-project
When you update, build, and deploy the above project, the associated project is updated on KIE Server with the latest version and contains the following properties:
-
GroupId
: org.jbpm -
ArtifactId
: my-project -
Version
: 2.0
If you want to deploy the latest version of the project, you need to update the containerID
as my-project2
because the my-project
container points to the old version.
Every project version contains a different containerID
name. The associated client applications need to be aware of all versions of the projects they interact with.
Container aliases also help you manage KIE containers. You can set the container aliases explicitly when creating a container, or implicitly based on the associated ArtifactId
name. You can add a single alias to multiple containers if required. If you do not specify a container alias, then the ArtifactId
of a project is set as the container alias by default.
When you set an alias for multiple containers that contain different GroupId
and ArtifactId
names, then you can use the same alias every time to interact with KIE Server.
You typically use container aliases in the following use cases:
- Starting a new process instance on the client application with the latest version of the process
- Interacting with an existing process of a specific version
- Interacting with an existing task in a process
- Interacting with a process definition image and form
For example, after you deploy the 1.0 version of a project, you send a POST request to the following KIE Server REST API endpoint to start the process in the project:
/http://localhost:8230/kie-server/services/rest/server/containers/my-project/processes/evaluation/instances
The sent request starts a new process instance from org.jbpm:my-project:1.0
in which my-project
is defined as the container alias. Later, when you deploy the 2.0 version of the project and send the same request, a new instance starts from org.jbpm:my-project:2.0
. You can deploy the latest version of the process without adding the containerID
name.
2.7. Editing the GAV values for a project in Business Central
The GroupId
, ArtifactId
, and Version
(GAV) values identify a project in a Maven repository. When Business Central and KIE Server are on the same file system and use the same Maven repository, the project is automatically updated in the repository each time you build a new version of your project. However, if Business Central and KIE Server are on separate file systems and use separate local Maven repositories, you must update a project GAV value, usually the version, for any new versions of the project to ensure that the project is seen as a different artifact alongside the old version.
For development purposes only, you can toggle the Development Mode option in project Settings SNAPSHOT
suffix in the project version. This suffix instructs Maven to get a new snapshot update according to the Maven policy. Do not use Development Mode or manually add the SNAPSHOT
version suffix for a production environment.
You can set the GAV values in the project Settings screen.
Procedure
-
In Business Central, go to Menu
Design Projects and click the project name. - Click the project Settings tab.
In General Settings, modify the Group ID, Artifact ID, or Version fields as necessary. If you have deployed the project and are developing a new version, usually you need to increase the version number.
NoteFor development purposes only, you can toggle the Development Mode option in project Settings
General Settings Version to add the SNAPSHOT
suffix in the project version. This suffix instructs Maven to get a new snapshot update according to the Maven policy. Do not use Development Mode or manually add theSNAPSHOT
version suffix for a production environment.- Click Save to finish.
2.8. Duplicate GAV detection in Business Central
In Business Central, all Maven repositories are checked for any duplicated GroupId
, ArtifactId
, and Version
(GAV) values in a project. If a GAV duplicate exists, the performed operation is canceled.
Duplicate GAV detection is disabled for projects in Development Mode. To enable duplicate GAV detection in Business Central, go to project Settings
Duplicate GAV detection is executed every time you perform the following operations:
- Save a project definition for the project.
-
Save the
pom.xml
file. - Install, build, or deploy a project.
The following Maven repositories are checked for duplicate GAVs:
-
Repositories specified in the
<repositories>
and<distributionManagement>
elements of thepom.xml
file. -
Repositories specified in the Maven
settings.xml
configuration file.
2.8.1. Managing duplicate GAV detection settings in Business Central
Business Central users with the admin
role can modify the list of repositories that are checked for duplicate GroupId
, ArtifactId
, and Version
(GAV) values for a project.
Duplicate GAV detection is disabled for projects in Development Mode. To enable duplicate GAV detection in Business Central, go to project Settings
Procedure
-
In Business Central, go to Menu
Design Projects and click the project name. - Click the project Settings tab and then click Validation to open the list of repositories.
Select or clear any of the listed repository options to enable or disable duplicate GAV detection.
In the future, duplicate GAVs will be reported for only the repositories you have enabled for validation.
NoteTo disable this feature, set the
org.guvnor.project.gav.check.disabled
system property totrue
for Business Central at system startup:$ ~/EAP_HOME/bin/standalone.sh -c standalone-full.xml -Dorg.guvnor.project.gav.check.disabled=true