Package org.jbpm.services.api.admin

## Interface ProcessInstanceAdminService

- All Known Implementing Classes:
    `ProcessInstanceAdminServiceImpl`

      public interface ProcessInstanceAdminService

  Admin Service - provides runtime modifications capabilities for active process instances.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `acknowledgeError​(String... errorId)` | Acknowledge given error that it was reviewed and understood
    `void` | `cancelNodeInstance​(long processInstanceId, long nodeInstanceId)` | Cancels node instance with given id within given process instance.
    `Collection<NodeInstanceDesc>` | `getActiveNodeInstances​(long processInstanceId)` | Returns all active node instances in given process instance;
    `org.kie.internal.runtime.error.ExecutionError` | `getError​(String errorId)` | Returns execution error identified by given error id
    `List<org.kie.internal.runtime.error.ExecutionError>` | `getErrors​(boolean includeAcknowledged, org.kie.api.runtime.query.QueryContext queryContext)` | Returns all execution errors regardless of their type
    `List<org.kie.internal.runtime.error.ExecutionError>` | `getErrorsByDeploymentId​(String deploymentId, boolean includeAcknowledged, org.kie.api.runtime.query.QueryContext queryContext)` | Returns all execution errors for a given deployment regardless of their type
    `List<org.kie.internal.runtime.error.ExecutionError>` | `getErrorsByProcessId​(String deploymentId, String processId, boolean includeAcknowledged, org.kie.api.runtime.query.QueryContext queryContext)` | Returns execution errors for given process id and deployment id
    `List<org.kie.internal.runtime.error.ExecutionError>` | `getErrorsByProcessInstanceId​(long processInstanceId, boolean includeAcknowledged, org.kie.api.runtime.query.QueryContext queryContext)` | Returns execution errors for given process instance id
    `List<org.kie.internal.runtime.error.ExecutionError>` | `getErrorsByProcessInstanceId​(long processInstanceId, String nodeName, boolean includeAcknowledged, org.kie.api.runtime.query.QueryContext queryContext)` | Returns execution errors for given process instance id and node
    `Collection<ProcessNode>` | `getProcessNodes​(long processInstanceId)` | Returns all process nodes found in given process instance.
    `Collection<TimerInstance>` | `getTimerInstances​(long processInstanceId)` | Returns active timers for given process instance.
    `void` | `retriggerNodeInstance​(long processInstanceId, long nodeInstanceId)` | Retriggers (which includes cancel) node instance given with node instance id within process instance.
    `void` | `triggerNode​(long processInstanceId, long nodeId)` | Triggers node to create new node instance with node id within process instance.
    `void` | `updateTimer​(long processInstanceId, long timerId, long delay, long period, int repeatLimit)` | Updates active timer identified by timer id with delay that is given in seconds.
    `void` | `updateTimerRelative​(long processInstanceId, long timerId, long delay, long period, int repeatLimit)` | Updates active timer identified by timer id with delay that is given in seconds and is relative to current time.

