@PublicApi public interface

WorkflowManager

com.atlassian.jira.workflow.WorkflowManager
Known Indirect Subclasses

@PublicApi

This interface is designed for plugins to consume (call its methods).

Clients of @PublicApi can expect that programs compiled against a given version will remain binary compatible with later versions of the @PublicApi as per each product's API policy as long as the client does not implement/extend @PublicApi interfaces or classes (refer to each product's API policy for the exact guarantee---usually binary compatibility is guaranteed at least across minor versions).

Note: since @PublicApi interfaces and classes are not designed to be implemented or extended by clients, we may perform certain types of binary-incompatible changes to these classes and interfaces, but these will not affect well-behaved clients that do not extend/implement these types (in general, only classes and interfaces annotated with @PublicSpi are safe to extend/implement).

Class Overview

The WorkflowManager is used to interface with the workflow implementation

Summary

Public Methods
void copyAndDeleteDraftWorkflows(ApplicationUser user, Set<JiraWorkflow> workflows)
This method is deprecated. Since 5.1. This method should not be used directly by external developers as it is an operation that only makes sense in the context of a higher level operation in JIRA (i.e. project removal / changing the workflow scheme of a given project).

Please use the API calls for these higher level operations instead.

@Internal void copyAndDeleteDraftsForInactiveWorkflowsIn(ApplicationUser user, Iterable<JiraWorkflow> workflows)
Provided a set of workflows, this method will check, if the passed in inactive workflows have any drafts linked to them.
JiraWorkflow copyWorkflow(ApplicationUser user, String clonedWorkflowName, String clonedWorkflowDescription, JiraWorkflow workflowToClone)
Clones a workflow by creating a deep copy of the workflow provided.
JiraWorkflow copyWorkflow(String username, String clonedWorkflowName, String clonedWorkflowDescription, JiraWorkflow workflowToClone)
JiraWorkflow createDraftWorkflow(String username, String parentWorkflowName)
This method is deprecated. Use createDraftWorkflow(com.atlassian.jira.user.ApplicationUser, String) instead. Since v6.0.
JiraWorkflow createDraftWorkflow(ApplicationUser user, String parentWorkflowName)
This will create an draft workflow of the named active workflow.
GenericValue createIssue(String remoteUserName, Map<StringObject> fields)
Create an issue in the database.
void createWorkflow(ApplicationUser user, JiraWorkflow workflow)
void createWorkflow(String username, JiraWorkflow workflow)
This method is deprecated. Use createWorkflow(com.atlassian.jira.user.ApplicationUser, JiraWorkflow) instead. Since v6.0.
boolean deleteDraftWorkflow(String parentWorkflowName)
Deletes all draft workflows (there should every be only one) for a given parent workflow.
void deleteWorkflow(JiraWorkflow workflow)
void doWorkflowAction(WorkflowProgressAware from)
ActionDescriptor getActionDescriptor(WorkflowProgressAware workflowProgressAware)
@Nonnull ActionDescriptor getActionDescriptor(Issue issue, int actionId)
Given an issue and the identifier if a workflow action, returns the ActionDescriptor associated.
Collection<JiraWorkflow> getActiveWorkflows()
Retrieve all currently active workflows.
JiraWorkflow getDefaultWorkflow()
JiraWorkflow getDraftWorkflow(String parentWorkflowName)
Retrieve a single draft workflow by name.
@Internal @Nonnull String getNextStatusIdForAction(Issue issue, int actionId)
Given an issue and the identifier of a workflow action, returns the next status object for the issue if the action gets executed.
Map<ActionDescriptor, Collection<FunctionDescriptor>> getPostFunctionsForWorkflow(JiraWorkflow workflow)
Retrieve a map: actions -> post functions for a workflow.
String getStepId(long actionDescriptorId, String workflowName)
Gets the first stepId for the given action and workflow name.
WorkflowStore getStore()
JiraWorkflow getWorkflow(String name)
Retrieve a single workflow by name.
JiraWorkflow getWorkflow(Long projectId, String issueTypeId)
Retrieve the workflow for a given project - issue type pair.
JiraWorkflow getWorkflow(GenericValue issue)
This method is deprecated. Use getWorkflow(com.atlassian.jira.issue.Issue) instead. Since v6.2.
JiraWorkflow getWorkflow(Issue issue)
Retrieve the workflow for a given issue.
JiraWorkflow getWorkflowClone(String name)
This method returns a JiraWorkflow, that contains a com.opensymphony.workflow.loader.WorkflowDescriptor that is mutable.
JiraWorkflow getWorkflowFromScheme(WorkflowScheme scheme, String issueTypeId)
Return the workflow in a particular scheme for a given issue type.
JiraWorkflow getWorkflowFromScheme(GenericValue scheme, String issueTypeId)
Return the workflow in a particular scheme for a given issue type.
Collection<JiraWorkflow> getWorkflows()
Retrieve all of the workflows in the system
Iterable<JiraWorkflow> getWorkflowsFromScheme(Scheme workflowScheme)
Returns all workflows for a given scheme.
Collection<JiraWorkflow> getWorkflowsFromScheme(GenericValue workflowScheme)
This method is deprecated. Since 5.0. Use getWorkflowsFromScheme(com.atlassian.jira.scheme.Scheme) instead.
List<JiraWorkflow> getWorkflowsIncludingDrafts()
Retrieve all of the workflows in the system including drafts.
boolean isActive(JiraWorkflow workflow)
Determine whether or not a given workflow is active in the system.
boolean isEditable(Issue issue)
boolean isSystemWorkflow(JiraWorkflow workflow)
Determine whether or not a given workflow is a system workflow.
Workflow makeWorkflow(ApplicationUser user)
Prepares Workflow object with given user as caller
Workflow makeWorkflow(String userName)
This method is deprecated. Use makeWorkflow(com.atlassian.jira.user.ApplicationUser) instead. Since v6.0.
Workflow makeWorkflowWithUserKey(String userKey)
Workflow makeWorkflowWithUserName(String userName)
void migrateIssueToWorkflow(MutableIssue issue, JiraWorkflow newWorkflow, Status status)
Migrates given issue to new workflow and sets new status on it.
void migrateIssueToWorkflow(GenericValue issue, JiraWorkflow newWorkflow, GenericValue status)
boolean migrateIssueToWorkflowNoReindex(GenericValue issue, JiraWorkflow newWorkflow, GenericValue status)
Migrates given issue to new workflow and sets new status on it.
void overwriteActiveWorkflow(ApplicationUser user, String workflowName)
Saves the draft workflow into the active workflow.
void overwriteActiveWorkflow(String username, String workflowName)
This method is deprecated. Use overwriteActiveWorkflow(com.atlassian.jira.user.ApplicationUser, String) instead. Since v6.0.
void removeWorkflowEntries(GenericValue issue)
void replaceConditionInTransition(ActionDescriptor transition, Map<StringString> matchMap, Map<StringString> newMap)
Changes the parameter map of all conditions that have the parameter map matching matchMap by adding all properties from newMap.
void saveWorkflowWithoutAudit(JiraWorkflow workflow)
This method will save the workflow and it will not affect the updatedDate and updatedAuthorName meta attributes of the workflow.
void updateWorkflow(String username, JiraWorkflow workflow)
This method is deprecated. Use updateWorkflow(com.atlassian.jira.user.ApplicationUser, JiraWorkflow) instead. Since v6.0.
void updateWorkflow(ApplicationUser user, JiraWorkflow workflow)
Saves the given JiraWorkflow, which may be either a "live" or "draft" version.
void updateWorkflowNameAndDescription(String username, JiraWorkflow currentWorkflow, String newName, String newDescription)
void updateWorkflowNameAndDescription(ApplicationUser user, JiraWorkflow currentWorkflow, String newName, String newDescription)
Used to change the name and description of an existing worfklow with the given name.
boolean workflowExists(String name)

