Worklog Assistant: Custom Workflows

Understanding custom workflows and transitions in JIRA

One of the most useful features in JIRA are the custom workflows. Custom workflows are a kind of finite automaton, which means that you have different states which can be triggered with the appropriate transition. Each transition is identified by an id, so that every transitions is unique. Unfortunately there is no easy way in Worklog Assistant to trigger a transition so that it will change the state but i will explain this in detail later.

Lets take the default JIRA-Workflow for example and analyze it.

As you can see, the transitions are described by the grey arrows. If you want to know, in which state your current taks is, you can use the in-build view in JIRA. A more technical way to do that is by using the JIRA REST API. The API-Call to list all available transitions from your current state is transitions.fields

https://JiraUrl/rest/api/latest/issue/<strong>yourjira-ticket</strong>?expand=transitions.fields

Lets put it together for a real world example

https://JiraUrl/rest/api/latest/issue/<strong>TEST-123</strong>?expand=transitions.fields

Ensure that you are logged in into JIRA. If the ticket exists, you now should see some text results on the screen. Actually its a JSON-Response which seems to be a little bit unreadable. If you are able to parse the code in some programmatic ways, then you are fine, otherwise if you want to have a more human readable presentation, you could use online tools like JS Beautifier. Just copy and paste the whole content into the editor and explore the results.

When handling with transitions and states, the following two entries are interesting (Just search for similar entries, as my JIRA is configured to be in German language).

I want to know the current state of my application

This is pretty useful as you can use this entry to check, in which state your application is. Also you can easily take a look at your workflow diagram and you will see which transitions are available.

"status": {
            "self": "https://<JiraUrl>/rest/api/2/status/1",
            "description": "Der Vorgang ist offen und bereit, dass der Bearbeiter mit der Arbeit daran beginnen kann.",
            "iconUrl": "https://JiraUrl/images/icons/statuses/generic.png",
            "name": "Offen",
            "id": "1"
        }

Displaying the possible transitions

If you want to use the API to trigger any transitions, then you will need the transitions-ids. Again: The REST-API will only display the possible transitions from your current state. If you can not see a specific transition, check that your ticket is in an exptected state or recheck your workflow rules.

"transitions": [{
        "id": "4",
        "name": "Fortschritt starten",
        "to": {
            "self": "https://JiraUrl/rest/api/2/status/3",
            "description": "Dieser Vorgang wird gerade durch den Bearbeiter bearbeitet.",
            "iconUrl": "https://JiraUrl/images/icons/statuses/generic.png",
            "name": "In Arbeit",
            "id": "3"
        }
    }, {
        "id": "5",
        "name": "Vorgang lösen",
        "to": {
            "self": "https://JiraUrl/rest/api/2/status/5",
            "description": "Eine Lösung wurde ermittelt und wartet auf die Verifizierung durch den Benutzer, der das Problem gemeldet hat. Von hier aus können Vorgänge erneut geöffnet oder geschlossen werden.",
            "iconUrl": "https://JiraUrl/images/icons/statuses/resolved.png",
            "name": "Erledigt",
            "id": "5"
        }
    }, {
        "id": "2",
        "name": "Vorgang schließen",
        "to": {
            "self": "https://JiraUrl/rest/api/2/status/6",
            "description": "Der Vorgang wird als erledigt betrachtet, die Lösung ist korrekt. Geschlossene Vorgänge können erneut geöffnet werden.",
            "iconUrl": "https://JiraUrl/images/icons/statuses/closed.png",
            "name": "Geschlossen",
            "id": "6"
        }
    }]

Adding support for custom transitions in Worklog Assistant

So, why is this so useful for Worklog Assistant? If you do not know Worklog Assistant, let me give you a short overview: Worklog Assistant is a very useful tool for tracking and logging your work and time with a desktop-based application on the client side and JIRA on the sever side. I can easily start on a ticket just by double clicking on the specific issue. A green background will indicate that the work is in progress. Worklog will also automatically change the state of your ticket in your default JIRA setup. So if the state was "Open" before, Worklog Assistant will automatically change the state to "In Progress". That is very handy for most JIRA-Installations.

But this will only work if you use the default worklog scheme as Worklog Assistant use hardcoded transistion ids. So for more advanced and custom workflows the states will not be changed automatically as Worklog Assistant can not know the transitions ids of your custom workflows. So you need a way to deal with it. This is where the "Custom Scripts" are useful. Custom Scripts are Shell-Scripts. So if you know how to write a Shell-Script, you should also be able to write a custom script.

Worklog Assistant comes with a complete set of build-in environmental variables - a full list is available at the companies blog.

Custom Scripts can be triggered on four different ways:

• Context Menu
• Worklog Export
• Issue Timer Toggle
• Timed Script

My use case is very simple: If i start working on a issue, then the script should automatically change into the right state, so using the "Issue Timer Toogle" seems to be the best choice! The script itself is also not very complicated. I have build a small script, which you can check here.

if [ "${JIRA_Status}"  == "Offen" ] || [ "${JIRA_Status}"  == "Open" ]
 
then
  # Fortschritt starten
  TRANSITION_ID=4
else 
  # Fortschritt stoppen
  TRANSITION_ID=301
fi
 
read -d '' data << EOF
{    
    "transition": 
    {
        "id": "$TRANSITION_ID"
    }
}
EOF
 
echo $data > /tmp/worklog.jira
curl -D- -u username:password -X POST --data @/tmp/worklog.jira -H "Content-Type: application/json" https://JiraUrl/rest/api/latest/issue/${JIRA_Key}/transitions?expand=transitions.fields

So what happens now is that at any time when you trigger a issue, the script will get fired. This use case is very simple but can easily be extended to be more advanced.

Conclusion

JIRA in Combination with Worklog Assistant are great tools to boost your productivity. I really would like to recommend anyone who is working with JIRA to at least try the trial version. The customer support is one of the best in the industry and you get your Return on Investment within a day.

Updates

Sohail, the developer of Worklog Assistant told me, that he has introduced two new environmental variables "JIRA_LoginUser" and "JIRA_LoginPassword" which will make your custom scripts more "shareable".