{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":1075,"path":"api-reference/server-api-reference/c_OCRosterSpanApprovalUtilAPI.md","title":"OCRosterSpanApprovalUtil - Global","bundle":null,"doc_type":null,"release":"australia","body":"\n# OCRosterSpanApprovalUtil- Global\n\nThe OCRosterSpanApprovalUtil script include provides methods for the PTO approval feature.\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## OCRosterSpanApprovalUtil - approvePTOSpan \\(GlideRecord rosterSpanGr\\)\n\nChanges the type of the roster\\_schedule\\_span to time-off from approval.\n\n|Name|Type|Description|\n|----|----|-----------|\n|rosterSpanGr|GlideRecord|A roster\\_schedule\\_span\\_proposal record.|\n\n|Type|Description|\n|----|-----------|\n|void| |\n\n## OCRosterSpanApprovalUtil - getContextualCalUrlPerSpanProposal \\(GlideRecord rosterSpanProposalGr\\)\n\nReturns a URL to the on-call calendar based on the rosterSpanProposalGr.\n\n|Name|Type|Description|\n|----|----|-----------|\n|rosterSpanProposalGr|GlideRecord|A roster\\_schedule\\_span\\_proposal record.|\n\n|Type|Description|\n|----|-----------|\n|String|A URL to the on-call calendar based on the rosterSpanProposalGr.|\n\n## OCRosterSpanApprovalUtil - getFromDateDisplayValuePerSpanProposal \\(GlideRecord rosterSpanProposalGr\\)\n\nReturns a formatted GlideScheduleDateTime string based on the start date of the rosterSpanProposalGr.\n\n|Name|Type|Description|\n|----|----|-----------|\n|rosterSpanProposalGr|GlideRecord|A roster\\_schedule\\_span\\_proposal record.|\n\n|Type|Description|\n|----|-----------|\n|String|A formatted GlideScheduleDateTime string based on the start date of the rosterSpanProposalGr.|\n\n## OCRosterSpanApprovalUtil - getPTOApproversList\\(GlideRecord rosterSpanProposalGr\\)\n\nReturns an array of group managers based on the user's rota groups.\n\n|Name|Type|Description|\n|----|----|-----------|\n|rosterSpanProposalGr|GlideRecord|A roster\\_schedule\\_span\\_proposal record.|\n\n|Type|Description|\n|----|-----------|\n|Array|An array of group managers based on the user's rota groups.|\n\nThe 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.\n\n```\nfunction OCPTOApprovalReminder() {\n\n\t//Passing parameters in 'getDateFormat()' function with the days which needs to be added\n\tvar startDate = getDateFormat(1); //We can use System property to set Start Date\n\tvar endDate = getDateFormat(2); //We can use System property to set End Date\n\t\n\t//Building the encoded query all the Pending approval state proposals whose start date is tomorrow\n\tvar encodedQuery = 'state=1^roster_schedule_span.start_date_time>' + startDate + '^roster_schedule_span.start_date_time<' + endDate;\n\t\n\t//Sends an event notification to all rota managers and their delegate managers\n\tgetNotApprovedList(encodedQuery);\n\t\n\t//Converts the date and time in ISO Format\n\tfunction getDateFormat(daysToBeAdded) {\n\n\t\t//Getting today's date and adding '1' day\n\t\tvar todaysDate = new GlideDate();\n\t\ttodaysDate.addDaysUTC(daysToBeAdded);\n\t\ttodaysDate = todaysDate.getValue();\n\n\t\t//Converting to today's date object to GlideDate object\n\t\tvar addingDaysToDate = new GlideDate();\n\t\taddingDaysToDate.setValue(todaysDate);\n\n\t\t//Setting the time default to '12:00:00' and returning the time in the specified format to match ISO\n\t\tvar staticTime = new GlideTime();\n\t\tstaticTime.setValue('00:00:00');\n\t\tstaticTime.setValue(staticTime.getHourOfDayUTC() + ':' + staticTime.getMinutesUTC() + ':' + staticTime.getSeconds());\n\n\t\t//Returns the date & time in the specified format\n\t\tvar isoFormattedDateTime = addingDaysToDate.getByFormat(\"yyyyMMdd\") + 'T' + staticTime.getByFormat(\"HHmmss\") + 'Z';\n\t\treturn isoFormattedDateTime;\n\t}\n\t\n\t//Gliding Roster schedule span proposal table with the built-in query to fetch the records whose proposals are not approved/rejected\n\tfunction getNotApprovedList(addEncodedQuery) {\n\t\tvar rosterScheduleEntryProposalGR = new GlideRecord('roster_schedule_span_proposal');\n\t\trosterScheduleEntryProposalGR.addEncodedQuery(addEncodedQuery);\n\t\trosterScheduleEntryProposalGR.query();\n\t\twhile(rosterScheduleEntryProposalGR.next()) {\n\n\t\t\t//Call On-Call Scheduling OCRosterSpanApprovalUtil library with 'getPTOApproversList' function \n\t\t\t//pass GlideRecord object of 'roster_schedule_span_proposal' table\n\t\t\tvar rotaManagers = new OCRosterSpanApprovalUtil().getPTOApproversList(rosterScheduleEntryProposalGR);\n\t\t\trotaManagers = rotaManagers.join(\",\");\n\n\t\t\t// Pull only the unique sys_ids\n\t\t\tvar managerList = new ArrayUtil().unique(getManagerDelegateApprovals(rotaManagers).toString().split(','));\n\n                     // Event to trigger a reminder notification for testing.\n                     // To use, create a an event registry named \"oc.manager.delegate.reminder\"\n                     // Call the event in a notification and uncomment the following line\n\t\t\t//gs.eventQueue(\"oc.manager.delegate.reminder\", rosterScheduleEntryProposalGR, managerList, \"\");\n\n               if(managerList)\n\t\t\tgs.info(\"Returns the list of manager and it's delegate members >>>>>> \" + managerList);\n\t\t}\n\t}\n\t\n\t//Get the sys_ids of the managers and their delegate managers\n\tfunction getManagerDelegateApprovals(manager) {\n\t\tvar answer = [];\n        answer.push(manager);\n\t\tvar delegateGR = new GlideRecord(\"sys_user_delegate\");\n\t\tdelegateGR.addQuery(\"user\", 'IN', manager);\n\t\tdelegateGR.addQuery(\"starts\", \"<=\", gs.daysAgo(0));\n\t\tdelegateGR.addQuery(\"ends\", \">=\", gs.daysAgo(0));\n\t\tdelegateGR.addQuery(\"approvals\", true);\n\t\tdelegateGR.query();\n\t\twhile(delegateGR.next()) {\n\t\t\tanswer.push(delegateGR.getValue('user'));\n\t\t\tanswer.push(delegateGR.getValue('delegate'));\n\t\t}\n\t\treturn answer;\n\t}\n}\n```\n\nAdd 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.\n\n```\nOCPTOApprovalReminder();\n```\n\n## OCRosterSpanApprovalUtil - getToDateDisplayValuePerSpanProposal \\(rosterSpanProposalGr GlideRecord\\)\n\nReturns a formatted GlideScheduleDateTime string based on the end date of the rosterSpanProposalGr.\n\n|Name|Type|Description|\n|----|----|-----------|\n|rosterSpanProposalGr|GlideRecord|A roster\\_schedule\\_span\\_proposal record.|\n\n|Type|Description|\n|----|-----------|\n|String|A formatted GlideScheduleDateTime string based on the end date of the rosterSpanProposalGr.|\n\n## OCRosterSpanApprovalUtil - getUserNamePerSpanProposal \\(GlideRecord rosterSpanProposalGr\\)\n\nReturns the user's name based on rosterSpanProposalGr.\n\n|Name|Type|Description|\n|----|----|-----------|\n|rosterSpanProposalGr|GlideRecord|A roster\\_schedule\\_span\\_proposal record.|\n\n|Type|Description|\n|----|-----------|\n|String|The user's name based on rosterSpanProposalGr.|\n\n## OCRosterSpanApprovalUtil - isPTOApprovalRequired \\(\\)\n\nChecks whether the system property **com.snc.on\\_call\\_rotation.pto.approval.required** is true.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n|Type|Description|\n|----|-----------|\n|Boolean|Returns true if the system property **com.snc.on\\_call\\_rotation.pto.approval.required** is true..|\n\n## OCRosterSpanApprovalUtil - rejectPTOSpan \\(rosterSpanGr GlideRecord\\)\n\nChanges the type of the roster\\_schedule\\_span to rejected from approval.\n\n|Name|Type|Description|\n|----|----|-----------|\n|rosterSpanGr|GlideRecord|A roster\\_schedule\\_span\\_proposal record.|\n\n|Type|Description|\n|----|-----------|\n|void| |\n\n"}}