Public Methods

public void copyAndDeleteDraftWorkflows (ApplicationUser user, Set<JiraWorkflow> workflows)

This method is deprecated.
Since 5.1. This method should not be used directly by external developers as it is an operation that only makes sense in the context of a higher level operation in JIRA (i.e. project removal / changing the workflow scheme of a given project).

Please use the API calls for these higher level operations instead.

Provided a set of workflows, this method will check, if the passed in inactive workflows have any drafts linked to them. If they do, it will copy the draft into a new inactive workflow, and then delete the draft.

Parameters
user The user performing the operation
workflows A set of parent JiraWorkflows

@Internal public void copyAndDeleteDraftsForInactiveWorkflowsIn (ApplicationUser user, Iterable<JiraWorkflow> workflows)

@Internal

This method is an internal implementation detail and will change without notice.

Clients that depend on @Internal classes and interfaces can not expect to be compatible with any version other than the version they were compiled against (even minor version and milestone releases may break binary compatibility with respect to @Internal elements).

Provided a set of workflows, this method will check, if the passed in inactive workflows have any drafts linked to them. If they do, it will copy the draft into a new inactive workflow, and then delete the draft.

This method is only meant to be used internally in JIRA. External developers should not call this method directly.

Parameters
user The user performing the operation
workflows A set of parent JiraWorkflows

