jBPM provides a jBPM controller REST API that you can use to interact with your KIE Server templates (configurations), KIE Server instances (remote servers), and associated KIE containers (deployment units) in jBPM without using the Business Central user interface. This API support enables you to maintain your jBPM servers and resources more efficiently and optimize your integration and development with jBPM.

With the jBPM controller REST API, you can perform the following actions:

Retrieve information about KIE Server templates, instances, and associated KIE containers

Update, start, or stop KIE containers associated with KIE Server templates and instances

Create, update, or delete KIE Server templates

Create, update, or delete KIE Server instances
1
2
3
4
5
6
7

Requests to the jBPM controller REST API require the following components:

Authentication

The jBPM controller REST API requires HTTP Basic authentication or token-based authentication for the following user roles, depending on controller type:

    rest-all user role if you installed Business Central and you want to use the built-in jBPM controller

    kie-server user role if you installed the headless jBPM controller separately from Business Central

To view configured user roles for your jBPM distribution, navigate to ~/$SERVER_HOME/standalone/configuration/application-roles.properties and ~/application-users.properties.

To add a user with the kie-server role or the rest-all role or both, navigate to ~/$SERVER_HOME/bin and run the following command with the role or roles specified:

$ ./add-user.sh -a --user <USERNAME> --password <PASSWORD> --role kie-server,rest-all

To configure the kie-server or rest-all user with jBPM controller access, navigate to ~/$SERVER_HOME/standalone/configuration/standalone-full.xml, uncomment the org.kie.server properties (if applicable), and add the controller user login credentials and controller location (if needed):

<property name="org.kie.server.location" value="http://localhost:8080/kie-server/services/rest/server"/>
<property name="org.kie.server.controller" value="http://localhost:8080/business-central/rest/controller"/>
<property name="org.kie.server.controller.user" value="baAdmin"/>
<property name="org.kie.server.controller.pwd" value="password@1"/>
<property name="org.kie.server.id" value="default-kieserver"/>

For more information about user roles and jBPM installation options, see Installing the KIE Server.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

HTTP headers

The jBPM controller 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)

    Content-Type: Data format of your POST or PUT API request data:

        application/json (JSON)

        application/xml (XML, for JAXB)
1
2
3
4
5
6
7
8
9
10
11
12
13

HTTP methods

The jBPM controller 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: Creates a resource or resource instance

    DELETE: Deletes a resource or resource instance
1
2
3
4
5
6
7
8
9

Base URL

The base URL for jBPM controller REST API requests is http://SERVER:PORT/CONTROLLER/rest/, such as http://localhost:8080/business-central/rest/ if you are using the jBPM controller built in to Business Central.
1

Endpoints

jBPM controller REST API endpoints, such as /controller/management/servers/{serverTemplateId} for a specified KIE Server template, are the URIs that you append to the jBPM controller REST API base URL to access the corresponding server resource or type of server resource in jBPM.
Example request URL for /controller/management/servers/{serverTemplateId} endpoint

http://localhost:8080/business-central/rest/controller/management/servers/default-kieserver
1
2
3
4

Request parameters and request data

Some jBPM controller 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 DELETE request URL with parameters

http://localhost:8080/business-central/rest/controller/server/new-kieserver-instance?location=http://localhost:8080/kie-server/services/rest/server

HTTP POST and PUT requests may additionally require a request body or file with data to accompany the request.
Example PUT request URL and JSON request body data

http://localhost:8080/business-central/rest/controller/management/servers/new-kieserver

{
  "server-id": "new-kieserver",
  "server-name": "new-kieserver",
  "container-specs": [],
  "server-config": {},
  "capabilities": [
    "RULE",
    "PROCESS",
    "PLANNING"
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21