- - ### Method Detail

    - #### getProcessNodes

          Collection<ProcessNode> getProcessNodes​(long processInstanceId)
                                           throws ProcessInstanceNotFoundException

      Returns all process nodes found in given process instance.
      Parameters:
        `processInstanceId` - unique id of process instance
      Returns:
        list of process nodes in process instance
      Throws:
        `ProcessInstanceNotFoundException` - in case process instance id with given id was not found

    - #### cancelNodeInstance

          void cancelNodeInstance​(long processInstanceId,
                                  long nodeInstanceId)
                           throws NodeInstanceNotFoundException,
                                  ProcessInstanceNotFoundException

      Cancels node instance with given id within given process instance.
      Parameters:
        `processInstanceId` - unique id of process instance
        `nodeInstanceId` - node instance id within given process instance to be canceled
      Throws:
        `NodeInstanceNotFoundException` - in case node instance with given id is not active
        `ProcessInstanceNotFoundException` - in case process instance id with given id was not found

    - #### retriggerNodeInstance

          void retriggerNodeInstance​(long processInstanceId,
                                     long nodeInstanceId)
                              throws NodeInstanceNotFoundException,
                                     ProcessInstanceNotFoundException

      Retriggers (which includes cancel) node instance given with node instance id within process instance.
      Parameters:
        `processInstanceId` - unique id of process instance
        `nodeInstanceId` - node instance id within given process instance to be retriggered
      Throws:
        `NodeInstanceNotFoundException` - in case node instance with given id is not active
        `ProcessInstanceNotFoundException` - in case process instance id with given id was not found

    - #### getActiveNodeInstances

          Collection<NodeInstanceDesc> getActiveNodeInstances​(long processInstanceId)
                                                       throws ProcessInstanceNotFoundException

      Returns all active node instances in given process instance;
      Parameters:
        `processInstanceId` - unique id of process instance
      Returns:
        found active node instances
      Throws:
        `ProcessInstanceNotFoundException` - in case process instance id with given id was not found

    - #### updateTimer

          void updateTimer​(long processInstanceId,
                           long timerId,
                           long delay,
                           long period,
                           int repeatLimit)
                    throws NodeInstanceNotFoundException,
                           ProcessInstanceNotFoundException

      Updates active timer identified by timer id with delay that is given in seconds. Delay is absolute meaning it is as it would be set when timer was created.
      Example:
      In case timer was initially created with delay of 1 hour and after 30 min we decide to update it to 2 hours it will then expire in 1,5 hour from the time it was updated.
      Parameters:
        `processInstanceId` - unique id of process instance
        `timerId` - timer id that should be updated
        `delay` - absolute delay in seconds
        `period` - in case of repeatable timer how often it should repeat in milliseconds - if not applicable should be set to -1
        `repeatLimit` - in case of repeatable timer how many times it should trigger - if not applicable should be set to -1
      Throws:
        `NodeInstanceNotFoundException` - in case node instance with given id is not active
        `ProcessInstanceNotFoundException` - in case process instance id with given id was not found

    - #### updateTimerRelative

          void updateTimerRelative​(long processInstanceId,
                                   long timerId,
                                   long delay,
                                   long period,
                                   int repeatLimit)
                            throws NodeInstanceNotFoundException,
                                   ProcessInstanceNotFoundException

      Updates active timer identified by timer id with delay that is given in seconds and is relative to current time.
      Example:
      In case timer was initially created with delay of 1 hour and after 30 min we decide to update it to 2 hours it will then expire in 2 hours from the time it was updated.
      Parameters:
        `processInstanceId` - unique id of process instance
        `timerId` - timer id that should be updated
        `delay` - absolute delay in seconds
        `period` - in case of repeatable timer how often it should repeat in milliseconds - if not applicable should be set to -1
        `repeatLimit` - in case of repeatable timer how many times it should trigger - if not applicable should be set to -1
      Throws:
        `NodeInstanceNotFoundException` - in case node instance with given id is not active
        `ProcessInstanceNotFoundException` - in case process instance id with given id was not found

    - #### getTimerInstances

          Collection<TimerInstance> getTimerInstances​(long processInstanceId)
                                               throws ProcessInstanceNotFoundException

      Returns active timers for given process instance.
      Parameters:
        `processInstanceId` - unique id of process instance
      Returns:
        list of timer found for given process instance
      Throws:
        `ProcessInstanceNotFoundException` - in case process instance id with given id was not found

    - #### triggerNode

          void triggerNode​(long processInstanceId,
                           long nodeId)
                    throws NodeNotFoundException,
                           ProcessInstanceNotFoundException

      Triggers node to create new node instance with node id within process instance. This results in new instance of a task within process instance.
      Parameters:
        `processInstanceId` - unique id of process instance
        `nodeId` - node id to be triggered (new instance of that node to be created)
      Throws:
        `NodeNotFoundException` - in case node with given id does not exist in process instance
        `ProcessInstanceNotFoundException` - in case process instance id with given id was not found

    - #### acknowledgeError

          void acknowledgeError​(String... errorId)
                         throws ExecutionErrorNotFoundException

      Acknowledge given error that it was reviewed and understood
      Parameters:
        `errorId` - unique id of the error
      Throws:
        `ExecutionErrorNotFoundException` - thrown when there is no unacknowledged error with that id

    - #### getError

          org.kie.internal.runtime.error.ExecutionError getError​(String errorId)
                                                          throws ExecutionErrorNotFoundException

      Returns execution error identified by given error id
      Parameters:
        `errorId` - unique id of the error
      Returns:
        returns execution error instance
      Throws:
        `ExecutionErrorNotFoundException` - is thrown in case no error was found for given error id

    - #### getErrorsByProcessId

          List<org.kie.internal.runtime.error.ExecutionError> getErrorsByProcessId​(String deploymentId,
                                                                                   String processId,
                                                                                   boolean includeAcknowledged,
                                                                                   org.kie.api.runtime.query.QueryContext queryContext)

      Returns execution errors for given process id and deployment id
      Parameters:
        `deploymentId` - deployment id that contains given process
        `processId` - process id of the process
        `includeAcknowledged` - indicates whether to include acknowledged errors or not
        `queryContext` - control parameters for pagination
      Returns:
        list of found errors

    - #### getErrorsByProcessInstanceId

          List<org.kie.internal.runtime.error.ExecutionError> getErrorsByProcessInstanceId​(long processInstanceId,
                                                                                           boolean includeAcknowledged,
                                                                                           org.kie.api.runtime.query.QueryContext queryContext)

      Returns execution errors for given process instance id
      Parameters:
        `processInstanceId` - process instance id of the process
        `includeAcknowledged` - indicates whether to include acknowledged errors or not
        `queryContext` - control parameters for pagination
      Returns:
        list of found errors

    - #### getErrorsByProcessInstanceId

          List<org.kie.internal.runtime.error.ExecutionError> getErrorsByProcessInstanceId​(long processInstanceId,
                                                                                           String nodeName,
                                                                                           boolean includeAcknowledged,
                                                                                           org.kie.api.runtime.query.QueryContext queryContext)

      Returns execution errors for given process instance id and node
      Parameters:
        `processInstanceId` - process instance id of the process
        `nodeName` - name of the node that error should be found for
        `includeAcknowledged` - indicates whether to include acknowledged errors or not
        `queryContext` - control parameters for pagination
      Returns:
        list of found errors

    - #### getErrors

          List<org.kie.internal.runtime.error.ExecutionError> getErrors​(boolean includeAcknowledged,
                                                                        org.kie.api.runtime.query.QueryContext queryContext)

      Returns all execution errors regardless of their type
      Parameters:
        `includeAcknowledged` - indicates whether to include acknowledged errors or not
        `queryContext` - control parameters for pagination
      Returns:
        list of found errors

    - #### getErrorsByDeploymentId

          List<org.kie.internal.runtime.error.ExecutionError> getErrorsByDeploymentId​(String deploymentId,
                                                                                      boolean includeAcknowledged,
                                                                                      org.kie.api.runtime.query.QueryContext queryContext)

      Returns all execution errors for a given deployment regardless of their type
      Parameters:
        `deploymentId` - deployment id that contains the errors
        `includeAcknowledged` - indicates whether to include acknowledged errors or not
        `queryContext` - control parameters for pagination
      Returns:
        list of found errors