Everything must come to an end. One could say that FY2018 is about to reach its resolution. (I’ll let you decide if want to mark it off as Fixed, Won’t Fix or simply Done.) The end of the year is a traditional time for stock-taking as we prepare for a fresh new start. You can apply that to your Jira application as well.
Cleaning Up Your Jira Application
Use the end of the year as an opportunity to check for and clean out stagnant Jira assets. Sometimes projects get abandoned instead of being properly closed out. This can happen when the organization’s priorities change or when teams reorganize. Sometimes an initiative that was tracked in Jira is completed and teams who are anxious to carry the momentum into the next project may forget to close out the previous one.
While you’re doing the high level assessment and clean up, you can encourage Project Leads to take a look at their active projects and see if any clean up needs to be done there. Rachel recommends checking for things such as:
Accurate and useful components (and component Leads)
Stagnant issues (haven’t been updated in x days)
A neglected backlog
An accurate listing of team members
This is also an opportunity to see if any adjustments (big or small) should be made to make the system more helpful. Are the filters, boards and dashboards useful? Could they be more useful if you made a few minor changes? Does the project configuration still fit the team’s needs? Are there any customizations that the team would like to have? Any painful processes that could be eased with the addition of the right app/plugin? Now is a good time to take a look.
What You and Jira Accomplished this Year
Year end is also an opportunity to compile and analyze a few statistics on how Jira is used within your organization. In fact, regular and thorough documentation will not only demonstrate how important Jira (and therefore the Jira support team) is to your organization, it will help you predict future needs. In addition to an Annual Report form, Rachel has also created a Jira Use and Future Predictionsworksheet which will help you document Jira usage over time.
Expanding Jira to Business Teams
While you’re making those predictions, consider whether Jira could benefit more teams in your organization. Many companies use Jira or Jira Service Desk not only for software or IT support, but also to manage HR, finance and facilities related processes.
Expanding Jira to other business teams doesn’t have to be an administrative nightmare. The simple addition of forms, available through the ProForma app, means that teams can customize their processes and collect exactly the data they need without requiring new issue types, hordes of custom fields, or special configurations. You can actually simplify Jira administration even as you’re bringing more teams into Jira.
Imagine being able to view issues from multiple Jira applications on one board. WatchTower does that easily. You can view issues and use familiar board features (swimlanes, JQL, and dragging issues to update status) without logging in to multiple Jira applications. I wish I had know about this add-on sooner!
Jira Server 7.7.1, Jira Server 7.9.2, and Jira Cloud
May 23, 2018
First I installed the application in my Server instance. It was very easy to install and configure. In minutes I created a new WatchTower board and saw issues from my Cloud instance from inside my Server instance. From the board, I was able to launch an issue in its source application and update it. Then, I refreshed the board and the changes were visible immediately.
In the example screenshot, there are two issues from the “HR” project in my Server instance, and 5 issues from the “DEMO” project in my Cloud instance.
It’s easy to create a new board and add a remote source. Simply enter a source name and any display preferences. Then enter your source URL, credentials, and a JQL query to pull the desired data. Use the handy “Test Connection” button at the bottom to verify your credentials are correct and issue data was found. Read more
I also installed the application in my Cloud instance to test another scenario. I added the current Cloud instance as a source and also a different remote Cloud instance. Everything worked as expected from within Cloud.
In the example screenshot, issues are displayed from a Cloud instance named “DEMO” and another Cloud instance named “JA.” You can name the instances anything you’d like.
I love that you can display issues from only remote sources or from both remote sources and the application you’re using. It’s great to see a subset of data, a full picture, or to do a comparison.
The add-on is fully documented, but unless you’re new to boards in general, you probably won’t need much configuration or use help.
Here are some ways the add-on helps:
Companies with Multiple Instances
How does a company end up with multiple Jira applications? Actually, it happens more often than you’d think. Consider the following:
A company acquires another company that has their own set of Atlassian tools
A team decides “try out” Jira not knowing other teams already use it
One team needs a public instance for customer support, however, other teams need their data inside the firewall
I once worked with a company that had 4 instances! The goal was to eventually merge them together, but that’s never a quick task. So how do you give users visibility while waiting? Whether your end goal is to merge or not merge, having a tool that can help you connect instances is a big help.
Let’s say you’re working on a Jira merge. This plugin can help you verify that the data you expect from the source application actually exists in the destination application. Simply create one board and query for the same data in both applications.
This functionality is especially useful for consultants, like me, who regularly work in multiple Jira instances at once. For example, I track most of my work in my own Jira instance. Sometimes a company I’m helping assigns an issue to me in their Jira instance, which is perfectly understandable. Now, I can see all my issues in one place.
Additionally, I store my work tasks in a Server instance and my personal tasks in a Cloud instance. I do this to separate my different roles and also because it forces me to be aware of changes in each application type. Now I won’t have to log in to my secondary Cloud instance as often.
The WatchTower boards don’t have the Atlassian board feature where you click an issue and details appear to the right of the board. See screenshot. But to be honest, I never loved that abbreviated display. If I want to see issue details I prefer to open the normal issue view page. That’s the way WatchTower handles it. Click on an issue ID and the issue opens immediately in a new window. You can log work on a remote issue directly from the WatchTower board however.
There are three sharing permissions. “Browse Board” allows the listed users to view the board and do nothing else. “Work on Issues” allows users to view the board, log work, and add a work description. “Transition Issues” allows users to do everything previously mentioned plus change issue status. This additive behavior was confusing to me at first, but once you know that “Transition Issues” includes the permissions from other levels, it makes sense. It doesn’t appear that you can grant sharing permissions to groups of users.
One thing to be aware of: any actions will be logged in the remote system as performed by board owner.
TIP: Speed up your boards by limiting their scope. Use JQL to pull in just the relevant issues, not all project issues. Definitely filter out issues in “Closed” or “Done” status.
Since performance of any type of board is typically slow, I conducted the following unscientific test. I created a test Jira Software project and loaded it with sample Jira data, which included a 4 column Kanban board and 10 issues. I created a WatchTower board to show the exact same data. Then I used the Chrome browser’s developer tools to compare load times. Results:
Adding a second, external Jira source didn’t create a huge delay. Of course my test was with only 10 issues. Don’t expect hundreds of issues to display quickly in any board type! And of course, if any remote instance is already slow or down, you’ll have expected loading issues. At one point, the connection to one of my sources broke. It was a quick fix though. When I loaded the WatchTower board, it alerted me to the problem, and where to fix it.
Bottom line: Any loading slowness caused by many sources and many issues is easily outweighed by the ability to see all your issues in one view.
How many instances can you connect?
There’s currently no limit although in the future the number of instances may be driven by pricing tier. You only need a license for one instance, not a license for each remote instance you’re connecting to.
What if the instances have different users? Example: My username is “rachelw” in app 1 and “rwright” in app 2.
It’s no problem; each user authenticates with their specific system credentials. TIP: Avoid using “currentUser()” in your source JQL queries if you have different usernames.
How do you handle different statuses per instance?
Map statuses to columns like you would for a Scrum or Kanban board. Differing statuses are handled the same way as different statuses between projects in a single instance. You can also not map certain statuses. A WatchTower board alerts you if there’s a status not mapped to a column.
What happens when source data changes?
Simply refresh and updated data will be pulled from the source(s). At this time, there’s no automatic prompt to refresh.
How is security handled?
Account credentials are used once to access the source application and are then stored in a token. Jira’s built in security mechanisms are respected. To see issue data you need an authenticated account in the source application. You cannot view issues you don’t already have permission to see.
What are you working on for the future?
Performance, the ability to display custom fields, and the ability connect to other applications. Imagine viewing your Jira data alongside your Salesforce or Trello data, for example. There may also be instance connection issues (like getting through a firewall) and two factor authentication issues to tackle in the future. Read more
For Users & Board Admins
Look for a new menu, in the main navigation, labeled WatchTower. All remote boards are in this area. Scrum and Kanban boards remain under the “Boards” nav link.
For Application Admins
This plugin is installed from System > Add-ons > Manage add-ons like other plugins. There’s only one configuration option for application admins. It’s located at: Admin > Add-ons > Configure. Look for the left sidebar link under the “WatchTower” heading.
This plugin is simple but powerful! If you have more than one Jira application at work, a work and personal instance, a side Jira administrator gig, or are a consultant, WatchTower can help you quickly and easily view all your issues in one place. I’m looking forward to not logging into my Cloud instance as often.
There are a plethora of plugins and add-on features available in the Atlassian Marketplace. But haphazard installs and free trials can leave behind remnants that negatively impact the system after the trial ends. You should develop specific procedures for handling add-ons and customization requests. Use our plugin vetting worksheets to craft your procedure.
I regularly review applications, add-ons, or plugins that I like! Have an app users should know about? Tell me about it at: firstname.lastname@example.org.
Jira comes with standard, built-in fields, like “Summary”, “Description”, and “Components” but you can also create additional Custom Fields to track more data.
Your instance starts out with 8-30 fields, on the “Custom Fields” page, depending on whether you have Cloud or Server. For example, Jira Server 7.7.1 comes with 8 custom fields. Installing Jira Service Desk on top of Jira Server adds 6 additional fields. More fields can be created by Jira, by application administrators, or by add-ons, plugins, and applications.
So how do you distinguish the standard fields from the ones created by applications and admins? Use this baseline list from a clean Jira install.
Standard Jira Fields
Default Fields & Functions
Project (On the “Create” screen)
Epic Name (For Epics)
Epic Link (For issues related to Epics)
Time Tracking (Includes Original Estimate and Remaining Estimate fields)
Status (A workflow step)
Default Fields on the “Custom Fields” Admin Page
From Jira Server 7.1.1
From Jira Cloud
From Jira Service Desk 3.12.2
The following fields are added when you create a support-type project and use the “Create sample data” option:
CAB (Description: Change Advisory Board members)
Change completion date
Change start date
Customer Request Type (Locked)
Request participants (Locked)
Time to approve normal change (Locked)
Time to close after resolution (Locked)
Time to first response (Locked)
Time to resolution (Locked)
Satisfaction date (Locked)
Clean Instance Worksheet
Use this default Jira setup worksheet to compare settings in your application and see how far you’ve strayed from the default. Use this template to document defaults in other versions.
Depending on where you are in the world, you may be smack in the middle of spring – as in time for Spring Cleaning. Even if it isn’t spring, it’s a good idea to occasionally audit your Jira installation, archive elements that aren’t being used and revisit your configuration to ensure that it’s optimized. Below are the basic steps you will need to perform a “Jira Clean-up.”
Jira Clean-up Step 1: Audit
The first step is taking stock of what you have. To do this, start with the “System info” page and note the number of projects, issues, custom fields, workflows, etc. Next, visit the Add-ons admin page and the admin area for each scheme and project asset.
Rachel Wright offers a worksheet for recording this information. Alternatively, you could use a spreadsheet or create a form in ProForma. The important thing is that you will want to track the number of Jira assets over time.
As you go through the admin pages, note assets that are unused (such as a field that doesn’t appear on any screens), duplicated (or perhaps similar enough in purpose that only one field is needed) or inactive.
Once you have a complete picture of your current application, you can set goals for your clean-up. Along with removing assets that aren’t being used, goals could include reducing the number of workflows for easier support and reducing the number of custom fields for better performance.
Jira Clean-up Step 2: Archive
Before you begin pruning out unnecessary elements, backup and verify your data. Also, make sure you have a rollback plan in case any of your changes cause unanticipated problems.
Go to the admin page for each element type and use the “identification” column to weed out unused items. The Jira Strategy Admin Workbook includes detailed instructions for easily identifying unused elements. In some cases (for example, if you are eliminating an issue type), you may need to migrate issues before deleting.
Deleting unused items is the first step. Depending on your goals, you may also want to consolidate custom fields or workflows. When consolidating fields, consider which field is more widely used, which has a better name, and which can be more easily deleted. Again, you may need to migrate data before you can delete.
Along with pruning down Jira elements, you should also check for stagnant projects. Use the Jira Strategy Admin worksheet or the ProForma form to identify projects that have an inactive project lead, few issues or no recently created issues.
You have several options for dispatching completed or stagnant projects:
Finally, you need to address users who have left the organization. Don’t users because you want to retain the history of their actions. Rather, set departed users to “inactive.” However, before doing so, Rachel recommends the following steps:
Move any not closed, assigned issues to the user’s supervisor
Move any not closed, reported issues to the user’s supervisor
Remove unshared custom dashboards, filters, filter subscriptions and boards
Remove favorite designations for dashboards
If a dashboard is used by others, move the dashboard to the supervisor or a generic user account
Remove favorite designations for filters
Move shared filters to the supervisor or a generic user account
Reassign project leads to the supervisor
Reassign component leads to the supervisor
Remove filter subscriptions
Remove draft workflows
Reassign agile boards to the supervisor
Check workflows for any auto assignment transition behaviors
Make the user account inactive
Making the time to regularly review and tidy up your application will make your ongoing admin duties easier and will keep your application clean, relevant and high-performing.
More than one Jira administrator has approached me about translating the Jira Strategy Admin Workbook into another language. But I only speak English and Jira Query Language! Enter wonderful Kerwin Chung, a Senior DevOps Consultant in China, who’s up to the task.
Kerwin’s translated the sample “Projects” chapter from Jira Strategy Admin Workbook into Chinese! You can download both the English and Chinese sample chapters for free. If you’re interested in a full Chinese or other language translation, let us know below! If there’s enough interest, we’ll translate the whole book!
About the Translator
Kerwin Chung, ACP-SW, ACP-JA
Atlassian DevOps Senior Consultant at Cenoq in China
The reason why I love Jira is its expandability.
It is the best tool for the DevOps toolchain. Lots of companies in China use a lot of open source tools but they use only one commercial tool, which is Jira.
I am proud of being a Jira evangelist. I enjoyed using Jira to organize my own job and am very happy to introduce Jira to my customers and friends. Everyone loves it.
For most Jira Server users, an upgrade is a major activity that requires careful planning. What is your upgrade plan? How will you prepare? How will you ensure success? How often will you upgrade?
I approach upgrades as five high level steps:
Step 1: Research
Conduct all pre-upgrade “what changed” and compatibility research
This very important first step can determine the success of your upgrade. Start by reviewing the retrospective from the last upgrade so you can improve the upgrade process and plan for issues encountered in the last event. Also, it’s a good time to make sure your emergency rollback plan is still accurate.
Next, read all of Atlassian’s “Release Notes” and “Upgrade Notes” for every version between yours and the one you’re upgrading too.
Look for changes that might impact the application, users, or user behavior. Look for bugs you’ve been waiting for fixes for.
Finally, double-check that your license is valid through the upgrade testing period and you are not about to reach your license limit. You don’t want license issues to delay your upgrade.
Step 2: Pre-Upgrade Tasks (Test Environment)
Copy all production data to lower environments, update plugins, upgrade and test
Don’t have a test environment? Remedy that issue first! Ideally you’ll have a secondary server instance but if that’s not possible at least create a local instance on your personal computer. Make sure the resources powering your test environment match your production environment as much as possible. Make sure the software version and configuration are an exact copy of production.
Before upgrading your test environment, be sure to copy all of your production data to the environment. It’s not enough to test an upgrade on a vanilla instance; you need to test it with your specific configuration data!
By now you should know which version you’re able to upgrade to. Download the installer file, stop the application, and run the binary. Document the installation process, so you can repeat the steps in production. Review all configuration files, paths, custom files, and settings for accuracy. Also check the logs for major problems.
If all is well on startup, it’s time to update the Universal Plugin Manager, other add-ons, and re-index. After the re-index, start your regression testing. Make sure all basic application functions and new features are working as expected.
MISTAKE During testing, I discovered one of my heavily used plugins wasn’t compatible with the upgrade version and had moved from free to paid. I clicked the “Buy Now” button on the “Manage add-ons” page, assuming it would take me to a shopping cart with pricing information. Instead, it immediately installed an unlicensed version of the new plugin code! All of our workflows broke and I was inundated by reports of license errors from users. I had to quickly generate a free trial code to restore functionality and sheepishly contact the purchasing department to secure emergency funding for the new plugin. I did all this in production! #facepalm
Finally, contact your REST API and database users so they can verify all is well with their applications. Also, compile any “new features” documentation to share with end users. Conduct an end user and project-level admin demo if UI or feature changes are substantial.
Step 3: Upgrade Preparation
Line up support resources, schedule production upgrade activities, and announce plans
At this point, you are confident in the stability of your test environment and ready to schedule the production event. Start by identifying an upgrade team. Who will execute the upgrade? Who will “smoke test” the major functions? Who can you contact if there’s emergency?
After you have your team assembled, pick an upgrade time outside of peak use hours. Communicate the upgrade date, time, and expected duration to users and any support teams, like the company help desk or network operations center. Don’t surprise these teams with “Jira is down!” reports during the upgrade window!
Use Jira’s announcement banner function to communicate upgrade plans.
Sample Code: <div style=”border: 1px solid #9e1c1c; background-color: #fff; padding: 10px;”>Upgrade Outage
The upgrade will start on [day], [date] at [time] [timezone] and conclude before the start of business on [day], [date]. During the upgrade window: (1) you WILL NOT be able to login to JIRA, (2) any changes attempted WILL NOT be retained, (3) API calls will fail, and (4) issue creation via email will fail. For a list of new features and fixes, see our JIRA Upgrade notes.
Download sample wording for your entire upgrade process from the Strategy for Jira store.
Step 4: Upgrade Tasks (Production)
Backup production data, update add-ons, upgrade and test
Hopefully you’re already taking regular (automated) backups of your database and file system. But when’s the last time you verified that your most recent backup occurred and is actually usable? Do that before proceeding.
At last, you’ve planned as much as possible, know what to expect, and are ready for the upgrade event! It’s time to repeat the installation steps you practiced in your test environment including: installation, add-on updates, and regression testing. Use the notes you took in step 2 and be sure to address any differences that exist in the production environment.
Step 5: Communication
Announce upgrade and communicate changes and benefits to user base
Finally, it’s time to announce the upgrade to users and complete post-upgrade steps.
Use Jira’s announcement banner function to communicate the upgrade is complete. Include a link to the “new features” documentation you compiled in step 2.
Review any previous trouble reports, in case the upgrade remedied them, and be ready to respond to new reports. Check in with your REST API and database users, to make sure all is well with their apps.
Finish any outstanding tasks, compile your retrospective, and make any needed plan updates in preparation for the next upgrade. Also be sure to thank your upgrade team!
Detailed Upgrade Plan
A well-crafted plan can help ensure upgrade success. Download the sample upgrade plan worksheet. Customize it to fit your needs and environment. This worksheet may contain more or fewer steps than necessary for your situation, but it gives you a great starting point. Don’t forget to update and improve the plan after each upgrade.
A test instance and a healthy application are the foundation of a successful upgrade event. You’ll want to upgrade often for the newest features, fixes, and performance improvements. Happy upgrading!
If you’re on a software team, you probably use the default Jira workflow or something close to it. But what if you’re on a business team or the default options don’t fit the way you want to work? Then it’s time to create a custom workflow.
A workflow is a standard set of statuses (steps) and transitions (movement between steps) that each issue follows in its lifecycle. Statuses take an idea from “conception” to “completion”. Each Jira project can have its own workflow and each issue type within a project can have its own workflow as well. For example, the Legal team has a specific process for contract review and a general process for all “other” types of requests. Their Jira project might include issue types like the standard “Task” and a custom type like “Contract.”
The “Task” issue type has a very simple workflow, with the statues “To Do” and “Done.”
The “Contract” issue type requires additional statuses for approval and execution steps that occur in a contract review process.
RECOMMENDATION In the beginning, keep workflows as simple as possible, until you’ve uncovered a deficiency or process step that needs special attention.
Custom Workflow Tips
The steps below outline the best practices for creating a workflow:
Before creating a new custom workflow, have the user explain their real life process to you. The workflow should be as simple as possible.
First, draw (preferably on paper) a workflow to ensure it makes logical sense and all forward and back transitions are accounted for. You can use the “Custom Workflow Documentation” template in the Jira Strategy Admin Workbook or in ThinkTilt’s Process Template library as a way to communicate and document workflows.
After drawing the workflow, write the workflow out in words. This can uncover additional needs you may have neglected to draw or consider.
Include logical backwards transitions so users can self-manage issues.
Give users options to abandon or stop progress on issues at appropriate times.
Give project-level administrators appropriate options to fix improperly transitioned issues.
Example: Include a “reopen” transition button in the final status to address issues that were improperly closed.
Use transition conditions sparingly. If a condition is needed, set the restriction to a project role, rather than to an individual, for easy maintenance.
Use transition validators and post functions to minimize the amount of manual work a user has to do.
Automatically assign an issue to the reporter when moving to an “information needed” or “verification needed” type of status.
Automatically assign an issue to the Project Lead in a “triage” type of status.
Automatically move a parent issue to “In Progress” when a child issue starts progress.
Name your statuses:
Name statuses so they reflect the current state. Good status names immediately tell a user what is occurring and what state an issue is in the workflow process. For example, “Pending Review”, “In Review”, “Being Reviewed”, “Awaiting Review”, etc.
Make any status names short and easy to understand what is happening. Long, multi-word names are harder to query and may be truncated on certain screens.
Name your transitions:
A Transition name should be short and reflect an action taken.
Good transition names immediately tell a user what action to perform to progress an issue. Example: For an issue in “Pending Review” status, a good transition name would be: “Review Complete.” If you need a “pass/fail” situation, where an action must pass a test before a transition can occur, good transition names would be: simply “Pass” and “Fail.”
Bad transition names confuse the user about how to move forward. Example: “Review.” A transition button should signify the start or end of an action. The word “Review” is ambiguous. If a user clicks “Review,” does that mean they should start a review or that the review has already occurred?
It’s easy to customize workflows and therefore easy to go overboard, creating more structure than you really need.
It’s certainly possible to capture every little step in your work process and build that into a complex and long Jira workflow. An alternative however, is a phased approach. Simply break your process into phases that represent a collection of smaller steps. The phases represent key decision points. An issue can’t be moved to another phase until the requirements of that phase have been satisfied. Your Jira status represents the entire phase, rather than a status for every small step in the phase.
Example: Your company is signing a partnership agreement
The contracts process requires a review of the contract by both parties and potential edits before final execution. It’s a predictable process requiring a short workflow like:
Open > In Review > In Execution > Closed
TIP A generically named status like “In Review” is better than a legal-specific name like “In Contract Review”. Other Jira projects can use the generic version regardless of what type of thing needs review. You want to share assets and schemes between projects as much as possible.
The Legal team is doing many things in the background that may not need to be reflected in the workflow. For example:
In the “In Review” phase, the Legal team is reviewing the contract, researching legal topics, communicating with internal teams, negotiating terms with the external company, etc.
In the “In Execution” status, the CEO is finding his favorite signing pen, both companies are trading paperwork, and your Legal team is entering the final result into their contracts database.
In the above example, is it useful to create a status for every step that occurs in the contracts process? Do you need to track how many times the contract was modified during the review process? Do you need to track which parties have signed the agreement so far? If the answer is “no” a phased approach may be more useful. Also, it might be more useful to track signature collection in a custom field.
RECOMMENDATION If you’re not going to report on something (ex: “How many contracts have been signed by us?” in the above example) that status or custom field may not be necessary or useful.
Don’t over-complicate your custom workflow with steps and statuses you don’t really need. Your end users will thank you for it.