xmtoolbox/lib/shifts.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 shifts.<br><br>
 * {@link https://help.xmatters.com/xmapi/index.html#shifts}
 *
 * @module shifts
 */

/**
 * Get a shift from xMatters<br><br>
 *
 * {@link https://help.xmatters.com/xmapi/index.html#get-a-shift}
 *
 * @param {module:environments.xMattersEnvironment} env The xmtoolbox representation of an xMatters instance.
 * @param {string} shiftId The unique identifier (id) of the shift to update.<br><br>
 * Examples:<br>
 * - b2341d69-8b83-4660-b8c8-f2e728f675f9<br>
 * @param {Object} query A json object representing the query string parameters for this request.
 * @param {string} groupId The unique identifier (id) or name (name) of the group that contains the shift.<br><br>
 * Examples:<br>
 * - Database<br>
 * - a5341d69-8b83-4660-b8c8-f2e728f675f9<br>
 * @returns {Promise<Shift>} Shift Object Requested
 */
async function get(env, shiftId, query, groupId) {
  return common.get(env, `/api/xm/1/groups/${encodeURIComponent(groupId)}/shifts/`, shiftId, query, `Shift`);
}

/**
 * Get all shifts in a group 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-shifts-in-a-group}
 *
 * @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} groupId The unique identifier (id) or name (name) of the group that contains the shift.<br><br>
 * Examples:<br>
 * - Database<br>
 * - a5341d69-8b83-4660-b8c8-f2e728f675f9<br>
 * @returns {Promise<Shift[]>} Array of Shift Objects Requested
 */
async function getMany(env, query, groupId) {
  return common.getMany(env, `/api/xm/1/groups/${encodeURIComponent(groupId)}/shifts`, query, 'Shifts');
}

/**
 * Get all shift members in a shift 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-shifts-in-a-group}
 *
 * @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} shiftId The unique identifier (id) or name of the of the shift.<br><br>
 * Examples:<br>
 * - b2341d69-8b83-4660-b8c8-f2e728f675f9<br>
 * - Morning
 * @param {string} groupId The unique identifier (id) or name (name) of the group that contains the shift.<br><br>
 * Examples:<br>
 * - Database<br>
 * - a5341d69-8b83-4660-b8c8-f2e728f675f9<br>
 * @returns {Promise<Shift>} Shift Object Requested
 */
async function getMembers(env, query, shiftId, groupId) {
  return common.getMany(
    env,
    `/api/xm/1/groups/${encodeURIComponent(groupId)}/shifts/${shiftId}/members`,
    query,
    'Shift Members'
  );
}

/**
 * Create a shift in xMatters<br><br>
 *
 * {@link https://help.xmatters.com/xmapi/index.html#create-a-shift}
 *
 * @param {module:environments.xMattersEnvironment} env The xmtoolbox representation of an xMatters instance.
 * @param {Shift} shift {@link https://help.xmatters.com/xmapi/index.html#shift-object}
 * @param {string} groupId The unique identifier (id) or name (name) of the group that contains the shift.<br><br>
 * Examples:<br>
 * - Database
 * - a5341d69-8b83-4660-b8c8-f2e728f675f9<br>
 * @returns {Promise<Shift>} Shift Object Created
 */
async function create(env, shift, groupId) {
  return common.create(env, `/api/xm/1/groups/${encodeURIComponent(groupId)}/shifts/`, shift, 'Shift', true);
}

/**
 * Update a shift in xMatters<br><br>
 *
 * {@link https://help.xmatters.com/xmapi/index.html#create-a-shift}
 *
 * @param {module:environments.xMattersEnvironment} env The xmtoolbox representation of an xMatters instance.
 * @param {Shift} shift {@link https://help.xmatters.com/xmapi/index.html#shift-object}
 * @param {string} shiftId The unique identifier (id) of the shift to update.<br><br>
 * Examples:<br>
 * - b2341d69-8b83-4660-b8c8-f2e728f675f9<br>
 * @param {string} groupId The unique identifier (id) or name (name) of the group that contains the shift.<br><br>
 * Examples:<br>
 * - Database
 * - a5341d69-8b83-4660-b8c8-f2e728f675f9<br>
 * @returns {Promise<Shift>} Shift Object Updated
 */
async function update(env, shift, shiftId, groupId) {
  return common.update(
    env,
    `/api/xm/1/groups/${encodeURIComponent(groupId)}/shifts/`,
    shift,
    shiftId,
    'Shift'
  );
}

/**
 * Delete a shift in xMatters<br><br>
 *
 * {@link https://help.xmatters.com/xmapi/index.html#delete-a-shift}
 * @param {module:environments.xMattersEnvironment} env The xmtoolbox representation of an xMatters instance.
 * @param {string} shiftId The unique identifier (id) or name (name) of the shift to delete.<br><br>
 * Examples:<br>
 * - Morning
 * - b2341d69-8b83-4660-b8c8-f2e728f675f9<br>
 * @param {string} groupId   The unique identifier (id) or name (name) of the group that contains the shift.<br><br>
 * Examples:<br>
 * - Database
 * - a5341d69-8b83-4660-b8c8-f2e728f675f9<br>
 * @returns {Promise}
 * @name delete
 */
async function _delete(env, shiftId, groupId) {
  await common.delete(env, `/api/xm/1/groups/${encodeURIComponent(groupId)}/shifts/`, shiftId, 'Shift');
}

/**
 * Add a member to a shift in xMatters<br><br>
 *
 * {@link https://help.xmatters.com/xmapi/index.html#add-a-member-to-a-shift}
 *
 * @param {module:environments.xMattersEnvironment} env The xmtoolbox representation of an xMatters instance.
 * @param {ShiftMember} member {@link https://help.xmatters.com/xmapi/index.html#shift-member-object}
 * @param {string} shiftId The unique identifier (id) or name (name) of the shift to delete.<br><br>
 * Examples:<br>
 * - Morning
 * - b2341d69-8b83-4660-b8c8-f2e728f675f9<br>
 * @param {string} groupId The unique identifier (id) or name (name) of the group that contains the shift.<br><br>
 * Examples:<br>
 * - Database
 * - a5341d69-8b83-4660-b8c8-f2e728f675f9<br>
 * @returns {Promise<ShiftMember>} ShiftMember Object Created
 */
async function addMember(env, member, shiftId, groupId) {
  return common.create(
    env,
    `/api/xm/1/groups/${groupId}/shifts/${shiftId}/members`,
    member,
    `Add Member to Shift`
  );
}

/**
 * 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 {Shift[]} shifts {@link https://help.xmatters.com/xmapi/index.html#shift-object}
 * @param {xMattersObjects} destinationData The xMatters data for the destination.
 * @returns {Promise}
 */
async function exportToImport(destination, shifts, destinationData) {
  const destinationPeople =
    (destinationData.all ? destinationData.all.people : null) || destinationData.people;

  const destinationGroups =
    (destinationData.all ? destinationData.all.groups : null) || destinationData.groups;

  const destinationDynamicTeams =
    (destinationData.all ? destinationData.all.dynamicTeams : null) || destinationData.dynamicTeams;

  const destinationDevices =
    (destinationData.all ? destinationData.all.devices : null) || destinationData.devices;

  return common.convertDefaultInitial(await shifts, convert);

  function convert(shift) {
    {
      //set group
      const group = shift.group; //For reference
      //group can be supplied as a string representing the targetName of the group or an object with targetName key.
      if (shift.group) {
        if (shift.group.targetName) {
          shift.group = shift.group.targetName;
        }
        //attempt to find a matching group and use it's id
        if (destinationGroups) {
          const destinationGroup = destinationGroups.find(
            ({ targetName }) => targetName === (group.targetName || group)
          );
          if (destinationGroup && destinationGroup.id) shift.group = destinationGroup.id;
        }
      }

      if (shift.members && shift.members.data) {
        shift.members = shift.members.data;

        shift.members = shift.members
          .map(member => {
            let destinationMemberRecipient;

            if (member.recipient.recipientType === 'PERSON' && destinationPeople) {
              destinationMemberRecipient = destinationPeople.find(
                ({ targetName }) => targetName === member.recipient.targetName
              );
            } else if (member.recipient.recipientType === 'DEVICE' && destinationDevices) {
              destinationMemberRecipient = destinationDevices.find(
                ({ targetName }) => targetName === member.recipient.targetName
              );
            } else if (member.recipient.recipientType === 'GROUP' && destinationGroups) {
              destinationMemberRecipient = destinationGroups.find(
                ({ targetName }) => targetName === member.recipient.targetName
              );
            } else if (member.recipient.recipientType === 'DYNAMIC_TEAM' && destinationDynamicTeams) {
              destinationMemberRecipient = destinationDynamicTeams.find(
                ({ targetName }) => targetName === member.recipient.targetName
              );
            }

            //2020-Jan-27: "400: If specified, escalation type needs to be NONE when delay is specified to be 0"
            if (member.delay === 0) {
              member.escalationType = 'NONE';
            }

            if (!destinationMemberRecipient) {
              destination.log.warn(
                `DATA INTEGRITY ISSUE: Shift Member mapping failed. Group [${
                  group.targetName || group
                }] has a Shift [${shift.name}] which has a member with targetName [${
                  member.recipient.targetName
                }] but this member was not found in the provided destination data.`
              );
              //assume it's in the same environment
              return member;
            } else if (member.recipient.recipientType === 'DEVICE') {
              member.recipient = member.recipient.targetName;
              return member;
            } else {
              delete member.shift;
              member.recipient = destinationMemberRecipient.id;
              return member;
            }
          })
          .filter(member => (member ? true : false));
      }

      //2020-April-10 Temp fix for API returining empty array of days. Should be treated as all days.
      if (
        shift.recurrence.onDays &&
        shift.recurrence.onDays.length === 0 &&
        shift.recurrence.frequency === 'WEEKLY'
      ) {
        shift.recurrence.onDays = ['MO', 'TU', 'WE', 'TH', 'FR', 'SA', 'SU'];
      }

      delete shift.links;
      //delete shift.group;
      return shift;
    }
  }
}

/**
 * The key values from the object that can be synchronized.
 */
const fields = [
  //'id',
  //'group',
  //'links',
  'name',
  'start',
  'end',
  'rotationType',
  'rotation',
  'timezone',
  'recurrence',
  'members',
];

/**
 * 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 {Shift[]} sourceShifts An array of the shift objects to synchronize from the source data.
 * @param {Shift[]} destinationShifts An array of the shift objects to synchronize from the destination data.
 * @param {Object} options
 */
async function sync(destination, sourceShifts, destinationShifts, options) {
  return common.syncObject(
    'Shift',
    sourceShifts,
    destinationShifts,
    destination,
    ['name', 'group'],
    fields,
    create,
    update, //TODO: 2020-Jan-29: Need shift updates to be supported https://xmexternal.zendesk.com/agent/tickets/152353
    _delete,
    options,
    'group'
  );
}

exports.get = get;
exports.getMany = getMany;
exports.getMembers = getMembers;
exports.create = create;
exports.delete = _delete;
exports.addMember = addMember;
/*
exports.objects = {
  shift,
  recipientPointer,
  shiftMember,
  shiftRecurrence,
  end
};
*/
exports.exportToImport = exportToImport;
exports.fields = fields;
exports.sync = sync;