The VisualScript Data SDK

The VisualScript Data SDK provides an object model that allows a developer to extract data from Jira and other sources.

VisualScript Data SDK Object Classes

At the moment, we only have a single class to use for querying Altassian's Jira. In the future, we plan to add classes for Altassian's Confluence as well as other platforms.

VS.Jira()

This class provides methods for querying the Jira database both on Server and in Cloud.

Using the VisualScript Data SDK

The VisualScript Data SDK is automatically included with the code editor inside VisualScript. The object class is instantiated and the methods can be used directly.

Most of these methods return either a list of objects or an object from the Jira database. They return a promise. JavaScript promises handle the asynchonous nature of these kind of calls by executing either a ".then" method upon success or return an error using "catch;".

var myPromise=VS.Jira.Query();
myPromise.then(SuccessFunction(params)).catch(FailFunction(params));

VisualScript Data SDK Object Class Methods

Below are the query methods that help you get data from Jira.

VS.Jira.Query()

This method can be used to return a set of issues with specified parameters.

Example

myPromise=VS.Jira.Query(jiraHostname, 'project = "project1" AND priority = "critical" AND status in ("Open", "Reopened", "In Progress")',null).then(SuccessFunction(issuesList));

This example queries Jira for all the open issues in project1 that have a priority of "critical".

Syntax

myPromise=VS.Jira.Query(jirahost,query, requestParams);

• {string} jirahost - base URL of the Jira host
• {string} query - query string to issue
• {string} requestParams - parameters for request (optional)

SuccessFunction()

The function passed to the .then method has an issuesList as a parameter. This an array of Jira issues as documented in the Jira REST API for the "Search" request. All of the pagination in the array is done for you and you're passed the array of objects.

Usage

This method issues a JQL query to the local Jira instance. When a query returns a large number of issues, Jira's REST API utilizes paging. The Jira API paging normally makes it necessary to issue multiple HTTP calls in order to obtain the full results set, however VS.Jira.Query takes care of that for you and delivers you the entire set of results at once.

VS.Jira.QueryResultsCount()

This method can be used to return the number of issues with a specified parameter.

Example

myPromise=VS.Jira.QueryResultsCount(jiraHostname, 'project = "project1" AND priority = "critical" AND status in ("Open", "Reopened", "In Progress")',null).then(SuccessFunction(queryCount));

This example gets a count of all the open issues in project1 that have a priority of "critical".

Syntax

myPromise=VS.Jira.QueryResultsCount(jirahost,query, requestParams);

• {string} jirahost - base URL of the Jira host
• {string} query - query string to issue
• {string} requestParams - parameters for request (optional)

SuccessFunction()

The function passed to the .then method has an queryCount as a parameter. This is an integer count of the number of issues that would be returned from this query.

Usage

Counts the number of issues that will be returned for a query.

VS.Jira.Issue()

This method can return information about a specific issue.

Example

myPromise=VS.Jira.Issue(jiraHostname, "DEMO-123",null).then(SuccessFunction(issue));

This example queries Jira for detailed information regarding issue "DEMO-123". This information is passed to the success function.

Syntax

myPromise=VS.Jira.Issue(jirahost,issueID, requestParams);

• {string} jirahost - base URL of the Jira host
• {string} issueID- ID of the issue
• {string} requestParams - parameters for request (optional)

SuccessFunction()

The function passed to the .then method has an issue as a parameter. This is a Jira issue as a JavaScript object as documented in the Jira REST API for the "Get Issue" request.

Usage

This method gets detailed information about the issue with ID "issueID".

VS.Jira.Project()

This method can be used to get information about a specific project.

Example

myPromise=VS.Jira.Project(jiraHostname, "DEMO",null).then(SuccessFunction(project));

This example queries Jira for detailed information regarding project "DEMO". This is passed to the success function.

Syntax

myPromise=VS.Jira.Project(jirahost,projectID, requestParams);

• {string} jirahost - base URL of the Jira host
• {string} projectID- ID of the project
• {string} requestParams - parameters for request (optional)

SuccessFunction()

The function passed to the .then method has a project as a parameter. This is a Jira project as a JavaScript object, as documented in the Jira REST API for the "Get Project" request.

Usage

This method gets detailed information about the project with identified with "projectID".

VS.Jira.Object()

This method can be used to get information about a specific Jira object like a user.

Example

myPromise=VS.Jira.Object(jiraHostname, "user", "username=fred",null).then(SuccessFunction(data));

This example queries Jira for detailed information regarding the user identified as "fred". This is passed to the success function.

Syntax

myPromise=VS.Jira.Project(jirahost,objectType,objectID, requestParams);

• {string} jirahost - base URL of the Jira host
• {string} objectType - type of object (Jira entity type)
• {string} objectID - ID of object
• {string} requestParams - parameters for request (optional)

SuccessFunction()

The function passed to the .then method has a parameter that contains information for a Jira object as a JavaScript object, as shown in the Jira REST API documentation.

Usage

This method gets detailed information about the object using "objectType" and "objectID".

VS.Jira.RestApiCall()

This method can be used to get any Jira information using an API call.

Example

myPromise=VS.Jira.RestAPICall(jiraHostname, "/rest/api/2/issue/createmeta",null).then(SuccessFunction(results));

This example gets metadata for all issues.

Syntax

myPromise=VS.Jira.Project(jirahost,apiPath, requestParams);

• {string} jirahost - base URL of the Jira host
• {string} apiPath - API path/string
• {string} requestParams - parameters for request (optional)

SuccessFunction()

The function passed to the .then method has a parameter (results) that contains information for a Jira Rest API call as a JavaScript object, as documented in the Jira REST API.

Usage

This method makes a generic Jira REST API call and returns the results.

Utility Methods

The methods below are used to communicate information about the querying process.

VS.Jira.FormatError()

This method is used to deliver error messages.

Example

This method should always appear in the FailFunction() called by .catch if there is an error in a Data SDK call.

{vsonRenderingCallback(null, VS.Jira.FormatError(err));};

Syntax

VS.Jira.FormatError(err);

• {string or Object} errorInfo - error information. Can be an HTTP error, a Javascript exception or a generic error message string

Usage

This method formats an error message or user-requested cancel. This information is passed to the "rendering" function in the case of an error.