public JiraWorkflow copyWorkflow (ApplicationUser user, String clonedWorkflowName, String clonedWorkflowDescription, JiraWorkflow workflowToClone)

Clones a workflow by creating a deep copy of the workflow provided.

Parameters
user The user performing the operation
clonedWorkflowName The name to store the new workflow with.
clonedWorkflowDescription The description to store with the cloned workflow. Can be null.
workflowToClone The workflow to copy.
Returns
  • A cloned copy of the original workflow.

public JiraWorkflow copyWorkflow (String username, String clonedWorkflowName, String clonedWorkflowDescription, JiraWorkflow workflowToClone)

This method is deprecated.
Use copyWorkflow(com.atlassian.jira.user.ApplicationUser, String, String, JiraWorkflow) instead. Since v6.0.

Clones a workflow by creating a deep copy of the workflow provided.

Parameters
username The user performing the operation
clonedWorkflowName The name to store the new workflow with.
clonedWorkflowDescription The description to store with the cloned workflow. Can be null.
workflowToClone The workflow to copy.
Returns
  • A cloned copy of the original workflow.

public JiraWorkflow createDraftWorkflow (String username, String parentWorkflowName)

This method is deprecated.
Use createDraftWorkflow(com.atlassian.jira.user.ApplicationUser, String) instead. Since v6.0.

This will create an draft workflow of the named active workflow. This draft workflow can be used to edit active workflows without overwriting the active workflow immediately.
This method will not allow you to create an draft workflow if the parent workflow is not active, the method will throw an IllegalStateException in this case.

Parameters
username identifies the user performing the action so that we can keep an audit trail of who has last saved the workflow. Empty string for anonymous user. If null an IllegalArgumentException will be thrown
parentWorkflowName identifies the parent workflow that should be used as the template for creating the draft workflow.
Returns
  • An instance of JiraWorkflow that represents a copy of the parent that can be edited without overwriting the active workflow immediately.
Throws
IllegalStateException thrown if the parentWorkflow is not Active or the draft already exists
IllegalArgumentException If the username is null

public JiraWorkflow createDraftWorkflow (ApplicationUser user, String parentWorkflowName)

This will create an draft workflow of the named active workflow. This draft workflow can be used to edit active workflows without overwriting the active workflow immediately.
This method will not allow you to create an draft workflow if the parent workflow is not active, the method will throw an IllegalStateException in this case.

Parameters
user identifies the user performing the action so that we can keep an audit trail of who has last saved the workflow. Empty string for anonymous user. If null an IllegalArgumentException will be thrown
parentWorkflowName identifies the parent workflow that should be used as the template for creating the draft workflow.
Returns
  • An instance of JiraWorkflow that represents a copy of the parent that can be edited without overwriting the active workflow immediately.
Throws
IllegalStateException thrown if the parentWorkflow is not Active or the draft already exists
IllegalArgumentException If the username is null

public GenericValue createIssue (String remoteUserName, Map<StringObject> fields)

Create an issue in the database.

Parameters
remoteUserName Issue creator
fields Map of fields. The key is the name of the field, and the type of the value depends on the key. Must include a key "issue", which contains MutableIssue object (holding values, not yet persisted to disk). May include other fields (eg "pkey"->String key of project, "originalissueobject"->Issue object) passed onto the workflow engine.
Returns
  • The created issue GenericValue
