---
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


---

# OCRosterSpanApprovalUtil - Global

# OCRosterSpanApprovalUtil - Global {#ariaid-title1}

The OCRosterSpanApprovalUtil script include provides methods for the PTO approval feature.

## OCRosterSpanApprovalUtil - approvePTOSpan (GlideRecord rosterSpanGr) {#ariaid-title2}

Changes the type of the roster_schedule_span to time-off from approval.
{#r_OCRosSpnApUtil-approvePTOSpan_GR__table_q5p_l1j_hx__entry__3}

| Name | Type | Description |
|-|-|-|
| rosterSpanGr | GlideRecord | A roster_schedule_span_proposal record. |
[Table 1. Parameters]

{#r_OCRosSpnApUtil-approvePTOSpan_GR__table_q5p_l1j_hx} {#r_OCRosSpnApUtil-approvePTOSpan_GR__table_r5p_l1j_hx__entry__2}

| Type | Description |
|-|-|
| void |   |
[Table 2. Returns]

{#r_OCRosSpnApUtil-approvePTOSpan_GR__table_r5p_l1j_hx}

## OCRosterSpanApprovalUtil - getContextualCalUrlPerSpanProposal (GlideRecord
rosterSpanProposalGr) {#ariaid-title3}

Returns a URL to the on-call calendar based on the rosterSpanProposalGr.
{#r_OCRosSpnApUtil-gtCtCalUrlPrSnP_GR__table_xhy_cy3_hx__entry__3}

| Name | Type | Description |
|-|-|-|
| rosterSpanProposalGr | GlideRecord | A roster_schedule_span_proposal record. |
[Table 3. Parameters]

{#r_OCRosSpnApUtil-gtCtCalUrlPrSnP_GR__table_xhy_cy3_hx} {#r_OCRosSpnApUtil-gtCtCalUrlPrSnP_GR__table_yhy_cy3_hx__entry__2}

| Type | Description |
|-|-|
| String | A URL to the on-call calendar based on the rosterSpanProposalGr. |
[Table 4. Returns]

{#r_OCRosSpnApUtil-gtCtCalUrlPrSnP_GR__table_yhy_cy3_hx}

## OCRosterSpanApprovalUtil - getFromDateDisplayValuePerSpanProposal (GlideRecord
rosterSpanProposalGr) {#ariaid-title4}

Returns a formatted GlideScheduleDateTime string based on the start date of the
rosterSpanProposalGr.
{#r_OCRosSpnApUtil-gtFrDtDpVlPSPrp_GR__table_f5s_gz3_hx__entry__3}

| Name | Type | Description |
|-|-|-|
| rosterSpanProposalGr | GlideRecord | A roster_schedule_span_proposal record. |
[Table 5. Parameters]

{#r_OCRosSpnApUtil-gtFrDtDpVlPSPrp_GR__table_f5s_gz3_hx} {#r_OCRosSpnApUtil-gtFrDtDpVlPSPrp_GR__table_g5s_gz3_hx__entry__2}

| Type | Description |
|-|-|
| String | A formatted GlideScheduleDateTime string based on the start date of the rosterSpanProposalGr. |
[Table 6. Returns]

{#r_OCRosSpnApUtil-gtFrDtDpVlPSPrp_GR__table_g5s_gz3_hx}

## OCRosterSpanApprovalUtil - getPTOApproversList(GlideRecord rosterSpanProposalGr) {#ariaid-title5}

Returns an array of group managers based on the user's rota groups.
{#r_OCRosSpnApUtil-getPTOApprList_GR__table_m5z_tx3_hx__entry__3}

| Name | Type | Description |
|-|-|-|
| rosterSpanProposalGr | GlideRecord | A roster_schedule_span_proposal record. |
[Table 7. Parameters]

{#r_OCRosSpnApUtil-getPTOApprList_GR__table_m5z_tx3_hx} {#r_OCRosSpnApUtil-getPTOApprList_GR__table_n5z_tx3_hx__entry__2}

| Type | Description |
|-|-|
| Array | An array of group managers based on the user's rota groups. |
[Table 8. Returns]

{#r_OCRosSpnApUtil-getPTOApprList_GR__table_n5z_tx3_hx}  
The following example is an on-demand script include named
OCPTOApprovalReminder. When called by running the scheduled job
manually, the managers and their delegate managers are notified of employees who are
scheduled for PTO on the following day.

    function OCPTOApprovalReminder() {

    	//Passing parameters in 'getDateFormat()' function with the days which needs to be added
    	var startDate = getDateFormat(1); //We can use System property to set Start Date
    	var endDate = getDateFormat(2); //We can use System property to set End Date
    	
    	//Building the encoded query all the Pending approval state proposals whose start date is tomorrow
    	var encodedQuery = 'state=1^roster_schedule_span.start_date_time>' + startDate + '^roster_schedule_span.start_date_time<' + endDate;
    	
    	//Sends an event notification to all rota managers and their delegate managers
    	getNotApprovedList(encodedQuery);
    	
    	//Converts the date and time in ISO Format
    	function getDateFormat(daysToBeAdded) {

    		//Getting today's date and adding '1' day
    		var todaysDate = new GlideDate();
    		todaysDate.addDaysUTC(daysToBeAdded);
    		todaysDate = todaysDate.getValue();

    		//Converting to today's date object to GlideDate object
    		var addingDaysToDate = new GlideDate();
    		addingDaysToDate.setValue(todaysDate);

    		//Setting the time default to '12:00:00' and returning the time in the specified format to match ISO
    		var staticTime = new GlideTime();
    		staticTime.setValue('00:00:00');
    		staticTime.setValue(staticTime.getHourOfDayUTC() + ':' + staticTime.getMinutesUTC() + ':' + staticTime.getSeconds());

    		//Returns the date & time in the specified format
    		var isoFormattedDateTime = addingDaysToDate.getByFormat("yyyyMMdd") + 'T' + staticTime.getByFormat("HHmmss") + 'Z';
    		return isoFormattedDateTime;
    	}
    	
    	//Gliding Roster schedule span proposal table with the built-in query to fetch the records whose proposals are not approved/rejected
    	function getNotApprovedList(addEncodedQuery) {
    		var rosterScheduleEntryProposalGR = new GlideRecord('roster_schedule_span_proposal');
    		rosterScheduleEntryProposalGR.addEncodedQuery(addEncodedQuery);
    		rosterScheduleEntryProposalGR.query();
    		while(rosterScheduleEntryProposalGR.next()) {

    			//Call On-Call Scheduling OCRosterSpanApprovalUtil library with 'getPTOApproversList' function 
    			//pass GlideRecord object of 'roster_schedule_span_proposal' table
    			var rotaManagers = new OCRosterSpanApprovalUtil().getPTOApproversList(rosterScheduleEntryProposalGR);
    			rotaManagers = rotaManagers.join(",");

    			// Pull only the unique sys_ids
    			var managerList = new ArrayUtil().unique(getManagerDelegateApprovals(rotaManagers).toString().split(','));

                         // Event to trigger a reminder notification for testing.
                         // To use, create a an event registry named "oc.manager.delegate.reminder"
                         // Call the event in a notification and uncomment the following line
    			//gs.eventQueue("oc.manager.delegate.reminder", rosterScheduleEntryProposalGR, managerList, "");

                   if(managerList)
    			gs.info("Returns the list of manager and it's delegate members >>>>>> " + managerList);
    		}
    	}
    	
    	//Get the sys_ids of the managers and their delegate managers
    	function getManagerDelegateApprovals(manager) {
    		var answer = [];
            answer.push(manager);
    		var delegateGR = new GlideRecord("sys_user_delegate");
    		delegateGR.addQuery("user", 'IN', manager);
    		delegateGR.addQuery("starts", "<=", gs.daysAgo(0));
    		delegateGR.addQuery("ends", ">=", gs.daysAgo(0));
    		delegateGR.addQuery("approvals", true);
    		delegateGR.query();
    		while(delegateGR.next()) {
    			answer.push(delegateGR.getValue('user'));
    			answer.push(delegateGR.getValue('delegate'));
    		}
    		return answer;
    	}
    }

Add the following call to a record in the Scheduled Script Execution \[sysauto_script\]
table. This trigger calls the OCPTOApprovalReminder script include when
the scheduled job is run manually.

    OCPTOApprovalReminder();

## OCRosterSpanApprovalUtil - getToDateDisplayValuePerSpanProposal (rosterSpanProposalGr
GlideRecord) {#ariaid-title6}

Returns a formatted GlideScheduleDateTime string based on the end date of the
rosterSpanProposalGr.
{#r_OCRosSpnApUtil-gtToDtDVlPrSnPr_GR__table_jbs_21j_hx__entry__3}

| Name | Type | Description |
|-|-|-|
| rosterSpanProposalGr | GlideRecord | A roster_schedule_span_proposal record. |
[Table 9. Parameters]

{#r_OCRosSpnApUtil-gtToDtDVlPrSnPr_GR__table_jbs_21j_hx} {#r_OCRosSpnApUtil-gtToDtDVlPrSnPr_GR__table_kbs_21j_hx__entry__2}

| Type | Description |
|-|-|
| String | A formatted GlideScheduleDateTime string based on the end date of the rosterSpanProposalGr. |
[Table 10. Returns]

{#r_OCRosSpnApUtil-gtToDtDVlPrSnPr_GR__table_kbs_21j_hx}

## OCRosterSpanApprovalUtil - getUserNamePerSpanProposal (GlideRecord
rosterSpanProposalGr) {#ariaid-title7}

Returns the user's name based on rosterSpanProposalGr.
{#r_OCRosSpnApUtil-gtUNmPerSnProp_GR__table_rpb_ly3_hx__entry__3}

| Name | Type | Description |
|-|-|-|
| rosterSpanProposalGr | GlideRecord | A roster_schedule_span_proposal record. |
[Table 11. Parameters]

{#r_OCRosSpnApUtil-gtUNmPerSnProp_GR__table_rpb_ly3_hx} {#r_OCRosSpnApUtil-gtUNmPerSnProp_GR__table_spb_ly3_hx__entry__2}

| Type | Description |
|-|-|
| String | The user's name based on rosterSpanProposalGr. |
[Table 12. Returns]

{#r_OCRosSpnApUtil-gtUNmPerSnProp_GR__table_spb_ly3_hx}

## OCRosterSpanApprovalUtil - isPTOApprovalRequired () {#ariaid-title8}

Checks whether the system property
com.snc.on_call_rotation.pto.approval.required is true.
{#r_OCRosSpnApUtil-isPTOAppRequired__table_ift_lx3_hx__entry__3}

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

{#r_OCRosSpnApUtil-isPTOAppRequired__table_ift_lx3_hx} {#r_OCRosSpnApUtil-isPTOAppRequired__table_jft_lx3_hx__entry__2}

| Type | Description |
|-|-|
| Boolean | Returns true if the system property com.snc.on_call_rotation.pto.approval.required is true.. |
[Table 14. Returns]

{#r_OCRosSpnApUtil-isPTOAppRequired__table_jft_lx3_hx}

## OCRosterSpanApprovalUtil - rejectPTOSpan (rosterSpanGr GlideRecord) {#ariaid-title9}

Changes the type of the roster_schedule_span to rejected from approval.
{#r_OCRosSpnApUtil-rejectPTOSpan_GR__table_vvb_t1j_hx__entry__3}

| Name | Type | Description |
|-|-|-|
| rosterSpanGr | GlideRecord | A roster_schedule_span_proposal record. |
[Table 15. Parameters]

{#r_OCRosSpnApUtil-rejectPTOSpan_GR__table_vvb_t1j_hx} {#r_OCRosSpnApUtil-rejectPTOSpan_GR__table_wvb_t1j_hx__entry__2}

| Type | Description |
|-|-|
| void |   |
[Table 16. Returns]

{#r_OCRosSpnApUtil-rejectPTOSpan_GR__table_wvb_t1j_hx}