Red Hat Training
A Red Hat training course is available for Red Hat Process Automation Manager
Chapter 1. Process Server REST API for KIE containers and business assets
Red Hat Process Automation Manager provides a Process Server REST API that you can use to interact with your KIE containers and business assets (such as business rules, processes, and solvers) in Red Hat Process Automation Manager without using the Business Central user interface. This API support enables you to maintain your Red Hat Process Automation Manager resources more efficiently and optimize your integration and development with Red Hat Process Automation Manager.
With the Process Server REST API, you can perform the following actions:
- Deploy or dispose KIE containers
- Retrieve and update KIE container information
- Return Process Server status and basic information
- Retrieve and update business asset information
- Execute business assets (such as rules and processes)
Process Server REST API requests require the following components:
- Authentication
The Process Server REST API requires HTTP Basic authentication or token-based authentication for the user role
kie-server
. To view configured user roles for your Red Hat Process Automation Manager distribution, navigate to~/$SERVER_HOME/standalone/configuration/application-roles.properties
and~/application-users.properties
.To add a user with the
kie-server
role, navigate to~/$SERVER_HOME/bin
and run the following command:$ ./add-user.sh -a --user <USERNAME> --password <PASSWORD> --role kie-server
For more information about user roles and Red Hat Process Automation Manager installation options, see Planning a Red Hat Process Automation Manager installation.
- HTTP headers
The Process Server REST API requires the following HTTP headers for API requests:
Accept
: Data format accepted by your requesting client:-
application/json
(JSON) -
application/xml
(XML, for JAXB or XSTREAM)
-
Content-Type
: Data format of yourPOST
orPUT
API request data:-
application/json
(JSON) -
application/xml
(XML, for JAXB or XSTREAM)
-
X-KIE-ContentType
: Required header forapplication/xml
XSTREAM API requests and responses:-
XSTREAM
-
- HTTP methods
The Process Server REST API supports the following HTTP methods for API requests:
-
GET
: Retrieves specified information from a specified resource endpoint -
POST
: Updates a resource or resource instance -
PUT
: Updates or creates a resource or resource instance -
DELETE
: Deletes a resource or resource instance
-
- Base URL
-
The base URL for Process Server REST API requests is
http://SERVER:PORT/kie-server/services/rest/
, such ashttp://localhost:8080/kie-server/services/rest/
. - Endpoints
Process Server REST API endpoints, such as
/server/containers/{containerId}
for a specified KIE container, are the URIs that you append to the Process Server REST API base URL to access the corresponding resource or type of resource in Red Hat Process Automation Manager.Example request URL for
/server/containers/{containerId}
endpointhttp://localhost:8080/kie-server/services/rest/server/containers/MyContainer
- Request parameters and request data
Many Process Server REST API requests require specific parameters in the request URL path to identify or filter specific resources and to perform specific actions. You can append URL parameters to the endpoint in the format
?<PARAM>=<VALUE>&<PARAM>=<VALUE>
.Example GET request URL with parameters
http://localhost:8080/kie-server/services/rest/server/containers?groupId=com.redhat&artifactId=Project1&version=1.0&status=STARTED
HTTP
POST
andPUT
requests may additionally require a request body or file with data to accompany the request.Example POST request URL and JSON request body data
http://localhost:8080/kie-server/services/rest/server/containers/MyContainer/release-id
{ "release-id": { "artifact-id": "Project1", "group-id": "com.redhat", "version": "1.1" } }
1.1. Sending requests with the Process Server REST API using a REST client or curl utility
The Process Server REST API enables you to interact with your KIE containers and business assets (such as business rules, processes, and solvers) in Red Hat Process Automation Manager without using the Business Central user interface. You can send Process Server REST API requests using any REST client or curl utility.
Prerequisites
- Process Server is installed and running.
-
You have
kie-server
user role access to Process Server.
Procedure
-
Identify the relevant API endpoint to which you want to send a request, such as
[GET] /server/containers
to retrieve KIE containers from Process Server. In a REST client or curl utility, enter the following components for a
GET
request to/server/containers
. Adjust any request details according to your use case.For REST client:
-
Authentication: Enter the user name and password of the Process Server user with the
kie-server
role. HTTP Headers: Set the following header:
-
Accept
:application/json
-
-
HTTP method: Set to
GET
. -
URL: Enter the Process Server REST API base URL and endpoint, such as
http://localhost:8080/kie-server/services/rest/server/containers
.
For curl utility:
-
-u
: Enter the user name and password of the Process Server user with thekie-server
role. -H
: Set the following header:-
Accept
:application/json
-
-
-X
: Set toGET
. -
URL: Enter the Process Server REST API base URL and endpoint, such as
http://localhost:8080/kie-server/services/rest/server/containers
.
curl -u 'baAdmin:password@1' -H "Accept: application/json" -X GET "http://localhost:8080/kie-server/services/rest/server/containers"
-
Authentication: Enter the user name and password of the Process Server user with the
Execute the request and review the Process Server response.
Example server response (JSON):
{ "type": "SUCCESS", "msg": "List of created containers", "result": { "kie-containers": { "kie-container": [ { "container-id": "itorders_1.0.0-SNAPSHOT", "release-id": { "group-id": "itorders", "artifact-id": "itorders", "version": "1.0.0-SNAPSHOT" }, "resolved-release-id": { "group-id": "itorders", "artifact-id": "itorders", "version": "1.0.0-SNAPSHOT" }, "status": "STARTED", "scanner": { "status": "DISPOSED", "poll-interval": null }, "config-items": [], "container-alias": "itorders" } ] } } }
-
For this example, copy or note the project
group-id
,artifact-id
, andversion
(GAV) data from one of the deployed KIE containers returned in the response. In your REST client or curl utility, send another API request with the following components for a
PUT
request to/server/containers/{containerId}
to deploy a new KIE container with the copied project GAV data. Adjust any request details according to your use case.For REST client:
-
Authentication: Enter the user name and password of the Process Server user with the
kie-server
role. HTTP Headers: Set the following headers:
-
Accept
:application/json
-
Content-Type
:application/json
-
-
HTTP method: Set to
PUT
. -
URL: Enter the Process Server REST API base URL and endpoint, such as
http://localhost:8080/kie-server/services/rest/server/containers/MyContainer
. - Request body: Add a JSON request body with the configuration items for the new KIE container:
{ "config-items": [ { "itemName": "RuntimeStrategy", "itemValue": "SINGLETON", "itemType": "java.lang.String" }, { "itemName": "MergeMode", "itemValue": "MERGE_COLLECTIONS", "itemType": "java.lang.String" }, { "itemName": "KBase", "itemValue": "", "itemType": "java.lang.String" }, { "itemName": "KSession", "itemValue": "", "itemType": "java.lang.String" } ], "release-id": { "group-id": "itorders", "artifact-id": "itorders", "version": "1.0.0-SNAPSHOT" }, "scanner": { "poll-interval": "5000", "status": "STARTED" } }
For curl utility:
-
-u
: Enter the user name and password of the Process Server user with thekie-server
role. -H
: Set the following headers:-
Accept
:application/json
-
Content-Type
:application/json
-
-
-X
: Set toPUT
. -
URL: Enter the Process Server REST API base URL and endpoint, such as
http://localhost:8080/kie-server/services/rest/server/containers/MyContainer
. -
-d
: Add a JSON request body or file (@file.json
) with the configuration items for the new KIE container:
curl -u 'baAdmin:password@1' -H "Accept: application/json" -H "Content-Type: application/json" -X PUT "http://localhost:8080/kie-server/services/rest/server/containers/MyContainer" -d "{ \"config-items\": [ { \"itemName\": \"RuntimeStrategy\", \"itemValue\": \"SINGLETON\", \"itemType\": \"java.lang.String\" }, { \"itemName\": \"MergeMode\", \"itemValue\": \"MERGE_COLLECTIONS\", \"itemType\": \"java.lang.String\" }, { \"itemName\": \"KBase\", \"itemValue\": \"\", \"itemType\": \"java.lang.String\" }, { \"itemName\": \"KSession\", \"itemValue\": \"\", \"itemType\": \"java.lang.String\" } ], \"release-id\": { \"group-id\": \"itorders\", \"artifact-id\": \"itorders\", \"version\": \"1.0.0-SNAPSHOT\" }, \"scanner\": { \"poll-interval\": \"5000\", \"status\": \"STARTED\" }}"
curl -u 'baAdmin:password@1' -H "Accept: application/json" -H "Content-Type: application/json" -X PUT "http://localhost:8080/kie-server/services/rest/server/containers/MyContainer" -d @my-container-configs.json
-
Authentication: Enter the user name and password of the Process Server user with the
Execute the request and review the Process Server response.
Example server response (JSON):
{ "type": "SUCCESS", "msg": "Container MyContainer successfully deployed with module itorders:itorders:1.0.0-SNAPSHOT.", "result": { "kie-container": { "container-id": "MyContainer", "release-id": { "group-id": "itorders", "artifact-id": "itorders", "version": "1.0.0-SNAPSHOT" }, "resolved-release-id": { "group-id": "itorders", "artifact-id": "itorders", "version": "1.0.0-SNAPSHOT" }, "status": "STARTED", "scanner": { "status": "STARTED", "poll-interval": 5000 }, "config-items": [], "messages": [ { "severity": "INFO", "timestamp": { "java.util.Date": 1540584717937 }, "content": [ "Container MyContainer successfully created with module itorders:itorders:1.0.0-SNAPSHOT." ] } ], "container-alias": null } } }
If you encounter request errors, review the returned error code messages and adjust your request accordingly.
REST API requests for process instancesFor REST API requests that send complex data objects to the process instance endpoint
/server/containers/{containerId}/processes/{processId}/instances
, ensure that you include either the fully qualified class name (such ascom.myspace.Person
) or the simple class name (such asPerson
) in the request body. The class name is required for the request body to be mapped to the correct business object in Red Hat Process Automation Manager. If you exclude the class name from the request, Process Server does not unmarshall the object to the expected type.Correct request body for process instance
{ "id": 4, "lease": { "com.myspace.restcall.LeaseModel": { "annualRent": 109608, "isAutoApproved": false } } }
Incorrect request body for process instance
{ "id": 4, "lease": { "annualRent": 109608, "isAutoApproved": false } }
1.2. Sending requests with the Process Server REST API using the Swagger interface
The Process Server REST API supports a Swagger web interface that you can use instead of a standalone REST client or curl utility to interact with your KIE containers and business assets (such as business rules, processes, and solvers) in Red Hat Process Automation Manager without using the Business Central user interface.
Prerequisites
- Process Server is installed and running.
-
You have
kie-server
user role access to Process Server.
Procedure
-
In a web browser, navigate to
http://SERVER:PORT/kie-server/docs
, such ashttp://localhost:8080/kie-server/docs
, and log in with the user name and password of the Process Server user with thekie-server
role. - In the Swagger page, select the relevant API endpoint to which you want to send a request, such as KIE Server :: Core → [GET] /server/containers to retrieve KIE containers from Process Server.
- Click Try it out and provide any optional parameters by which you want to filter results, if needed.
- In the Response content type drop-down menu, select the desired format of the server response, such as application/json for JSON format.
Click Execute and review the Process Server response.
Example server response (JSON):
{ "type": "SUCCESS", "msg": "List of created containers", "result": { "kie-containers": { "kie-container": [ { "container-id": "itorders_1.0.0-SNAPSHOT", "release-id": { "group-id": "itorders", "artifact-id": "itorders", "version": "1.0.0-SNAPSHOT" }, "resolved-release-id": { "group-id": "itorders", "artifact-id": "itorders", "version": "1.0.0-SNAPSHOT" }, "status": "STARTED", "scanner": { "status": "DISPOSED", "poll-interval": null }, "config-items": [], "container-alias": "itorders" } ] } } }
-
For this example, copy or note the project
group-id
,artifact-id
, andversion
(GAV) data from one of the deployed KIE containers returned in the response. - In the Swagger page, navigate to the KIE Server :: Core → [PUT] /server/containers/{containerId} endpoint to send another request to deploy a new KIE container with the copied project GAV data. Adjust any request details according to your use case.
Click Try it out and enter the following components for the request:
-
containerId: Enter the ID of the new KIE container, such as
MyContainer
. - body: Set the Parameter content type to the desired request body format, such as application/json for JSON format, and add a request body with the configuration items for the new KIE container:
{ "config-items": [ { "itemName": "RuntimeStrategy", "itemValue": "SINGLETON", "itemType": "java.lang.String" }, { "itemName": "MergeMode", "itemValue": "MERGE_COLLECTIONS", "itemType": "java.lang.String" }, { "itemName": "KBase", "itemValue": "", "itemType": "java.lang.String" }, { "itemName": "KSession", "itemValue": "", "itemType": "java.lang.String" } ], "release-id": { "group-id": "itorders", "artifact-id": "itorders", "version": "1.0.0-SNAPSHOT" }, "scanner": { "poll-interval": "5000", "status": "STARTED" } }
-
containerId: Enter the ID of the new KIE container, such as
- In the Response content type drop-down menu, select the desired format of the server response, such as application/json for JSON format.
Click Execute and review the Process Server response.
Example server response (JSON):
{ "type": "SUCCESS", "msg": "Container MyContainer successfully deployed with module itorders:itorders:1.0.0-SNAPSHOT.", "result": { "kie-container": { "container-id": "MyContainer", "release-id": { "group-id": "itorders", "artifact-id": "itorders", "version": "1.0.0-SNAPSHOT" }, "resolved-release-id": { "group-id": "itorders", "artifact-id": "itorders", "version": "1.0.0-SNAPSHOT" }, "status": "STARTED", "scanner": { "status": "STARTED", "poll-interval": 5000 }, "config-items": [], "messages": [ { "severity": "INFO", "timestamp": { "java.util.Date": 1540584717937 }, "content": [ "Container MyContainer successfully created with module itorders:itorders:1.0.0-SNAPSHOT." ] } ], "container-alias": null } } }
If you encounter request errors, review the returned error code messages and adjust your request accordingly.
REST API requests for process instancesFor REST API requests that send complex data objects to the process instance endpoint
/server/containers/{containerId}/processes/{processId}/instances
, ensure that you include either the fully qualified class name (such ascom.myspace.Person
) or the simple class name (such asPerson
) in the request body. The class name is required for the request body to be mapped to the correct business object in Red Hat Process Automation Manager. If you exclude the class name from the request, Process Server does not unmarshall the object to the expected type.Correct request body for process instance
{ "id": 4, "lease": { "com.myspace.restcall.LeaseModel": { "annualRent": 109608, "isAutoApproved": false } } }
Incorrect request body for process instance
{ "id": 4, "lease": { "annualRent": 109608, "isAutoApproved": false } }
1.3. Supported Process Server REST API endpoints
The Process Server REST API provides endpoints for the following types of resources in Red Hat Process Automation Manager:
- Process Server and KIE containers
- KIE session assets (for runtime commands)
- DMN assets
- Planning solvers
- Processes
- Process images
- Process and task forms
- Tasks
- Cases
- Documents
- Jobs
- Queries for processes, tasks, and cases
- Custom queries
The Process Server REST API base URL is http://SERVER:PORT/kie-server/services/rest/
. All requests require HTTP Basic authentication or token-based authentication for the kie-server
user role.
For the full list of Process Server REST API endpoints and descriptions, use one of the following resources:
- Execution Server REST API on the jBPM Documentation page (static)
-
Swagger UI for the Process Server REST API at
http://SERVER:PORT/kie-server/docs
(dynamic, requires running Process Server)
Endpoint requirements
Note the following requirements for some of the Process Server REST API endpoints:
-
Process images: For API access to process images, the system property
<storesvgonsave enabled="true"/>
must be configured for your Red Hat Process Automation Manager project in$SERVER_HOME/standalone/deployments/business-central.war/org.kie.workbench.KIEWebapp/profiles/jbpm.xml
. This property is set totrue
by default. If the API is not working with process images, set it totrue
in the file, restart your Process Server, modify the relevant process and save it, and then build and deploy your project. This property enables SVG images to be stored so that they can be retrieved by the Process Server REST API. Custom queries: Some custom query requests with the Process Server REST API require a query
mapper
definition to map the query results to concrete objects. You can implement your own query result mappers or use the mappers provided with Red Hat Process Automation Manager. The query mappers in Red Hat Process Automation Manager are similar to other object-relational mapping (ORM) providers, such as Hibernate, which maps tables to entities. For example, you can use theorg.jbpm.kie.services.impl.query.mapper.ProcessInstanceQueryMapper
, also registered asProcessInstances
, in custom query endpoints for returning process instance data.Example POST endpoint with
ProcessInstances
mapper parameter:http://localhost:8080/kie-server/services/rest/server/queries/definitions/jbpmProcessInstances?mapper=ProcessInstances
For a list of available query mappers in Red Hat Process Automation Manager, download and extract the Red Hat Process Automation Manager 7.2 Source Distribution from the Red Hat Customer Portal and navigate to
~/jbpm-$VERSION/jbpm-services/jbpm-kie-services/src/main/java/org/jbpm/kie/services/impl/query/mapper
.