The sequence of states a JIRA issue can be is determined by the issue's 'workflow'. Workflows are defined in terms of steps (states) and transitions between states in JIRA's workflow editor (see the documentation for details). JIRA uses the OSWorkflow library in the background.

In some (rare) circumstances, it is necessary to edit a JIRA workflow in its native OSWorkflow XML format, rather than through JIRA's workflow editor. JIRA allows you to export/import XML workflow definitions for this purpose. This page is intended as a repository for notes and tips related to this process. Please feel free to add your thoughts here.

Workflows in the database

JIRA stores workflows in their native XML format as strings inside the database:

mysql> describe jiraworkflows;
+--------------+---------------+------+-----+---------+-------+
| Field        | Type          | Null | Key | Default | Extra |
+--------------+---------------+------+-----+---------+-------+
| ID           | decimal(18,0) | NO   | PRI | 0       |       |
| workflowname | varchar(255)  | YES  |     | NULL    |       |
| creatorname  | varchar(255)  | YES  |     | NULL    |       |
| DESCRIPTOR   | text          | YES  |     | NULL    |       |
| ISLOCKED     | varchar(60)   | YES  |     | NULL    |       |
+--------------+---------------+------+-----+---------+-------+
5 rows in set (0.01 sec)

The 'descriptor' field contains the XML.

If you are using MySQL, and are a command-line junkie, here are three useful scripts, available for download as a tar.gz.

jira_listworkflows

This lists the custom workflows in a MySQL database:

jturner@teacup:/tmp/wf$ ./jira_listworkflows jira
+-------+----------------+-------------+
| ID    | workflowname   | creatorname |
+-------+----------------+-------------+
| 10040 | Quest Workflow |             |
| 10011 | Demo Workflow  |             |
+-------+----------------+-------------+

jira_workflow

This prints a workflow's XML

jturner@teacup:/tmp/wf$ jira_workflow jira 'Demo Workflow'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE workflow PUBLIC "-//OpenSymphony Group//DTD OSWorkflow 2.8//EN" "http://www.opensymphony.com/osworkflow/workflow_2_8.dtd">
<workflow>
  <meta name="jira.description">The default JIRA workflow.</meta>
  <initial-actions>
    <action id="1" name="Create Issue">
      <meta name="jira.i18n.title">common.forms.create</meta>
      <validators>
        <validator type="class">
.....

jira_editworkflow

Loads an editor with the workflow XML (using the jira_workflow script), and saves modifications made to the database.

This script is useful for making small workflow edits that the JIRA editor doesn't let you (see issue JRA-7661 - editing workflows is too inflexible. Making any changes beyond small tweaks is dangerous - if you change the workflow step definitions from under JIRA, it can leave your data in a broken state (workflows unable to be transitioned, etc).

Discovering screen names

JIRA lets one display a certain screen on workflow transitions. In the workflow XML, this is denoted with a jira.fieldscreen.id 'meta' attribute, eg:

<action id="3" name="Reopen Issue" view="fieldscreen">
      <meta name="jira.i18n.title">issue.operations.reopen.issue</meta>
      <meta name="jira.i18n.submit">issue.operations.reopen.issue</meta>
      <meta name="jira.fieldscreen.id">10001</meta>
      <meta name="jira.i18n.description">issue.operations.reopen.description</meta>
      <meta name="jira.description"></meta>
      <restrict-to>

Here the screen with ID 10001 will be shown when 'Reopen Issue' is clicked. The IDs for screens can be found by examining the database:

mysql> select ID, NAME from fieldscreen;
+-------+----------------------+
| ID    | NAME                 |
+-------+----------------------+
|     1 | Default Screen       |
|     2 | Assign Issue Screen  |
|     3 | Resolve Issue Screen |
| 10000 | Simplified Bug Entry |
| 10001 | Simplified Reopen    |
+-------+----------------------+
5 rows in set (0.00 sec)

Workflows in a hsqldb database

If you are using the hsqldb database that comes with JIRA Standalone, you can run SQL commands with the built-in hsql utility described in Running SQL commands in a HSQL database. Please consider switching to a more robust database though, if you are using JIRA in earnest.

Editing JIRA workflow XML by hand