Throws
WorkflowException If any errors occur while trying to create the issue.

public void createWorkflow (ApplicationUser user, JiraWorkflow workflow)

public void createWorkflow (String username, JiraWorkflow workflow)

This method is deprecated.
Use createWorkflow(com.atlassian.jira.user.ApplicationUser, JiraWorkflow) instead. Since v6.0.

Throws
WorkflowException
WorkflowException

public boolean deleteDraftWorkflow (String parentWorkflowName)

Deletes all draft workflows (there should every be only one) for a given parent workflow.

Parameters
parentWorkflowName The parentworkflow for which the draft workflow needs to be deleted.
Returns
  • true if a draft workflow as deleted, false otherwise.
Throws
IllegalArgumentException if the parentWorkflowName is null

public void deleteWorkflow (JiraWorkflow workflow)

public void doWorkflowAction (WorkflowProgressAware from)

public ActionDescriptor getActionDescriptor (WorkflowProgressAware workflowProgressAware)

Throws
Exception

@Nonnull public ActionDescriptor getActionDescriptor (Issue issue, int actionId)

Given an issue and the identifier if a workflow action, returns the ActionDescriptor associated.

Parameters
issue The issue.
actionId The identifier of a workflow action.
Returns
  • The ActionDescriptor corresponding to the workflow action id for the given issue.

public Collection<JiraWorkflow> getActiveWorkflows ()

Retrieve all currently active workflows.

Returns
  • Collection of JiraWorkflow objects.
Throws
WorkflowException RuntimeException wrapper for any errors.

public JiraWorkflow getDefaultWorkflow ()

public JiraWorkflow getDraftWorkflow (String parentWorkflowName)

Retrieve a single draft workflow by name. If there is not an draft workflow associated with the name this will return null.

Parameters
parentWorkflowName is the name of the Saved workflow which identifies then paritally edited draft workflow to retrieve.
Returns
  • a JiraWorkflow that represents an draft edited workflow.
Throws
IllegalArgumentException if no parentWorkflow with the name provided can be found.

@Internal @Nonnull public String getNextStatusIdForAction (Issue issue, int actionId)

@Internal

This method is an internal implementation detail and will change without notice.

Clients that depend on @Internal classes and interfaces can not expect to be compatible with any version other than the version they were compiled against (even minor version and milestone releases may break binary compatibility with respect to @Internal elements).

Given an issue and the identifier of a workflow action, returns the next status object for the issue if the action gets executed.

Parameters
issue The issue
actionId The identifier of a workflow action
Returns
  • The status object corresponding to the next status of the issue if the action got executed

public Map<ActionDescriptor, Collection<FunctionDescriptor>> getPostFunctionsForWorkflow (JiraWorkflow workflow)

Retrieve a map: actions -> post functions for a workflow.

Parameters
workflow The Workflow
Returns
  • Map of actions-> post functions

public String getStepId (long actionDescriptorId, String workflowName)

Gets the first stepId for the given action and workflow name.

Parameters
actionDescriptorId id of the ActionDescriptor
workflowName name of the JiraWorkflow
Returns
  • the first stepId for the given action and workflow name.

public WorkflowStore getStore ()

Throws
StoreException

public JiraWorkflow getWorkflow (String name)

Retrieve a single workflow by name. The returned JiraWorkflow contains a descriptor that by default isn't mutable.

If you need to edit a workflow, please see getWorkflowClone(String).

Parameters
name The workflow name
Returns
  • A JiraWorkflow that wraps an Immutable WorkflowDescriptor or null

public JiraWorkflow getWorkflow (Long projectId, String issueTypeId)

Retrieve the workflow for a given project - issue type pair.

Parameters
projectId the Project
issueTypeId the IssueType ID
Returns
  • the workflow for the given project - issue type pair.
Throws
WorkflowException RuntimeException wrapper for any errors.

public JiraWorkflow getWorkflow (GenericValue issue)

This method is deprecated.
Use getWorkflow(com.atlassian.jira.issue.Issue) instead. Since v6.2.

Retrieve the workflow for a given issue.

Parameters
issue the Issue
Returns
  • the workflow for the given issue.
