Package org.flowable.engine.runtime

# Interface ProcessInstanceBuilder

public interface ProcessInstanceBuilder
Helper for starting new ProcessInstance. An instance can be obtained through `RuntimeService.createProcessInstanceBuilder()`. processDefinitionId or processDefinitionKey should be set before calling `start()` to start a process instance.

Author:
  Bassam Al-Sarori, Joram Barrez

- ## Method Summary

  Modifier and Type
  Method
  Description
  `ProcessInstanceBuilder`
  `assignee(String userId)`
  Set the assignee of the process instance to be created to the given user id.
  `ProcessInstanceBuilder`
  `businessKey(String businessKey)`
  Set the businessKey of process instance
  `ProcessInstanceBuilder`
  `businessStatus(String businessStatus)`
  Set the businessStatus of process instance
  `ProcessInstanceBuilder`
  `callbackId(String callbackId)`
  Sets the callback identifier of the process instance.
  `ProcessInstanceBuilder`
  `callbackType(String callbackType)`
  Sets the callback type of the process instance.
  `ProcessInstanceBuilder`
  `fallbackToDefaultTenant()`
  Use default tenant as a fallback in the case when process definition was not found by key and tenant id
  `ProcessInstanceBuilder`
  `formVariables(Map<String,Object> formVariables, org.flowable.form.api.FormInfo formInfo, String formOutcome)`
  Start the process instance with the given form variables from the given `formInfo`.
  `ProcessInstanceBuilder`
  `messageName(String messageName)`
  Set the message name that needs to be used to look up the process definition that needs to be used to start the process instance.
  `ProcessInstanceBuilder`
  `name(String processInstanceName)`
  Set the name of process instance
  `ProcessInstanceBuilder`
  `outcome(String outcome)`
  Allows to set an outcome for a start form.
  `ProcessInstanceBuilder`
  `overrideProcessDefinitionTenantId(String tenantId)`
  Indicator to override the tenant id of the process definition with the provided value.
  `ProcessInstanceBuilder`
  `owner(String userId)`
  Set the owner of the process instance to be created to the given user id.
  `ProcessInstanceBuilder`
  `predefineProcessInstanceId(String processInstanceId)`
  When starting a process instance from the CMMN engine process task, the process instance id needs to be known beforehand to store entity links and callback references before the process instance is started.
  `ProcessInstanceBuilder`
  `processDefinitionId(String processDefinitionId)`
  Set the id of the process definition
  `ProcessInstanceBuilder`
  `processDefinitionKey(String processDefinitionKey)`
  Set the key of the process definition, latest version of the process definition with the given key.
  `ProcessInstanceBuilder`
  `processDefinitionParentDeploymentId(String parentDeploymentId)`
  When looking up for a process definition by key it would first lookup for a process definition within the given parent deployment.
  `ProcessInstanceBuilder`
  `referenceId(String referenceId)`
  Sets the reference identifier of the process instance.
  `ProcessInstanceBuilder`
  `referenceType(String referenceType)`
  Sets the reference type of the process instance.
  `ProcessInstanceBuilder`
  `stageInstanceId(String stageInstanceId)`
  Set the optional instance id of the stage this process instance belongs to, if it runs in the context of a CMMN case.
  `ProcessInstance`
  `start()`
  Start the process instance
  `ProcessInstance`
  `startAsync()`
  Start the process instance asynchronously
  `ProcessInstanceBuilder`
  `startEventId(String startEventId)`
  Set the start event in case of an event registry start event that is triggered to start the process instance.
  `ProcessInstanceBuilder`
  `startFormVariable(String variableName, Object value)`
  Adds one variable from a start form to the process instance.
  `ProcessInstanceBuilder`
  `startFormVariables(Map<String,Object> startFormVariables)`
  Adds variables from a start form to the process instance.
  `ProcessInstanceBuilder`
  `tenantId(String tenantId)`
  Set the tenantId of to lookup the process definition
  `ProcessInstanceBuilder`
  `transientVariable(String variableName, Object value)`
  Adds a transient variable to the process instance
  `ProcessInstanceBuilder`
  `transientVariables(Map<String,Object> transientVariables)`
  Sets the transient variables
  `ProcessInstanceBuilder`
  `variable(String variableName, Object value)`
  Adds a variable to the process instance
  `ProcessInstanceBuilder`
  `variables(Map<String,Object> variables)`
  Sets the process variables

