Chapter 38. Adding dynamic tasks and processes to a case using the KIE Server REST API

You can add dynamic tasks and processes to a case during run time to address unforeseen changes that can occur during the lifecycle of a case. Dynamic activities are not defined in the case definition and therefore they cannot be signaled the way that a defined ad hoc task or process can.

You can add the following dynamic activities to a case:

  • User tasks
  • Service tasks (any type that is implemented as a work item)
  • Reusable sub-processes

Dynamic user and service tasks are added to a case instance and immediately executed. Depending on the nature of a dynamic task, it might start and wait for completion (user task) or directly complete after execution (service task). For dynamic sub-processes, the process engine requires a KJAR containing the process definition for that dynamic process to locate the process by its ID and execute it. This sub-process belongs to the case and has access to all of the data in the case file.

You can use the Swagger REST API application to create dynamic tasks and sub-processes.

Prerequisites

Procedure

  1. In a web browser, open the following URL:

    http://localhost:8080/kie-server/docs

  2. Open the list of available endpoints under Case instances :: Case Management.

  3. Locate the POST method endpoints for creating dynamic activities.

    POST /server/containers/{id}/cases/instances/{caseId}/tasks

    Adds a dynamic task (user or service depending on the payload) to the case instance.

    POST /server/containers/{id}/cases/instances/{caseId}/stages/{caseStageId}/tasks

    Adds a dynamic task (user or service depending on the payload) to specific stage within the case instance.

    POST /server/containers/{id}/cases/instances/{caseId}/processes/{pId}

    Adds a dynamic sub-process identified by the process ID to case instance.

    POST /server/containers/{id}/cases/instances/{caseId}/stages/{caseStageId}/processes/{pId}

    Adds a dynamic sub-process identified by process ID to stage within a case instance.

    swagger case management dynamic
  4. To open the Swagger UI, click the REST endpoint required to create the dynamic task or process.
  5. Click Try it out and enter the parameters and body required to create the dynamic activity.
  6. Click Execute to create the dynamic task or sub-process using the REST API.

38.1. Creating a dynamic user task using the KIE Server REST API

You can create a dynamic user task during case run time using the REST API. To create a dynamic user task, you must provide the following information:

  • Task name
  • Task subject (optional, but recommended)
  • Actors or groups (or both)
  • Input data

Use the following procedure to create a dynamic user task for the IT_Orders sample project available in Business Central using the Swagger REST API tool. The same endpoint can be used for REST API without Swagger.

Prerequisites

Procedure

  1. In a web browser, open the following URL:

    http://localhost:8080/kie-server/docs.

  2. Open the list of available endpoints under Case instances :: Case Management.

  3. Click click the following POST method endpoint to open the details:

    /server/containers/{id}/cases/instances/{caseId}/tasks

  4. Click Try it out and then input the following parameters:

    Table 38.1. Parameters

    NameDescription

    id

    itorders

    caseId

    IT-0000000001

    Request body

    {
 "name" : "RequestManagerApproval",
 "data" : {
   "reason" : "Fixed hardware spec",
   "caseFile_hwSpec" : "#{caseFile_hwSpec}"
  },
 "subject" : "Ask for manager approval again",
 "actors" : "manager",
 "groups" : ""
}

  5. In the Swagger application, click Execute to create the dynamic task.

This procedure creates a new user task associated with case IT-000000001. The task is assigned to the person assigned to the manager case role. This task has two input variables:

  • reason
  • caseFile_hwSpec: defined as an expression to allow run time capturing of a process or case data.

Some tasks include a form that provides a user-friendly UI for the task, which you can locate by task name. In the IT Orders case, the RequestManagerApproval task includes the form RequestManagerApproval-taskform.form in its KJAR.

After it is created, the task appears in the assignee’s Task Inbox in Business Central.

38.2. Creating a dynamic service task using the KIE Server REST API

Service tasks are usually less complex than user tasks, although they might need more data to execute properly. Service tasks require the following information:

  • name: The name of the activity
  • nodeType: The type of node that will be used to find the work item handler
  • data: The map of the data to properly deal with execution

During case run time, you can create a dynamic service task with the same endpoint as a user task, but with a different body payload.

Use the following procedure using the Swagger REST API to create a dynamic service task for the IT_Orders sample project available in Business Central. You can use the same endpoint for REST API without Swagger.

Prerequisites

Procedure

  1. In a web browser, open the following URL:

    http://localhost:8080/kie-server/docs

  2. Open the list of available endpoints under Case instances :: Case Management.

  3. Click the following POST method endpoint to open the details:

    /server/containers/{id}/cases/instances/{caseId}/stages/{caseStageId}/tasks

  4. Click Try it out and then enter the following parameters:

    Table 38.2. Parameters

    NameDescription

    id

    itorders

    caseId

    IT-0000000001

    Request body

    {
 "name" : "InvokeService",
 "data" : {
   "Parameter" : "Fixed hardware spec",
   "Interface" : "org.jbpm.demo.itorders.services.ITOrderService",
   "Operation" : "printMessage",
   "ParameterType" : "java.lang.String"
  },
 "nodeType" : "Service Task"
}

  5. In the Swagger application, click Execute to create the dynamic task.

In this example, a Java-based service is executed. It consists of an interface with the public class org.jbpm.demo.itorders.services.ITOrderService and the public printMessage method with a single String argument. When executed, the parameter value is passed to the method for execution.

Numbers, names, and other types of data given to create service tasks depend on the implementation of a service task’s handler. In the example provided, the org.jbpm.process.workitem.bpmn2.ServiceTaskHandler handler is used.

Note

For any custom service tasks, ensure the handler is registered in the deployment descriptor in the Work Item Handlers section, where the name is the same as the nodeType used for creating a dynamic service task. For more information about registering the deployment descriptor, see Developing process services in Red Hat Process Automation Manager.

38.3. Creating a dynamic sub-process using the KIE Server REST API

When creating a dynamic sub-process, only optional data is provided. There are no special parameters as there are when creating dynamic tasks.

The following procedure describes how to use the Swagger REST API to create a dynamic sub-process task for the IT_Orders sample project available in Business Central. The same endpoint can be used for REST API without Swagger.

Prerequisites

Procedure

  1. In a web browser, open the following URL:

    http://localhost:8080/kie-server/docs.

  2. Open the list of available endpoints under Case instances :: Case Management.

  3. Click the following POST method endpoint to open the details:

    /server/containers/{id}/cases/instances/{caseId}/processes/{pId}

  4. Click Try it out and enter the following parameters:

    Table 38.3. Parameters

    NameDescription

    id

    itorders

    caseId

    IT-0000000001

    pId

    itorders-data.place-order

    The pId is the process ID of the sub-process to be created.

    Request body

    {
 "placedOrder" : "Manually"
}

  5. In the Swagger application, click Execute to start the dynamic sub-process.

In this example, the place-order sub-process has been started in the IT Orders case with the case ID IT-0000000001. You can see this process in Business Central under Menu → Manage → Process Instances.

If the described example has executed correctly, the place-order process appears in the list of process instances. Open the details of the process and note that the correlation key for the process includes the IT Orders case instance ID, and the Process Variables list includes the variable placedOrder with the value Manually, as delivered in the REST API body.