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.



VS.Jira.GetPromisesForArray()

Example

myPromise=VS.Jira.GetPromisesForArray(projectList, getProjectInfo).then(SuccessFunction(results));

function getProjectInfo(project) {
return VS.Jira.Project(jiraHost, project.key);
}

This example gets project information for a list of projects. It assumes that projectList is an array of objects containing the Jira key for a project.

Syntax

myPromise=VS.Jira.GetPromisesForArray(list, promiseFunction);

  • {Array} list - list of elements to pass to promise function
  • {Function} promiseFunction- function that receives each list element and returns a promise
SuccessFunction()

The function passed to the .then method for this method has a parameter (results) that contains the results for the entire list. These results can be extracted by using either the VS.Jira.GetPromisesResults or VS.Jira.MergePromisesResults (see below).

Usage

This method allows you to issue a large number of queries (or other requests) to Jira without excessive server usage or having Jira fail the requests for arriving too quickly.

VS.Jira.GetPromisesResults()

Example

projectInfo=VS.Jira.GetPromisesResults( results );

This example receives the results for a VS.Jira.GetPromisesArray promise.

Syntax

resultsArray=VS.Jira.GetPromisesResults( rawResults );

  • {Array} rawResults - results passed to the “.then” function of a VS.Jira.GetPromisesForArray API call.
  • {Array} resultsArray - Array of results of each promise generated by VS.Jira.GetPromisesForArray.
Usage

This method allows you to receive the results of a VS.Jira.GetPromisesForArray call.

VS.Jira.MergePromisesResults()

Example

VS.Jira.MergePromisesResults(projectList, results );

This example merges the results for a VS.Jira.GetPromisesArray promise back into the original list of objects

Syntax

VS.Jira.MergePromisesResults( list, rawResults, destinationFieldName );

  • {Array} list - original array of objects passed to the VS.Jira.GetPromisesForArray call.
  • {Array} rawResults - results passed to the ".then" function of a VS.Jira.GetPromisesForArray API call.
  • {string} destinationFieldName (Optional)- field name in each list object that will contain the results information. Default for this field is "results".
Usage

This method allows you to merge the results of a VS.Jira.GetPromisesForArray call into the original list used in the VS.Jira.GetPromisesForArray call.

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.