Jump to content
Search In
  • More options...
Find results that contain...
Find results in...
  • Jimi Wikman
    Jimi Wikman

    Setup Jira and Confluence for success - Part 3: Defining Jira workflows

    • Like 1
    • Thanks 1

    In the previous articles we have defined what tool to use for what and what issue types we need. New it's time to define the workflows for those issue types. Before we can do that however we should first define what workflows are and how we should use them in Jira.

    Three types of workflows
    In short we can narrow down workflows to three types: sequential, state machine and rules driven workflows.

    Sequential workflow
    This workflow is usually chart based from one step to the next, always moving forward without ever going back. Each step depends on the completion of the activities on the previous step. You can think of this workflow as a connect the dots system: you have to follow the numbers correctly, one after the other, to complete the big picture.

    State Machine Workflow
    This type of workflow can be considered like puzzle solving, in which you’re constantly putting important pieces in place to complete a project. State machine workflow are frequently used when there are creative elements in the process, or products and services that require extra review or input from clients and management.

    Rules-driven Workflow
    This workflow is executed based on a sequential workflow with rules that dictate the progress of the workflow. This can be compared to following a blueprint to make one complete structure. Rules driven workflows are very useful when working on a variety of projects with clear goals but varying levels of specifications.

    We should also define what a workflow is NOT:

    • A workflows is NOT a process - A process is more then just a workflow as it includes data, forms, reports, actors and more. A workflow usually span over multiple processes as we hand over responsibility between different capabilities (requirement, development, test, acceptance).
    • A workflow is NOT a list of unconnected tasks - Unconnected tasks are task management and not a workflow.
    • A workflow is NOT a checklist - Checklists are binary. It's either done or not done. That is not a workflow.
    • A workflow is NOT a state diagram - This is probably the biggest issue I see when people try to design workflows. The idea that you need to track every single state in a workflow comes from a misunderstanding of who we actually build workflows for and what they actually need.


    "A state machine (panel (a)) performs actions in response to explicit events. In contrast, the flowchart (panel (b)) does not need explicit events but rather transitions from node to node in its graph automatically upon completion of activities." - Wikipedia



    Who do we build workflows for?
    In order to understand why state diagrams are not the best choice to design workflows in Jira we should understand who we build workflows for and what purpose they serve.

    The reason we use Jira is because we  want a good way to define and assign work. We also need a way to oversee, or manage, the work. This means that we want a way to track what work we are doing, what the current status is on that work and who is responsible for completing the work at the moment.

    So for developers and testers we want en easy way to see what is ready to be worked on, what is being worked on and and what have we completed. For managers we need the same, but over the whole chain of responsibility. We also want to connect the work to the need so we can follow up when the need is being fulfilled.

    So we have two basic need to fulfill:

    1. What is ready for me to work on?
    2. Are we on track to fulfill the need or do I need to take action?

    In the previous article we mentioned transitional and producing items when defining what issue types we need. We can match these theories with these two need as well. #1 is producing as we just need to track the actual work in a fetch and release process. For #2 we use transitional as we want to track all areas of responsibility.

    Based on this we can see that there is no need to see everything that happen in the work we do. We need to see who is doing what and if there are any impediments that could prevent us from completing the need in time. This is why we choose to work with flow charts and not state diagrams.


    "Design for collaboration, not control"


    If you feel that you must track every single step in the work, then I suggest you take a look at why you need that. Usually it is because you lack trust in your organization due to poor communication or that someone in the chain of management suffer from an unhealthy need for control. Either way you should fix that outside of Jira as we should design for collaboration, not control.


    What statuses do we need?
    So now that we know what types of workflows we have to work with and what the need is we need to fulfill, then it's time to break down what statuses we actually need. We start by defining the different areas of responsibility that we need to track in our workflows.

    • Development
    • Test
    • Acceptance

    First we start with adding a waiting status in each so we can fulfill the need of knowing what is ready for us to work on. This will also allow us to get statistics on waiting periods to see where we have resource issues. We name them the same to keep a proper naming convention: "Ready for <area of responsibility>".

    Secondly we add a status for when someone is working on something. Again we can track this for statistics, but most importantly we can quickly see what is being worked on and by whom. We name this the same as well: "In <area of responsibility>.

    We end the basics with setting a Closed status as the last status. This will allow us to set a resolution and indicate that the development work has been completed and is ready to be deployed. I often see people adding things like resolved or done, but in a workflow you should not have partial closure and there is actually no need for it.

    We now have the basics for a fetch and release process and we have fulfilled the first need.


    Skärmavbild 2019-09-01 kl. 14.05.29.png


    In order to fulfill the next need we need to add a few additional statuses, but first we should change the starting status. In Jira we have Open as the first status when a  new issue is created. This is a bad status as it is not clear what Open really mean and I have seen whole organizations failing due to this misunderstanding. So we will rename this status to New if we can do that for the whole organization. If not, then we create a new status and use that as our first status.

    In order to track when something is blocked or waiting for something we add a status called Waiting/On Hold. Even though we can use the flag function to visualize this I have found that a dedicated status usually make this far more visible in the boards.

    We will also add a Reopened status in the event that we need to open a closed status for some reason. This either happen because we close by mistake, but in the event that someone actually revoke a closed issue we want to track that. Adding this is a status allow us to define how we want to handle this situation later.

    Finally we will add a status mostly used for defect management, but it can be used in any development workflow. That status is Rejected. While this can sound like a very harsh status it's purpose is to revert something back to the reporter for clarification rather than using the Close status and then Reopen.

    With just these few statuses we can manage both need to see what is ready for me to work on (ready for <area of responsibility>), who is working on what (In <area of responsibility>)and if there are any issues that need attention (waiting/on hold). We can not take any issue type and look at what area of responsibility is involved in fulfilling that task and then map the statuses we have defined to that.

    All generic workflows will have the same statuses. This makes it very easy to work with boards and no matter what capability you work with you always have only 3 statuses to keep track of: ready for me to work on, I am working on this, ready for someone else.


    What about release management?!
    Another common question is how I handle release management since there is no statuses for release. The answer to that is that we do not need that since Jira has that built into the core system in the form or versions. Every development should be closed with at least one version in the Fix Version field to indicate what code package the code is placed in. Every defect should also have an Affect Version that indicate what version of the code the defect was found in.

    By doing this we can map what code is in what package, but Jira should never be master for this information. This information should come from Bitbucket, or similar code versioning tool. This is also the same for deploys, which we do not manage in Jira at all since that is a completely different process. This comes from Bamboo or similar tools.

    The idea of managing deploys as a status in Jira quickly become silly as you would have a separate step that happen long after development, test and acceptance has been completed. This task is unconnected to the areas of responsibility. It is not a producing step, just a transportation step that is done not on story level, but on code package level. Like we established above this is not a part of a workflow since it is an unconnected task. We will however keep track of deployment in Confluence, but we will get to that in later articles.


    Let's build the default workflow
    Let us take all the theories above and make it real by designing the workflow in Jira and see if it hold up for real work.

    Skärmavbild 2019-09-01 kl. 15.30.53.png


    Requirement & business processes happen outside of this workflow. The expectation is that the beginning of the workflow comes in the form of a clarified need as a story. Even in Agile way of working the story is clear enough to be worked on once put into the ”Ready for Development” status.

    Once a story is clear enough to be worked on and we have acceptance from Development and Test, then we move the story to the status "Ready for Development". Producing items are created for development and we start working on the issue  by transition the store to In Development.

    Once done we transition the story to Ready for development to complete the fetch and release process. This is repeated in the test and acceptance steps. In the event that we get a defect, then we create a defect sub-task and block the story from completion. We can use this for all development tasks as they all follow the same path.

    Let's see how we set this up in Jira.


    Building workflows in Jira
    In order to build global workflows in Jira you need Admin access to Jira. Go to Jira Settings ->  Issues. Here you will find the two sections we need to configure to build a new workflow and to assign it to a project. Under Workflows you will see the current active and inactive workflows. In the top right corner you will see a button with the text "Add Workflow" Click that and you will get a popup to enter a name for the workflow and a description.

    Skärmavbild 2019-09-01 kl. 15.41.46.png

    Once you have added a name and description you will come to the design view. Here you use the "Add Status" to add the statuses we want. We create them with global transitions to make the workflow as open and flexible as possible by checking the box "Allow all statuses to transition to this one".

    I usually have transitions between rejected and new, as well as for Closed to Reopen, just to make it more clear that the rejection is used in a certain part of the workflow. This way you can't go to rejected or reopened from other statuses than the intended ones. In a proper workforce where the users get education on how to use Jira this is not really needed however so you can skip that if you do not feel it is necessary.

    Skärmavbild 2019-09-01 kl. 15.54.24.png


    Add Workflows to a workflow schema
    Now we can go to workflow schemes where you find all your active and inactive workflow schemes. in the top right corner you have a button with the text "Add workflow scheme". Click that and in the popup you add the name and description of your scheme. You will then be taken to the screen where you add workflows to the scheme and map it to specific issue types.

    Click the add workflow button and select the workflow we created earlier. In the next screen you get to select which issue types you want to map to this workflow. Select the ones you like, which should be all of our development issue types and then click finish. Your scheme is now configured with a workflow that is mapped to the issue types you want. You can edit this scheme at any time should you add workflows and/or issue types.

    Skärmavbild 2019-09-01 kl. 16.03.27.png


    Add Issue Type Scheme to your project
    Go to your project and then click on project setting in the left menu. It should be at the bottom of the list of areas for your project, but if you can not see it then you may not have admin rights for your project and you need to get some help with this step. If you have access then in the project settings go to Workflows.

    Here you see your current workflow schema and the workflows attached to it. To change click on "Switch Scheme" and select the new scheme that we created above. Click associate and if needed map statuses on the next screen and wait for all statuses to resolve. Once done you have your new workflow scheme mapped and you can start using your new workflow.

    Skärmavbild 2019-09-01 kl. 16.09.44.png


    We now have workflows setup for our issue types, but we still have a few things to do before they are completely ready to be used. That is to define the screens and custom fields we will use in our setup. That will all be explained in Part 4: Defining Jira Screens & Custom fields that we will look at next.


    Edited by Jimi Wikman

    • Like 1
    • Thanks 1

    User Feedback

    Recommended Comments

    There are no comments to display.

    Join the conversation

    You can post now and register later. If you have an account, sign in now to post with your account.

    Add a comment...

    ×   Pasted as rich text.   Paste as plain text instead

      Only 75 emoji are allowed.

    ×   Your link has been automatically embedded.   Display as a link instead

    ×   Your previous content has been restored.   Clear editor

    ×   You cannot paste images directly. Upload or insert images from URL.

  • Similar Content

    • By ©Jimi Wikman
      A simple icon set for Priorities I use in my own Jira instance.
      It uses colors to indicate priority / Severity ranging from full red in the blocker and then scale down in the color range down to purple for the lowest.
      The symbols are simplified as well to make them as visible as possible.
      Blocker - Full red with a blocked icon as the indicator. Highest - 7 sided background in deep red with a white exclamation mark. High - Orange triangle pointing upwards. Medium - Green circle Low - Blue triangle pointing downwards. Lowest - Three purple dashes.
    • By ©Jimi Wikman
      View File Priorities
      A simple icon set for Priorities I use in my own Jira instance.
      It uses colors to indicate priority / Severity ranging from full red in the blocker and then scale down in the color range down to purple for the lowest.
      The symbols are simplified as well to make them as visible as possible.
      Blocker - Full red with a blocked icon as the indicator. Highest - 7 sided background in deep red with a white exclamation mark. High - Orange triangle pointing upwards. Medium - Green circle Low - Blue triangle pointing downwards. Lowest - Three purple dashes. Submitter ©Jimi Wikman Submitted 02/04/2020 Category Graphics  
    • By ©Jimi Wikman
      For agile teams, all product release cycles typically follow the same route –
      Once the storyboarding is completed, backlog is set up in Jira, tasks are assigned to development after you work out the estimates. Then it is time to ship the application to an initial release. Agile teams across the world are familiar with Jira – the collaboration tool designed for issue and project tracking developed by Atlassian. While the basic use of Jira is to track issues, bugs etc. with your mobile and software apps, many teams have extended its use beyond just planning, managing and reporting.
      For example, some DevOps teams like using Jira for test case management. And with a little creativity, a little customization, it can absolutely be configured to support manual test case management.
      However, when it comes to supporting Test Automation in Jira, there is no direct way of doing that in Jira. The only way to incorporate or support Test Automation in Jira is by installing supporting apps from Marketplace in your Jira instance.
      Now there are two categories of apps that could help your agile teams achieve test automation in Jira.
      One is – Test Automation Apps. The problem with these apps is they only support automated test cases. Now to manage manual test cases, you will still have to rely on some other marketplace apps or do it in Jira as suggested earlier.
      The other option is to install – an app from the category Test Management Apps.
      QMetry Test Management for Jira (QTM4J) offers complete test management capabilities to Agile and DevOps Teams inside Jira. QTM4J provides powerful test authoring capabilities for Manual Testing as well as provides seamless integration with Automation tools.
      QTM4J has integration capabilities with automation tools such as QAF/QAS that is QMetry’s Selenium based framework and IDE developed as part of contribution towards Open Source Community. It also allows integration with other automation tools such as HP UFT, Cucumber, Specflow, JUnit and TestNG.
      So how does this Test Automation work inside Jira?
      QMetry Test Management for Jira integrates with Automation Tools which then allows users to import automation test results into Jira.
      Now there are two different ways of integrating with the automation tools –
      Users can directly import their automation test result (JSON/XML/Zip) files using a REST API as soon as the automation test gets executed, which creates a new test run in Jira with all associated test cases and results as executed in the automation test. QMetry can easily integrate with other CI/CD tools. There are ready made plugin available for Maven, Jenkins and Bamboo for importing test results. So next question that arises is – How does Test case reusability work to avoid repeatability between manual and automated tests? This is how QTM4J ensures reusability –
      If Test case summary and Test step summary (for all steps) matches with the automated Test case, Test case key and version will be reused. If Test case summary matches and Test step summary do not match (for any of the steps) with the automated Test case, Test case key will be reused but new version will be created. If Test case summary does not match, new Test case will be created. Combining the power of Jira and automated testing can remarkably speed up your cycles, improve collaboration and execute metrics that help with project delivery and visibility.
      To see this in action, sign up for a free trial of QTM4J.
    • By ©Jimi Wikman
      This is a repost from Atlassian's blog where the latest updates to the Atlassian cloud platform is posted. It is reposted here since the Atlassian blog does not have an RSS feed and so we can discuss the changes to the Atlassian Cloud architecture. You can follow these posts withe the tag "atlassian cloud changes".
      Atlassian Cloud
      Your cloud-hosted products are supported by the Atlassian Cloud platform. This section usually includes changes related to multiple Atlassian Cloud products, site administration, and user management.
      See location details in the audit log 
      The audit log has a new Location column that displays the IP address where the activity took place. Read more about audit logging.
      Email users with suggested account changes 
      From the Change details button, you can suggest that a user changes their account details to make their profile more consistent and easier to identify. Read more about administering Atlassian accounts.
      Give your users a Trusted permission 
      From a user's Permission options, select Trusted to give certain users more responsibility. These users will be able to install and configure new products on your site and invite new users themselves.
      Claim accounts after verifying a domain 
      To start managing accounts on your domain, we’ve included an additional step that requires you to claim accounts after verifying that you own the domain. From the table on the Domains page, click Claim accounts next to the verified domain. Read more about verifying a domain.
      Set your language and time zone for Jira and Confluence in your Atlassian account profile 
      Rather than individually setting your language and time zone in Jira and Confluence, these preferences will soon come from your Atlassian account profile. Visit your account preferences to update these settings. It may take up to 10 mins before your updated preferences are reflected in Jira and Confluence.
      Jira platform
      Changes in this section usually apply to all Jira products. We'll tell you in the change description if something is only for a specific Jira product.
      New user profile cards 
      When you hover over someone’s name in directories, on dashboards, and in user picker fields, you’ll now start to see rich profile cards with more information and a link to the user’s profile (if you have permission to see it).
      Next-gen: Epic panel in backlog 
      You can now manage epics on the backlog of your next-gen project via the Epics panel, similar to how epic management works in classic Jira Software projects. Changes you make in the panel on the backlog will reflect on the Roadmap, and vice-versa.
      Having trouble with next-gen projects? Better help is here. 
      We improved our in-product help experience. Try the Help button in the navigation bar to see help articles related to your next-gen project or service desk.
      Advanced search (JQL): Search for content updated by a specific user
      Use the updatedBy() function to search for issues that were updated by a specific user, optionally within the specified time range. For example, if you want to find issues updated by John Smith between June and September 2018, enter issuekey IN updatedBy(jsmith, "2018/06/01", "2018/08/31"). Read more about the updatedBy() function.
      Portfolio for Jira - Scheduling Team Sorting 
      When scheduling work, Portfolio now prioritizes teams that have associated issue sources over teams that don't. Also, teams without issue sources will only be considered if they have capacity to complete work earlier.
      Jira Software
      We're rolling out a new type of project known as next-gen. By default, any Jira Software licensed user can create their own next-gen project. These projects don't affect existing Jira projects, shared configurations, or your schemes. You can manage who's allowed to create next-gen projects with the new Create independent projects global permission. Read more about next-gen projects.
      Enforce CSFR protection on Agile 2.0 mutations 
      If a user attempts to perform any JSW create/update action with a stale Xsrf token, they will be presented with an error flag with a message:
      Our session has expired
      Refresh the page and try again
      GitHub app on the Atlassian Marketplace 
      We've partnered with GitHub to build a new and improved integration, which you can install at the Atlassian Marketplace. This replaces the DVCS connector in Jira's system settings. Current GitHub integrations set up under the old method will continue to work, but new integrations must be set up using the app on the Atlassian Marketplace. We're rolling out this update gradually, so it may not be on your Jira Cloud site yet.
      This won't affect GitHub Enterprise integrations, which must still be set up via the DVCS connector.
      Next-gen: Roadmap issue hierarchy
      You can now expand an epic on your roadmap to see its child issues and their statuses. Learn more about managing epics on the roadmap.
      Next-gen: Create child issues on your roadmap 
      You can now add child issues directly on your roadmap. Just hover over an epic, click the + icon, and give your issue a name. Learn more about managing epics on the roadmap.
      Next-gen: Environment system field in JSW
      Add Jira’s built-in Environment field to your issue types in next-gen projects. In your project, go to Project settings > Issue types and drag the Environment field into the Description section of the issue layout.
      Jira Service Desk
      Automatically clear the value of a request's field when changing its status in your next-gen service desk  
      We improved our “Update a request field” workflow rule. Now, you can use the rule to clear your request’s fields when someone moves the request using a specific transition.
      New issue view for Jira Service Desk 
      The new issue view groups key actions and information in a logical way, making it easier for you to scan and update requests. Learn more about the new issue view.
      Use keyboard shortcuts in your queues 
      Use keyboard shortcuts to navigate around your queues and get your work done faster. You can now move through issues, select their fields, and go to the issue view from your queues just by using your keyboard!
      Customer portal request details page redesign 
      We have redesigned the customer portal request details page to make it easier to use. You’ll notice we have added a rich text editor, sorted the activity stream from old to new, and have moved the location of the request fields, share button, approval and comment boxes.
      Maintenance complete on the customer portal user profile page 
      We have just completed some maintenance on the customer portal user profile page.
      We also introduced a new layout that is easier to use on mobile devices. Go team!
      Easier configuration for the new issue view 
      If you have the new issue view, you can now easily configure how your issue view looks for each request type.
      From your service desk project, go to Project settings > Request types and you'll find the new layout for making changes.
      Global create can select request type and raise on behalf of 
      You can now create a request on behalf of your customers and set them as the reporter. Use the global create button ( + ), then select Raise this request on behalf of and add in your customer's email.
      Convert legacy editor pages to the new editor  
      Our goal is to allow you to convert your pages from the legacy editor to the new editor without data loss and with little to no changes to the look and feel of the content, which is why you’ll have control over which pages get converted and when. You'll also have the option to preview any page before converting it. We want you to feel comfortable with the process. You'll also have the chance to restore a page to its previous, legacy editor version after conversion. Learn more
      Your editing experience just got an upgrade 
      The new Confluence editor allows anyone to create beautiful, powerful pages effortlessly. Check out the editor roadmap to learn more.
      We're extending editing improvements to all pages on Android 
      The editing improvements we made to blogs a few months ago are coming to the rest of your Android mobile pages, too. In addition to being faster and more reliable, your new pages are also responsive, optimized for readability, and have advanced tables. Some macros are still missing as we rebuild them, but you can check the list of changes and track updates to macros on our docs site.
      Annotate images in the new editor 
      Annotate images by adding text, inserting shapes and lines, using brushes, or adding a blur to a certain area.
      Confluence Cloud recent pages drawer 
      We’ve made it easier to get to the pages you visited or worked with most recently. A new action has been added to the global sidebar that presents you with a list of your recent pages; interaction-specific tabs help you narrow the list based on your actions, like visited, edited, or saved as draft.
      Share pages directly with your team 
      It’s now easier to share pages with everyone on your team, all in one go. When you click Share on any page or blog post, Confluence now lets you add a team – no need to enter each person individually. Learn more
      Jira issue URLs are converted to smart links 
      When you paste a Jira issue link into a Confluence page, the URL is converted to a smart link that displays the page icon and the page title. This works if the Jira and Confluence sites are linked or if they are both cloud versions.
      Convert pages to use the new editor 
      You can now convert your existing pages that were created using the legacy editor to use the new editing experience! Learn more
      Confluence navigation just got better 
      Get to information faster with improved navigation – making what you need visible from anywhere in Confluence. Learn more
      Align and resize images in tables in the new editor 
      When images are inserted in table cells, you now have the ability to align and resize them.
      Portfolio for Jira plan macro 
      The Portfolio for Jira plan Confluence macro lets you embed a Portfolio for Jira Server and Data Center plan in a Confluence page. Join key stakeholders in the spaces where business goals are built and tracked, and share how work is progressing across multiple projects and teams.
      Improved expand element replaces the macro 
      Content creators just got a better way to control the way information is presented. The existing expand macro has been replaced with a quicker, easier way to include the expand functionality. Insert the improved expand element using /expand or by inserting the element from the editor's Insert toolbar.
      New Code Review - Limit the amount of rendered diff content 
      Limits the amount of pull request content rendered in the diff and file tree to improve browser performance. Limits include the overall # of files and # of lines for the entire diff. Learn more
    • By ©Jimi Wikman
      One of the most common questions I get is when to use the issue type Task in Jira. This is not surprising since Jira is intentionally not defining how to use the issue types and their hierarchy. This is to avoid restricting the users from building a way of working that is best suited for them. In this article I will explain my thoughts from a development perspective.
      As I have described before in the article "Setup Jira and Confluence for success - Part 2: Defining Jira Issue Types" there are three levels in the standard Jira hierarchy. Task would fall into the middle level and the sub-tasks would be the last level. This means that Task would be on the same level as a Story and that is what we can start from when defining what should a Task be for in a development perspective.
      In a normal workflow for development we would have a Story issue created as a result from the requirement, or need if working Agile, process. So the Story would map towards a need or requirement and as such we would have a workflow where we can trace actions from idea all the way to production.

      Then where do Task fit into that workflow?
      In most cases it will not as a task would not be a part of a requirement or a need. That is what a Story is for. A Task is most likely only going to be used for Task management rather than as a workflow. This means that a Task would most likely be something that have limited states such as New, In Progress and Closed. It might even just have New and Closed to be even closer to the way task management is defined.
      In a development situation where you need to have a workflow a Task is best suited for activities that are not directly related to the workflow. Things like setting up environments, prepare presentations or Demos and even things like buying cake for the next retrospective (which of course always is mandatory!).
      If you use Tasks in this way, then sub-tasks would follow the same pattern. For a development task for example you might need to schedule a meeting with an external vendor to go over the API details for an integration. For a test task you might need to organize a workshop for end to end testing across multiple teams and systems and so on.
      In short, my definition is that Tasks are used for internal task management that is not directly related to the workflow.
      Do you agree or disagree?
  • Create New...