- ## Method Details

  - ### processDefinitionId

    ProcessInstanceBuilder processDefinitionId(String processDefinitionId)
    Set the id of the process definition

  - ### processDefinitionKey

    ProcessInstanceBuilder processDefinitionKey(String processDefinitionKey)
    Set the key of the process definition, latest version of the process definition with the given key. If processDefinitionId was set this will be ignored

  - ### processDefinitionParentDeploymentId

    ProcessInstanceBuilder processDefinitionParentDeploymentId(String parentDeploymentId)
    When looking up for a process definition by key it would first lookup for a process definition within the given parent deployment. Then it would fallback to the latest process definition with the given key.

    This is typically needed when the ProcessInstanceBuilder is called for example from the case engine to start a process instance and it needs to look up the process definition in the same deployment as the case.

  - ### messageName

    ProcessInstanceBuilder messageName(String messageName)
    Set the message name that needs to be used to look up the process definition that needs to be used to start the process instance.

  - ### startEventId

    ProcessInstanceBuilder startEventId(String startEventId)
    Set the start event in case of an event registry start event that is triggered to start the process instance.

  - ### name

    ProcessInstanceBuilder name(String processInstanceName)
    Set the name of process instance

  - ### businessKey

    ProcessInstanceBuilder businessKey(String businessKey)
    Set the businessKey of process instance

  - ### businessStatus

    ProcessInstanceBuilder businessStatus(String businessStatus)
    Set the businessStatus of process instance

  - ### callbackId

    ProcessInstanceBuilder callbackId(String callbackId)
    Sets the callback identifier of the process instance.

  - ### callbackType

    ProcessInstanceBuilder callbackType(String callbackType)
    Sets the callback type of the process instance.

  - ### referenceId

    ProcessInstanceBuilder referenceId(String referenceId)
    Sets the reference identifier of the process instance.

  - ### referenceType

    ProcessInstanceBuilder referenceType(String referenceType)
    Sets the reference type of the process instance.

  - ### stageInstanceId

    ProcessInstanceBuilder stageInstanceId(String stageInstanceId)
    Set the optional instance id of the stage this process instance belongs to, if it runs in the context of a CMMN case.

  - ### tenantId

    ProcessInstanceBuilder tenantId(String tenantId)
    Set the tenantId of to lookup the process definition

  - ### overrideProcessDefinitionTenantId

    ProcessInstanceBuilder overrideProcessDefinitionTenantId(String tenantId)
    Indicator to override the tenant id of the process definition with the provided value. The tenantId to lookup the process definition should still be provided if needed.

  - ### predefineProcessInstanceId

    ProcessInstanceBuilder predefineProcessInstanceId(String processInstanceId)
    When starting a process instance from the CMMN engine process task, the process instance id needs to be known beforehand to store entity links and callback references before the process instance is started.

  - ### owner

    ProcessInstanceBuilder owner(String userId)
    Set the owner of the process instance to be created to the given user id.
    Parameters:
      `userId` - the id of the user to become the owner of the process instance
    Returns:
      the process instance builder for method chaining

  - ### assignee

    ProcessInstanceBuilder assignee(String userId)
    Set the assignee of the process instance to be created to the given user id.
    Parameters:
      `userId` - the id of the user to become the owner of the process instance
    Returns:
      the process instance builder for method chaining

  - ### variables

    ProcessInstanceBuilder variables(Map<String,Object> variables)
    Sets the process variables

  - ### variable

    ProcessInstanceBuilder variable(String variableName, Object value)
    Adds a variable to the process instance

  - ### transientVariables

    ProcessInstanceBuilder transientVariables(Map<String,Object> transientVariables)
    Sets the transient variables

  - ### transientVariable

    ProcessInstanceBuilder transientVariable(String variableName, Object value)
    Adds a transient variable to the process instance

  - ### startFormVariables

    ProcessInstanceBuilder startFormVariables(Map<String,Object> startFormVariables)
    Adds variables from a start form to the process instance.

  - ### startFormVariable

    ProcessInstanceBuilder startFormVariable(String variableName, Object value)
    Adds one variable from a start form to the process instance.

  - ### outcome

    ProcessInstanceBuilder outcome(String outcome)
    Allows to set an outcome for a start form.

  - ### formVariables

    ProcessInstanceBuilder formVariables(Map<String,Object> formVariables, org.flowable.form.api.FormInfo formInfo, String formOutcome)
    Start the process instance with the given form variables from the given `formInfo`. This is different than `startFormVariables(Map)` and it can be used in addition to that.

  - ### fallbackToDefaultTenant

    ProcessInstanceBuilder fallbackToDefaultTenant()
    Use default tenant as a fallback in the case when process definition was not found by key and tenant id

  - ### start

    ProcessInstance start()
    Start the process instance
    Throws:
      `FlowableIllegalArgumentException` - if processDefinitionKey and processDefinitionId are null
      `FlowableObjectNotFoundException` - when no process definition is deployed with the given processDefinitionKey or processDefinitionId

  - ### startAsync

    ProcessInstance startAsync()
    Start the process instance asynchronously
    Throws:
      `FlowableIllegalArgumentException` - if processDefinitionKey and processDefinitionId are null
      `FlowableObjectNotFoundException` - when no process definition is deployed with the given processDefinitionKey or processDefinitionId