Managing your workflows

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

Workflows need to be activated to use them in Jira. Activating a workflow is the process of mapping the workflow to a workflow scheme, and then associating the workflow scheme with a project. To configure a workflow scheme, see Configuring workflow schemes.

A workflow scheme defines a set of associations – or mappings – between a workflow and an issue type. Workflow schemes are associated with a project and make it possible to use a different workflow for every combination of project and issue type.

For all of the following procedures, you must be logged in as a user with the Jira Administrators global permission.

On this page:

Activating a workflow

Active workflows are those that are currently being used, while inactive workflows are those that are not associated with any workflow schemes, or are associated with workflow schemes that are not associated with any projects. Active workflow schemes are also those associated with projects, while inactive workflow schemes are not.

  1. Create a workflow scheme or find an existing workflow scheme. See Configuring workflow schemes for instructions.
  2. Configure the workflow scheme to use your workflow. See Configuring workflow schemes for instructions.
    Associate your workflow scheme with a project, as described in the Associating a workflow scheme with a project section below.

Managing workflows for projects

You can manage your workflows by associating workflow schemes, importing, exporting, uploading, and sharing.

Associate a workflow scheme with a project

You can associate a single workflow scheme with more than one project, although only one workflow scheme can be associated with a given project. The issue type scheme associated with a project defines the issue types that are available to that project. If an issue type is not defined in the project's issue type scheme, its workflow is not used.

  1. In the upper-right corner of the screen, select Administration  > Projects.
  2. Select the relevant project.
  3. In the sidebar, Workflows (you can also click the More link in the Workflows section in the middle of the screen). This is the current workflow scheme used by the project.
  4. Select the Switch scheme link to display the Associate workflow scheme to project page.

  5. Select the relevant workflow scheme from the Scheme list and click the Associate button to begin the migration process.
    Each issue has to be in a valid status. The valid statuses for an issue are defined by its workflow. This means that when changing a workflow, you may need to tell Jira the status for specific issues after the change.

  6. A screen displays that indicates the progress of migrating all the project's issues to the updated scheme's workflows. Acknowledge to finish the process.

Disassociate a workflow scheme from a project

A Jira project must always be associated with a workflow scheme, since all issues must move through a workflow, even if that workflow only consists of a single Create Issue transition. By default all Jira projects with unmodified workflows use Jira's system workflow. Disassociating a workflow scheme re-associates your project's workflow with Jira's default workflow scheme.

  1. Follow the instructions in Associating a workflow scheme with a project above.
  2. When selecting the workflow scheme from the Scheme list, select the Default workflow scheme
  3. Click the Associate button, and follow the wizard, which guides you through migrating all of the project's issues.

Exporting your workflow

The workflow sharing feature allows you to share your team's workflow with other teams in your organization on different Jira instances, or external parties in other organizations via the Atlassian Marketplace. This feature allows you to easily share and use workflows that other people have published, or to move a workflow from staging to production in your own organization. If you wish to share your Jira Workflow with another instance of Jira or upload it to the Atlassian Marketplace, you first need to download it. 

  1. In the upper-right corner of the screen, select Administration  > Issues.
  2. In the sidebar, select Workflows.
  3. Find the workflow you wish to share.
  4. Select View or Edit under the Operations column.
  5. Select Export > As workflow and click Next to continue.
  6. In the Add Notes field, add any special configuration notes; for example, information about plugins that should be installed. Jira auto-populates these notes for you when it discards parts of your workflow (for example, plugins, post functions, conditions, validators).
  7. Select Export and select a download location. Ensure the location is publicly accessible.

Upload workflow to Atlassian Marketplace

To share your workflow with other Jira users, upload it to the Atlassian Marketplace.

  1. Create an account on Atlassian Marketplace, or log in and choose Manage apps (more info: Step-by-step Paid-via-Atlassian Listing).
  2. Click Create new app.
  3. Choose My app is not directly installable (ensure that 'App Type' is listed as 'Not a Plugin').
    You will need to host the workflow on your own servers, and add information about where the workflow export can be accessed in the Binary URL textbox. This should be the location you specified in step 6 of the prior instruction set.
  4. Fill out the submission form, be sure to note the following:
    1. The Summary field contains the information that will be displayed to users searching the Marketplace. 
    2. The Category for your workflow must be Workflow Bundles. Choosing Workflow Bundles ensures other Jira users will have visibility to your workflow.
    3. The App Key must be unique, as it uniquely identifies your application; it will become the application URL.

You don't have to complete the form in one session. You can save your form and come back to it later. Once you accept the Atlassian Marketplace Vendor Agreement, the system submits your app for review by Atlassian's Developer Relations team.

Importing workflows

Custom fields in workflow imports

If your workflow contains custom fields that are disabled, the workflow importer will not create these fields unless they are enabled before importing. You will receive a warning about this. To fix this, you need to enable the missing custom fields before proceeding with the import.

  1. Click on the highlighted Custom field Ttypes & searchers plugin in the displayed warning. This opens the plugin in a new window and scrolls to the right place to make the necessary changes.
  2. Click to expand the list of enabled modules.
  3. Find the modules that are disabled and enable them.

After enabling the corresponding modules of the Custom Field Types & Searchers plugin, return to the summary page and proceed. You may need to refresh the page first. For information on installing apps, see Viewing installed apps.

Import workflow from Atlassian Marketplace

This procedure covers importing a workflow from Atlassian Marketplace.

  1. In the upper-right corner of the screen, select Administration  > Issues.
  2. In the sidebar, select Workflows.
  3. Select Import > Import workflow in the top right of the screen.
  4. The From Atlassian Marketplace option should be selected by default.
  5. Find the workflow you want and click the Select button.
  6. Follow steps 5 through 8 of the Importing from a local instance procedure.

Import workflow from a local instance

This procedure covers importing a workflow from a local instance.

For all of the following procedures, you must be logged in as a user with the Jira system administrator global permissions.

  1. In the upper-right corner of the screen, select Administration  > Issues.
  2. In the sidebar, select Workflows.
  3. Select Import > Import workflow.
  4. Select a workflow from your computer to upload, and then select Next.
  5. Jira automatically generates a workflow name, but you can change this if you like. Click Next.
  6. Next, you are presented with a screen that details your workflow statuses, as shown below. You can map the steps of the workflow to your existing workflow statuses or create new statuses at this point. When you are finished, select Next to continue.
  7. At the Preview of Import screen, select Import at the bottom of this screen to accept the changes and import the workflow.
  8. Your workflow is imported and you are presented with a screen with additional configuration details. Select Done to exit this process.

All custom fields will have brand new custom fields created. This is regardless of a custom field of the same name / type already existing. See: JRA-37358 - Getting issue details... STATUS  for the request to improve this.

Last modified on Oct 10, 2022

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.