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.
