---
sourceDocument: Xanadu API Reference
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/xanadu/api-reference

 Release :

    - xanadu

ft:locale :

    - en-US

ft:publication_title :

    - Xanadu API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# OnCallContactPreferenceUtil - Global

# OnCallContactPreferenceUtil - Global {#ariaid-title1}

* Release version: Xanadu
* 
* Updated August 1, 2024
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 4 minutes to read

The OnCallContactPreferenceUtil script include provides methods for handling contact preferences.

For contact preference configuration, see [Configure contact preferences](https://www.servicenow.com/docs/access?context=config-my-contact-prefs-oncall&version=xanadu&pubname=xanadu-it-service-management&ft:locale=en-US).

This script include supports the [OnCallRotation](https://servicenow-prod.fluidtopics.net/_kLZtcNfjEIocJOkCa8SHA#c_OnCallRotationAPI "The OnCallRotation script include provides methods to manage on-call schedules.") script include.

## OnCallContactPreferenceUtil - OnCallContactPreferenceUtil() {#ariaid-title2}

Creates an instance of the OnCallContactPreferenceUtil class.
{#P-OnCallContactPreferenceUtil__table_pzm_w3f_2w__entry__3}

| Name | Type | Description |
|-|-|-|
| None |   |   |
[Table 1. Parameters]

{#P-OnCallContactPreferenceUtil__table_pzm_w3f_2w}

## OnCallContactPreferenceUtil - getContactsAtByEscalatee(Object escalatee, Number
contactAttempt, GlideDateTime gdt, String rotaSysIds) {#ariaid-title3}

Gets a list of contacts with the escalatee object. Each returned contact contains a
list of user contact preferences.
{#P-getContactsAtByEscalatee_O_N_F_S__table_o1s_x5j_3gb__entry__3}

| Name | Type | Description |
|-|-|-|
| escalatee | Object | Mandatory. Escalatee object returned by the [getEscalationPlan()](https://servicenow-prod.fluidtopics.net/_kLZtcNfjEIocJOkCa8SHA#r_OCR-getEscalationPlan_S_GDT "Gets a list of objects to escalate to, escalation plans that consist of either a user [sys_user] or notification device [cmn_notif_device], for a group's shift at the specified date and time. This API is applicable for a single shift, overlapping shifts, and custom escalation.") method. |
| contactAttempt | Number | Optional. The attempt you are trying to contact \[ default value = 1 \]. * <kbd class="ph userinput">1</kbd>: First attempt * <kbd class="ph userinput">2</kbd>: First reminder * <kbd class="ph userinput">3 or more</kbd>: Subsequent reminders {#P-getContactsAtByEscalatee_O_N_F_S__ul_gp2_q4w_gjb} |
| gdt | GlideDateTime | Optional. yyyy-MM-dd HH:mm:ss format in the UTC timezone. Default is now.admin |
| rotaSysIds | String | Optional. Comma-separated string of Sys IDs of shifts from the \[cmn_rota\] table. Default value returns Sys IDs of the shifts at current time. |
[Table 2. Parameters]

{#P-getContactsAtByEscalatee_O_N_F_S__table_o1s_x5j_3gb} {#P-getContactsAtByEscalatee_O_N_F_S__table_nmd_wvj_3gb__entry__2}

| Type | Description |
|-|-|
| Array object | Array of escalatees (either a user, group, or device records depending on the notification rules) at a specific time and position. * type: String. Type of contact, e.g., user. * sys_id: String. Sys ID of the user from the \[sys_user\] table. * rota_id: String. Sys ID of the shift from the \[cmn_rota\] table. * roster_id: String. Sys ID of the roster from the \[cmn_rota_roster\] table. * escalation_step_id: String. If an escalation path has been defined, Sys ID of the escalation step from the \[cmn_rota_esc_step_def\] table. * forced_communication_channel: String. If specified in the preferences, mandatory communication channel. Supported values include SMS, voice or email. * override_user_contact_preference: Boolean. True if there are contact overrides, false otherwise. * preference_source: String. Source of preference, such as contact or group. * contact_attempt: Number. Contact attempts: 1 = first attempt, 2 = first reminder, and so on. * user_preferences: Array Object. * type: String. User's preferred contact format, e.g. sms, email, or number. * \<name of preferred format, e.g., email or number\>: String. Content of preferred contact type, e.g., email address or phone number. {#P-getContactsAtByEscalatee_O_N_F_S__ul_pzn_52r_gjb} * contact_preferences, Array Object. * type: String. User's preferred contact format, e.g., email or number. * \<name of preferred format, e.g., email or number\>: String. Content of preferred contact type, e.g., email address or phone number. {#P-getContactsAtByEscalatee_O_N_F_S__ul_vnw_y2r_gjb} {#P-getContactsAtByEscalatee_O_N_F_S__ul_whv_4bp_3jb} |
[Table 3. Returns]

{#P-getContactsAtByEscalatee_O_N_F_S__table_nmd_wvj_3gb}  

    var serviceDeskSysId = '<Sys_ID>';
    var ocRotation = new OnCallRotation();
    var escalationPlan = ocRotation.getEscalationPlan(serviceDeskSysId);
    var escalatee = escalationPlan[0];

    var onContactPrefUtil = new OnCallContactPreferenceUtil();
    var contactAttempt = 1;
    var gdt = new GlideDateTime();
    var contacts = onContactPrefUtil.getContactsAtByEscalatee(escalatee, contactAttempt, gdt);
    gs.log(JSON.stringify(contacts));

Output:

    [{
        "type": "user",
        "sys_id": "<Sys_ID>",
        "rota_id": "<Rotation_ID>",
        "roster_id": "",
        "escalation_step_id": "<Escalation_Step_ID>",
        "forced_communication_channel": "",
        "override_user_contact_preference": true,
        "preference_source": "contact",
        "contact_attempt": 1,
        "user_preferences": [{
            "type": "sms",
            "number": "8587200477"
        }],
        "contact_preferences": [{
            "type": "voice",
            "number": "5555555555"
        }]
    }]

## OnCallContactPreferenceUtil - getUserPreferences(String userSysId, Number contactAttempt, GlideDateTime gdt, String communicationTypes) {#ariaid-title4}

Gets the list of contact preferences at the time at which the user has opted for communication. If no time is specified, then current time is used. This method is applicable to single and overlapping
shifts.
{#P-getUserPreferences_S_N_GDT_S__table_ixr_4jk_3gb__entry__3}

| Name | Type | Description |
|-|-|-|
| userSysId | String | Sys ID of the user from the \[sys_user\] table. |
| contactAttempt | Number | Optional. The attempt you are trying to contact \[ default value = 1 \]. * <kbd class="ph userinput">1</kbd>: First attempt * <kbd class="ph userinput">2</kbd>: First reminder * <kbd class="ph userinput">3 or more</kbd>: Subsequent reminders {#P-getUserPreferences_S_N_GDT_S__ul_gp2_q4w_gjb} |
| gdt | GlideDateTime | Optional. yyyy-MM-dd HH:mm:ss format in the UTC timezone. Default is now. |
| communicationTypes | String | Optional. Comma-separated string containing one or more of the following values: * email * sms * voice {#P-getUserPreferences_S_N_GDT_S__ul_pbz_gp5_1jb} Default includes all available communication types. |
[Table 4. Parameters]

{#P-getUserPreferences_S_N_GDT_S__table_ixr_4jk_3gb} {#P-getUserPreferences_S_N_GDT_S__table_ubq_ykk_3gb__entry__2}

| Type | Description |
|-|-|
| Array Object | On-call user contact preference. * type: String. User's preferred contact format, e.g. sms, email, or number. * \<name of preferred format, e.g., email or number\>: String. Content of preferred contact type, e.g., email address or phone number. {#P-getUserPreferences_S_N_GDT_S__ul_pzn_52r_gjb} |
[Table 5. Returns]

{#P-getUserPreferences_S_N_GDT_S__table_ubq_ykk_3gb}  

    var onContactPrefUtil = new OnCallContactPreferenceUtil();
    var contactAttempt = 1;
    var gdt = new GlideDateTime();
    var itilUserSysId = '<itilUserSysId>;
    var userPreferences = onContactPrefUtil.getUserPreferences(itilUserSysId, contactAttempt, gdt);
    gs.log(JSON.stringify(userPreferences));

Output:

    [{
        "type": "sms",
        "number": "5555555555"
    }, {
        "type": "voice",
        "number": "5555555555"
    }]

## OnCallContactPreferenceUtil - getCatchAllContacts(String rotaId, GlideDateTime gdt) {#ariaid-title5}

Gets a list of catch-all contacts and preferences.
{#P-getCatchAllContacts_S_GDT_S__table_xgb_ypj_3gb__entry__3}

| Name | Type | Description |
|-|-|-|
| rotaId | String | Sys ID of the shift from the \[cmn_rota\] table. |
| gdt | GlideDateTime | Optional. yyyy-MM-dd HH:mm:ss format in the UTC timezone. Default is now. |
[Table 6. Parameters]

{#P-getCatchAllContacts_S_GDT_S__table_xgb_ypj_3gb} {#P-getCatchAllContacts_S_GDT_S__table_ygb_ypj_3gb__entry__2}

| Type | Description |
|-|-|
| Array object | List of catch-all contacts with preferences. * type: String. Type of contact, e.g., user. * sys_id: String. Sys ID of the user from the \[sys_user\] table. * rota_id: String. Sys ID of the shift from the \[cmn_rota\] table. * roster_id: String. Sys ID of the roster from the \[cmn_rota_roster\] table. * escalation_step_id: String. If an escalation path has been defined, Sys ID of the escalation step from the \[cmn_rota_esc_step_def\] table. * forced_communication_channel: String. If specified in the preferences, mandatory communication channel. Supported values include SMS, voice or email. * override_user_contact_preference: Boolean. True if there are contact overrides, false otherwise. * preference_source: String. Source of preference, such as contact or group. * contact_attempt: Number. Contact attempts: 1 = first attempt, 2 = first reminder, and so on. * user_preferences: Array Object. * type: String. User's preferred contact format, e.g. sms, email, or number. * \<name of preferred format, e.g., email or number\>: String. Content of preferred contact type, e.g., email address or phone number. {#P-getCatchAllContacts_S_GDT_S__ul_pzn_52r_gjb} * contact_preferences, Array Object. * type: String. User's preferred contact format, e.g., email or number. * \<name of preferred format, e.g., email or number\>: String. Content of preferred contact type, e.g., email address or phone number. {#P-getCatchAllContacts_S_GDT_S__ul_vnw_y2r_gjb} {#P-getCatchAllContacts_S_GDT_S__ul_ftv_sbp_3jb} |
[Table 7. Returns]

{#P-getCatchAllContacts_S_GDT_S__table_ygb_ypj_3gb}  
Example:


    var onContactPrefUtil = new OnCallContactPreferenceUtil();
    var contactAttempt = 1;
    var gdt = new GlideDateTime();
    var rotaSysId = '<Rotation_Sys_ID>';
    var catchAllContacts = onContactPrefUtil.getCatchAllContacts(rotaSysId, gdt);
    gs.log(JSON.stringify(catchAllContacts));

Output:

    [{
        "type": "user",
        "sys_id": "<Sys_ID>",
        "rota_id": "<Rotation_ID>",
        "roster_id": "",
        "escalation_step_id": "<Escalation_Step_ID>",
        "forced_communication_channel": "",
        "override_user_contact_preference": true,
        "preference_source": "contact",
        "contact_attempt": 1,
        "user_preferences": [{
            "type": "sms",
            "number": "8587200477"
        }],
        "contact_preferences": [{
            "type": "voice",
            "number": "5555555555"
        }]
    }]