Creating a VisualScript Report Using a REST Endpoint


In order to generate a visual with VisualScript you have to write code that describes a diagram. One of the ways you can do this is to point it at any REST endpoint API that is configured to generate the right code. For example, you can use Adaptavist's ScriptRunner and simply point VisualScript to your ScriptRunner endpoint. The beauty of this way of generating a visual is you can use any tool and write it in any language.

How to use the REST Report Builder in VisualScript:

  1. Set up or obtain a REST endpoint
  2. Add a VisualScript REST Report Builder to your dashboard or page
  3. Configure the gadget to use the URL of the REST endpoint

To illustrate this process in detail, we'll walk through the steps of setting up a VisualScript gadget on Jira to obtain data from an Adaptavist ScriptRunner REST endpoint.

Get the SDK

You can write a program in any language you want that connects to VisualScript. You can use ScriptRunner, Groovy, Java, or C#, and so on.

VisualScript has a built-in JavaScript editor, but if you want to develop a REST endpoint outside of VisualScript, we also created an SDK in Java and C# to help.

You can download the SDKs here.

Set Up a REST Endpoint

The first step is to set up a REST Endpoint. The team from Adaptavist helped us get a very simple "hello world" script using ScriptRunner. From Jira's Administration menu, click "Manage Add-ons", look for the ScriptRunner heading in the left navigation, and choose "REST Endpoints".

Set up REST endpoint

Click the "Add New Item" button, then click the "Define a REST Endpoint" link. This gives you the form to define your endpoint.

Add new item

Since we have a copy of the script we want to use, for the purposes of this tutorial, we'll just copy and paste it inline into the mini-editor on the page. If the script was stored in a file that is accessible to Jira, you could also use the script file control instead. Click the "Add" button to add the script.

For your reference, here's the full script we'll be pasting in here:

This script provides a framework for interacting with Jira and returning the results as VisualScript

Developers: Johnson Howard, Neal Riley and Phill Fox


import groovy.json.JsonBuilder
import groovy.json.JsonOutput
import groovy.transform.BaseScript
import org.apache.log4j.Level
import org.apache.log4j.Logger
// Setup the log and leave a message to show what we're doing
Logger logger = log
logger.setLevel( Level.ALL )
@BaseScript CustomEndpointDelegate delegate

httpMethod: "GET"
) { MultivaluedMap queryParams, String body ->
def param = queryParams.get("parameter")?.first()
log.debug("Param :"+param)
return Response.ok(JsonOutput.toJson(getVS(param))).build()

def getVS(def variable){
// Set Variables
def vsMap = [:]
vsMap.put('DiagramType', 'Flowchart')
def label = [:]
label.put('Label', variable)
def baseShape = []
vsMap.put('RootShape', baseShape)
return vsMap //.toString()

Get the Link to the REST Endpoint

Once the script is in place, we just need to get the URL we can use for VisualScript. The simplest way to get the URL for this to click the name of the script itself, then copy the URL on the page that opens. Now we're ready to add a VisualScript gadget to the dashboard so that we can make calls to this REST endpoint.

Get link

Add the VisualScript REST Report Builder Gadget

To add the VisualScript REST Report Builder gadget, go to the dashboard you wish to use. If you don't already have a dashboard set up, you can create one using the "Manage Dashboards" option in Jira's "Dashboard" menu.

Jira dashboard dropdown

On the dashboard, click on the "add a new gadget" link to open the gadget browser.

Add new gadget

The "Add a gadget" dialog contains a list of gadgets that have already been loaded, but you'll almost certainly need to click the "Load All Gadgets" link in the "More Gadgets Available" box.

Gadget dialog

After you click the "Load all Gadgets" link, you'll see a longer list of possible gadgets. You can either scroll down to the list of VisualScript gadgets, or you can type "VisualScript" into the search/filter box in the top left area of the list. Choose the "VisualScript REST Report Builder" by clicking its "Add gadget" button.

Gadgets list

Configure the Gadget

At this point the gadget is ready to use on the dashboard. Click the "Edit" button to add information about your REST endpoint.

Configure REST Report Builder gadget

To configure the gadget, add a name for your Connector, a brief description, and then the endpoint URL you copied. This particular script will require a parameter, so that will need to be added at the end of the URL. The parameter is aptly named "parameter". It's entered by adding the string ?parameter={{parameter}} to the end of the URL. VisualScript will respond to this by adding fields that you can use to customize the interface that you will see when you actually use this gadget. This is what we call the VisualScript UI Builder. We will explore that in more detail next.

REST report builder UI

Passing User Input

The VisualScript REST Report Builder will build a user input form for you if you define parameters in the URL, headers, or the message body (with POST) using matching double curly brackets like this {{param1}}. This is called the UI Builder.

The VisualScript UI Builder allows you to format a string that is passed to a REST call or a JavaScript function with field tokens that are replaced by their values.

Field tokens are defined with matching double curly brackets:


sends a string

<value of param1>,<value of param2>

Note that the comma is included. So


produces the JSON:

{"Name":"<value of Name>","Title":"<Value of Title>"}

Variables that you define with curly brackets appear as fields in a form that is presented to the user. You get to define the label for the field and a description. For example:

REST UI fields

This presents a form to the end user that looks like this:

REST end user form

Below we pass a variable as a URL parameter.

Variable URL parameter

Click the "Save" button to save your changes or "Save and Run" to also run your script.

You will then see the gadget in its ready to use form on your dashboard or page.

The gadget is now ready to use. It has placed the name for the gadget that you chose into the title bar. Click the "Go!" button to obtain the data from the script and display it using VisualScript.

REST gadget ready

The output is as expected: a single shape containing your parameter text.