Relocating Activities

The Stardust WorkflowService provides two methods to perform relocation of activities. One for finding the target activity and one to perform the transition.

• Finding the Target Activity
• Performing the Transition
• Relocating and Switching to a new Version

Finding the Target Activity

Method getAdHocTransitionTargets retrieves the possible targets for forward transitions starting from the specified activity instance.

List<TransitionTarget> getAdHocTransitionTargets(long activityInstanceOid, TransitionOptions options, ScanDirection direction)
    throws ObjectNotFoundException;

The method returns a list of possible transition targets. Parameters are the following:

• activityInstanceOid: the OID of the activity instance from where the transition will be performed.
• options: options for searching possible targets for relocation transitions. The options are described in section Transition Options.
• direction: the scanning direction, see Scan Direction.

An ObjectNotFoundException is thrown in case there is no activity instance with the specified OID.

Transition Options

The transition options are a combination of Boolean values to determine if relocation transitions inside sub processes and out of them is allowed.

• allowTransitionOutOfSubprocesses: allows relocation transition out of subprocesses.
• allowTransitionIntoSubprocesses: allows relocation transitions inside subprocesses.
• allowLoops: allows relocation transitions in loops.

For details on these options refer to TransitionOptions. In case no options are specified (null), TransitionOptions.DEFAULT will be used, which means false values for all three options.

Scan Direction

Possible scan directions are:

• FORWARD
• BACKWARD
• BOTH

For more details on the ScanDirection enumeration type refer to ScanDirection.

FORWARD

The order of the transition targets in the list is based on the flow of activity graph.

BACKWARD

In case the scan direction is BACKWARD, the search is performed in the following way:

• If the process is the root process, the search ends here.
• If the process is a subprocess, go to subprocess activity in the parent process that started the subprocess and do backward searching from that activity.

The order of the transition targets in the list is based on the reversed flow of activity graph.

BOTH

If the scan direction is BOTH, the search order is to search for transition targets for ScanDirection.FORWARD first, then for ScanDirection.BACKWARD next.

Search Rules

The following rules apply to the search mechanism apart from the given transition directions:

1. When encountering a subprocess activity, the method searches transition targets into the subprocess first, for example a recursive search.
2. When encountering the end of a process with ScanDirection.FORWARD:
   • If the process is the root process, the search ends here.
   • If the process is a subprocess, the search goes to the subprocess activity in the parent process that started the subprocess and does forward searching from that activity.
3. When encountering the start of a process with ScanDirection.BACKWARD:
   • If the process is the root process, the search ends here.
   • If the process is a subprocess, the search goes to the subprocess activity in the parent process that started the subprocess and does backward searching from that activity.
4. When encountering an XOR Split/Join gateway:
   1. The method searches the path with the activity whose activity ID is ordered first alphabetically and searches targets along that path.
   2. After that, it searches targets for the second path with the second (alphabetically ordered) activity.
   3. After all paths are searched and if an XOR Join gateway exists, searching targets form the activity right after the XOR Join gateway are resumed.

Performing the Transition

Method performAdHocTransition performs the transition from the specified activity instance to the specified target.

ActivityInstance performAdHocTransition(long activityInstanceOid, TransitionTarget target, boolean complete)
    throws IllegalOperationException, ObjectNotFoundException, AccessForbiddenException;

The method returns the activity instance from which the transition was performed. Parameters are the following:

• activityInstanceOid: the OID of the activity instance from where the transition will be performed.
• target: the transition target of type TransitionTarget.
• complete: determines if the activity instance should be completed or aborted.
  • true: the activity instance specified should be completed.
    • the operation is similar with WorkflowService.complete()
    • activity will be aborted, as well as all involved subprocesses
    • modeled transitions are not followed. Instead the execution continues with the specified target as if a transition between the source and the target was modeled.
    • if the target is in a different process, the current subprocess must be in a state to be able for completion.
    • if the transition involves multiple levels of subprocesses, all of them must be in a state to be able for completion.
  • false: the activity as well as all involved subprocesses should be aborted. The operation is similar with WorkflowService.abort().

An IllegalOperationException occurs if the transition could not be performed because of one of the following reasons:

• the specified TransitionTarget does not originate from the specified activity instance
• the activity instance was already terminated
• the process instance containing the activity instance has more than one active activity instance.

An ObjectNotFoundException is thrown in case there is no activity instance with the specified OID.

Security

To use this method, you need the permission to perform this activity, otherwise an AccessForbiddenException occurs. Additionally, the following security restrictions apply:

• If parameter complete is true:
  • the user must qualify as OWNER of the source activity
  • if the source activity is interactive, the state must be either application or hibernated
  • an administrator is allowed to relocate from a suspended interactive activity
  • if the activity is non-interactive, the user must be an administrator and the state must be either hibernated or interrupted
