synergia-jira-connector/api/group.js

Easy to use NodeJS wrapper for the Jira REST API.

"use strict";

module.exports = GroupClient;

/**
 * Used to access Jira REST endpoints in '/rest/api/2/group'
 *
 * These are considered experimental according to the Jira Docs, use at your own risk.
 *
 * @param {JiraClient} jiraClient
 * @constructor GroupClient
 */
function GroupClient (jiraClient) {
  this.jiraClient = jiraClient;

  /**
   * Creates a group by given group parameter Returns REST representation for the requested group.
   *
   * @method createGroup
   * @memberOf GroupClient#
   * @param opts The request options sent to jira
   * @param opts.group The group to create.  See {@link https://docs.atlassian.com/jira/REST/latest/#d2e2011}
   * @param callback Called when the group is created
   */
  this.createGroup = function (opts, callback) {
    var options = {
      uri: this.jiraClient.buildURL('/group'),
      method: 'POST',
      json: true,
      followAllRedirects: true,
      body: opts.group
    };

    this.jiraClient.makeRequest(options, callback);
  };

  /**
   * Returns REST representation for the requested group. Allows to get list of active users belonging to the
   * specified group and its subgroups if "users" expand option is provided. You can page through users list by using
   * indexes in expand param. For example to get users from index 10 to index 15 use "users[10:15]" expand value.
   * This will return 6 users (if there are at least 16 users in this group). Indexes are 0-based and inclusive.
   *
   * @method getGroup
   * @memberOf GroupClient#
   * @param opts The request options sent to the Jira API
   * @param opts.groupName A name of requested group.
   * @param opts.expand Array of fields to expand. Currently only available expand is "users".
   * @param callback Called when the group is retrieved.
   */
  this.getGroup = function (opts, callback) {
    var qs = {
      groupname: opts.groupName
    };

    if (opts.expand) {
      qs.expand = '';
      opts.expand.forEach(function (ex) {
        qs.expand += ex + ','
      });
    }

    var options = {
      uri: this.jiraClient.buildURL('/group'),
      method: 'GET',
      json: true,
      followAllRedirects: true,
      qs: qs
    };

    this.jiraClient.makeRequest(options, callback);
  };

  /**
   * Adds given user to a group. Returns the current state of the group.
   *
   * @method addUserToGroup
   * @memberOf GroupClient#
   * @param {Object} opts The request options sent to the Jira API
   * @param {string} opts.groupName A name of requested group.
   * @param {string} opts.userName The name of the user to add to the group.
   * @param callback Called when the user has been added to the group.
   */
  this.addUserToGroup = function (opts, callback) {
    var options = {
      uri: this.jiraClient.buildURL('/group/user'),
      method: 'POST',
      json: true,
      followAllRedirects: true,
      qs: {
        groupname: opts.groupName
      },
      body: {
        name: opts.userName
      }
    };

    this.jiraClient.makeRequest(options, callback);
  };

  /**
   * Removes given user from a group. Returns no content
   *
   * @method removeUserFromGroup
   * @memberOf GroupClient#
   * @param {Object} opts The request options sent to the Jira API
   * @param {string} opts.groupName A name of requested group.
   * @param {string} opts.userName The name of the user to add to the group.
   * @param callback Called when the user has been added to the group.
   */
  this.removeUserFromGroup = function (opts, callback) {
    var options = {
      uri: this.jiraClient.buildURL('/group/user'),
      method: 'DELETE',
      json: true,
      followAllRedirects: true,
      qs: {
        groupname: opts.groupName,
        username: opts.userName
      }
    };

    this.jiraClient.makeRequest(options, callback, 'User Removed from Group');
  };

  /**
   * Deletes a group by given group parameter. Returns no content
   *
   * @method deleteGroup
   * @memberOf GroupClient#
   * @param {Object} opts The request options sent to the Jira API
   * @param {string} opts.groupName A group to delete.
   * @param {string} [opts.swapGroup] A group to transfer visibility restrictions of the group that is being deleted
   * @param callback Called when the group has been deleted.
   */
  this.deleteGroup = function (opts, callback) {
    var options = {
      uri: this.jiraClient.buildURL('/group'),
      method: 'DELETE',
      json: true,
      followAllRedirects: true,
      qs: {
        groupname: opts.groupName,
        swapGroup: opts.swapGroup
      }
    };

    this.jiraClient.makeRequest(options, callback, 'Group Deleted');
  };
}