Skip to main content
Contact usBook your demo
Using ScriptRunner to build custom features
Share on socials
A screen filled with code surrounded by abstract shapes
An orange circle placeholder
Chirag Harendra
26th June, 2018
Jira

Using ScriptRunner to build custom features

With ScriptRunner you can enhance your Jira workflows and respond to events with your own code. In this blog, we empower you to build custom features to meet your specific business needs.

Using ScriptRunner to build your own custom features

With any application, add-on or plug-in we tend to find ourselves wishing for more features to meet our own specific needs. We're greedy; we're selfish, we want more and, we want it just for us. When you find the 'Holy Grail' you want to engrave it. This post explores the story of a keen Jira and Test Management for Jira (TM4J) power-user who wanted more, and how by working with Adaptavist ScriptRunner they achieved their wish!

The challenge

For the sake of this story we are going to call the Jira and TM4J power-user 'Ted.' Ted has two Jira instances, one internal and one external. Both have TM4J installed but for slightly different purposes. Ted wants the TM4J data in these instances to be 'synced' or 'mirrored' as we call it at Adaptavist. The problem is that TM4J does not currently have this capability. Even if it did, they are not allowed to communicate with each other due to a firewall bigger and stronger than anything President Trump could imagine! Ted began to have a 'syncing' feeling that his wish was not going to be possible.
WRONG!...in steps Adaptavist ScriptRunner to the rescue...

The solution

The answer to Ted's challenge is a semi-automated 'sync.' Ted needs to download a file containing all the data from the external Jira instance and then upload it to the internal instance. To implement this Ted needs a custom plugin, as neither TM4J nor ScriptRunner for Jira (SR4J) offer this functionality out-of-the-box. A combination of a few different SR4J features married with some fairly basic programming skills meant it was possible without the need to create a brand new independent 'add-on' (which tends to be both a little trickier and more expensive).

Steps to success

Create the custom download and upload dialogs

  • Add a REST endpoint that returns the custom dialog HTML. Ted needs two of these, one for downloading and one for uploading. You can add whatever you like to this dialog but be sure to follow the Atlassian AUI guidelines.
  • TIP - You can treat this HTML like you would pretty much any other HTML form. Add any form fields from the AUI docs that will help you capture the data that you need.

Add a web item that points towards your REST endpoint

  • Again, for Ted he needs two to match the downloading and uploading dialogs. When telling a web item what it should do, there is a 'run code and show dialog' option. Choose this; it does what it says on the tin.
  • TIP - you can tell a web item to point towards any URL you like, pass parameters through the URL and run code when it gets there - think of the possibilities!

Create the form handling REST endpoint

  • Add a REST endpoint that matches what you are trying to do, i.e., get, post, etc. In Ted's case, we needed one that was a get (download) and a post (upload).
  • Execute the actions. For Ted's REST endpoints they need to call yet another API, the TM4J API. The download endpoint will get the data and create a downloadable file. The upload will open the downloadable file and send the contents to the TM4J API.
  • Add some clever bits in between to make sure the data is clean and formatted correctly
  • TIP - you can do anything you like in these REST endpoints, once you have the data from the form your only limitation is your programming skills.

Add the JavaScript to handle the form

  • Add a web-resource.JS file - this will need to be in a folder on the instances' server and a resource directory - For more details view the Adaptavist ScriptRunner how-to guide.
  • Add a function to the JS file that retrieves the form data on submit. In Ted's case, he needs two functions to match his downloading and uploading forms.
  • Add an AJAX (Asynchronous Javascript & XML HTTP request or web development tool in short!) call to each and send the form data to the previously configured 'Form REST Handling Endpoints'
  • See the below example for how to get data from a text area and forward to the endpoint.
  • TIP - The same applies to web resources as it does to REST endpoints. The script is your oyster, use JavaScript to make the dialog perform how you wish. Moreover, it doesn't have to be a JS script; you could add a CSS (Cascading Style Sheets) script here to jazz things up.

// Form Handling Example

1function bindMyCustomEvents() {
2  (function($) {
3    var customDialog = AJS.dialog2("#sr-dialog")
4    customDialog.on("show", function(e) {
5      var targetId = e.target.id;
6      if (targetId === "sr-dialog") {
7        $('form').submit(function(event) {
8          $.ajax({
9           type: "POST",
10            dataType: "json",
11             "contentType": "application/json",
12              url: "http://<YOUR-URL>/jira/rest/scriptrunner/latest/custom/formHandler",
13              data: $('#textarea-id').val()
14          }).done(function(data) {
15            alert(data);
16          }).fail(function() {
17            alert("Sorry. Server unavailable. ");
18          });
19          event.preventDefault();
20        });
21      }
22    });
23  })(AJS.$);
24}

Bind the JavaScript in the web-resource to the dialog form

  • Add a script tag to the bottom of the of the HTML in the dialog REST endpoints
  • Add the name of the functions inside the script tag. For example: <script> bindMyCustomEvent() </script>
  • Set the functions to be the 'on process' event for your form

Summary

To create this mini-plugin style feature using Adaptavist ScriptRunner you need to:
  • Add a REST endpoint that gets all the TM4J data using the TM4J API to create a downloadable file
  • Add a REST endpoint that returns an HTML dialog form
  • Add a web item button that calls the HTML dialog and presents it
  • Add a web resource that processes the dialog form on submit and calls the first download REST endpoint
  • Add a REST endpoint that takes TM4J data and uploads it by sending it to the TM4J API
  • Add a REST endpoint that returns a different HTML dialog form
  • Add a web item button that calls the HTML dialog and presents it
  • Add a web resource that processes the dialog form on submit and calls the upload REST endpoint

The possibilities are endless

We solved Ted's problem by creating a mini plugin using ScriptRunner and the TM4J API. So now it is up to you to consider the possibilities. You could create your own forms for the dialog and replace the TM4J with any public API.
If you find yourself manually transferring data or if you have other applications with public APIs that you want to integrate with Jira. You can build the integration yourself. ScriptRunner makes it very simple to do this, as we have shown using a combination of some of it's most powerful features.
The moral of Ted's story is that you don't have to settle for the standard functionality. ScriptRunner gives you the ability to think out-of-the-box and build mini plugins that are completely bespoke to meet your needs, big or small.
If you would like to find out more about how ScriptRunner could help you and your business, we would love to hear from you.

Try ScriptRunner for free

Download ScriptRunner for Jira from the Atlassian Marketplace today for a free trial.
Visit Marketplacearrow icon