Throws
WorkflowException RuntimeException wrapper for any errors.

public JiraWorkflow getWorkflow (Issue issue)

Retrieve the workflow for a given issue.

Parameters
issue the Issue
Returns
  • the workflow for the given issue.
Throws
WorkflowException RuntimeException wrapper for any errors.

public JiraWorkflow getWorkflowClone (String name)

This method returns a JiraWorkflow, that contains a com.opensymphony.workflow.loader.WorkflowDescriptor that is mutable. This method should be called, if you require to edit the workflow.

If you only need to view a workflow, please use getWorkflow(String) as it will provide better performance. Cloning a workflow is expensive, as it requires de-constructing and re-constructing the underlying com.opensymphony.workflow.loader.WorkflowDescriptor from XML.

Parameters
name The workflow name
Returns

public JiraWorkflow getWorkflowFromScheme (WorkflowScheme scheme, String issueTypeId)

Return the workflow in a particular scheme for a given issue type.

Parameters
scheme the Scheme
issueTypeId the IssueType ID
Returns
  • the workflow for the issue type in the scheme.
Throws
WorkflowException RuntimeException wrapper for any errors.

public JiraWorkflow getWorkflowFromScheme (GenericValue scheme, String issueTypeId)

Return the workflow in a particular scheme for a given issue type.

Parameters
scheme the Scheme
issueTypeId the IssueType ID
Returns
  • the workflow for the issue type in the scheme.
Throws
WorkflowException RuntimeException wrapper for any errors.

public Collection<JiraWorkflow> getWorkflows ()

Retrieve all of the workflows in the system

Returns

public Iterable<JiraWorkflow> getWorkflowsFromScheme (Scheme workflowScheme)

Returns all workflows for a given scheme.

Parameters
workflowScheme the Workflow Scheme.
Returns
  • Collection of workflow schemes, empty collection if none exists.
Throws
WorkflowException RuntimeException wrapper for any errors.

public Collection<JiraWorkflow> getWorkflowsFromScheme (GenericValue workflowScheme)

This method is deprecated.
Since 5.0. Use getWorkflowsFromScheme(com.atlassian.jira.scheme.Scheme) instead.

Returns all workflows for a given scheme.

Parameters
workflowScheme the Workflow Scheme.
Returns
  • Collection of workflow schemes, empty collection if none exists.
Throws
WorkflowException RuntimeException wrapper for any errors.

public List<JiraWorkflow> getWorkflowsIncludingDrafts ()

Retrieve all of the workflows in the system including drafts. We return a list as we want to keep workflows and associated drafts are adjacent.

Returns

public boolean isActive (JiraWorkflow workflow)

Determine whether or not a given workflow is active in the system.

Active workflows are those currently assigned to schemes and associated with projects - they cannot be edited but can be used.

Parameters
workflow the JiraWorkflow to check
Returns
  • true if the given workflow is active
Throws
WorkflowException RuntimeException wrapper for any errors.

public boolean isEditable (Issue issue)

public boolean isSystemWorkflow (JiraWorkflow workflow)

Determine whether or not a given workflow is a system workflow.

Check for a system or XML based workflow - can not be edited.

Parameters
workflow the JiraWorkflow to check
Returns
  • true if the given workflow is a system workflow
Throws
WorkflowException maybe - but it doesn't look like it?

public Workflow makeWorkflow (ApplicationUser user)

Prepares Workflow object with given user as caller

Parameters
user caller
Returns
  • created Workflow

public Workflow makeWorkflow (String userName)

This method is deprecated.
Use makeWorkflow(com.atlassian.jira.user.ApplicationUser) instead. Since v6.0.

Prepares Workflow object with given username as caller

Parameters
userName caller username
Returns
  • created Workflow

public Workflow makeWorkflowWithUserKey (String userKey)

public Workflow makeWorkflowWithUserName (String userName)

public void migrateIssueToWorkflow (MutableIssue issue, JiraWorkflow newWorkflow, Status status)

Migrates given issue to new workflow and sets new status on it.

Parameters
issue issue to migrate
newWorkflow new workflow
status new status
Throws
WorkflowException if migration fails

public void migrateIssueToWorkflow (GenericValue issue, JiraWorkflow newWorkflow, GenericValue status)

