Switch to RotaNG.

This document describes the steps needed to switch over from the cron/python based rotation generator to the new RotaNG service.

See Design Doc for further information.

Switch a rotation to the RotaNG service.

Create/Import a Rotation

Browse to (https://rota-ng-staging.googleplex.com/).

From here you have a few options on how to create a rotation.

  • It's already in there!.

    • If when following the Manage rotations link you can see your rotation it was already imported.

      Continue to next step.

  • If your rotation does show up when following the List configurations in backend store but not in Manage rotations it‘s probably b/c you’re not part of the owners of the rotation.

    Drop a mail to olakar@chromium.org to have this sorted.

  • Your rotation is not in List configurations in backend store.

    • Either Create a new rotation from scratch.

      Choose Create new rotation from the Manage rotation page.

    • Or Import rotation from a configuration file.

      Follow the link Upload Legacy JSON rota configuration to upload and convert.

Configure a Rotation

  • If your rotation already existed press the modify button.

You should now be looking at a form with the following fields.

  • Rotation Name

    If you're modifying a rotation this field can not be changed due to it being used as the key in the backend storage. To rename a rotation you need to delete the rotation and create a new one with the desired name.

    This field is also used when creating calendar entries.

  • Description

    Describes the rotation. Also used for the summary of calendar events. See the Email templates for more information about how to fill out this field.

  • Calendar

    This should contain the id of the team shared calendar.

    Eg. google.com_d3itj7r696lolrs39d0to7rtjc@group.calendar.google.com

    To give the rotation service the rights to read/modify the team calendar you need to share the calendar with the rota service account. rota-ng-staging.google.com@appspot.gserviceaccount.com.

    CalShare

  • Owners

    A comma separated list of rotation owners.

    Note: This will be changed to use mdb groups shortly

  • Expiration

    This specifies when to automatically schedule new shifts. Setting this to 0 gives no automatic shifts will be scheduled.

    Note: Nothing will be scheduled before the rotation is enabled

  • Shifts To Schedule

    Defines how many shifts to be scheduled when Expired.

  • Email Subject Template

    The subject of the emails sent from the rotation service to upcoming oncallers.

    This uses Go templates to generated the final message.

    The structures used to feed the template looks like this.

    type Info struct {
  RotaName    string
  ShiftConfig ShiftConfig
  ShiftEntry  ShiftEntry
  Member      Member
  MemberURL   string
}

type ShiftConfig struct {
  // StartTime represents the start-time of the first shift.
  // Only the Time of day is considered.
  // Defaults to 00:00 PDT.
  StartTime time.Time
  // Length sets the number of days a shift lasts.
  Length int
  // Skip defines a number of days with no oncalls.
  Skip int
  // Shifts represents the shifts over a 24hour period.
  Shifts []Shift
  // ShiftMembers specifides number of members per shift.
  ShiftMembers int
  // Generator used to schedule new shifts.
  Generator string
}

type ShiftEntry struct {
  // Name of the Shift this entry belongs to.
  Name string
  // OnCall are the members on-call for this shift.
  OnCall    []ShiftMember
  StartTime time.Time
  EndTime   time.Time
  // Comment is an optional comment where the rota algo
  // can add some extra information.
  Comment string
  // EvtID can be used to match an event to a calendar event.
  EvtID string
}

type Member struct {
  Name        string
  Email       string
  TZ          time.Location
  OOO         []OOO
  Preferences []Preference
}

    This gives that you can have any information from the Info struct inserted in your message.

    Eg.

    Upcoming On-call shift for rotation: \{\{.RotaName\}\} \{\{.ShiftEntry.StartTime.In .Member.TZ\}\} to \{\{.ShiftEntry.EndTime.In .Member.TZ\}\}

    Will produce:

    Upcoming On-call shift for rotation: Name of rota 2006-04-05 17:00:00 -0700 PDT to 2006-04-06 17:00:00 -0700 PDT

    For a member with a US Pacific TZ.

    Note: The current %s format replacement will not work. You could replace the %s with {{.RotaName}} for something similar.

  • Email Body Template

    See Email Subject Template.

  • Email Days Before Notify

    Number of days before an on-call shift to send mails out.

    Note: No mails will be produced until the rotation is enabled.

  • Members

    Manage members of the rotation.

  • Shift StartTime

    Specifies the start in MTV time of the first shift.

  • Length

    Number of days a shift spans.

  • Skip

    Skip in the shift schedule. Eg. if you rotation is weekdays only you'd set this to Length/Skip: 5/2

  • ShiftMembers

    Number of members to schedule per shift.

  • Generator

    Specifies what Generator to use when scheduling shifts

    • Fair

      Takes previous shifts into account when scheduling shifts. If there are no previous shifts it'll fall back to random.

    • Random

    • Legacy

      Tries to emulate the current scheduler.

  • Shifts

    The service supports split shifts so you can have follow the sun kind of configurations with MTV -> SYD -> EU.

    This would be configured as 3 shifts.

    Name: MTV OnCall  Duration: 8
Name: SYD OnCall  Duration: 8
Name: EU OnCall   Duration: 8

    When scheduling the RotaMembers ShiftsName would be used to figure out which users to put into which shift.

    It's also OK to have empty splits Eg.

    Name: MTV Office      Duration: 6
Name: MTV->SYD no-one Duration: 2
Name: SYD Office      Duration: 6
Name: SYD->EU no-one  Duration: 2
Name: EU Office       Duration: 6
Name: EU->MTV no-one  Duration: 2

    The calendar entries created will have the Shift name added to the description.

    Note: The sum of the shift durations should always be 24

Import shifts from current calendar.

With rota-ng-staging.google.com@appspot.gserviceaccount.com permissions added to the shared calendar we can import the current rotations.

  • Go back to the Shift Management page.
  • Press the import button.
  • You should now see a list of current shifts.
  • If all looks good click Submit Shifts to have them imported.

Mange shifts

  • Go back to the Shift Management page.

  • Click the Shifts button.

  • Shift History

    • Shows the shift history.

  • Current Shifts

    Contains current shifts. From here you can modify who's oncall for the different shifts.

    Note: The down arrow will remove all shifts from the pressed one. Note: Nothing is saved to backend storage until you click Update Shifts

  • Generate Shifts

    As default Generate will generate new shifts after the last shift in store using the configuration values for number of shifts and the Fair generator.

    Note: When setting the StartDate and having skip configured , make sure the date is on a Monday Note: Nothing is saved until you press Submit

  1. Start using the new service.

To switch over to the new service you do the following.

  • Remove the legacy json configuration.

    Without this step the oncallers will get duplicate emails for upcoming shifts.

  • Enable the rotation in the Manage rotations section.

FAQ

  • The interface looks like something from the early 90s ..

    Yes this was probably the last time I touched HTML so I've had quite a bit of rust to remove off of my frontend skillz. This is rapidly getting improved though with the help of the ChOps Frontend team.

  • What about go/chromecals allshifts.txt etc.

    I'm currently working on getting all the users of those sources switched over to the new service. b/889221

  • Bugs

    File bugs in component:Infra>Sheriffing>Rotations and assign to: olakar@chromium.org