Working with Easy for Jira
Easy for Jira was designed to reduce effort, but it won’t code by itself yet so you need to catch some basic concepts of Jira and how app such ours, explore the APIS to make the engine available.
Modules
We do have a few modules to explore in Easy for Jira, such as Listeners and Post Functions, often allied to the use of the Code Repository.
Modules will allow you to put Python code to work on your workflows and events.
Recommendations
The two main recommendations We can outline from my usage/experience with the app are:
Both usually are used together.
Easy for Jira Wrappers (Context Variables)
To do that, we’ve worked out a few wrappers, those wrappers are designed so you use less code, that allows you to
DEVELOP → TEST → VALIDATE → DEPLOY faster.
The wrappers we currently have available are outlined here:
Each one will have some specific examples and usage you can explore and use to scale integrations, make your systems more dynamic and your life much easier. We will not explain all of them in detail, just the ones that if you master, you get to the mastery of the app.
The Issue Object
Let’s explore the Issue Object, the main object in Easy for Jira, this class was tailored specially to minimize the iterations from the user to be able to work the issue data, so when you need to edit information from the issue, you don’t have to recur to the API, you can use the issue.set(field, value) function.
If you are using it on Post Functions you can do the following using the issue context:
issue.set("description", issue.fields.description + " This was added on transition.")
This block of code will just append some text to your description field.
To explain what happened in there, during the transition, Jira communicated with EFJ, which received the issue data and transition data, and performed the action that you asked for, which is to set the description field as description + some more text.
This is all made using the APIS, but we created a wrapper so you don’t have to be calling the lower level functionality to do it, as the name suggests, It’s supposed to be Easy.
To understand better how the structure of an issue works, you should go to:
https://<yourjiracloudsite>.atlassian.net/rest/api/2/issue/<anyissuekey>
Replace the placeholders and read the structure of the response, it should look like:
issue
key
id
fields
summary
description
labels
status
name
id
statusCategory
....
...
When using the Issue object, the structure you have available is exactly that, so you can get the summary of an issue like this:
summary = issue.fields.summary
or get the labels as a list as follows:
labels = issue.fields.labels
And perhaps you want to get the issue key, or the parent issue key
key = issue.key
parent_key = issue.parent.key
The API Object
The API wrapper allows you to interact with your instance and even to make web requests towards the Jira official API.
resource = api.get("/rest/api/2/<resource>").json()
resource = api.put("/rest/api/2/<resource>", {key: value}).json()
resource = api.post("/rest/api/2/<resource>", {key: value}).json()
The API also allows you to search for issues:
issues = api.search_issues(jql)
Or iterate them directly:
for issue in api.search_issues(jql):
# do something
You can also interact with instance objects such as Projects
api.project("ABC").update(**kwargs)
api.project("ABC").set_lead(accountId)
Depth Look into Common Issues
On your day to day as a Jira Admin versed in the arts of Easy for Jira, you will eventually face different problems with the same root resolution.
You will generally have to get one or more issues, apply some calculation, treatment, etc and after that, edit one or more issues, those issues are generally related somehow (parent/child, linked) and they will require getting more than one issue to do so.
Easy for Jira allows you to handle those problems with ease, so let’s check how you can solve some day to day issues, such as calculating story points for all issues in one epic.
# In our context, we have our issue (assume a transition post function)
print(issue.key)
# If you are on Console, grab a TASK
issue = Issue("TEST-123")
# Parent issue (epic) needs to calculate the story points for his child issues
siblings = issue.parent.child
# Get the Story Points field key
field_key = api.fields.by_name("Story Points").key
# Calculate Story Points
story_points_total = 0
# Sum the points
for i in siblings:
issue_story_points = i.fields.<story points customfield key>
story_points_total += issue_story_points if issue_story_points > 0 else 0
# Update parent issue
issue.parent.set("<story points customfield id>", story_points_total)
Exercises & Challenges
As mentioned before, you only really learn code by doing it, so We challenge you to perform 3 levels of challenges to confirm you got the knowledge to use the app. With my past experience, 90% of the time, what you need to know is to handle the trigger issue and his related issues and to do something with them.
The following exercises will confirm you can work with Easy for Jira confidently in your day to day.
Beginner
These are entry level exercises, if you can confidently code solutions for the following scenarios, you can consider yourself a WHITE BELT in Easy for Jira.
This is the easiest one. You just need to update one ticket via Post Function.
Edit the parent issue of the trigger issue.
This is also not that hard, We would recommend using the Issue to perform this test.
Edit all the linked issues of an specific type with a Post Function. Any change you want. This one is also better performed with the Issue Object.
These are mid level exercises, if you can confidently code solutions for the following scenarios, you can consider yourself a YELLOW BELT.
This is doable using the api wrapper, that allows you to search issues. Get the results of some JQL, calculate something from data that you got from all of the results and update the trigger issue (a numeric custom field that you created) to beat this challenge.
Think of this as a corrective step for inattentive employees, they added all data necessary to tickets but forgot to transition it. Your job will be creating a Console Script to check and transition forgotten issues.
Using the Agent you can create a simplified agent to respond to tickets. This agent should be created with the Code Repository and imported as a Listener, only to listen for comment created events.
Advanced
These are advanced level exercises, if you can code solutions for the following scenarios, you can consider yourself a BLACK BELT in Easy for Jira.
This is doable using the api wrapper, that allows you to search issues. Get the results of some JQL, calculate something from data that you got from all of the results and update the trigger issue (a numeric custom field that you created) to beat this challenge.
Think of this as a corrective step for unattentive employees, they added all data necessary to tickets but forgot to transition it. Your job will be creating a Console Script to check and transition forgotten issues.
Using the Agent you can create a simplified agent to respond to tickets. This agent should be created withing the Repository and imported as a Listener, only to listen for comment created events.
Once your exercises are done, you can check the Exercise Answers, to check if your approach is the recommended one.
