xmtoolbox/lib/people.js

A Node JS package for interacting with xMatters. Contains functions to interact with xMatters APIs or perform a synchronization, create events, libraries to convert data, and much much more!

const common = require('./common');

/**
 * A module related to xMatters people.<br><br>
 * {@link https://help.xmatters.com/xmapi/index.html#people}
 *
 * @module people
 */

/**
 * Get a person from xMatters<br><br>
 *
 * {@link https://help.xmatters.com/xmapi/index.html#get-a-person-by-id}
 *
 * @param {module:environments.xMattersEnvironment} env The xmtoolbox representation of an xMatters instance.
 * @param {*} personId The unique identifier (id) or name (targetName) of the person.<br><br>
 * Examples:<br>
 * - b2341d69-8b83-4660-b8c8-f2e728f675f9<br>
 * - mmcbride
 * @param {Object} query A json object representing the query string parameters for this request.
 * @returns {Promise<Person>} Person Object Requested
 */
async function get(env, personId, query, throwError) {
  return common.get(env, '/api/xm/1/people/', personId, query, 'Person', throwError);
}

/**
 * Get all people from xMatters matching the query. Please refer to the link below for the available query parameters.<br><br>
 *
 * {@link https://help.xmatters.com/xmapi/index.html#get-people}
 *
 * @param {module:environments.xMattersEnvironment} env The xmtoolbox representation of an xMatters instance.
 * @param {Object} query A json object representing the query string parameters for this request.
 * @returns {Promise<Person[]>} Array of Person Objects Requested
 */
async function getMany(env, query) {
  return common.getMany(env, '/api/xm/1/people', query, 'People');
}

/**
 * Get all supervisors for a person from xMatters matching the query. Please refer to the link below for the available query parameters.<br><br>
 *
 * {@link https://help.xmatters.com/xmapi/index.html#get-a-person-39-s-supervisors}
 *
 * @param {module:environments.xMattersEnvironment} env The xmtoolbox representation of an xMatters instance.
 * @param {Object} query A json object representing the query string parameters for this request.
 * @param {string} personId The unique identifier (id) or name (targetName) of the person.<br><br>
 * Examples:<br>
 * - b2341d69-8b83-4660-b8c8-f2e728f675f9<br>
 * - mmcbride
 * @returns {Promise<Person[]>} Array of Person Objects Requested
 */
async function getSupervisors(env, query, personId) {
  return common.getMany(
    env,
    `/api/xm/1/people/${encodeURIComponent(personId)}/supervisors`,
    query,
    'Person Supervisors'
  );
}

/**
 * Get all devices for a person from xMatters matching the query. Please refer to the link below for the available query parameters.<br><br>
 *
 * {@link https://help.xmatters.com/xmapi/index.html#get-a-person-39-s-devices}
 *
 * @param {module:environments.xMattersEnvironment} env The xmtoolbox representation of an xMatters instance.
 * @param {Object} query A json object representing the query string parameters for this request.
 * @param {string} personId The unique identifier (id) or name (targetName) of the person.<br><br>
 * Examples:<br>
 * - b2341d69-8b83-4660-b8c8-f2e728f675f9<br>
 * - mmcbride
 * @returns {Promise<Device[]>} Array of Device Objects Requested
 */
async function getDevices(env, query, personId, throwError) {
  return common.getMany(
    env,
    `/api/xm/1/people/${encodeURIComponent(personId)}/devices`,
    query,
    'Person Devices',
    throwError
  );
}

/**
 * Get all groups for a person from xMatters matching the query. Please refer to the link below for the available query parameters.<br><br>
 *
 * {@link https://help.xmatters.com/xmapi/index.html#get-a-person-39-s-groups}
 *
 * @param {module:environments.xMattersEnvironment} env The xmtoolbox representation of an xMatters instance.
 * @param {Object} query A json object representing the query string parameters for this request.
 * @param {string} personId The unique identifier (id) or name (targetName) of the person.<br><br>
 * Examples:<br>
 * - b2341d69-8b83-4660-b8c8-f2e728f675f9<br>
 * - mmcbride
 * @returns {Promise<Group[]>} Array of Group Objects Requested
 */
async function getGroups(env, query, personId) {
  return common.getMany(
    env,
    `/api/xm/1/people/${encodeURIComponent(personId)}/group-memberships`,
    query,
    'Person Groups'
  );
}

/**
 * Create a person in xMatters<br><br>
 *
 * {@link https://help.xmatters.com/xmapi/index.html#create-a-person}
 *
 * @param {module:environments.xMattersEnvironment} env The xmtoolbox representation of an xMatters instance.
 * @param {Person} person {@link https://help.xmatters.com/xmapi/index.html#person-object}
 * @returns {Promise<Person>} Person Object Created
 */
async function create(env, person) {
  return common.create(env, '/api/xm/1/people', person, 'Person', true);
}

/**
 * Update a person in xMatters<br><br>
 *
 * {@link https://help.xmatters.com/xmapi/index.html#modify-a-person}
 *
 * @param {module:environments.xMattersEnvironment} env The xmtoolbox representation of an xMatters instance.
 * @param {Person} person {@link https://help.xmatters.com/xmapi/index.html#person-object}
 * @param {string} personId The unique identifier (id) of the person.<br><br>
 * Examples:<br>
 * - b2341d69-8b83-4660-b8c8-f2e728f675f9<br>
 * @returns {Promise<Person>} Person Object Updated
 */
