synergia-jira-connector

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <title>JSDoc: Source: api/issue.js</title> <script src="scripts/prettify/prettify.js"></script> <script src="scripts/prettify/lang-css.js"></script>  <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css"> <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css"> </head> <body> <div id="main"> <h1 class="page-title">Source: api/issue.js</h1> <section> <article> <pre class="prettyprint source linenums"><code>"use strict"; var errorStrings = require('./../lib/error'); var fs = require('fs'); module.exports = IssueClient; /** * Used to access Jira REST endpoints in '/rest/api/2/issue' * @constructor IssueClient * @param {JiraClient} jiraClient */ function IssueClient(jiraClient) { this.jiraClient = jiraClient; /** * Creates an issue or a sub-task from a JSON representation. * * The fields that can be set on create, in either the fields parameter or the update parameter can be determined * using the /rest/api/2/issue/createmeta resource. If a field is not configured to appear on the create screen, * then it will not be in the createmeta, and a field validation error will occur if it is submitted. * * Creating a sub-task is similar to creating a regular issue, with two important differences: * * * the issueType field must correspond to a sub-task issue type (you can use /issue/createmeta to discover * sub-task issue types), and * * you must provide a parent field in the issue create request containing the id or key of the parent issue. * * @method createIssue * @memberof IssueClient# * @param {Object} issue The issue data in the form of POST body to the JIRA API. * See {@link https://docs.atlassian.com/jira/REST/latest/#d2e398} * @param callback Called when the issue has been created. */ this.createIssue = function (issue, callback) { var options = { uri: this.jiraClient.buildURL('/issue'), method: 'POST', followAllRedirects: true, json: true, body: issue }; this.jiraClient.makeRequest(options, callback); }; /** * Returns the meta data for creating issues. This includes the available projects, issue types and fields, * including field types and whether or not those fields are required. Projects will not be returned if the user * does not have permission to create issues in that project. * * The fields in the createmeta correspond to the fields in the create screen for the project/issuetype. Fields not * in the screen will not be in the createmeta. * * Fields will only be returned if ```expand=projects.issuetypes.fields.``` * * The results can be filtered by project and/or issue type, given by the query params. * * @method getCreateMetadata * @memberOf IssueClient# * @param {Object} [opts] The options for the API request. * @param {string} [opts.projectIds] combined with the projectKeys param, lists the projects with which to filter * the results. If absent, all projects are returned. This parameter can be specified multiple times, and/or be * a comma-separated list. Specifiying a project that does not exist (or that you cannot create issues in) is * not an error, but it will not be in the results. * @param {string} [opts.projectKeys] combined with the projectIds param, lists the projects with which to filter * the results. If null, all projects are returned. This parameter can be specified multiple times, and/or be a * comma-separated list. Specifiying a project that does not exist (or that you cannot create issues in) is not * an error, but it will not be in the results. * @param {string} [opts.issuetypeIds] combinded with issuetypeNames, lists the issue types with which to filter * the results. If null, all issue types are returned. This parameter can be specified multiple times, and/or * be a comma-separated list. Specifiying an issue type that does not exist is not an error. * @param {string} [opts.issuetypeNames] combinded with issuetypeIds, lists the issue types with which to filter * the results. If null, all issue types are returned. This parameter can be specified multiple times, but is * NOT interpreted as a comma-separated list. Specifiying an issue type that does not exist is not an error. * @param {string} [opts.expand] in order to get expanded field descriptions, specify 'projects.issuetypes.fields' here. * @param callback Called when the metadata has been retrieved. */ this.getCreateMetadata = function (opts, callback) { var options = { uri: this.jiraClient.buildURL('/issue/createmeta'), method: 'GET', followAllRedirects: true, json: true, qs: { projectIds: opts.projectIds, projectKeys: opts.projectKeys, issuetypeIds: opts.issuetypeIds, issuetypeNames: opts.issuetypeNames, expand: opts.expand } }; this.jiraClient.makeRequest(options, callback); }; /** * Creates issues or sub-tasks from a JSON representation. * * Creates many issues in one bulk operation. * * Creating a sub-task is similar to creating a regular issue. More details can be found in createIssue section: * {@link IssueResource#createIssue(IssueUpdateBean)}} * * @method bulkCreate * @memberof IssueClient# * @param issues See {@link https://docs.atlassian.com/jira/REST/latest/#d2e828} * @param callback Called when the issues have been created. */ this.bulkCreate = function (issues, callback) { var options = { uri: this.jiraClient.buildURL('/issue/bulk'), method: 'POST', followAllRedirects: true, json: true, body: issues }; this.jiraClient.makeRequest(options, callback); }; /** * Returns a full representation of the issue for the given issue key. * * An issue JSON consists of the issue key, a collection of fields, a link to the workflow transition sub-resource, * and (optionally) the HTML rendered values of any fields that support it (e.g. if wiki syntax is enabled for the * description or comments). * * The fields param (which can be specified multiple times) gives a comma-separated list of fields to include in * the response. This can be used to retrieve a subset of fields. A particular field can be excluded by prefixing * it with a minus. * * By default, all (\*all) fields are returned in this get-issue resource. Note: the default is different when doing * a jql search -- the default there is just navigable fields (\*navigable). * * * \*all - include all fields * * \*navigable - include just navigable fields * * summary,comment - include just the summary and comments * * -comment - include everything except comments (the default is *all for get-issue) * * \*all,-comment - include everything except comments * * JIRA will attempt to identify the issue by the issueIdOrKey path parameter. This can be an issue id, or an issue * key. If the issue cannot be found via an exact match, JIRA will also look for the issue in a case-insensitive * way, or by looking to see if the issue was moved. In either of these cases, the request will proceed as normal * (a 302 or other redirect will not be returned). The issue key contained in the response will indicate the * current value of issue's key. * * @method getIssue * @memberof IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param {Object} [opts.fields] See {@link https://docs.atlassian.com/jira/REST/latest/#d2e611} * @param {Object} [opts.expand] See {@link https://docs.atlassian.com/jira/REST/latest/#d2e611} * @param callback */ this.getIssue = function (opts, callback) { var options = this.buildRequestOptions(opts, '', 'GET'); this.jiraClient.makeRequest(options, callback); }; /** * Delete an issue. If the issue has subtasks you must set the parameter deleteSubtasks=true to delete the issue. * You cannot delete an issue without its subtasks also being deleted. * * @method deleteIssue * @memberof IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param {boolean} [opts.deleteSubTasks] "a String of true or false indicating that any subtasks should also * be deleted. If the issue has no subtasks this parameter is ignored. If the issue has subtasks and this * parameter is missing or false, then the issue will not be deleted and an error will be returned." * @param callback */ this.deleteIssue = function (opts, callback) { var options = this.buildRequestOptions(opts, '', 'DELETE', null, {deleteSubTasks: opts.deleteSubTasks}); this.jiraClient.makeRequest(options, callback, 'Issue Deleted'); }; /** * Edits an issue from a JSON representation. * * The issue can either be updated by setting explicit the field value(s) or by using an operation to change the * field value. * * The fields that can be updated, in either the fields parameter or the update parameter, can be determined using * the {@link IssueClient#getEditMetadata} method. If a field is not configured to appear on the edit * screen, then it will not be in the editmeta, and a field validation error will occur if it is submitted. * * Specifying a "field_id": field_value in the "fields" is a shorthand for a "set" operation in the "update" * section. Field should appear either in "fields" or "update", not in both. * * @method editIssue * @memberof IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param {Object} opts.issue See {@link https://docs.atlassian.com/jira/REST/latest/#d2e656} * @param callback */ this.editIssue = function (opts, callback) { if (!opts.issue) { throw new Error(errorStrings.NO_ISSUE_ERROR); } var options = this.buildRequestOptions(opts, '', 'PUT', opts.issue); this.jiraClient.makeRequest(options, callback, 'Issue Updated'); }; /** * Assigns an issue to a user. You can use this resource to assign issues when the user submitting the request has * the assign permission but not the edit issue permission. If the name is "-1" automatic assignee is used. A null * name will remove the assignee. * * @method assignIssue * @memberof IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param {string} opts.assignee The name of the user to whom to assign the issue. -1 for default, null for no * assignee. * @param callback Called when the issue has been assigned. */ this.assignIssue = function (opts, callback) { if (typeof opts.assignee === "string" && opts.assignee.length || opts.assignee === null) { var options = this.buildRequestOptions(opts, '/assignee', 'PUT', {name: opts.assignee}); this.jiraClient.makeRequest(options, callback, 'Issue Assigned'); } else { throw new Error(errorStrings.NO_ASSIGNEE_ERROR); } }; /** * Get all the comments for an issue. * * @method getComments * @memberof IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param {Object} opts.expand See {@link https://docs.atlassian.com/jira/REST/latest/#d2e461} * @param callback Called when the issue has been assigned. */ this.getComments = function (opts, callback) { var options = this.buildRequestOptions(opts, '/comment', 'GET'); this.jiraClient.makeRequest(options, callback); }; /** * Add a comment to an issue * * @method addComment * @memberof IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param {Object} opts.comment See {@link https://docs.atlassian.com/jira/REST/latest/#d2e482} * @param callback */ this.addComment = function (opts, callback) { var options = this.buildRequestOptions(opts, '/comment', 'POST', opts.comment); this.jiraClient.makeRequest(options, callback); }; /** * Get a specific comment. * * @method getComment * @memberof IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param {string} opts.commentId The id of the comment. * @param callback Called when the comment is retrieved. */ this.getComment = function (opts, callback) { if (!opts.commentId) { throw new Error(errorStrings.NO_COMMENT_ID); } var options = this.buildRequestOptions(opts, '/comment/' + opts.commentId, 'GET'); this.jiraClient.makeRequest(options, callback); }; /** * Updates an existing comment using its JSON representation. * * @method editComment * @memberof IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param {string} opts.commentId The id of the comment. * @param {Object} opts.comment See {@link https://docs.atlassian.com/jira/REST/latest/#d2e539} * @param callback */ this.editComment = function (opts, callback) { if (!opts.comment) { throw new Error(errorStrings.NO_COMMENT_ERROR); } else if (!opts.commentId) { throw new Error(errorStrings.NO_COMMENT_ID); } var options = this.buildRequestOptions(opts, '/comment/' + opts.commentId, 'PUT', opts.comment); this.jiraClient.makeRequest(options, callback); }; /** * Delete an existing comment. * * @method deleteComment * @memberof IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param {string} opts.commentId The id of the comment. * @param callback Called when the comment is retrieved. */ this.deleteComment = function (opts, callback) { if (!opts.commentId) { throw new Error(errorStrings.NO_COMMENT_ID); } var options = this.buildRequestOptions(opts, '/comment/' + opts.commentId, 'DELETE'); this.jiraClient.makeRequest(options, callback, 'Comment Deleted'); }; /** * Returns the meta data for editing an issue. * * The fields in the editmeta correspond to the fields in the edit screen for the issue. Fields not in the screen * will not be in the editemeta. * * @method getEditMetadata * @memberof IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param callback Called when the metadata is retrieved. */ this.getEditMetadata = function (opts, callback) { var options = this.buildRequestOptions(opts, '/editmeta', 'GET'); this.jiraClient.makeRequest(options, callback); }; /** * Sends a notification (email) to the list or recipients defined in the request. * A couple of notes: this may call back with the error 'No recipients were defined for notification.' if all * of the intended recipients have disabled notifications from Jira. * * @method sendEmailNotification * @memberof IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param {Object} opts.notification See {@link https://docs.atlassian.com/jira/REST/latest/#d2e435} * @param callback Called when the metadata is retrieved. */ this.sendEmailNotification = function (opts, callback) { if (!opts.notification) { throw new Error(errorStrings.NO_NOTIFICATION_ERROR); } var options = this.buildRequestOptions(opts, '/notify', 'POST', opts.notification); this.jiraClient.makeRequest(options, callback, 'Notifications Sent'); }; /** * Get a REST sub-resource representing the remote issue links on the issue. * * @method getRemoteLinks * @memberof IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param {string} opts.globalId The id of the remote issue link to be returned. If null (not provided) all remote * links for the issue are returned. For a full explanation of Issue Link fields please refer to * {@link https://developer.atlassian.com/display/JIRADEV/Fields+in+Remote+Issue+Links} * @param callback Called when the remote links are retrieved. */ this.getRemoteLinks = function (opts, callback) { var options = this.buildRequestOptions(opts, '/remotelink', 'GET', null, {globalId: opts.globalId}); this.jiraClient.makeRequest(options, callback); }; /** * Creates (or updates) a remote issue link from a JSON representation. If a globalId is provided and a remote issue * link exists with that globalId, the remote issue link is updated. Otherwise, the remote issue link is created. * * @method createRemoteLink * @memberof IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param {Object} opts.remoteLink See {@link https://docs.atlassian.com/jira/REST/latest/#d2e945} * @param callback Called when the remote links are retrieved. */ this.createRemoteLink = function (opts, callback) { var options = this.buildRequestOptions(opts, '/remotelink', 'POST', opts.remoteLink); this.jiraClient.makeRequest(options, callback); }; /** * Updates (or creates) a remote issue link from a JSON representation. If a globalId is provided and a remote issue * link exists with that globalId, the remote issue link is updated. Otherwise, the remote issue link is created. * * @method updateRemoteLink * @memberof IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param {Object} opts.remoteLink See {@link https://docs.atlassian.com/jira/REST/latest/#d2e945} * @param callback Called when the remote links are retrieved. */ this.updateRemoteLink = function (opts, callback) { // The one API endpoint handles both updates and creation. this.createRemoteLink(opts, callback); }; /** * Delete the remote issue link with the given global id on the issue. * * @method deleteRemoteLink * @memberof IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param {string} opts.globalId The global id of the remote issue link * @param callback Called when the remote links are retrieved. */ this.deleteRemoteLink = function (opts, callback) { if (!opts.globalId) { throw new Error(errorStrings.NO_GLOBAL_ID_ERROR); } var options = this.buildRequestOptions(opts, '/remotelink', 'DELETE', null, {globalId: opts.globalId}); this.jiraClient.makeRequest(options, callback, 'RemoteLink Deleted'); }; /** * Get the remote issue link with the given id on the issue. * * @method getRemoteLinkById * @memberof IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param {string} opts.linkId The id of the remote link * @param callback Called when the remote links are retrieved. */ this.getRemoteLinkById = function (opts, callback) { if (!opts.linkId) { throw new Error(errorStrings.NO_LINK_ID_ERROR); } var options = this.buildRequestOptions(opts, '/remotelink/' + opts.linkId, 'GET'); this.jiraClient.makeRequest(options, callback); }; /** * Get the remote issue link with the given id on the issue. * * @method updateRemoteLinkById * @memberof IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param {string} opts.linkId The id of the remote link * @param {string} opts.remoteLink See {@link https://docs.atlassian.com/jira/REST/latest/#d2e1037} * @param callback Called when the remote links are retrieved. */ this.updateRemoteLinkById = function (opts, callback) { if (!opts.linkId) { throw new Error(errorStrings.NO_LINK_ID_ERROR); } var options = this.buildRequestOptions(opts, '/remotelink/' + opts.linkId, 'PUT', opts.remoteLink); this.jiraClient.makeRequest(options, callback, 'RemoteLink Updated'); }; /** * Get the remote issue link with the given id on the issue. * * @method deleteRemoteLinkById * @memberof IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param {string} opts.linkId The id of the remote link * @param callback Called when the remote links are retrieved. */ this.deleteRemoteLinkById = function (opts, callback) { if (!opts.linkId) { throw new Error(errorStrings.NO_LINK_ID_ERROR); } var options = this.buildRequestOptions(opts, '/remotelink/' + opts.linkId, 'DELETE'); this.jiraClient.makeRequest(options, callback, 'RemoteLink Deleted'); }; /** * Get a list of the transitions possible for this issue by the current user, along with fields that are required * and their types. * * Fields will only be returned if ```expand=transitions.fields.``` * * The fields in the metadata correspond to the fields in the transition screen for that transition. Fields not in * the screen will not be in the metadata. * * @method getTransitions * @memberof IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param {string} opts.transitionId If specified, will call back with only the transition with the specified id. * @param callback Called when the transitions are retrieved. */ this.getTransitions = function (opts, callback) { var options = this.buildRequestOptions(opts, '/transitions', 'GET', null, {transitionId: opts.transitionId}); this.jiraClient.makeRequest(options, callback); }; /** * Perform a transition on an issue. When performing the transition you can udate or set other issue fields. * * The fields that can be set on transtion, in either the fields parameter or the update parameter can be * determined using the** /rest/api/2/issue/{issueIdOrKey}/transitions?expand=transitions.fields resource**. If a * field is not configured to appear on the transition screen, then it will not be in the transition metadata, and * a field validation error will occur if it is submitted. * * @method getTransitions * @memberof IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param {string} opts.transition See {@link https://docs.atlassian.com/jira/REST/latest/#d2e698} * @param callback Called when the transitions are retrieved. */ this.transitionIssue = function (opts, callback) { if (!opts.transition) { throw new Error(errorStrings.NO_TRANSITION_ERROR); } var options = this.buildRequestOptions(opts, '/transitions', 'POST', opts.transition); this.jiraClient.makeRequest(options, callback, 'Issue Transitioned'); }; /** * Remove your vote from an issue. (i.e. "unvote") * * @method unvote * @memberof IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param callback Called after the vote is removed. */ this.unvote = function (opts, callback) { var options = this.buildRequestOptions(opts, '/votes', 'DELETE'); this.jiraClient.makeRequest(options, callback, 'Vote Removed'); }; /** * Cast your vote in favour of an issue. * * @method vote * @memberof IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param callback Called after the vote is removed. */ this.vote = function (opts, callback) { var options = this.buildRequestOptions(opts, '/votes', 'POST'); this.jiraClient.makeRequest(options, callback, 'Vote Added'); }; /** * Get a REST sub-resource representing the voters on the issue. * * @method getVotes * @memberof IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param callback Called after the votes are retrieved. */ this.getVotes = function (opts, callback) { var options = this.buildRequestOptions(opts, '/votes', 'GET'); this.jiraClient.makeRequest(options, callback); }; /** * Returns the list of watchers for the issue with the given key. * * @method getWatchers * @memberOf IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param callback Called after the watchers are retrieved. */ this.getWatchers = function (opts, callback) { var options = this.buildRequestOptions(opts, '/watchers', 'GET'); this.jiraClient.makeRequest(options, callback); }; /** * Adds a user to an issue's watcher list. * * @method addWatcher * @memberOf IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param {string} opts.watcher The username of the user to add as a watcher. * @param callback Called after the watcher is added. */ this.addWatcher = function (opts, callback) { if (!opts.watcher) { throw new Error(errorStrings.NO_WATCHER_ERROR); } var options = this.buildRequestOptions(opts, '/watchers', 'POST', opts.watcher); this.jiraClient.makeRequest(options, callback, 'Watcher Added'); }; /** * Adds a user to an issue's watcher list. * * @method removeWatcher * @memberOf IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param {string} opts.watcher The username of the user to remove as a watcher. * @param callback Called after the watcher is removed. */ this.removeWatcher = function (opts, callback) { if (!opts.watcher) { throw new Error(errorStrings.NO_WATCHER_ERROR); } var options = this.buildRequestOptions(opts, '/watchers', 'DELETE', null, {username: opts.watcher}); this.jiraClient.makeRequest(options, callback, 'Watcher Removed'); }; /** * Gets all work logs for an issue. * * @method getWorkLogs * @memberOf IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param callback Called after the worklogs are retrieved. */ this.getWorkLogs = function (opts, callback) { var options = this.buildRequestOptions(opts, '/worklog', 'GET'); this.jiraClient.makeRequest(options, callback); }; /** * Adds a new worklog entry to an issue. * * @method addWorkLog * @memberOf IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param {string} [opts.adjustEstimate] Allows you to provide specific instructions to update the remaining time * estimate of the issue. Valid values are * * "new" - sets the estimate to a specific value * * "leave"- leaves the estimate as is * * "manual" - specify a specific amount to increase remaining estimate by * * "auto"- Default option. Will automatically adjust the value based on the * new timeSpent specified on the worklog * @param {string} [opts.newEstimate] (required when "new" is selected for adjustEstimate) the new value for the * remaining estimate field. e.g. "2d" * @param {string} [opts.reduceBy] (required when "manual" is selected for adjustEstimate) the amount to reduce the * remaining estimate by e.g. "2d" * @param {Object} opts.worklog See {@link: https://docs.atlassian.com/jira/REST/latest/#d2e1106} * @param callback Called after the worklog is added. */ this.addWorkLog = function (opts, callback) { if (!opts.worklog) { throw new Error(errorStrings.NO_WORKLOG_ERROR); } var options = this.buildRequestOptions(opts, '/worklog', 'POST', opts.worklog, { newEstimate: opts.newEstimate, reduceBy: opts.reduceBy, adjustEstimate: opts.adjustEstimate }); this.jiraClient.makeRequest(options, callback, 'Worklog Added'); }; /** * Gets a specific worklog. * * @method getWorkLog * @memberOf IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param {string} opts.worklogId The id of the work log to retrieve. * @param callback Called after the worklog is retrieved. */ this.getWorkLog = function (opts, callback) { if (!opts.worklogId) { throw new Error(errorStrings.NO_WORKLOG_ID_ERROR); } var options = this.buildRequestOptions(opts, '/worklog/' + opts.worklogId, 'GET'); this.jiraClient.makeRequest(options, callback); }; /** * Updates an existing worklog entry using its JSON representation. * * @method updateWorkLog * @memberOf IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param {string} opts.worklogId The id of the work log to retrieve. * @param {string} [opts.adjustEstimate] Allows you to provide specific instructions to update the remaining time * estimate of the issue. Valid values are * * "new" - sets the estimate to a specific value * * "leave"- leaves the estimate as is * * "auto"- Default option. Will automatically adjust the value based on the * new timeSpent specified on the worklog * @param {string} [opts.newEstimate] (required when "new" is selected for adjustEstimate) the new value for the * remaining estimate field. e.g. "2d" * @param {Object} opts.worklog See {@link: https://docs.atlassian.com/jira/REST/latest/#d2e1161} * @param callback Called after the worklog is updated. */ this.updateWorkLog = function (opts, callback) { if (!opts.worklogId) { throw new Error(errorStrings.NO_WORKLOG_ID_ERROR); } else if (!opts.worklog) { throw new Error(errorStrings.NO_WORKLOG_ERROR); } var options = this.buildRequestOptions(opts, '/worklog/' + opts.worklogId, 'PUT', opts.worklog, { newEstimate: opts.newEstimate, adjustEstimate: opts.adjustEstimate }); this.jiraClient.makeRequest(options, callback); }; /** * Deletes an existing worklog entry * * @method deleteWorkLog * @memberOf IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param {string} opts.worklogId The id of the work log to delete. * @param {string} [opts.adjustEstimate] Allows you to provide specific instructions to update the remaining time * estimate of the issue. Valid values are * * "new" - sets the estimate to a specific value * * "leave"- leaves the estimate as is * * "manual" - specify a specific amount to increase remaining estimate by * * "auto"- Default option. Will automatically adjust the value based on the * new timeSpent specified on the worklog * @param {string} [opts.newEstimate] (required when "new" is selected for adjustEstimate) the new value for the * remaining estimate field. e.g. "2d" * @param {string} [opts.increaseBy] (required when "manual" is selected for adjustEstimate) the amount to reduce * the remaining estimate by e.g. "2d" * @param callback Called after the work log is deleted. */ this.deleteWorkLog = function (opts, callback) { if (!opts.worklogId) { throw new Error(errorStrings.NO_WORKLOG_ID_ERROR); } var options = this.buildRequestOptions(opts, '/worklog/' + opts.worklogId, 'DELETE', null, { newEstimate: opts.newEstimate, increaseBy: opts.increaseBy, adjustEstimate: opts.adjustEstimate }); this.jiraClient.makeRequest(options, callback, 'Work Log Deleted'); }; /** * Add an attachments to an issue. * * @method addAttachment * @memberOf IssueClient.js * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param {string} opts.filename The file name of attachment. If you pass an array of filenames, multiple attachments will be added. * @param callback Called when the attachment has been attached. */ this.addAttachment = function (opts, callback) { if (!opts.filename) { throw new Error(errorStrings.NO_FILENAME_ERROR); } var options = this.buildRequestOptions(opts, '/attachments', 'POST'); delete options.body; if (opts.filename.constructor !== Array) opts.filename = [opts.filename]; var attachments = opts.filename.map (function (filename) {return fs.createReadStream(filename)}); options.formData = {file: attachments}; options.headers = { "X-Atlassian-Token": "nocheck" }; this.jiraClient.makeRequest(options, callback); }; /** * Returns the keys of all properties for the issue identified by the key or by the id. This function is maked as * experimental in the Jira API docs, use at your own risk. * * @method getProperties * @memberOf IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param callback Called when the properties are retrieved. */ this.getProperties = function (opts, callback) { var options = this.buildRequestOptions(opts, '/properties', 'GET'); this.jiraClient.makeRequest(options, callback); }; /** * Sets the value of the specified issue's property. You can use this resource to store a custom data against the * issue identified by the key or by the id. The user who stores the data is required to have permissions to edit * the issue. * * This function is maked as experimental in the Jira API docs, use at your own risk. * * @method setProperty * @memberOf IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param {string} opts.propertyKey The key of the property being set. * @param {Object} opts.propertyValue The value of the property being set. * @param callback Called when the property is set. */ this.setProperty = function (opts, callback) { if (!opts.propertyKey) { throw new Error(errorStrings.NO_PROPERTY_KEY_ERROR); } else if (!opts.propertyValue) { throw new Error(errorStrings.NO_PROPERTY_VALUE_ERROR); } var options = this.buildRequestOptions(opts, '/properties/' + opts.propertyKey, 'PUT', opts.propertyValue); this.jiraClient.makeRequest(options, callback, 'Property Set'); }; /** * Returns the value of the property with a given key from the issue identified by the key or by the id. The user * who retrieves the property is required to have permissions to read the issue. * * This function is maked as experimental in the Jira API docs, use at your own risk. * * @method getProperty * @memberOf IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param {string} opts.propertyKey The key of the property being set. * @param callback Called when the property is retrieved. */ this.getProperty = function (opts, callback) { if (!opts.propertyKey) { throw new Error(errorStrings.NO_PROPERTY_KEY_ERROR); } var options = this.buildRequestOptions(opts, '/properties/' + opts.propertyKey, 'GET'); this.jiraClient.makeRequest(options, callback); }; /** * Removes the property from the issue identified by the key or by the id. Ths user removing the property is * required to have permissions to edit the issue. * * This function is maked as experimental in the Jira API docs, use at your own risk. * * @method getProperty * @memberOf IssueClient# * @param {Object} opts The options to pass to the API. Note that this object must contain EITHER an issueId or * issueKey property; issueId will be used over issueKey if both are present. * @param {string} [opts.issueId] The id of the issue. EX: 10002 * @param {string} [opts.issueKey] The Key of the issue. EX: JWR-3 * @param {string} opts.propertyKey The key of the property being set. * @param callback Called when the property is deleted. */ this.deleteProperty = function (opts, callback) { if (!opts.propertyKey) { throw new Error(errorStrings.NO_PROPERTY_KEY_ERROR); } var options = this.buildRequestOptions(opts, '/properties/' + opts.propertyKey, 'DELETE'); this.jiraClient.makeRequest(options, callback, 'Property Deleted'); }; /** * Build out the request options necessary to make a particular API call. * * @private * @method buildRequestOptions * @param {Object} opts The arguments passed to the method. * @param {string} path The path of the endpoint following /issue/{idOrKey} * @param {string} method The request method. * @param {Object} [body] The request body, if any. * @param {Object} [qs] The querystring, if any. opts.expand and opts.fields arrays will be automagically added. * @returns {{uri: string, method: string, body: Object, qs: Object, followAllRedirects: boolean, json: boolean}} */ this.buildRequestOptions = function (opts, path, method, body, qs) { if (!opts.issueId && !opts.issueKey) { throw new Error(errorStrings.NO_ISSUE_IDENTIFIER); } var idOrKey = opts.issueId || opts.issueKey; var basePath = '/issue/' + idOrKey; if (!qs) qs = {}; if (!body) body = {}; if (opts.fields) { qs.fields = ''; opts.fields.forEach(function (field) { qs.fields += field + ',' }); } if (opts.expand) { qs.expand = ''; opts.expand.forEach(function (ex) { qs.expand += ex + ',' }); } return { uri: this.jiraClient.buildURL(basePath + path), method: method, body: body, qs: qs, followAllRedirects: true, json: true }; } } </code></pre> </article> </section> </div> <nav> <h2><a href="index.html">Home</a></h2> <h3>Classes</h3> <ul> <li><a href="ApplicationPropertiesClient.html">ApplicationPropertiesClient</a></li> <li><a href="AttachmentClient.html">AttachmentClient</a></li> <li><a href="AuditingClient.html">AuditingClient</a></li> <li><a href="AvatarClient.html">AvatarClient</a></li> <li><a href="CommentClient.html">CommentClient</a></li> <li><a href="ComponentClient.html">ComponentClient</a></li> <li><a href="CustomFieldOptionClient.html">CustomFieldOptionClient</a></li> <li><a href="DashboardClient.html">DashboardClient</a></li> <li><a href="FieldClient.html">FieldClient</a></li> <li