Historical On Call report

As a supervisor, you might want to see details of your team members' on-call times so you can identify trends or coverage gaps, or so you can see how often a specific person has been on-call during a certain period. The Historical On Call report lets you export a spreadsheet (.xlsx file) containing up to 100 days' worth of historical data.

The date when the report began collecting data depends on your region: for instances based in North America, there is no data available prior to February 1, 2020. For instances in the European and Asia-Pacific regions, there is no data available prior to January 1, 2020. Because large on-call groups can't contain escalations or rotations, the Historical On Call report doesn't include data for on-call groups with more than 200 members. The report also excludes shifts that are longer than 30 days in duration.

To export the Historical On Call report:

  1. Navigate to the Groups tab, and then click Historical On Call.
  2. Use the date pickers to set From and To dates, ensuring that the dates are no more than 100 days apart.
    • If you select dates that are more than 100 days apart, the From and To dates adjust automatically to stay within 100 days of each other.
  3. Set the time zone you want to use to calculate the report.
  4. Select whether report should export Groups I Supervise or All Groups.
  5. Choose an escalation option:
    • Include all escalations: Includes all escalations in the report.
    • Filter by escalation level: Limits the report to the maximum number of escalation levels. For example, to return a report that contains primary and secondary on-call resources, set the level to 2. The maximum escalation level is 9. For more information on escalation levels, see Filter by escalation order.
    • Filter by escalation time: Limits the report to a maximum escalation delay, in minutes. For example, if you enter "20", the generated report only includes on-call information for the first 20 minutes of escalation delay. For more information on escalation delays, see About escalations.
  6. Select the check box beside Exclude temporary absences and replacements to exclude temporary absences and their replacements whose on call time is zero.
  7. Click Export.
    • xMatters generates the report and downloads it to your system as an .xlsx file.

There are a few things you might notice when you open and view the downloaded file:

  • Each row of the report represents a block of uninterrupted on-call time for a single user at the same escalation level, referred to as a segment. As shifts can span days, weeks, or even longer, splitting shifts into segments allows supervisors to calculate on-call pay without waiting for the entire shift to end. Even a shift that only lasts a few hours can have multiple segments because of shift rotation or temporary absences.
  • The report automatically excludes 24x7 shifts with no escalations.
  • If someone modified an escalation delay during the time period the report covers, it affects shift segments for the current and following shift members.
  • The information in the report is based on your permission level, and is restricted to only those users you have permission to access (such as the users you supervise).
  • The data in the exported report is based on the permissions of the roles you're assigned in xMatters. If your role does not have permission to view a custom field, the information is redacted and replaced with "<Restricted>".
  • Depending on when they were removed, deleted shifts may still appear in the Historical On Call report.

Each row of the Historical On Call report includes the following information:

Column Name

Description

Shift Type

 The type of shift; available options include: ON_CALL, ABSENCE, and REPLACEMENTS.

User ID

 A unique identifier that the user uses when logging into xMatters. For example, Mary McBride's user ID is mmcbride. If there are two users named Mary McBride, their user IDs could be mmcbride1 and mmcbride2.

First Name

 The first name of the user.

Last Name

 The last name of the user.
User UUID The unique alpha-numeric identifier of the user in xMatters.
User's Site Name The name of the user's assigned site.
Group Name The name of the group the user belongs to.
Group UUID The unique alpha-numeric identifier of the group.
On-Call Shift Name The name of the shift within the group for which the user was on call.
Holiday Shift A Boolean value of either TRUE or FALSE that indicates whether the on-call shift was covering a holiday.
Shift Occurrence Start The timestamp of the start of the shift in UTC format (YYYY-MM-DDT00:00:00:000Z).
Shift Occurrence End The timestamp of the end of the shift in UTC format (YYYY-MM-DDT00:00:00:000Z).
Segment Time Start The start time of a portion of a shift.
Segment Time End The end time of a shift segment.
Escalation Level The escalation level of the user. For example, a user could be the primary escalation for one group and the secondary escalation for another.
Escalation Time The elapsed time (in minutes) before an alert is escalated.
On-Call Time (mins) The total amount of time, in minutes, that the user was on call.
Absence Time (mins) The total amount of time, in minutes, the user was absent from being on call.
Replacement Time (mins) The amount of time, in minutes, the user replaced another user during their on-call shift. For example, if Mary McBride replaced Steve Smith for an hour during his on call shift, the Replacement Time is listed as 60.
Replacement User Name Displayed only if a Replacement Time was logged. The name of the person who was replaced by the user during the on-call shift. Using the example above, Steve Smith is listed as the Replacement User Name column.
Replacement User UUID Displayed only if a Replacement Time was logged. The unique alpha-numeric identifier of the user who was replaced. Using the example above, Steve Smith's UUID is listed in this column.
Custom Fields Additional columns for your custom fields. Custom field data is displayed in a comma-separated list. Custom fields are permission-based and only visible to specific roles. If you do not have the appropriate permission, the information is redacted and replaced with "<Restricted>".

Changes to shifts in progress

If you make changes to a shift after it's already started, the Historical On Call report includes those changes. When a shift is modified after it has started, the exported report contains all shift segment variations for the day the change is made.

Example

Your company has two shifts: a daily 9 - 5, Monday - Friday shift, and a 24 x 7 shift. On Wednesday a new escalation is added to both shifts at 11:30 am.

When you generate the Historical On Call report for the week on Friday night, the exported report shows:

  • For the 9 - 5 shift: The Monday and Tuesday entries are unchanged. For Wednesday, there are entries for the segments prior to the escalation change and separate entries for after the addition of the escalation.
  • For the 24 x 7 shift: There are no entries for Monday and Tuesday as a 24 x 7 shift without escalations is excluded from the report. On Wednesday, the exported report contains shift segments from both before and after the escalation is added.

Interpreting report data

The wealth of data included in an exported Historical On Call report can seem somewhat daunting. For tips on using pivot tables to correlate and parse the data in the report, see this helpful article on the xMatters Support site: Making the most of your Historical On Call report data