Manage a process

Product version:
7.2, 7.1, 7.0
Product edition:
  • Community
  • Teamwork
  • Efficiency
  • Performance
Get the PDF version

In this page:

List the deployed processes
Enable a process and start an instance
Set variables in a process instance
Set string variables and start a process instance
Set variables of any type and start a process instance
Create a map of variables and values and start a process instance
For a running process instance, set the value of a custom data type variable
Execute a task
List the processes I started
List the open instances of a process
Get the history for a case
Query archived process instances
Stop a process instance
Deploy a process
Deploy and enable a process from a bar file
Deploy and enable a process from the processDefinitionBuilder
Get the process design definition
Undeploy a process

List the deployed processes

This example shows you how to get a list of the deployed processes.

The search options specify that the list is sorted by deployment date, the maximum number of results to list is 100, and the list starts with the first results (that is, the processes that were deployed first).

final ProcessAPI processAPI = TenantAPIAccessor.getProcessAPI(apiSession);
final SearchOptions searchOptions = new SearchOptionsBuilder(0, 100).sort(ProcessDeploymentInfoSearchDescriptor.DEPLOYMENT_DATE, Order.DESC).done();
final SearchResult<ProcessDeploymentInfo> deploymentInfoResults = processAPI.searchProcessDeploymentInfos(searchOptions);

Enable a process and start an instance

After a process is deployed it must be enabled.

If a process is not enabled, it is not possible to start a process instance.

To enable a process, call the method enableProcess specifying the processDefinition id:

// enable the process
processAPI.enableProcess(processDefinition.getId());
System.out.println("A new process was enabled: " + processDefinition.getId());

The next step is to start an instance of the deployed process:

// start the process
            final ProcessInstance processInstance = processAPI.startProcess(processDefinition.getId());
System.out.println("A new process instance was started with id: " + processInstance.getId());

Set variables in a process instance

This section contains some examples of how to set the values of some variables using a list of operations when starting an instance of a process and in a running process instance.

Set string variables and start a process instance

In this example, createInstance takes the process definition name, the process version, a map of text variables and their values, and the session identifier. The startProcess method, which creates the process instance, takes a list of operations, not a map of variables, so the map must be converted into a list of operations that will set the values of the variables in the process instance. The example calls buildAssignOperation for each variable in turn, to build an operation that will assign the value to the variable when the process instance is created. Each operation is built as an assignment expression.

public void createInstance(String processDefinitionName,
         String processVersion,
         Map<String, Object> variables,
         APISession apiSession)  {
    ProcessAPI processAPI;
    try {
        processAPI = TenantAPIAccessor.getProcessAPI(apiSession);
        long processDefinitionId = processAPI.getProcessDefinitionId(processDefinitionName, processVersion);
       
        List<Operation> listOperations = new ArrayList<Operation>();
        for (String variableName : variables.keySet()) {
            if (variables.get(variableName) == null)
continue;
           Operation operation = buildAssignOperation(variableName, variables.get(variableName).toString(),
                String.class.getName(), ExpressionType.TYPE_CONSTANT);
           listOperations.add(operation);
       }
       processAPI.startProcess(processDefinitionId, listOperations, null);
    } catch (Exception e) {
        e.printStackTrace();
    }
}

private Operation buildAssignOperation(final String dataInstanceName,
    final String newConstantValue,
    final String className,
    final ExpressionType expressionType) throws InvalidExpressionException
{ final LeftOperand leftOperand = new LeftOperandBuilder().createNewInstance().setName(dataInstanceName).done();
    final Expression expression = new ExpressionBuilder().createNewInstance(dataInstanceName).setContent(newConstantValue).setExpressionType(expressionType.name()).setReturnType(className).done();
    final Operation operation;
    operation = new OperationBuilder().createNewInstance().setOperator("=").setLeftOperand(leftOperand).setType(OperatorType.ASSIGNMENT).setRightOperand(expression).done();
    return operation;}

Set variables of any type and start a process instance

In this example, createCase takes the process definition name, the process version, a map of variable names and objects, and the session identifier. The startProcess method, which creates the process instance, takes a list of operations, not a map of variables, so the map must be converted into a list of operations that will set the values of the variables in the process instance. For each variable in turn, the example builds an expression that assigns the value to the variable to the object supplied in the map, specifying the data type by identifying the class of the object. These expressions are concatenated into a list of operations, which is used to initialize the variables when the process instance is created.

