Source

groupMembers.js

  1. const common = require('./common');
  2. /**
  3. * A module related to xMatters group members/group roster.<br><br>
  4. * {@link https://help.xmatters.com/xmapi/index.html#group-roster}
  5. *
  6. * @module groupMembers
  7. */
  8. /**
  9. * Get all group members from xMatters matching the query. Please refer to the link below for the available query parameters.<br><br>
  10. *
  11. * {@link https://help.xmatters.com/xmapi/index.html#get-the-group-roster}
  12. *
  13. * @param {module:environments.xMattersEnvironment} env The xmtoolbox representation of an xMatters instance.
  14. * @param {Object} query A json object representing the query string parameters for this request.
  15. * @param {*} groupId The unique identifier (id) or name (targetName) of the group.
  16. * @returns {Promise<GroupMember[]>} Array of Group Member Objects Requested
  17. */
  18. async function getMany(env, query, groupId) {
  19. return common.getMany(env, `/api/xm/1/groups/${groupId}/members`, query, 'Group Members');
  20. }
  21. /**
  22. * Add a group member to a group in xMatters<br><br>
  23. *
  24. * {@link https://help.xmatters.com/xmapi/index.html#add-a-member-to-the-group-roster}
  25. *
  26. * @param {module:environments.xMattersEnvironment} env The xmtoolbox representation of an xMatters instance.
  27. * @param {*} member
  28. * @param {*} groupId The unique identifier (id) or name (targetName) of the group.
  29. * Examples:<br>
  30. * - Oracle Administrators<br>
  31. * - bab4a72f-e118-462d-ad87-e38e28e822e0
  32. * @returns {Promise<GroupMember>} Group Member Object Created
  33. */
  34. async function create(env, member, groupId) {
  35. return common.create(env, `/api/xm/1/groups/${groupId}/members/`, member, `Group Member`, false);
  36. }
  37. /**
  38. * Remove a group member from a group in xMatters<br><br>
  39. *
  40. * {@link https://help.xmatters.com/xmapi/index.html#remove-a-member-from-the-group-roster}
  41. *
  42. * @param {module:environments.xMattersEnvironment} env The xmtoolbox representation of an xMatters instance.
  43. * @param {*} memberId
  44. * @param {*} groupId The unique identifier (id) or name (targetName) of the group.
  45. * Examples:<br>
  46. * - IT<br>
  47. * - aeb08e86-2674-4812-9145-e157b0e24c16
  48. * @returns {Promise}
  49. * @name delete
  50. */
  51. async function _delete(env, memberId, groupId) {
  52. await common.delete(env, `/api/xm/1/groups/${groupId}/members/`, memberId, 'Group Member');
  53. }
  54. /**
  55. * Transforms an array of records exported from xMatters to the format needed to import into xMatters.
  56. * @param {module:environments.xMattersEnvironment} destination The xmtoolbox representation of the target or destination xMatters instance.
  57. * @param {GroupMember[]} groupMembers Array of group members to transform.
  58. * @param {xMattersObjects} destinationData The xMatters data for the destination.
  59. */
  60. async function exportToImport(destination, groupMembers, destinationData) {
  61. const destinationPeople =
  62. (destinationData.all ? destinationData.all.people : null) || destinationData.people;
  63. const destinationGroups =
  64. (destinationData.all ? destinationData.all.groups : null) || destinationData.groups;
  65. return common.convertDefaultInitial(await groupMembers, convert);
  66. function convert(groupMember) {
  67. {
  68. //set group
  69. //group can be supplied as a string representing the targetName of the group or an object with targetName key.
  70. if (groupMember.group) {
  71. if (groupMember.group.targetName) {
  72. groupMember.group = groupMember.group.targetName;
  73. //attempt to find a matching group and use it's id
  74. if (destinationGroups) {
  75. const destinationGroup = destinationGroups.find(
  76. ({ targetName }) => targetName === groupMember.group
  77. );
  78. if (destinationGroup && destinationGroup.id) groupMember.group = destinationGroup.id;
  79. }
  80. }
  81. }
  82. //set group
  83. //group can be supplied as a string representing the targetName of the group or an object with targetName key.
  84. if (groupMember.member) {
  85. groupMember.id = groupMember.member; //support direct TargetName or id for member
  86. if (groupMember.member.targetName) {
  87. groupMember.id = groupMember.member.targetName;
  88. groupMember.recipientType = groupMember.member.recipientType;
  89. if (groupMember.recipientType === 'PERSON') {
  90. //attempt to find a matching person and use it's id
  91. if (destinationPeople) {
  92. const destinationPerson = destinationPeople.find(
  93. ({ targetName }) => targetName === (groupMember.member || groupMember.member.targetName)
  94. );
  95. if (destinationPerson && destinationPerson.id) groupMember.id = destinationPerson.id;
  96. }
  97. } else if (groupMember.recipientType === 'GROUP') {
  98. //attempt to find a matching group and use it's id
  99. if (destinationGroups) {
  100. const destinationGroup = destinationGroups.find(
  101. ({ targetName }) => targetName === (groupMember.member || groupMember.member.targetName)
  102. );
  103. if (destinationGroup && destinationGroup.id) groupMember.id = destinationGroup.id;
  104. }
  105. }
  106. }
  107. }
  108. delete groupMember.links;
  109. delete groupMember.shifts;
  110. delete groupMember.member;
  111. return groupMember;
  112. }
  113. }
  114. }
  115. /**
  116. * The key values from the object that can be synchronized.
  117. */
  118. const fields = ['id', 'recipientType'];
  119. /**
  120. * Synchronizes an array of objects from a source with destination objects and updates the destination as necessary.
  121. * @param {module:environments.xMattersEnvironment} destination The xmtoolbox representation of the target or destination xMatters instance.
  122. * @param {GroupMember[]} sourceGroupMembers An array of the group member objects to synchronize from the source data.
  123. * @param {GroupMember[]} destinationGroupMembers An array of the group member objects to synchronize from the destination data.
  124. * @param {Object} options
  125. * @param {string} groupId The UUID of the group to sync the group members to.
  126. * @returns {Promise<module:sync.SyncResults>}
  127. */
  128. async function sync(destination, sourceGroupMembers, destinationGroupMembers, options) {
  129. return common.syncObject(
  130. 'Group Members',
  131. sourceGroupMembers,
  132. destinationGroupMembers,
  133. destination,
  134. ['id', 'group'],
  135. fields,
  136. create,
  137. undefined,
  138. _delete,
  139. options,
  140. 'group'
  141. );
  142. }
  143. exports.getMany = getMany;
  144. exports.create = create;
  145. exports.delete = _delete;
  146. exports.exportToImport = exportToImport;
  147. exports.fields = fields;
  148. exports.sync = sync;