Creating a VisualScript Report Using a REST Endpoint

Introduction

In order to generate a visual with VisualScript Studio you just have to hand it VisualScript markup 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 VisualScript. For example, you can use Adaptavist's ScriptRunner to produce VisualScript using your Jira data and then simply point VisualScript Studio 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 Endpoint Connector in VisualScript Studio:

  1. Set up or obtain a REST endpoint
  2. Add a VisualScript REST Endpoint Connector 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 generates VisualScript. You can use ScriptRunner, Groovy, Java, or C#, and so on.

VisualScript Studio has a built-in JavaScript editor, but if you want to develop a REST endpoint outside of VisualScript Studio, 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 that can generate VisualScript markup. 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. You may also have some built-in scripts that the ScriptRunner team has included for your use. 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 com.onresolve.scriptrunner.runner.rest.common.CustomEndpointDelegate
import groovy.json.JsonOutput
import groovy.transform.BaseScript
import javax.ws.rs.core.MultivaluedMap
import javax.ws.rs.core.Response
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

generateVSWithParam(
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 = []
baseShape.add(label)
vsMap.put('RootShape', baseShape)
log.debug(vsMap)
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 Studio. 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 Connector Gadget

To add the VisualScript Studio REST Connector 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 Studio gadgets, or you can type "VisualScript" into the search/filter box in the top left area of the list. Choose the "VisualScript REST Connector" 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 "Configure" button to add information about your REST endpoint.

Configure REST 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 Studio 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 connector name

Passing User Input to the REST Endpoint with the UI Builder

The VisualScript REST Connector Gadget 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 Studio 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:

{{param1}},{{param2}}

sends a string

<value of param1>,<value of param2>

Note that the comma is included. So

{"Name":"{{Name}}","Title":"{{Title}}"}

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 "Update Existing" button to save your changes.

At the top of the page, click "Save and Close" to exit this edit mode. 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 "Run" button to run it.

REST gadget ready

Clicking the "Run" button displays the user interface you set up in the previous step. The label for the parameter is shown to the left of the input field, and the description text is to the right. "Hello World" is filled in as the default, but you're free to override it. Click the "Go!" button to obtain the data from the script and display it using VisualScript Studio.

REST label

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

REST output