This method is deprecated.
Please use migrateIssueToWorkflow(com.atlassian.jira.issue.MutableIssue, JiraWorkflow, com.atlassian.jira.issue.status.Status). Since: 3.9.

Migrates given issue to new workflow and sets new status on it.

Parameters
issue issue to migrate
newWorkflow new workflow
status new status
Throws
WorkflowException if migration fails

public boolean migrateIssueToWorkflowNoReindex (GenericValue issue, JiraWorkflow newWorkflow, GenericValue status)

Migrates given issue to new workflow and sets new status on it. It returns true iff the issue that was migrated needs a reindex. The passed issue is not reindexed even if necessary.

Parameters
issue issue to migrate
newWorkflow new workflow
status new status
Returns
  • true if the issue
Throws
WorkflowException if migration fails

public void overwriteActiveWorkflow (ApplicationUser user, String workflowName)

Saves the draft workflow into the active workflow.

Parameters
user User will be added to the workflows Audit trail
workflowName The workflow to be overwritten

public void overwriteActiveWorkflow (String username, String workflowName)

This method is deprecated.
Use overwriteActiveWorkflow(com.atlassian.jira.user.ApplicationUser, String) instead. Since v6.0.

Saves the draft workflow into the active workflow.

Parameters
username User will be added to the workflows Audit trail
workflowName The workflow to be overwritten

public void removeWorkflowEntries (GenericValue issue)

public void replaceConditionInTransition (ActionDescriptor transition, Map<StringString> matchMap, Map<StringString> newMap)

Changes the parameter map of all conditions that have the parameter map matching matchMap by adding all properties from newMap.

Parameters
transition transition to change the conditions in
matchMap the map used to determine if the condition should be modified
newMap a map of properties to be added to the parameter map

public void saveWorkflowWithoutAudit (JiraWorkflow workflow)

This method will save the workflow and it will not affect the updatedDate and updatedAuthorName meta attributes of the workflow. This should only ever be invoked by system operations such as upgrade tasks. All other saves should use the method updateWorkflow(String, JiraWorkflow)

Parameters
workflow the workflow to save.
Throws
WorkflowException RuntimeException wrapper for any errors.

public void updateWorkflow (String username, JiraWorkflow workflow)

This method is deprecated.
Use updateWorkflow(com.atlassian.jira.user.ApplicationUser, JiraWorkflow) instead. Since v6.0.

Saves the given JiraWorkflow, which may be either a "live" or "draft" version. This method does not save the changes to the active workflow. Instead, this is meant to be used to make persistent changes to your working edit. Once all changes have been made you can over write the active workflow by calling overwriteActiveWorkflow(String, String)

Parameters
username User making the request.
workflow The JiraWorkflow to save.
Throws
IllegalArgumentException if the workflow or its descriptor is null.

public void updateWorkflow (ApplicationUser user, JiraWorkflow workflow)

Saves the given JiraWorkflow, which may be either a "live" or "draft" version. This method does not save the changes to the active workflow. Instead, this is meant to be used to make persistent changes to your working edit. Once all changes have been made you can over write the active workflow by calling overwriteActiveWorkflow(ApplicationUser, String)

Parameters
user User making the request.
workflow The JiraWorkflow to save.
Throws
IllegalArgumentException if the workflow or its descriptor is null.

public void updateWorkflowNameAndDescription (String username, JiraWorkflow currentWorkflow, String newName, String newDescription)

This method is deprecated.
Use updateWorkflowNameAndDescription(com.atlassian.jira.user.ApplicationUser, JiraWorkflow, String, String) instead. Since v6.0.

Used to change the name and description of an existing worfklow with the given name.

Parameters
username The user performing the operation
currentWorkflow The workflow to update.
newName The new name to save with the workflow
newDescription The new description to save with the workflow

public void updateWorkflowNameAndDescription (ApplicationUser user, JiraWorkflow currentWorkflow, String newName, String newDescription)

Used to change the name and description of an existing worfklow with the given name.

Parameters
user The user performing the operation
currentWorkflow The workflow to update.
newName The new name to save with the workflow
newDescription The new description to save with the workflow

public boolean workflowExists (String name)