{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":856,"path":"api-reference/server-api-reference/NotifyUtilAPI.md","title":"NotifyUtil - Global","bundle":null,"doc_type":null,"release":"australia","body":"\n# NotifyUtil- Global\n\nThe NotifyUtil script include provides utility methods to use when interacting with Notify calls and SMS messages using server-side scripts.\n\nTo use this script include you must activate the Notify \\(com.snc.notify\\) plugin.\n\nUsing the NotifyUtil script include you can:\n\n-   Obtain all of the Notify telephone numbers and related Notify information from a specified source record.\n-   Obtain a list of unique Notify telephone numbers.\n-   Determine whether there are any active conference calls for the specified source record.\n-   Obtain the SMS-capable number associated with the specified Notify user.\n-   Validate a specified Notify telephone number.\n\n**Parent Topic:**[Server API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/api-server.md)\n\n## NotifyUtil - NotifyUtil\\(\\)\n\nInstantiates a NotifyUtil class object.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| ||\n\nThis example instantiates a NotifyUtil object.\n\n```\nvar notifyUtil = new NotifyUtil(); \nnotifyUtil.getTelephonyProviers();\n```\n\n## NotifyUtil - getListOfNotifyNumbersAndProviders\\(String sourceTable, String sourceSysId, String notifyGroupSelectorSysId, Boolean filterSMSCapableNums\\)\n\nReturns all of the Notify telephone numbers and related Notify information from a specified source record, such as an incident.\n\nYou can use this information to initiate a call or send an SMS message on a particular source record. The information that is returned is based on the configuration of the Notify Provider Selector framework. For additional information, see [Notify](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/servicenow-platform/notify-landing-page.md)\n\n<table id=\"table_pmg_pyt_kmb\" class=\"parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nfilterSMSCapableNums\n\n</td><td>\n\nBoolean\n\n</td><td>\n\nOptional. Flag that indicates if only numbers that are SMS-capable should be returned.Valid values:\n\n-   true: Only return SMS-capable telephone numbers and information.\n-   false: Return all notify telephone numbers and information.\n\n Default: false\n\n</td></tr><tr><td>\n\nnotifyGroupSelectorSysId\n\n</td><td>\n\nString\n\n</td><td>\n\nOptional. Sys\\_id of a Notify group for which to return the notify numbers and information. Default: All groups\n\n</td></tr><tr><td>\n\nsourceSysId\n\n</td><td>\n\nString\n\n</td><td>\n\nSys\\_id of the source record for which to return the Notify numbers and information. For example, this could be the sys\\_id of a record in the Incident \\[incident\\] table.\n\n</td></tr><tr><td>\n\nsourceTable\n\n</td><td>\n\nString\n\n</td><td>\n\nName of the table that contains the source record that contains the desired Notify numbers and information.\n\n</td></tr></tbody>\n</table><table id=\"table_qmg_pyt_kmb\" class=\"returns\"><thead><tr><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nconfProviders\n\n</td><td>\n\nList of available conference providers.Data type: Array\n\n</td></tr><tr><td>\n\nnumbers\n\n</td><td>\n\nList of objects, each describing a single Notify number.Data type: Array\n\n ```\n\"numbers\": [{\n  \"defaultFlag\": Boolean,\n  \"name\": \"String\",\n  \"number\": \"String\",\n  \"shortCode\": Boolean,\n  \"sysId\": \"String\n}]\n```\n\n</td></tr><tr><td>\n\nnumbers.defaultFlag\n\n</td><td>\n\nFlag that indicates whether the associated Notify number is the default number.Possible values:\n\n-   true: Default number\n-   false: Not the default number\n\n Data type: Boolean\n\n</td></tr><tr><td>\n\nnumbers.name\n\n</td><td>\n\nName or label of the number.Data type: String\n\n</td></tr><tr><td>\n\nnumbers.number\n\n</td><td>\n\nNotify number.Data type: String\n\n</td></tr><tr><td>\n\nnumbers.shortCode\n\n</td><td>\n\nFlag that indicates whether the associated Notify number is a short code.Possible values:\n\n-   true: Short code\n-   false: Not a short code\n\n Data type: Boolean\n\n</td></tr><tr><td>\n\nnumbers.sysId\n\n</td><td>\n\nSys\\_id of the Notify number.Data type: String\n\n</td></tr></tbody>\n</table>This example shows how to obtain the Notify telephone numbers and related Notify information from a specified source record.\n\n```\nfunction updateConferenceBridges(sourceTable, sourceId) {\n\n  var notifyUtil = new global.NotifyUtil();\n  var numbersAndProviders = notifyUtil.getListOfNotifyNumbersAndProviders(sourceTable, sourceId);\n  var confBridges = [];\n  if (numbersAndProviders.confProviders) {\n    numbersAndProviders.confProviders.forEach(function(provider){\n    confBridges.push(provider);\n    });\n  }\n  if (numbersAndProviders.numbers) {\n    numbersAndProviders.numbers.forEach(function(number){\n      confBridges.push(number.name);\n    });\n  }\n} \n```\n\n## NotifyUtil - getSMSNumberForUser\\(String userGrOrId\\)\n\nReturns the SMS-capable number associated with the specified Notify user.\n\n<table id=\"table_dkn_1wt_kmb\" class=\"parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nuserGROrId\n\n</td><td>\n\nString or [GlideRecord - Global](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/c_GlideRecordAPI.md)\n\n</td><td>\n\nSys\\_id of the user record, Table: User \\[sys\\_user\\] table or the sys\\_user GlideRecord of the user for whom to return the SMS-capable telephone number.\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|String|User SMS-capable telephone number. Returns null if the specified user is not found.|\n\nThis example shows how to obtain an SMS-capable telephone number using the associated GlideRecord.\n\n```\nvar sourceRecord = new GlideRecord('incident');\nsourceRecord.query();\nif (sourceRecord.next()) {\n  var fromNumber = getFromNumber();\n  var nUtil = new NotifyUtil();\n  var toNumber = nUtil.getSMSNumberForUser(sourceRecord.assigned_to.getRefRecord());\n  var message = 'Incident ' + sourceRecord.getDisplayValue() + ' has been assigned to you.';\n  if (fromNumber && nUtil.validateOutboundNotifyPhoneNumber(fromNumber) && toNumber && nUtil.validatePhoneNumber(toNumber)) {\n    var notifySMS = new NotifySMS();\n    notifySMS.sendToNumber(fromNumber, toNumber, message, sourceRecord);\n  }\n}\n\nfunction getFromNumber() {\n  var prop = gs.getProperty('custom_property_name', '');\n  if (!prop){\n    return getFallbackFromNumber();\n  }\n  return prop;\n} \n\nfunction getFallbackFromNumber() {\n  var notifyNumGr = new GlideRecord(\"notify_number\");\n  notifyNumGr.addActiveQuery();\n  notifyNumGr.addQuery('has_sms_out', 'yes');\n  notifyNumGr.query();\n  if (notifyNumGr.next()) {\n    return notifyNumGr.number + '';\n  }\n  return '';\n} \n```\n\n## NotifyUtil - getUniquePhoneNumbersForUsersAndGroups\\(Array numbers, Array users, Array groups, String type, Boolean getData\\)\n\nReturns a list of unique Notify telephone numbers.\n\nIf you don't pass any parameters in the call, all Notify numbers within the Notify Phone Number \\[notify\\_number\\] table are checked for duplicates, with each available phone number only appearing once in the returned list. You can refine the return results by specifying a list of users or groups to check, or by specifying a set of numbers or number types \\(SMS or voice.\\) You can also request that the metadata associated with each number be returned along with the unique numbers. If you do not want to use a parameter, simply pass `null` as a placeholder. For example: `return nUtil.getUniquePhoneNumbersForUsersAndGroups(null, userIds, null, 'sms', false);`.\n\n<table id=\"table_kxw_hs5_kmb\" class=\"parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\ngetData\n\n</td><td>\n\nBoolean\n\n</td><td>\n\nOptional. Flag that indicates whether to return metadata along with the list of unique phone numbers.Valid values:\n\n-   true: Return metadata.\n-   false: Do not return metadata.\n\n Default: false\n\n</td></tr><tr><td>\n\ngroups\n\n</td><td>\n\nArray\n\n</td><td>\n\nOptional. List of sys\\_id groups to check.Default: Check all groups.\n\nTable: Group \\[sys\\_user\\_group\\]\n\n</td></tr><tr><td>\n\nnumbers\n\n</td><td>\n\nArray\n\n</td><td>\n\nOptional. List of specific Notify telephone numbers to check.Default: Check all phone numbers.\n\n</td></tr><tr><td>\n\ntype\n\n</td><td>\n\nString\n\n</td><td>\n\nOptional. Type of telephone numbers to check.Valid values \\(case-sensitive\\):\n\n-   voice\n-   sms\n\nDefault: Check all phone number types\n\n</td></tr><tr><td>\n\nusers\n\n</td><td>\n\nArray\n\n</td><td>\n\nOptional. List of sys\\_ids of specific users to check.Default: Check all users\n\nTable: User \\[sys\\_user\\]\n\n</td></tr></tbody>\n</table><table id=\"table_lxw_hs5_kmb\" class=\"returns\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nnumbers\n\n</td><td>\n\nUnique Notify telephone numbers.Data type: Array\n\n</td></tr><tr><td>\n\nresult\n\n</td><td>\n\nOnly returned if **getData** is set to true. Metadata associated with each unique number.Data type: Object\n\n```\n\"result\": {\n  \"number\": \"String\",\n  \"sysId\": \"String\",\n  \"type\": \"String\",\n  \"valid\": Boolean\n}\n```\n\n</td></tr><tr><td>\n\nresult.number\n\n</td><td>\n\nUnique Notify telephone number.Data type: String\n\n</td></tr><tr><td>\n\nresult.sysId\n\n</td><td>\n\nSys\\_id of the record that contains the Notify telephone number.Data type: String\n\nTable: Notify Phone Number \\[notify\\_number\\]\n\n</td></tr><tr><td>\n\nresult.type\n\n</td><td>\n\nAlways contains \"u\" for user.Data type: String\n\n</td></tr><tr><td>\n\nresult.valid\n\n</td><td>\n\nFlag that indicates whether the Notify telephone number is in valid E.164 format.Possible values:\n\n-   true: Valid E.164 format.\n-   false: Not in E.164 format.\n\nData type: Boolean\n\n</td></tr></tbody>\n</table>This example shows how to request a specific set of unique Notify telephone numbers that have SMS capabilities.\n\n```\nvar fromNumber = getFromNumber();\nvar toNumbers = getRecipientNumbers();\nvar message = 'This is an example SMS';\nvar sourceRecord = new GlideRecord('incident');\nsourceRecord.query();\nif (sourceRecord.next()) {\n  var notifySMS = new NotifySMS();\n  notifySMS.sendToNumber(fromNumber, toNumbers, message, sourceRecord);\n}\n\nfunction getRecipientNumbers() {\n  var userGr = new GlideRecord('sys_user');\n  userGr.addActiveQuery();\n  userGr.addQuery('first_name', 'STARTSWITH', 'A');\n  userGr.setLimit(5);\n  userGr.query(); \n  var userIds = [];\n  while (userGr.next()) {\n    userIds.push(userGr.getUniqueValue());\n  }\n  if (userIds.length > 0) {\n    var nUtil = new NotifyUtil();\n    return nUtil.getUniquePhoneNumbersForUsersAndGroups(null, userIds, null, 'sms', false);\n  } \n}\n\nfunction getFromNumber() {\n  var prop = gs.getProperty('custom_property_name', '');\n  if (!prop){\n    return getFallbackFromNumber();\n  } \n  return prop; \n}\n\nfunction getFallbackFromNumber() {\n  var notifyNumGr = new GlideRecord(\"notify_number\");\n  notifyNumGr.addActiveQuery();\n  notifyNumGr.addQuery('has_sms_out', 'yes');\n  notifyNumGr.query();\n  if (notifyNumGr.next()) {\n    return notifyNumGr.number + '';\n  }\n  return '';\n}\n```\n\n## NotifyUtil - hasActiveConferenceCalls\\(String sourceRecSysId\\)\n\nDetermines whether there are any active conference calls for the specified source record.\n\n|Name|Type|Description|\n|----|----|-----------|\n|sourceRecSysId|String|Sys\\_id of the record to check for active conference calls. For example the sys\\_id of a record in the Incident table.|\n\n<table id=\"table_xwv_ktm_kmb\" class=\"returns\"><thead><tr><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nBoolean\n\n</td><td>\n\nFlag that indicates whether the specified record has associated active conference calls.Possible values:\n\n-   true: Active conference calls are available for the specified record.\n-   false: No active conference calls.\n\n</td></tr></tbody>\n</table>This example displays an information message if there are any active conference calls associated with an incident record.\n\n```\n(function executeRule(current, previous /*null when async*/) {\n  var nUtil = new NotifyUtil();\n  if (nUtil.hasActiveConferenceCalls(current.getUniqueValue())) {\n    gs.addInfoMessage(\"There are active conference calls related to this Incident.\");\n  } \n})(current, previous);\n```\n\n## NotifyUtil - validateOutboundNotifyPhoneNumber\\(String number\\)\n\nValidates a specified Notify telephone number.\n\nThe method performs three types of validation:\n\n1.  Whether the Notify number exists in the Notify Phone Number \\[notify\\_number\\] table.\n2.  Whether the Notify number has a Notify group associated with it.\n3.  Whether the Notify number is active.\n\nIf any one of these validations fail, the method throws an exception.\n\n|Name|Type|Description|\n|----|----|-----------|\n|number|String|Notify number to validate.|\n\n|Type|Description|\n|----|-----------|\n|None| |\n\nThis example illustrates how to validate a notify number.\n\n```\nvar sourceRecord = new GlideRecord('incident');\nsourceRecord.query();\nif (sourceRecord.next()) {\n  var fromNumber = getFromNumber();\n  var nUtil = new NotifyUtil();\n  var toNumber = nUtil.getSMSNumberForUser(sourceRecord.assigned_to.getRefRecord());\n  var message = 'Incident ' + sourceRecord.getDisplayValue() + ' has been assigned to you.';\n  if (fromNumber && nUtil.validateOutboundNotifyPhoneNumber(fromNumber) && toNumber && nUtil.validatePhoneNumber(toNumber)) {\n    var notifySMS = new NotifySMS();\n    notifySMS.sendToNumber(fromNumber, toNumber, message, sourceRecord);\n  }\n}\n\nfunction getFromNumber() {\n  var prop = gs.getProperty('custom_property_name', '');\n  if (!prop){\n    return getFallbackFromNumber();\n  }\n  return prop;\n} \n\nfunction getFallbackFromNumber() {\n  var notifyNumGr = new GlideRecord(\"notify_number\");\n  notifyNumGr.addActiveQuery();\n  notifyNumGr.addQuery('has_sms_out', 'yes');\n  notifyNumGr.query();\n  if (notifyNumGr.next()) {\n    return notifyNumGr.number + '';\n  }\n  return '';\n} \n```\n\n## NotifyUtil - validatePhoneNumber\\(String number\\)\n\nVerifies that the specified number is a valid E.164 telephone number.\n\n|Name|Type|Description|\n|----|----|-----------|\n|number|String|Telephone number to validate.|\n\n<table id=\"table_oyd_b5t_kmb\" class=\"returns\"><thead><tr><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nBoolean\n\n</td><td>\n\nFlag that indicates whether the specified number is a valid telephone number.Possible values:\n\n-   true: Valid E.164 telephone number.\n-   false: Invalid telephone number.\n\n</td></tr></tbody>\n</table>This example illustrates how to validate a telephone number.\n\n```\nvar sourceRecord = new GlideRecord('incident');\nsourceRecord.query();\nif (sourceRecord.next()) {\n  var fromNumber = getFromNumber();\n  var nUtil = new NotifyUtil();\n  var toNumber = nUtil.getSMSNumberForUser(sourceRecord.assigned_to.getRefRecord());\n  var message = 'Incident ' + sourceRecord.getDisplayValue() + ' has been assigned to you.';\n  if (fromNumber && nUtil.validateOutboundNotifyPhoneNumber(fromNumber) && toNumber && nUtil.validatePhoneNumber(toNumber)) {\n    var notifySMS = new NotifySMS();\n    notifySMS.sendToNumber(fromNumber, toNumber, message, sourceRecord);\n  }\n}\n\nfunction getFromNumber() {\n  var prop = gs.getProperty('custom_property_name', '');\n  if (!prop){\n    return getFallbackFromNumber();\n  }\n  return prop;\n} \n\nfunction getFallbackFromNumber() {\n  var notifyNumGr = new GlideRecord(\"notify_number\");\n  notifyNumGr.addActiveQuery();\n  notifyNumGr.addQuery('has_sms_out', 'yes');\n  notifyNumGr.query();\n  if (notifyNumGr.next()) {\n    return notifyNumGr.number + '';\n  }\n  return '';\n} \n```\n\n"}}