The GlideMultiRecurrence API provides methods that return GlideDateTime objects that describe the run times for a specified scheduled job.

Use this API when you need to determine when a specific periodic or recurring job needs to run, also known as an occurrence.

This API runs in the sn_schdl_ns namespace.

To use this API, the associated scheduling table must contain one or more of the following fields (triggers).
When using this API, you must first create a GlideRecord object for the scheduling table on which the API should act. You then retrieve the scheduling record for which to obtain the occurrence records. For example:
var table_nameGR = new GlideRecord('<table_name>'); // Scheduling table, such as sys_trigger
table_nameGR.addQuery('sys_id', '<sys_id>'); // Sys_id of the scheduling record
table_nameGR.query();
table_nameGR.next();  // Retrieve the scheduling record

GlideMultiRecurrence - getOccurrences()

Returns a GlideDateTime object for each scheduled run time (occurrence) that a specified scheduled job should execute within a specific time period, based on the triggers defined in the associated schedule record (GlideRecord).

This method analyzes the current GlideRecord scheduling object, using the triggers defined within the scheduling object, to determine when the job should run.

Properties that control the return results:
  • com.glide.schedule.recurrence.num_occurrences_max: Maximum number of occurrences to return.
  • com.glide.schedule.recurrence.num_occurrences_default: Default number of occurrences to return.
The method applies the following rules to determine the occurrences to return for the defined period of time and associated triggers:
  • If the effective_start field is valid and not null or empty, use it as the date to start returning occurrences. Otherwise use the current date.
  • If the effective_end date field is valid and not null or empty, return the occurrences between the effective_start and the effective_end date fields.

    Exception to the above rule: If the effective_end date is too far in the future, resulting in the return of more than the number of occurrences specified in the com.glide.schedule.recurrence.num_occurrences_max property, then the result is limited to the value specified in com.glide.schedule.recurrence.num_occurrences_max (default 500).

  • If the effective_end date field is null or empty, but the frequency field is set, then use frequency to determine the number of occurrences to return.
  • Return historical dates if the effective_start date field is in the past.
  • If the frequency and effective_end date fields are both specified, use the effective_end date with the maximum number of occurrences limited to the value specified in the com.glide.schedule.recurrence.num_occurrences_max property.
If none of the rules above are true, then the method returns occurrences based on the system properties' default setting.
Note: MAX_Drift is not supported by this API.

Example: Both frequency and effective_end are specified. Effective_end date takes precedence, and frequency is ignored.

  • frequency: 10
  • effective_start: 1st Aug 2022
  • effective_end: 10th Oct 2022
  • Trigger type: Day in month
  • Run day of month: 15

Number of GlideDateTime objects returned = 2.

Occurrences returned: 15th Aug 2022, 15th Sep 2022.

Example: Both frequency and effective_end are specified. Effective_end date takes precedence and frequency is ignored, however, the number of returned occurrences is restricted by the value in the com.glide.schedule.recurrence.num_occurrences_max property.

  • frequency: 20
  • effective_start: 1st Aug 2022
  • effective_end: 30th Oct 2070
  • Trigger type: Day in month
  • Run day of month: 15

Number of GlideDateTime objects returned = 500.

Table 1. Parameters
Name Type Description
grSchedule GlideRecord GlideRecord object pointing to the record containing the job for which you want to get the schedule occurrences.
Table 2. Returns
Type Description
Array of GlideDateTime objects GlideDateTime object for each time that the schedule job should run.

Example

The following example shows how to retrieve GlideDateTime objects for all scheduled run date/time for a specific period for a specified job schedule record. The selected job is scheduled to run every hour.

var sys_id = 'a9e30c7dc61122760116894de7bcc7bd'; // Sys_id of the job schedule record
var table = 'sys_trigger'; // Table that contains the job schedule record

var grSchedule = new GlideRecord(table);
if
 (grSchedule.get(sys_id)) {
  var multiRecurrence = new sn_schdl_ns.GlideMultiRecurrence();
  var dates = multiRecurrence.getOccurrences(grSchedule); // Display the list of occurrences
  for(var i=0; i<dates.length; i++) {
    gs.info('occurrence = ' + dates[i]);
  }
}

Output:

occurrence = 2022-11-21 16:23:23
occurrence = 2022-11-21 17:23:23
occurrence = 2022-11-21 18:23:23
occurrence = 2022-11-21 19:23:23
occurrence = 2022-11-21 20:23:23
occurrence = 2022-11-21 21:23:23
occurrence = 2022-11-21 22:23:23
occurrence = 2022-11-21 23:23:23
occurrence = 2022-11-22 00:23:23
occurrence = 2022-11-22 01:23:23