public void createCase(String processDefinitionName, String processVersion, Map<String, Object> variables, ProcessAPI processAPI) {

    try {

            long processDefinitionId = processAPI.getProcessDefinitionId(processDefinitionName, processVersion);
            // ----- create list of operations -----
            List<Operation> listOperations = new ArrayList<Operation>();
            Map<String, Serializable> listVariablesSerializable = new HashMap<String, Serializable>();

            for (String variableName : variables.keySet()) {

                if (variables.get(variableName) == null || (!(variables.get(variableName) instanceof Serializable)))
                    continue;
            Object value = variables.get(variableName);
            Serializable valueSerializable = (Serializable) value;

            variableName = variableName.toLowerCase();
            Expression expr = new ExpressionBuilder().createExpression(variableName, variableName, value.getClass().getName(), ExpressionType.TYPE_INPUT);
            Operation op = new OperationBuilder().createSetDataOperation(variableName, expr);
            listOperations.add(op);
            listVariablesSerializable.put(variableName, valueSerializable);
            }

            // ----- start process instance -----
            processAPI.startProcess(processDefinitionId, listOperations, listVariablesSerializable);

            // System.out.println("*** End Create Case ****");

        } catch (Exception e) {
              e.printStackTrace();
    }
}

Create a map of variables and values and start a process instance

Version 6.1 of Bonita BPM introduces a new method for starting a case of process and setting the variables.

Create a map specifying the values of the variables required to start a case, then pass it to the instantiateProcess method, as shown in the following example:

public void instantiateProcess(String processDefinitionName, String processVersion, Map<String, Serializable> variables, APISession apiSession)  {
    try {
        ProcessAPI processAPI = TenantAPIAccessor.getProcessAPI(apiSession);
        long processId = processAPI.getProcessDefinitionId(processDefinitionName, processVersion);
        processAPI.startProcess(processId, variables);
    } catch (Exception e) {
        e.printStackTrace();
    }
}

For a running process instance, set the value of a custom data type variable

To update the value of a variable with a custom data type, you need to call a Groovy script expression that returns the new value of the variable., as shown in the example below:

final ProcessAPI processAPI = TenantAPIAccessor.getProcessAPI(session);
final String dataInstanceName = "acase";
final long activityInstanceId = 2;

final LeftOperand leftOperand = new LeftOperandBuilder().createNewInstance().setName(dataInstanceName)
                .setType(LeftOperand.TYPE_DATA).done();
final Expression expression = new ExpressionBuilder().createGroovyScriptExpression("updateDataCaseTest",
                "new com.bonitasoft.support.Case(\"title\", \"description\")",
                Case.class.getName());
final Operation operation = new OperationBuilder().createNewInstance().setOperator("=").setLeftOperand(leftOperand).setType(OperatorType.ASSIGNMENT)
                .setRightOperand(expression).done();

final List<Operation> operations = new ArrayList<Operation>();
operations.add(operation);
processAPI.updateActivityInstanceVariables(operations, activityInstanceId, null);

Note: this applies starting from version 6.3.4.

Another method, updateActivityDataInstance also exists. However, this cannot be used with custom data types if you are using a remote connection, because the data type definition is not present in the Engine.

Execute a task

This example shows you how to execute a task.

The task is specified by an activityInstanceID.

final ProcessAPI processAPI = TenantAPIAccessor.getProcessAPI(apiSession);
processAPI.executeFlowNode(activityInstanceID);

List the processes I started

This example shows you how to list the open process instances started by the current user.

The search options specify that a maximum of 100 items are listed, starting with the first one.

final ProcessAPI processAPI = TenantAPIAccessor.getProcessAPI(apiSession);
final SearchOptionsBuilder builder = new SearchOptionsBuilder(0, 100);
builder.filter(ProcessInstanceSearchDescriptor.STARTED_BY, apiSession().getUserId());
final SearchResult<ProcessInstance> processInstanceResults = processAPI.searchOpenProcessInstances(builder.done());

List the open instances of a process

This example shows you how to list the open instances of a specified process.

The process is specified by the processDefinitonID. The search options specify that a maximum of 100 items are listed, starting with the first one.

