Don’t worry, get HAPI
Quick note! This blog post is sponsored by ScriptRunner.
What is scripting
Check out my prior post for more information on what scripting is. In short, it’s a way to expand what a system is capable of, and to allow a system to meet a specific use case. It is a very powerful tool… however, it can also be a bit challenging (and intimidating!) to learn.
Unless you have a background in writing scripts, getting started can be incredibly confusing. Systems will use different types of scripting, meaning lessons you’ve learned in one system may not apply to another one. If you don’t have a background in scripting, even the basic concepts can be challenging to learn as they can be unlike anything else you’ve done in the past.
Many scripting languages are also incredibly complex, requiring you to understand a variety of topics, but also know a wide range of commands. While this complexity can be warranted to support various use cases, it makes it very hard to learn it.
Jira is Groovy (well, it uses Groovy)
A lot of scripting in Jira relies on Groovy - a scripting language that has a lot of power and makes it easier to use Jira’s APIs (Application Programmer Interfaces). That said, it also has a bit of a learning curve - even if you know another scripting language like Javascript. Unless you happen to have a deep set of technical skills or a background in scripting, you may find yourself quickly overwhelmed with its “easy to learn” setup.
Personally, I find this to be a shame, as almost every group can benefit from scripting. It allows admins to unlock a lot of potential, and to alleviate a lot of manual processes that teams go through. This is especially true for teams using Jira, as many times there are steps in their process that can, and should, be automated.
The high cost of entry for Groovy means that many admins simply won’t learn it. If they’re very lucky they’ll have another resource at their company (or a contractor) who can help script, but many times they simply won’t have access to this powerful tool. Even if an admin does know scripting, they may find themselves lacking the time necessary to write out useful scripts.
When an admin gets lucky and happens to inherit a good script or have someone else build it out, they may find themselves in trouble as they may not understand the code. This makes it hard to troubleshoot issues or bugs that may crop up, but this also makes it hard to modify the code if they want to. Adjusting existing code is a very common approach to improving things, but if it’s too confusing to figure out, admins will simply not get those benefits.
When admins are lucky enough to have existing code they might also find themselves lacking any documentation about what it does, or how to adjust it. Poorly documented code is nothing new, but it still represents a big challenge. This reliance on “tribal knowledge” can make it impossible for an admin to make progress, or even understand what a specific script does.
How ScriptRunner’s HAPI helps overcome those challenges
Despite all of these challenges, scripting is still an incredibly valuable tool for admins. Fortunately, there is help out there in the form of HAPI. HAPI provides a simplified structure for interacting with Jira Groovy scripts that is substantially more intuitive writing scripts in Groovy without HAPI.
For example, this bit of Groovy code
Can be rewritten in HAPI as
Not only is the new code substantially shorter( 4 lines vs 30) it is vastly easier to read and understand. I bet after you read the HAPI code you could explain what it does to someone else… much easier than just the pure Groovy version above!
This readability is one of the biggest advantages HAPI provides - simply read it left to right like you would a sentence in English to know what it does. For example, the code above could be read as
“Create an issue in the SSPA project with the Task type. Make the summary “I need to create a ticket” and the description “well, that was easy”.
Imagine being a new admin and being able to decode your scripts this quickly (or make new ones…)!
Seamless integration
HAPI is an extension to ScriptRunner, which might make you wonder if they play nice together. The good news is they do! Scripts using HAPI can seamlessly integrate with existing ScriptRunner scripts. This means groups already using ScriptRunner can easily add new scripts utilizing HAPI, but also easily refactor existing scripts to be more easily readable. Even better, scripts you write can use both HAPI and more traditional Java API calls in the same script so you’re not forced to choose one or the other.
This backwards compatibility is a great feature and means that even if an admin doesn’t know Groovy (or doesn’t want to risk breaking existing scripts), they can easily add new HAPI scripts to their environment.
Quality of Life (QoL)
If HAPI stopped there and only made scripts easier to read/interpret and was compatible with Groovy, it would be amazing. Fortunately the nice people at ScriptRunner have gone a few steps further to make HAPI even more useful for admins.
One way they’ve done this is by adding auto-complete for your custom values. This means that as you type in commands, HAPI will start showing possible valid entries based on what you typed. This drastically reduces the risk that you’ll mistype a command, or pick one that doesn’t exist. Personally, I find this incredibly useful, as I typically find myself opening up documentation to double-check what commands there are.
In the example below we can see HAPI serving up possible completions to “setD” - something that Groovy does on its own.
HAPI, however, takes this a step further by pulling in valid options for fields. For example, if you wanted to add an issue to a project, HAPI would display a list of valid project keys in the code. Without this feature, you’d either have to look up what you wanted, or memorize every project key (trust me, don’t try this one!). By displaying valid options for fields directly in the code HAPI saves admins a lot of time.
In this screenshot we can see HAPI suggesting possible valid values for “Assignee”:
HAPI also works with other ScriptRunner features. For example, it can be used to build out custom listeners (scripts that detect when a specific event occurs, for example an issue being created or a field changing a value). While this can be done in with Atlassian’s APIs, having all of the features mentioned above make it substantially easier. Similarly, you can use it to extend Jira’s standard UI - again leveraging all of the benefits of HAPI in an existing (very useful) feature.
Availability
HAPI was originally built out for Jira Data Center (DC)... but the great news is it it is now available on Jira Cloud!
Conclusion
HAPI is a big step forward in terms of scripting in Jira. Its backward compatibility with existing ScriptRunner scripts, and the wide range of QoL features make it a great choice for admins looking to automate things. These features also make it a lot more approachable to someone who is just beginning to learn Groovy as it has a much flatter learning curve. Even better, it helps eliminate a need for a deep understanding of Groovy or Jira API’s, making it much more approachable to basically everyone.
