Red Hat Training

A Red Hat training course is available for Red Hat Process Automation Manager

Chapter 8. Adding dynamic tasks and processes to a case using the 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 subprocesses

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 subprocesses, 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 subprocess 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 subprocesses.

Prerequisite

You are logged in to Business Central and a case instance has been started using the Showcase application. For more information about using Showcase, see Case management Showcase application.

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.

    swagger case management dynamic
  4. Click the REST endpoint required to create the dynamic task or process to open the documentation.
  5. Click Try it out and provide the parameters and body required to create the dynamic activity.
  6. Click Execute to create the dynamic task or subprocess using the REST API.

8.1. Creating a dynamic user task using the REST API

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

  • Task name
  • Task description (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.

Prerequisite

You are logged in to Business Central and an IT Orders case instance has been started using the Showcase application. For more information about using Showcase, see Case management Showcase application.

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 to complete the following parameters:

    Table 8.1. Parameters

    NameDescription

    id

    itorders

    caseId

    IT-0000000001

    body
    {
 "name" : "RequestManagerApproval",
 "data" : {
   "reason" : "Fixed hardware spec",
   "caseFile_hwSpec" : "#{caseFile_hwSpec}"
  },
 "description" : "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 process or case data.

Depending on the task, a form might be defined to provide a user-friendly UI for the task, which can be looked up 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.

8.2. Creating a dynamic service task using the REST API

Service tasks are generally less complex than user tasks, although they might need more data to execute properly. Service tasks require 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.

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

Use the following procedure use the Swagger REST API to create a dynamic service task for the IT Orders sample project available in Business Central . The same endpoint can be used for REST API without Swagger.

Prerequisite

You are logged in to Business Central and an IT Orders case instance has been started using the Showcase application. For more information about using Showcase, see Case management Showcase application.

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}/stages/{caseStageId}/tasks

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

    Table 8.2. Parameters

    NameDescription

    id

    itorders

    caseId

    IT-0000000001

    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, public printMessage method with a single String argument. Upon execution, the parameter value is passed to the method for execution.

Numbers and names and other types of data given to create service tasks depend on the implementation of a service task’s handler. In the provided example, 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 same as the nodeType used for creating a dynamic service task.

8.3. Creating a dynamic subprocess using the REST API

When creating a dynamic subprocess, only optional data is provided; there are no special parameters as there are when creating dynamic tasks.

Use the following procedure use the Swagger REST API to create a dynamic subprocess task for the IT Orders sample project available in Business Central . The same endpoint can be used for REST API without Swagger.

Prerequisite

You are logged in to Business Central and an IT Orders case instance has been started using the Showcase application. For more information about using Showcase, see Case management Showcase application.

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}/processes/{pId}

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

    Table 8.3. Parameters

    NameDescription

    id

    itorders

    caseId

    IT-0000000001

    pId

    itorders-data.place-order

    The pId is the process ID of the subprocess to be created.

    body
    {
 "placedOrder" : "Manually"
}
  5. In the Swagger application, click Execute to start the dynamic subprocess.

In this example, the place-order subprocess 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.