Zero to Hero Guide

Easy for Jira is an app that has a very low entry barrier, to learn and master it, there’s 2 things you need to know, at least the very basics. One of them is of course, Python, and the other is the Atlassian REST APIS. That will unlock at least 65% of what you can do with the app, if you want to expand further, you can study other areas as General API Usage and conventions.

To help you master the app, We’ve assembled this simple guide, straight from the developer, to you, the final user, which is generally the Jira Admin or some external contracted Consultant performing tasks on the Customer Instance. We hope this guide helps you, young Padawan.

The only requirement you really need external from this guide is to understand programming logic, which don’t really require programming, logic is the central baseline of all programming languages and its what dictates how one can communicate with the computer.

We’ve assembled some knowledge here Simple Programming Logic Guide but this might not be enough if you have 0 background in technology. For more in depth visual guide, this series of videos might help you as well.

https://www.youtube.com/watch?v=vOEN65nm4YU&list=PLb1JOlXNnNeeEabeqbMYaBNpmYD-7Fui9

Programming looks scary at first, but once you understand is as simple as learning the basic rules of the language and respecting them.

Topics covered in this Page

1 Topics covered in this Page
- 1.1 Modules
- 1.2 Recommendations
- 1.3 Easy for Jira Wrappers (Context Variables)
- 1.4 The Issue Object
- 1.5 The API Object
- 1.6 Depth Look into Common Issues
2 Exercises & Challenges
- 2.1 Beginner
- 2.2 Intermediate
- 2.3 Advanced
3 Extras
- 3.1 Application Programming Interface (API)
  - 3.1.1 What is it used for?

Expand the section you want to study

If you don’t know Python at all or have little knowledge around it, we created a guide for you!

https://easyforjira.atlassian.net/wiki/spaces/Documentation/pages/49184823

If you know your ways around Python and want to learn Easy for Jira, use this:

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.

Intermediate

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.

Extras

Application Programming Interface (API)

Understanding API’s will help you a lot through scripting in Atlassian.

API stands for Application Programming Interface. Think of it as a messenger that allows different software applications to communicate with each other. Just like how you might use a menu to order food at a restaurant, software applications use APIs to request and exchange data and services from each other.

What is it used for?

APIs are used for a variety of purposes, but primarily they enable different software systems to work together seamlessly. They define the methods and data formats that applications can use to request and exchange information with each other. This allows developers to create new functionalities by leveraging existing services or data without having to build everything from scratch.

Example - Let's say you're using a weather app on your smartphone. This app doesn't generate the weather forecasts itself; instead, it uses an API provided by a weather service. When you open the app, it sends a request to the weather service's API asking for the current weather information for your location. The API then processes this request, gathers the necessary data, and sends it back to the app, which then displays it to you in a user-friendly format.

So, in this example:

The weather app is the client application.
The weather service's API acts as the intermediary between the app and the weather data.
The weather service is the server providing the weather data.

Without the API, the weather app wouldn't be able to access the weather data from the weather service, and you wouldn't be able to get the current weather forecast on your smartphone.