OnCallRotation - Global

Use to manage on-call schedules.

OnCallRotation - getCatchAll(String rotaID)

Gets the sys_id of the catch all person. Use together with the getCatchAllType() method to determine the source of the returned id. Get the sys_id of the catch all persons.

Table 1. Parameters
Name Type Description
rotaID String The sys_id of the rota.
Table 2. Returns
Type Description
String The sys_id of a sys_user, a cmn_rota_roster, or null.
var rotaID = "...";
var rota = new SNC.OnCallRotation()
gs.log("catch all: " + rota.catchAll(rotaID) + " (type:" + rota.catchAllType(rotaID) + ")");
}

OnCallRotation - getCatchAllType(String rotaID)

Gets the type of _catch all_ that lives at the end of the escalation chain. When the escalation chain finishes without assigning an on-call person, if configured, the incident is assigned to the _catch all_.

Table 3. Parameters
Name Type Description
rotaID String The sys_id of the rota.
Table 4. Returns
Type Description
String
  • Null: invalid rota id or catch all is not available.
  • Group_manager: the manager of the group linked to the rota is the catch all person.
  • Individual: a configured user is the catch all person.
  • All: all members of the configured roster are the catch all person.
var rotaID = "...";
var rota = new SNC.OnCallRotation()
gs.log("catch all: " + rota.catchAll(rotaID) + " (type:" + rota.catchAllType(rotaID) + ")");
}

OnCallRotation - getEscalateeAt(String groupID, GlideDateTime dateTime, Number position)

Gets an item to escalate to, either a user [sys_user] or notification device [cmn_notif_device], for a group's rota at the specified date and time and at a certain position in the escalation lineup.

The function returns null if an invalid position or group is passed as an argument.

You can use the getTableName() function to check whether the returning GlideRecord comes from the sys_user or cmn_notif_device table.

Table 5. Parameters
Name Type Description
groupID String The sys_id for the group from which to get the item to escalate.
dateTime GlideDateTime The date and time when the escalation lineup should begin.
position Number The position in the lineup to determine the item to escalate to (1-based, which means the count starts with 1).
Table 6. Returns
Type Description
GlideRecord The item to escalate to. Returns null if nothing is found.
var oncall = new SNC.OnCallRotation();
var escalatee = oncall.getEscalateeAt("287ebd7da9fe198100f92cc8d1d2154e", 
    new GlideDateTime("2013-11-26 09:00:00"), 2);
 
if (escalatee){
    gs.print(escalatee.getTableName());
    gs.print(escalatee.getTableName());
}

OnCallRotation - getEscalationPlan(String groupID, GlideDateTime dateTime)

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 rota at the specified date and time.

The Escalation object contains the following fields:
  • Number order: the escalation order within the lineup
  • String userId: sys_id of the sys_user record or null
  • String deviceId: sys_id of the cmn_notif_device record or null
  • Boolean isDevice: true or false depending on whether the item to escalate to is a device or user
  • GlideDuration timeBetweenReminders: the time between reminders being sent
  • Number reminderNum: number of reminders to be sent for each item to escalate to
Table 7. Parameters
Name Type Description
groupID String The sys_id for the group to get the to escalate to from.
dateTime GlideDateTime The date and time when the escalation lineup should begin.
Table 8. Returns
Type Description
List A list of escalation objects to escalate to.
var rota = new SNC.OnCallRotation()
var gdt = new GlideDateTime();
gdt.addMonths(1);//Next month 
 
var escalationPlan = rota.getEscalationPlan("486ae95aeb201100fcfb858ad106fe40", gdt);
 
for(var i = 0;  i < escalationPlan.size(); i++){
    gs.log(escalationPlan.get(i).order + " " + escalationPlan.get(i).userId + " " +
       escalationPlan.get(i).deviceId + " " +  escalationPlan.get(i).timeBetweenReminders + " " +
       escalationPlan.get(i).reminderNum );
}

OnCallRotation - getEscalationType(String rotaID)

Gets the type of escalation based on a simple calculation. If there is one active roster in the rota, rotate through members. If there is more than one active roster in the rota, rotate through rosters.

Table 9. Parameters
Name Type Description
rotaID String The sys_id for the rota to check for rosters.
Table 10. Returns
Type Description
String
  • Member: if there is one roster in the rota.
  • Roster: if there is more than one roster in the rota.
  • No rosters in this rota: if none of the above.
var rota = new SNC.OnCallRotation() //contains one roster
 
gs.log(rota.getEscalationType("486ae95aeb201100fcfb858ad106fe40")); // logs 'member'

OnCallRotation - OnCallRotation()

Creates an instance of the OnCallRotation class.

Table 11. Parameters
Name Type Description
None
var oncall = new SNC.OnCallRotation();

OnCallRotation - spansOverlap(ArrayList parent, ArrayList child, String timeZone)

Checks if the parent span and child spans overlap.

Table 12. Parameters
Name Type Description
parent ArrayList The parent spans to compare.
child ArrayList The child spans to compare.
timeZone String The name of the time zone.
Table 13. Returns
Type Description
Boolean Returns true if the parent and child spans overlap.
var onCall = new SNC.OnCallRotation();
 
// get a time range we are interested in
var timeZone = gs.getSession().getTimeZoneName();
var dateStart = new GlideDateTime();
var dateEnd = new GlideDateTime().addMonths(1);
 
// convert glidedatime to scheduledatetime because it is required
// by the function being called below
var scheduleStart = new GlideScheduleDateTime(dateStart);
var scheduleEnd =  new GlideScheduleDateTime(dateEnd);
scheduleStart.setTimeZone(timeZone);
scheduleEnd.setTimeZone(timeZone);
 
// calculate rotation items based on the date and time given
// for all the groups the currently logged in user is a member of
gs.include("OnCallRotationPersonal");
var rotation = new OnCallRotationPersonal();
var myGroups = gs.getUser().getMyGroups();
var groupIter = myGroups.iterator();
 
while(groupIter.hasNext()){
	var rotaItems = rotation.onCallDuringPeriod(groupIter.next(), scheduleStart, scheduleEnd);
 
	// loop through rotation schedules
	for (var i = 0; i < rotaItems.length - 1; i++) {
		var parentItem = rotaItems[i];
		var nextItem = rotaItems[i + 1];
 
		// check if previous and next time spans overlap
		var overlaps = onCall.spansOverlap(parentItem.getTimeSpans(), nextItem.getTimeSpans(), 
			gs.getSession().getTimeZoneName());
	}
}