final ProcessAPI processAPI = TenantAPIAccessor.getProcessAPI(apiSession);
final SearchOptionsBuilder builder = new SearchOptionsBuilder(0, 100);
builder.filter(ProcessInstanceSearchDescriptor.PROCESS_DEFINITION_ID, processDefinitionID);
final SearchResult<ProcessInstance> processInstanceResults = processAPI.searchOpenProcessInstances(builder.done());

Get the history for a case

This example shows how to get the history for a case.

A case is a process instance. To get the history, you retrieve the archived process instance, which is specified by processInstanceID.

final ProcessAPI processAPI = TenantAPIAccessor.getProcessAPI(apiSession);
final ArchivedProcessInstance archivedProcessInstance = processAPI.getArchivedProcessInstance(processInstanceID);

Query archived process instances

This example shows how to get a list of archived process instances that meet a specified filter.

Note that this type of query is only possible with archived process instances.

final ProcessAPI processAPI = TenantAPIAccessor.getProcessAPI(apiSession);
final SearchOptionsBuilder builder = new SearchOptionsBuilder(0, 100);
builder.filter(ArchivedProcessInstancesSearchDescriptor.<attribute to filter on>, <attribute value>);
final SearchResult<ArchivedProcessInstance> archivedProcessInstanceResults = processAPI.searchArchivedProcessInstances(builder.done());

Stop a process instance

This example shows how to stop (or cancel) an active process instance.

No further activities in this process instance are started.

final ProcessAPI processAPI = TenantAPIAccessor.getProcessAPI(apiSession);
processAPI.cancelProcessInstance(processInstanceID);

Deploy a process

This example will show you how to use the Bonita BPM Engine API to deploy and enable a process.

The process can be in a business archive (.bar) file or can be built using the processDefinitionBuilder.

Deploy and enable a process from a bar file

First create a business archive from the bar file. In this example, the bar file is /deploy/travelRequest. The process is deployed and enabled in a single step.

// create a business archive
final BusinessArchive businessArchive = BusinessArchiveFactory.readBusinessArchive(new File("/deploy/travelRequest"));

Now deploy and enable the process:

// deploy and enable the process
final ProcessDefinition processDefinition = getProcessAPI().deployAndEnableProcess(businessArchive);

Deploy and enable a process from the processDefinitionBuilder

In this example, there are three steps: deploy the process, map the actor, and enable the process.

First deploy the process:

// deploy the process
final ProcessDefinition processDefinition = processAPI.deploy(processDefinitionBuilder.done());
System.out.println("A new process was deployed with id: " + processDefinition.getId());

Once the process is deployed, it's necessary to map the actors defined in the process to existing users in the database before enabling the process. In this example, the actor defined in the process will be mapped to the current logged in user, whose id is available in the session (attention, this user cannot be the technical user):

// map the actor "delivery" to the current logged in user
final List<ActorInstance> actors = processAPI.getActors(processDefinition.getId(), 0, 1, ActorCriterion.NAME_ASC);
processAPI.addUserToActor(actors.get(0).getId(), session.getUserId());

At this point, the process is deployed but not enabled. This means that no instances of this process can be started. To enable the process, call the method enableProcess:

// enable the process
processAPI.enableProcess(processDefinition.getId());
System.out.println("A new process was enabled: " + processDefinition.getId());

Get the process design definition

This example shows how to retrieve the definition of a deployed process.

//Create a process definition
final ProcessDefinitionBuilder processBuilder = new ProcessDefinitionBuilder().createNewInstance("name", "1.0");
processBuilder.addDescription("description");
processBuilder.addAutomaticTask("AutomaticTask");
       
//Deploy and enable the process
final ProcessDefinition processDefinition = getProcessAPI().deploy(
        new BusinessArchiveBuilder().createNewBusinessArchive().setProcessDefinition(processBuilder.done()).done());
getProcessAPI().enableProcess(processDefinition.getId());

//Get the design process definition
final DesignProcessDefinition resultDesignProcessDefinition = getProcessAPI().getDesignProcessDefinition(processDefinition.getId());

Undeploy a process

This example shows you how to undeploy a process.

A process is undeployed by deleting the processDefinition, specified by a processDefinitionID.

After the process is undeployed, no new instance can be started. Existing instances continue to completion.

final ProcessAPI processAPI = TenantAPIAccessor.getProcessAPI(apiSession);
processAPI.deleteProcessDefinition(processDefinitionId)
Get the PDF version
Last update on Jan, 21 2016