Chapter 6. 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.

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 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 subprocess identified by the process ID to case instance.

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

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

    swagger case management dynamic
  4. To open the documentation, 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 subprocess using the REST API.

6.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, you must provide the following information:

  • 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.

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 6.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 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.

6.2. Creating a dynamic service task using the 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 6.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 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 same as the nodeType used for creating a dynamic service task.

6.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 to 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.

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 6.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 MenuManageProcess 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.