• If parameter complete is false, the user must have the right to abort the top most activity instance involved in the transition.

Relocating and Switching to a new Version

To switch between versions of a process definition and perform relocation in the same step, you can use the generalized implementation of the spawnPeerProcessInstance method, which is described in section Aborting and Starting a Process of chapter Workflow Processing to Abort and Start Subprocess. In that case, use the method with specified spawn options:

   public ProcessInstance spawnPeerProcessInstance(long processInstanceOid,
         String spawnProcessID, SpawnOptions options) throws IllegalOperationException,
         ObjectNotFoundException, InvalidArgumentException;

Hereby the SpawnOptions parameter specifies options that controls how the spawning operation has to be performed. Refer to the JavaDoc of SpawnOptions for details.

The spawn options contain the following parameters:

• startActivity - the activity from which the spawned process instance should start. If null, the spawned process instance will start from the default start activity.
• abortProcessInstance - The processing behavior of the originating process instance. Value true determines to abort the originating process instance. Currently only a value of true is accepted for processing.
• comment - comment describing the operation. May be null.
• dataCopyOptions - instructions on how the data should be transferred from the originating process instance to the spawned process instance. If null, then the DataCopyOptions with the default values are used (true, null, null, true). For details on the DataCopyOptions type refer to the DataCopyOptions class JavaDoc. Data copy options are the following:
  • copyAllData - if true, it will attempt to copy all data from the source process instance to the target process instance.
  • dataTranslationTable - a Map indicating that the values for the specified data should be taken from another data object. The keys are the IDs of the target data and the values are the IDs of the source data objects.
  • replacementTable - a Map that specifies concrete values for target data. The keys are the IDs of the target data.
  • useHeuristics - if true, the engine will attempt to auto determine which data must be copied by investigating the data mappings and data paths of the target process instance.

Data Copy Restrictions

Using the method described above, the following restricted data copying functionality applies:

1. Primitives with the same Id and compatible types have to be there from the existing switch functionality.
2. A deep copy of structured data (standalone or as document metadata) is performed. Deep copy copies all fields with matching XPaths and types.
3. No copy of Java type data is performed.

For details on the data copy semantics for relocating activities, refer to section Data Copy Semantics of chapter Relocation of Activities.

Example Use Cases

The following examples demonstrate when to use the spawnPeerProcessInstance method and in which cases a performTransition call is needed additionally.

Relocating an activity by aborting and starting

In this example we have a process definition PD1 with a manual activity M2, which we like to abort and start in a new process instance version of PD1.

Figure: Relocation by Spawning Example

To jump from manual activity M2 in process definition PD1 with version 1 to manual activity M2 in process definition PD1 with version 2, you need a single call of the spawnPeerProcessInstance method.

   ProcessInstance orgProcess = ws.startProcess("PD1", null, true);

   // Spawn process instance (Spawned process starts from activity M2)
   DataCopyOptions copyOption = new DataCopyOptions(true, null, null, false);
      
   SpawnOptions options = new SpawnOptions("M2", true, "No comment", copyOption);
      
   ProcessInstance spawnedProcInst
      = wfService.spawnPeerProcessInstance(orgProcess.getOID(), "PD1", options);

Relocating an activity by aborting and starting to a process instance with XOR split and join

The following example has a process definition PD1 with a manual activity M2, which we like to abort and start in a new process instance version of PD1, where an XOR split and join transition is used.

Figure: Relocation by Spawning Example

To jump from manual activity M2 in process definition PD1 with version 1 to manual activity M2 in process definition PD1 with version 2, you also need a single call of the spawnPeerProcessInstance method. Note that in this case, only root process instances can be aborted and destination activities must only be on root processes.

Relocating an activity by aborting and starting from a process instance with XOR split and join

If the source activity M3 is in process definition PD1 with version 1 inside an XOR transition, and we like to jump to target activity M2 in process instance of PD1 with version 2, having no XOR transition, this is also possible with a single call of the spawnPeerProcessInstance method.

Figure: Relocation by Spawning Example

Relocating an activity by aborting and starting to a subprocess activity in another process instance version

Figure: Relocation by Spawning Example

In this case, two API calls are needed:

1. A call to spawnPeerProcessInstance to jump from manual activity M1 in process definition PD1 version 1 to manual activity M1 in process definition PD1 version 2.
2. A performTransition call to jump from manual activity M1 in process definition PD1 version 2 to M22 in subprocess PD2 version 2.

Relocating an activity from a subprocess by aborting and starting to an activity in another process instance version

Figure: Relocation by Spawning Example

Two API calls are also needed in this case:

1. A performTransition call to jump from manual activity M21 in subprocess PD2 version 1 to manual activity M3 in process PD1 version 1.
2. A call to spawnPeerProcessInstance to jump from manual activity M3 in process definition PD1 version 1 to manual activity M3 in process definition PD1 version 2.