async function update(env, person, personId) {
  return common.update(env, '/api/xm/1/people/', person, personId, 'Person');
}

/**
 * Delete a person in xMatters<br><br>
 *
 * {@link https://help.xmatters.com/xmapi/index.html#delete-a-person}
 *
 * @param {module:environments.xMattersEnvironment} env The xmtoolbox representation of an xMatters instance.
 * @param {string} personId The unique identifier (id) or name (targetName) of the person.<br><br>
 * Examples:<br>
 * - b2341d69-8b83-4660-b8c8-f2e728f675f9<br>
 * - mmcbride
 * @returns {Promise}
 * @name delete
 */
async function _delete(env, personId) {
  return common.delete(env, '/api/xm/1/people/', personId, 'Person');
}

/**
 * Transforms an array of records exported from xMatters to the format needed to import into xMatters.
 * @param {module:environments.xMattersEnvironment} destination The xmtoolbox representation of the target or destination xMatters instance.
 * @param {Person[]} people Array of person objects to transform.
 * @param {xMattersObjects} destinationData The xMatters data for the destination.
 * @returns {Promise}
 */
async function exportToImport(destination, people, destinationData) {
  const destinationPeople =
    (destinationData.all ? destinationData.all.people : null) || destinationData.people;
  const destinationSites = (destinationData.all ? destinationData.all.sites : null) || destinationData.sites;
  return common.convertDefaultInitial(people, convert);

  function convert(person) {
    {
      delete person.links;
      //handle import from xMatters and simpler file import like just the site name.
      if (person.site) {
        const siteId = person.site.name || person.site;

        const site = destinationSites && destinationSites.find(({ name }) => siteId === name);

        if (!site) {
          destination.log.warn(
            `DATA INTEGRITY ISSUE: Site mapping failed. Person [${person.targetName}] has the site [${siteId}] but this site was not found in the provided destination data.`
          );
        } else {
          person.site = site.id;
        }
      }

      //supervisors from xMatters....
      if (person.supervisors && person.supervisors.data) {
        person.supervisors = person.supervisors.data.map(d => d.targetName);
      }

      if (person.supervisors) {
        person.supervisors = person.supervisors.map(supervisor => {
          const destinationSupervisor = destinationPeople.find(
            //support the xMatters import format and a simpler array of targetNames that might come from a import file.
            destinationPerson =>
              supervisor === destinationPerson.targetName ||
              (supervisor.targetName && supervisor.targetName === destinationPerson.targetName)
          );

          if (!destinationSupervisor) {
            destination.log.warn(
              `DATA INTEGRITY ISSUE: Supervisor mapping failed. Person [${person.targetName}] has a supervisor with targetName [${supervisor.targetName || supervisor}] but this supervisor was not found in the provided destination data.`
            );
          } else {
            return destinationSupervisor.id;
          }
        });
      }

      //pull any null values from the supervisor array. will be null if matches are not found.
      if (person.supervisors) {
        person.supervisors = person.supervisors.filter(function (el) {
          return el != null;
        });
      }

      //data from xMatters....
      if (person.roles && person.roles.data) {
        person.roles = person.roles.data.map(d => d.name);
      }

      if (person.properties) {
        for (const key in person.properties) {
          if (Object.hasOwnProperty.call(person.properties, key)) {
            const property = person.properties[key];

            //remove undefined properties. The API does nothing with it and it
            // results in unnecessary updates
            if (property === undefined) delete person.properties[key];
          }
        }
      }

      return person;
    }
  }
}

/**
 * The key values from the object that can be synchronized.
 */
const fields = [
  'externalKey',
  //'externallyOwned',
  'firstName',
  //'id',
  'language',
  'lastName',
  'phoneLogin',
  'properties',
  'recipientType',
  'roles',
  'site',
  'status',
  'supervisors',
  'targetName',
  'timezone',
  'webLogin',
];

/**
 * Synchronizes an array of objects from a source with destination objects and updates the destination as necessary.
 * @param {module:environments.xMattersEnvironment} destination The xmtoolbox representation of the target or destination xMatters instance.
 * @param {Person[]} sourcePeople An array of the person objects to synchronize from the source data.
 * @param {Person[]} destinationPeople An array of the person objects to synchronize from the destination data.
 * @param {Object} options
 * @returns {Promise<module:sync.SyncResults>}
 */
async function sync(destination, sourcePeople, destinationPeople, options) {
  return common.syncObject(
    'Person',
    sourcePeople,
    destinationPeople,
    destination,
    'targetName',
    fields,
    create,
    update,
    _delete,
    options
  );
}

exports.get = get;
exports.getMany = getMany;
exports.getDevices = getDevices;
exports.getSupervisors = getSupervisors;
exports.getGroups = getGroups;
exports.create = create;
exports.update = update;
exports.delete = _delete;
exports.exportToImport = exportToImport;
exports.fields = fields;
exports.sync = sync;