How to Add a Screen to a Workflow Transition in Jira

Adding a screen to a workflow in Jira involves associating a specific screen with a workflow transition, which dictates the fields users see when moving an issue from one status to another. This powerful feature helps collect necessary information at critical points in an issue's lifecycle.

Understanding Jira Screens and Workflows

Before diving into the steps, it's essential to grasp the roles of screens and workflows in Jira:

• Jira Screens: A screen is a collection of fields that are displayed when users perform certain operations, such as creating an issue, viewing an issue, or, in this case, transitioning an issue. They allow you to control which information is collected and presented to users.
• Jira Workflows: A workflow defines the lifecycle of an issue in Jira, illustrating the various statuses an issue can have (e.g., Open, In Progress, Done) and the transitions between these statuses.
• Screens in Workflows: Screens are not added directly to an entire workflow. Instead, they are linked to specific workflow transitions. When a user executes a transition (e.g., moving an issue from "Open" to "In Progress"), the associated screen appears, prompting them to enter or update relevant field information.

Step-by-Step Guide to Associating a Screen with a Workflow Transition

To effectively add a screen to a workflow transition, you'll generally follow these steps: creating the screen (if it doesn't exist) and then linking it to the desired transition.

Step 1: Create or Locate Your Jira Screen

First, ensure you have the screen you want to use. If you need to create a new one, follow these instructions:

1. Navigate to Jira's administration area. Typically, this is done by selecting Settings (⚙️) > Issues.
2. In the left-hand navigation panel, under "SCREENS," click on Screens.
3. On the Screens page, click the Add screen button.
4. Provide a Name and Description for your new screen. The description should clearly indicate when and why this screen should be used (e.g., "Screen for collecting Resolution details").
5. Click Add.
6. Once the screen is created, you can then add the desired fields to it by navigating back to the screen's configuration page and selecting fields from the available list.

If you already have an existing screen you wish to use, you can skip the creation process and simply make a note of its name.

Step 2: Access Your Workflow

Next, you need to find and edit the workflow you want to modify:

1. From Jira's administration area (Settings (⚙️) > Issues), navigate to Workflows in the left-hand panel.
2. Locate the workflow you intend to modify. You'll typically find an associated workflow scheme that links this workflow to specific project issue types.
3. Click the Edit button next to the relevant workflow. This will open the workflow editor, usually in diagram mode.

Step 3: Select the Workflow Transition

In the workflow editor, identify the specific transition where you want the screen to appear:

1. In diagram mode, click on the arrow representing the desired transition (e.g., the arrow moving from "To Do" to "In Progress" or from "In Progress" to "Done").
2. The transition details will appear in a panel, usually on the right side of the screen.

Step 4: Add or Modify the Screen for the Transition

Now, you can associate the screen with the selected transition:

1. Within the transition details panel, look for the Screen property.
2. From the dropdown menu, select the name of the screen you created or located in Step 1.
3. Once selected, click the Update or Save button to apply the change to the transition.
4. After making your changes to the workflow, remember to Publish Draft (if you were editing a draft workflow) to make your changes live. Jira will prompt you to associate a workflow scheme if necessary.

Practical Insights and Best Practices

Implementing screens on workflow transitions effectively can significantly improve data quality and user experience.

When to Use Screens on Transitions

• Mandatory Information Collection: Use screens to enforce the collection of crucial data before an issue moves to a new status (e.g., requiring "Resolution" and "Resolution Comment" when an issue is moved to "Done").
• Conditional Data Entry: For specific transitions, you might need different fields. For instance, a "Reopen" transition might require a "Reopen Reason" field that isn't present during other transitions.
• Data Consistency: Ensure that all issues following a certain path collect the same essential information, leading to more consistent reporting.

Tips for Effective Screen Management

• Keep Screens Simple and Relevant: Avoid overwhelming users with too many fields. Only include fields absolutely necessary for that specific transition.
• Reuse Screens: If multiple transitions require the same set of fields (e.g., a "Resolve Issue Screen" could be used for "Done," "Closed," and "Won't Do" transitions), reuse the same screen to maintain consistency and simplify administration.
• Test Thoroughly: Always test your workflow and screen changes in a development or staging environment before publishing them to production. This helps catch any configuration errors or unexpected behavior.
• Clearly Name Screens: Use descriptive names for your screens so their purpose is immediately clear to administrators.

Common Screen Scenarios in Jira Workflows

Here’s a table illustrating common uses for screens on different workflow transitions:

Transition Type	Common Screen Purpose	Example Fields Included
Open to In Progress	Initial Assignment/Start Work	Assignee, Start Date
In Progress to Done	Issue Resolution	Resolution, Resolution Comment, Time Spent
Done to Reopen	Reopening an Issue	Reopen Reason, Reopen Date, Assignee
Any to Blocked	Recording Blockage Details	Block Reason, Blocked By, Expected Unblock
Open to Rejected	Rejecting an Issue	Rejection Reason, Not Relevant Comment

Further Resources

For more detailed information on configuring screens and workflows, refer to the official Atlassian Jira documentation.