synergia-jira-connector
Version:
Easy to use NodeJS wrapper for the Jira REST API.
636 lines (596 loc) • 25.1 kB
HTML
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>JSDoc: Source: api/user.js</title>
<script src="scripts/prettify/prettify.js"></script>
<script src="scripts/prettify/lang-css.js"></script>
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<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/user.js</h1>
<section>
<article>
<pre class="prettyprint source linenums"><code>"use strict";
var fs = require('fs');
var path = require('path');
module.exports = UserClient;
/**
* Used to access Jira REST endpoints in '/rest/api/2/user'
*
* @param {JiraClient} jiraClient
* @constructor UserClient
*/
function UserClient(jiraClient) {
this.jiraClient = jiraClient;
/**
* Get a user. This resource cannot be accessed anonymously.
*
* @method getUser
* @memberOf UserClient#
* @param opts The request options sent to the Jira API
* @param opts.username The name of the user to retrieve.
* @param opts.userKey The key of the user to retrieve.
* @param callback Called when the user has been retrieved.
*/
this.getUser = function (opts, callback) {
var options = {
uri: this.jiraClient.buildURL('/user'),
method: 'GET',
json: true,
followAllRedirects: true,
qs: {
username: opts.username,
key: opts.userKey
}
};
this.jiraClient.makeRequest(options, callback);
};
/**
* Removes user.
*
* @method deleteUser
* @memberOf UserClient#
* @param opts The request options sent to the Jira API
* @param opts.username The name of the user to delete.
* @param opts.userKey The key of the user to delete.
* @param callback Called when the user has been deleted.
*/
this.deleteUser = function (opts, callback) {
var options = {
uri: this.jiraClient.buildURL('/user'),
method: 'DELETE',
json: true,
followAllRedirects: true,
qs: {
username: opts.username,
key: opts.userKey
}
};
this.jiraClient.makeRequest(options, callback, 'User removed.');
};
/**
* Create user. By default created user will not be notified with email. If password field is not set then password
* will be randomly generated.
*
* @method createUser
* @memberOf UserClient#
* @param opts The request options sent to the Jira API.
* @param opts.user See {@link https://docs.atlassian.com/jira/REST/latest/#d2e4049}
* @param callback Called when the user has been created.
*/
this.createUser = function (opts, callback) {
var options = {
uri: this.jiraClient.buildURL('/user'),
method: 'POST',
json: true,
followAllRedirects: true,
body: opts.user
};
this.jiraClient.makeRequest(options, callback);
};
/**
* Modify user. The "value" fields present will override the existing value. Fields skipped in request will not be
* changed.
*
* @method editUser
* @memberOf UserClient#
* @param opts The request options sent to the Jira API
* @param opts.user See {@link https://docs.atlassian.com/jira/REST/latest/#d2e4081}
* @param opts.username The name of the user to edit.
* @param opts.userKey The key of the user to edit.
* @param callback Called when the user has been edited.
*/
this.editUser = function (opts, callback) {
var options = {
uri: this.jiraClient.buildURL('/user'),
method: 'PUT',
json: true,
followAllRedirects: true,
qs: {
username: opts.username,
key: opts.userKey
},
body: opts.user
};
this.jiraClient.makeRequest(options, callback);
};
/**
* Returns a list of users that match the search string and can be assigned issues for all the given projects. This
* resource cannot be accessed anonymously.
*
* @method multiProjectSearchAssignable
* @memberOf UserClient#
* @param {Object} opts The request options sent to the Jira API
* @param {string} opts.username The name of the user to search.
* @param {Array} opts.projectKeys The keys of the projects we are finding assignable users for
* @param {number} [opts.startAt] The index of the first user to return (0-based)
* @param {number} [opts.maxResults] The maximum number of users to return (defaults to 50). The maximum allowed
* value is 1000. If you specify a value that is higher than this number, your search results will be
* truncated.
* @param callback Called when the search results have been retrieved.
*/
this.multiProjectSearchAssignable = function (opts, callback) {
var projectKeyString = '';
if (opts.projectKeys) {
opts.projectKeys.forEach(function (key) {
projectKeyString += key + ',';
});
projectKeyString = projectKeyString.slice(0, -1);
}
var options = {
uri: this.jiraClient.buildURL('/user/assignable/multiProjectSearch'),
method: 'GET',
json: true,
followAllRedirects: true,
qs: {
username: opts.username,
projectKeys: projectKeyString,
startAt: opts.startAt,
maxResults: opts.maxResults
}
};
this.jiraClient.makeRequest(options, callback);
};
/**
* Returns a list of users that match the search string. This resource cannot be accessed anonymously. Please note
* that this resource should be called with an issue key when a list of assignable users is retrieved for editing.
* For create only a project key should be supplied. The list of assignable users may be incorrect if it's called
* with the project key for editing.
*
* @method searchAssignable
* @memberOf UserClient#
* @param {Object} opts The request options sent to the Jira API
* @param {string} opts.username The username
* @param {string} opts.project The key of the project we are finding assignable users for
* @param {string} [opts.issueKey] The issue key for the issue being edited we need to find assignable users for.
* @param {number} [opts.startAt] The index of the first user to return (0-based)
* @param {number} [opts.maxResults] The maximum number of users to return (defaults to 50). The maximum allowed
* value is 1000. If you specify a value that is higher than this number, your search results will be
* truncated.
* @param {number} [opts.actionDescriptorId]
* @param callback Called when the search results have been retrieved.
*/
this.searchAssignable = function (opts, callback) {
var options = {
uri: this.jiraClient.buildURL('/user/assignable/search'),
method: 'GET',
json: true,
followAllRedirects: true,
qs: {
username: opts.username,
project: opts.project,
issueKey: opts.issueKey,
startAt: opts.startAt,
maxResults: opts.maxResults,
actionDescriptorId: opts.actionDescriptorId
}
};
this.jiraClient.makeRequest(options, callback);
};
/**
* Creates temporary avatar. Creating a temporary avatar is part of a 3-step process in uploading a new avatar for
* a user: upload, crop, confirm.
*
* @method createTemporaryAvatar
* @memberOf UserClient#
* @param {Object} opts The request options sent to the Jira API
* @param {string} opts.username The username
* @param {string} opts.filepath The path to the file to upload.
* @param callback Called when the temporary avatar has been uploaded.
*/
this.createTemporaryAvatar = function (opts, callback) {
var extension = path.extname(opts.filepath).slice(1);
var baseName = path.basename(opts.filepath);
var fileSize = fs.statSync(opts.filepath).size;
extension = extension == 'jpg' ? 'jpeg' : extension;
var options = {
uri: this.jiraClient.buildURL('/user/avatar/temporary'),
method: 'POST',
followAllRedirects: true,
qs: {
username: opts.username,
filename: baseName,
size: fileSize
},
body: fs.readFileSync(opts.filepath),
headers: {
"X-Atlassian-Token": 'no-check',
"Content-Type": 'image/' + extension
}
};
this.jiraClient.makeRequest(options, callback);
};
/**
* Converts temporary avatar into a real avatar
*
* @method convertTemporaryAvatar
* @memberOf UserClient#
* @param {Object} opts The request options sent to the Jira API
* @param {string} opts.username The username
* @param {Object} opts.avatarId The id of the temporary avatar to convert.
* @param callback Called when the avatar has been converted
*/
this.convertTemporaryAvatar = function (opts, callback) {
var options = {
uri: this.jiraClient.buildURL('/user/avatar/'),
method: 'PUT',
json: true,
followAllRedirects: true,
qs: {
username: opts.username
},
body: {id: opts.avatarId},
headers: {
"X-Atlassian-Token": 'no-check'
}
};
this.jiraClient.makeRequest(options, callback, 'Avatar Converted');
};
/**
* Deletes avatar
*
* @method deleteAvatar
* @memberOf UserClient#
* @param {Object} opts The request options sent to the Jira API
* @param {string} opts.username The username
* @param {Object} opts.avatarId The id of the temporary avatar to delete.
* @param callback Called when the avatar has been deleted.
*/
this.deleteAvatar = function (opts, callback) {
var options = {
uri: this.jiraClient.buildURL('/user/avatar/' + opts.avatarId),
method: 'DELETE',
json: true,
followAllRedirects: true,
qs: {
username: opts.username
}
};
this.jiraClient.makeRequest(options, callback, 'Avatar Deleted');
};
/**
* Returns all avatars which are visible for the currently logged in user.
*
* @method getAvatars
* @memberOf UserClient#
* @param {Object} opts The request options sent to the Jira API
* @param {string} opts.username The username
* @param callback Called when the avatars have been retrieved.
*/
this.getAvatars = function (opts, callback) {
var options = {
uri: this.jiraClient.buildURL('/user/avatars'),
method: 'GET',
json: true,
followAllRedirects: true,
qs: {
username: opts.username
}
};
this.jiraClient.makeRequest(options, callback);
};
/**
* Returns the default columns for the given user. Admin permission will be required to get columns for a user
* other than the currently logged in user.
*
* @method getDefaultColumns
* @memberOf UserClient#
* @param {Object} opts The request options sent to the Jira API
* @param {string} opts.username The username
* @param callback Called when the columns have been retrieved.
*/
this.getDefaultColumns = function (opts, callback) {
var options = {
uri: this.jiraClient.buildURL('/user/columns'),
method: 'GET',
json: true,
followAllRedirects: true,
qs: {
username: opts.username
}
};
this.jiraClient.makeRequest(options, callback);
};
/**
* Sets the default columns for the given user. Admin permission will be required to get columns for a user other
* than the currently logged in user.
*
* @method setDefaultColumns
* @memberOf UserClient#
* @param {Object} opts The request options sent to the Jira API
* @param {string} opts.username The username
* @param {Array} opts.columns The names of the new columns. See {@link
* https://docs.atlassian.com/jira/REST/latest/#d2e4566}
* @param callback Called when the columns have been set.
*/
this.setDefaultColumns = function (opts, callback) {
var options = {
uri: this.jiraClient.buildURL('/user/columns'),
method: 'PUT',
json: true,
followAllRedirects: true,
qs: {
username: opts.username
},
body: {
columns: opts.columns
}
};
this.jiraClient.makeRequest(options, callback, 'Default Columns Set');
};
/**
* Reset the default columns for the given user to the system default. Admin permission will be required to get
* columns for a user other than the currently logged in user.
*
* @method resetDefaultColumns
* @memberOf UserClient#
* @param {Object} opts The request options sent to the Jira API
* @param {string} opts.username The username
* @param callback Called when the columns have been reset.
*/
this.resetDefaultColumns = function (opts, callback) {
var options = {
uri: this.jiraClient.buildURL('/user/columns'),
method: 'DELETE',
json: true,
followAllRedirects: true,
qs: {
username: opts.username
}
};
this.jiraClient.makeRequest(options, callback, 'Default Columns Reset');
};
/**
* Modify user password.
*
* @method changePassword
* @memberOf UserClient#
* @param opts The request options sent to the Jira API
* @param opts.username The name of the user for which to change the password.
* @param opts.userKey The key of the user for which to change the password.
* @param opts.password The new password.
* @param callback Called when the password has been set.
*/
this.changePassword = function (opts, callback) {
var options = {
uri: this.jiraClient.buildURL('/user/password'),
method: 'PUT',
json: true,
followAllRedirects: true,
qs: {
username: opts.username,
key: opts.userKey
},
body: {
password: opts.password
}
};
this.jiraClient.makeRequest(options, callback, 'Password Changed');
};
/**
* Returns a list of active users that match the search string and have all specified permissions for the project
* or issue.
*
* This resource can be accessed by users with ADMINISTER_PROJECT permission for the project or global
* ADMIN or SYSADMIN rights.
*
* @method searchPermissions
* @memberOf UserClient#
* @param {Object} opts The request options sent to the jira API
* @param {string} opts.username The username filter, list includes all users if unspecified
* @param {Array} opts.permissions Array of permissions for project or issue returned users must have, see
* [Permissions]{@link
* https://developer.atlassian.com/static/javadoc/jira/6.0/reference/com/atlassian/jira/security/Permissions.Permission.html}
* JavaDoc for the list of all possible permissions.
* @param {string} [opts.issueKey] the issue key for the issue for which returned users have specified permissions.
* @param {string} [opts.projectKey] the optional project key to search for users with if no issueKey is supplied.
* @param {number} [opts.startAt] the index of the first user to return (0-based)
* @param {number} [opts.maxResults] the maximum number of users to return (defaults to 50). The maximum allowed
* value is 1000. If you specify a value that is higher than this number, your search results will be
* truncated.
* @param callback Called when the search results are retrieved.
*/
this.searchPermissions = function (opts, callback) {
var permissions = '';
if (opts.permissions) {
opts.permissions.forEach(function (s) {
permissions += s + ','
});
permissions = permissions.slice(0, -1);
}
var options = {
uri: this.jiraClient.buildURL('/user/permission/search'),
method: 'GET',
json: true,
followAllRedirects: true,
qs: {
username: opts.username,
permissions: permissions,
issueKey: opts.issueKey,
projectKey: opts.projectKey,
startAt: opts.startAt,
maxResults: opts.maxResults
}
};
this.jiraClient.makeRequest(options, callback);
};
/**
* Returns a list of users matching query with highlighting. This resource cannot be accessed anonymously.
*
* @method searchPicker
* @memberOf UserClient#
* @param opts The request options sent to the Jira API.
* @param {string} opts.query
* @param {number} [opts.maxResults=50]
* @param {boolean} [opts.showAvatar=false]
* @param {string} [opts.exclude]
* @param callback Called when the search results are retrieved.
*/
this.searchPicker = function (opts, callback) {
var options = {
uri: this.jiraClient.buildURL('/user/picker'),
method: 'GET',
json: true,
followAllRedirects: true,
qs: {
query: opts.query,
maxResults: opts.maxResults,
showAvatar: opts.showAvatar,
exclude: opts.exclude
}
};
this.jiraClient.makeRequest(options, callback);
};
/**
* Returns a list of users that match the search string. This resource cannot be accessed anonymously.
*
* @method search
* @memberOf UserClient#
* @param {Object} opts The request options sent to the Jira API.
* @param {string} opts.username A query string used to search username, name or e-mail address
* @param {number} [opts.startAt=0] the index of the first user to return (0-based)
* @param {number} [opts.maxResults=50] the maximum number of users to return (defaults to 50). The maximum allowed
* value is 1000. If you specify a value that is higher than this number, your search results will be
* truncated.
* @param {boolean} [opts.includeActive=true] If true, then active users are included in the results (default true)
* @param {boolean} [opts.includeInactive=false] If true, then inactive users are included in the results (default
* false)
* @param callback Called when the search results are retrieved.
*/
this.search = function (opts, callback) {
var options = {
uri: this.jiraClient.buildURL('/user/search'),
method: 'GET',
json: true,
followAllRedirects: true,
qs: {
username: opts.username,
maxResults: opts.maxResults,
startAt: opts.startAt,
includeActive: opts.includeActive,
includeInactive: opts.includeInactive
}
};
this.jiraClient.makeRequest(options, callback);
};
/**
* Returns a list of active users that match the search string. This resource cannot be accessed anonymously. Given
* an issue key this resource will provide a list of users that match the search string and have the browse issue
* permission for the issue provided.
*
* @method viewIssueSearch
* @memberOf UserClient#
* @param {Object} opts The request options sent to the Jira API.
* @param {string} opts.username A query string used to search username, name or e-mail address
* @param {string} [opts.issueKey] the issue key for the issue being edited we need to find viewable users for.
* @param {string} [opts.projectKey] the optional project key to search for users with if no issueKey is supplied.
* @param {number} [opts.startAt=0] the index of the first user to return (0-based)
* @param {number} [opts.maxResults=50] the maximum number of users to return (defaults to 50). The maximum allowed
* @param callback
*/
this.viewIssueSearch = function (opts, callback) {
var options = {
uri: this.jiraClient.buildURL('/user/viewissue/search'),
method: 'GET',
json: true,
followAllRedirects: true,
qs: {
username: opts.username,
issueKey: opts.issueKey,
projectKey: opts.projectKey,
startAt: opts.startAt,
maxResults: opts.maxResults
}
};
this.jiraClient.makeRequest(options, callback);
};
}</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><a href="FilterClient.html">FilterClient</a></li>
<li><a href="GroupClient.html">GroupClient</a></li>
<li><a href="GroupsClient.html">GroupsClient</a></li>
<li><a href="GroupUserPickerClient.html">GroupUserPickerClient</a></li>
<li><a href="IssueClient.html">IssueClient</a></li>
<li><a href="IssueLinkClient.html">IssueLinkClient</a></li>
<li><a href="IssueLinkTypeClient.html">IssueLinkTypeClient</a></li>
<li><a href="IssueTypeClient.html">IssueTypeClient</a></li>
<li><a href="JiraClient.html">JiraClient</a></li>
<li><a href="JqlClient.html">JqlClient</a></li>
<li><a href="LicenseRoleClient.html">LicenseRoleClient</a></li>
<li><a href="LicenseValidatorClient.html">LicenseValidatorClient</a></li>
<li><a href="MyPermissionsClient.html">MyPermissionsClient</a></li>
<li><a href="MyPreferencesClient.html">MyPreferencesClient</a></li>
<li><a href="MyselfClient.html">MyselfClient</a></li>
<li><a href="PasswordClient.html">PasswordClient</a></li>
<li><a href="PriorityClient.html">PriorityClient</a></li>
<li><a href="ProjectClient.html">ProjectClient</a></li>
<li><a href="ProjectValidateClient.html">ProjectValidateClient</a></li>
<li><a href="ReindexClient.html">ReindexClient</a></li>
<li><a href="ResolutionClient.html">ResolutionClient</a></li>
<li><a href="ScreensClient.html">ScreensClient</a></li>
<li><a href="SearchClient.html">SearchClient</a></li>
<li><a href="SecurityLevelClient.html">SecurityLevelClient</a></li>
<li><a href="ServerInfoClient.html">ServerInfoClient</a></li>
<li><a href="SettingsClient.html">SettingsClient</a></li>
<li><a href="StatusCategoryClient.html">StatusCategoryClient</a></li>
<li><a href="StatusClient.html">StatusClient</a></li>
<li><a href="UserClient.html">UserClient</a></li>
<li><a href="VersionClient.html">VersionClient</a></li>
<li><a href="WorkflowClient.html">WorkflowClient</a></li>
<li><a href="WorkflowSchemeClient.html">WorkflowSchemeClient</a></li>
</ul>
<h3>Namespaces</h3>
<ul>
<li><a href="OauthUtil.html">OauthUtil</a></li>
</ul>
</nav>
<br class="clear">
<footer>
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.3.0-alpha13</a> on Sun Aug 09 2015
00:40:20 GMT-0500 (CDT)
</footer>
<script> prettyPrint(); </script>
<script src="scripts/linenumber.js"></script>
</body>
</html>