Package com.almworks.jira.structure.api.effector.process

Interface EffectorProcessManager

@PublicApi public interface EffectorProcessManager
Manages Effector preview, effect application, and undo background processes.

  • Method Details

    • validateStartProcess

      void validateStartProcess(@NotNull List<EffectorInstance> effectorInstances, long structureId) throws StructureException
      Checks whether an effector process can be started, as if by calling startProcess(List, long, boolean), without actually starting it. Returns normally if such a process can be started, throws a StructureException otherwise.
      Parameters:
      effectorInstances - effector instances to run, the scope is defined by the structure ID and position
      structureId - ID of the structure for which effects are calculated.
      Throws:
      StructureException - if the process cannot be started, e.g. due to missing permissions or other problems.

    • validateStartProcess

      void validateStartProcess(@NotNull String moduleKey, @NotNull Map<String,Object> parameters, @NotNull ForestSpec forestSpec) throws StructureException
      Checks whether an effector process can be started, as if by calling startProcess(String, Map, ForestSpec, boolean), without actually starting it. Returns normally if such a process can be started, throws a StructureException otherwise.
      Parameters:
      moduleKey - complete module key of the effector
      parameters - effector parameters
      forestSpec - forest spec, the scope will be the whole forest
      Throws:
      StructureException - if the process cannot be started, e.g. due to missing permissions or other problems.

    • startProcess

      long startProcess(@NotNull List<EffectorInstance> effectorInstances, long structureId, boolean requiresConfirmation) throws StructureException
      Starts a new effector process for installed effector instances. The current user will be the process owner.
      Parameters:
      effectorInstances - effector instances to run, the scope is defined by the structure id and position
      structureId - id of the structure for which effects are calculated.
      requiresConfirmation - if false, don't wait for confirmation, start applying effects as soon as the preview is ready (if successful).
      Returns:
      id of the new process
      Throws:
      StructureException - if the process cannot be started, e.g. due to missing permissions or other problems.

    • startProcess

      long startProcess(@NotNull String moduleKey, @NotNull Map<String,Object> parameters, @NotNull ForestSpec forestSpec, boolean requiresConfirmation) throws StructureException
      Starts a one-off effector process. The current user will be the process owner.
      Parameters:
      moduleKey - complete module key of the effector
      parameters - effector parameters
      forestSpec - forest spec, the scope will be the whole forest
      requiresConfirmation - if false, don't wait for confirmation, start applying effects as soon as the preview is ready (if successful).
      Returns:
      id of the new process
      Throws:
      StructureException - missing permissions, no such effector module, missing or invalid parameters, invalid forest spec, other problems

    • startUndoProcess

      long startUndoProcess(long processId, @Nullable Collection<Integer> recordIndexes) throws StructureException

      Starts a new process which undoes the effects performed by an earlier process. The process being undone must be in COMPLETED, COMPLETED_WITH_ERRORS, APPLY_INTERRUPTED, or APPLY_STOPPED status.

      The current user will be the new process owner. This method will throw a StructureException if the current user is not the owner of the process identified by processId and not a Jira admin.

      The new process proceeds to the apply queue immediately.

      Parameters:
      processId - the process id whose effects are to be undone
      recordIndexes - the effect record indexes to be undone, or null for all process records
      Returns:
      id of the new process
      Throws:
      StructureException - no access to process, process doesn't exist or is not finished, or its effect records cannot be found

    • getProcess

      @NotNull EffectorProcess getProcess(long processId) throws StructureException

      Retrieves the current state of the process.

      This method will throw a StructureException if the current user is not the process owner and not a Jira admin.

      Parameters:
      processId - process ID
      Returns:
      process state
      Throws:
      StructureException - no access to process or process doesn't exist

    • getEffectRecords

      @NotNull List<EffectRecord> getEffectRecords(long processId) throws StructureException

      Retrieves the list of effect records that describe the changes made by the given effector process or the errors that occurred while applying effects. Can be non-empty if the process is in one of the following statuses: IN_PROGRESS, COMPLETED, COMPLETED_WITH_ERRORS, APPLY_INTERRUPTED, or APPLY_STOPPED.

      This method will throw a StructureException if the current user is not the process owner and not a Jira admin.

      Parameters:
      processId - process ID
      Returns:
      a list of effect records
      Throws:
      StructureException - no access to process or process doesn't exist

    • confirm

      void confirm(long processId) throws StructureException

      Starts applying effects for an existing process with a calculated preview. The process must be in the CALCULATED status.

      This method will throw a StructureException if the current user is not the process owner and not a Jira admin.

      Parameters:
      processId - process ID
      Throws:
      StructureException - no access to process, or it doesn't exist, is not in the CALCULATED status

    • confirm

      @Deprecated void confirm(long processId, @Nullable Collection<Integer> effectIndices) throws StructureException
      Deprecated.
      Deprecated. Use confirm(long) instead.
      Parameters:
      processId - process ID
      effectIndices - used to filter effects from the preview.
      Throws:
      StructureException - no access to process, or it doesn't exist, is not in the CALCULATED status, or no effects can be found in the preview for the given indices

    • cancel

      void cancel(long processId) throws StructureException

      Asks a process to stop. The operation is asynchronous, so there is no guarantee that process will be stopped after this call.

      This method will throw a StructureException if the current user is not the process owner and not a Jira admin.

      Parameters:
      processId - process ID
      Throws:
      StructureException - no access to process or process doesn't exist

    • acknowledgeFinished

      void acknowledgeFinished(long processId) throws StructureException

      Sets the "acknowledged" flag for a finished process, so it is no longer shown in the list of current processes. The process must be in the COMPLETED, COMPLETED_WITH_ERRORS, APPLY_INTERRUPTED, or APPLY_STOPPED status.

      This method will throw a StructureException if the current user is not the process owner and not a Jira admin.

      Parameters:
      processId - process ID
      Throws:
      StructureException - no access to process, or process doesn't exist, or it is not in one of the "finished" statuses

    • deleteCalculated

      void deleteCalculated(long processId) throws StructureException

      Deletes a calculated process so that it is no longer shown in the list of processes. The process must be in the CALCULATED, CALCULATION_STOPPED, or CALCULATION_FAILED status.

      This method will throw a StructureException if the current user is not the process owner and not a Jira admin.

      Parameters:
      processId - process ID
      Throws:
      StructureException - no access to process, or process doesn't exist, or it is not in one of the "calculated" statuses

    • resumeInterrupted

      void resumeInterrupted(long processId) throws StructureException

      Moves an interrupted process back to the apply queue to resume applying previously calculated effects in its preview. The process must be in the APPLY_INTERRUPTED status.

      This method will throw a StructureException if the current user is not the process owner and not a Jira admin.

      Parameters:
      processId - process ID
      Throws:
      StructureException - no access to process, or process doesn't exist, or it is not in the "interrupted" status

    • findProcesses

      @NotNull List<EffectorProcess> findProcesses(@Nullable ApplicationUser user, @Nullable EffectorProcess.Status status, @Nullable Long structureId)

      Finds effector processes by owner, status, or structure ID. The three criteria are combined by logical AND. Passing null for any parameter means no restriction.

      This method does not check the current user's access to the returned processes.

      Parameters:
      user - process owner, pass null for all owners
      status - process status, pass null for all statuses
      structureId - structure ID, pass null for all structures
      Returns:
      the list of processes matching the search criteria

    • getRunningProcessesForUser

      @NotNull List<EffectorProcess> getRunningProcessesForUser(@NotNull ApplicationUser user)

      Finds all effector processes for the given user, except finished processes for which the "acknowledged" flag is set.

      This method does not check the current user's access to the returned processes.

      Parameters:
      user - the user
      Returns:
      the list of current processes for the given user