oncall

package
v0.15.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 24, 2026 License: AGPL-3.0 Imports: 10 Imported by: 0

Documentation

Overview

Package oncall provides a typed client and data transformation layer for the Grafana OnCall OSS HTTP API (v1). It is used exclusively by the one-time migration import flow; it does not maintain any persistent state.

Index

Constants

View Source 
const (
	StepTypeWait                     = "wait"
	StepTypeNotifyPersons            = "notify_persons"
	StepTypeNotifyPersonNextEachTime = "notify_person_next_each_time"
	StepTypeNotifyOnCallFromSchedule = "notify_on_call_from_schedule"
	StepTypeNotifyWholedTeam         = "notify_whole_channel"
	StepTypeResolveIncident          = "resolve_incident"
)

OnCall escalation step type constants.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is a minimal, typed HTTP client for the Grafana OnCall OSS API v1. Construct one with NewClient; it is safe for concurrent use after construction.

func NewClient 

func NewClient(baseURL, apiToken string) *Client

NewClient creates a new OnCall API client. baseURL must be the root of the Grafana/OnCall instance (no trailing slash required). apiToken is the Grafana OnCall API key prefixed with "Token ".

func (*Client) ListEscalationChains 

func (c *Client) ListEscalationChains() ([]OnCallEscalationChain, error)

ListEscalationChains returns all escalation chains from GET /api/v1/escalation_chains.

func (*Client) ListEscalationSteps 

func (c *Client) ListEscalationSteps() ([]OnCallEscalationStep, error)

ListEscalationSteps returns all escalation policy steps from GET /api/v1/escalation_policies. Steps are returned flat and must be grouped by EscalationChain.ID in the caller.

func (*Client) ListIntegrations 

func (c *Client) ListIntegrations() ([]OnCallIntegration, error)

ListIntegrations returns all integrations from GET /api/v1/integrations.

func (*Client) ListSchedules 

func (c *Client) ListSchedules() ([]OnCallSchedule, error)

ListSchedules returns all schedules from GET /api/v1/schedules.

func (*Client) ListShifts 

func (c *Client) ListShifts() ([]OnCallShift, error)

ListShifts returns all on-call shifts from GET /api/v1/on_call_shifts.

func (*Client) ListTeams 

func (c *Client) ListTeams() ([]OnCallTeam, error)

ListTeams returns all teams from GET /api/v1/teams.

func (*Client) ListUsers 

func (c *Client) ListUsers() ([]OnCallUser, error)

ListUsers returns all users from GET /api/v1/users, paginating automatically.

func (*Client) Ping 

func (c *Client) Ping() error

Ping validates the URL and API token by calling GET /api/v1/users with a page size of 1. Returns a descriptive error on auth failure or unreachable host.

type ConflictItem 

type ConflictItem struct {
	Type   string `json:"type"` // "user", "schedule", "escalation_policy"
	Name   string `json:"name"`
	Reason string `json:"reason"` // human-readable reason
}

ConflictItem describes an entity that already exists in Regen and will be skipped rather than overwritten during import.

type ImportPreview 

type ImportPreview struct {
	Users              []models.User             `json:"users"`
	Schedules          []models.Schedule         `json:"schedules"`
	EscalationPolicies []models.EscalationPolicy `json:"escalation_policies"`
	Webhooks           []WebhookMapping          `json:"webhooks"`
	Conflicts          []ConflictItem            `json:"conflicts"`
	Skipped            []SkippedItem             `json:"skipped"`
}

ImportPreview is the complete dry-run result: what would be created plus any conflicts or items that will be skipped.

func TransformAll 

func TransformAll(
	ocUsers []OnCallUser,
	ocSchedules []OnCallSchedule,
	ocShifts []OnCallShift,
	ocChains []OnCallEscalationChain,
	ocSteps []OnCallEscalationStep,
	ocIntegrations []OnCallIntegration,
	existingEmails map[string]bool,
	existingScheduleNames map[string]bool,
	existingPolicyNames map[string]bool,
	baseURL string,
) ImportPreview

TransformAll runs the full transformation pipeline on raw OnCall API data. existingEmails, existingScheduleNames, and existingPolicyNames are sets of names/emails already present in Regen (used for conflict detection). baseURL is the Regen instance base URL used to generate new webhook URLs.

type OnCallEscalationChain 

type OnCallEscalationChain struct {
	ID   string `json:"id"`
	Name string `json:"name"`
	Team string `json:"team"` // team ID, may be empty
}

OnCallEscalationChain represents a chain returned by GET /api/v1/escalation_chains.

type OnCallEscalationStep 

type OnCallEscalationStep struct {
	ID              string   `json:"id"`
	Step            int      `json:"step"`                             // 0-based position within the chain
	EscalationChain string   `json:"escalation_chain"`                 // parent chain ID
	Type            string   `json:"type"`                             // see step type constants below
	Duration        *int     `json:"duration"`                         // seconds; only set for "wait" steps
	PersonsToNotify []string `json:"persons_to_notify"`                // user IDs
	PersonsNextTime []string `json:"persons_to_notify_next_each_time"` // user IDs
	Schedule        string   `json:"schedule"`                         // schedule ID; for notify_on_call_from_schedule
}

OnCallEscalationStep represents a single step within a chain, returned by GET /api/v1/escalation_policies (the OnCall API calls these "policies").

type OnCallIntegration 

type OnCallIntegration struct {
	ID   string `json:"id"`
	Name string `json:"name"`
	Type string `json:"type"` // "alertmanager", "grafana", "cloudwatch", "generic", etc.
	Link string `json:"link"` // existing OnCall inbound webhook URL
	Team string `json:"team"` // team ID, may be empty
}

OnCallIntegration represents a webhook integration returned by GET /api/v1/integrations.

type OnCallSchedule 

type OnCallSchedule struct {
	ID       string   `json:"id"`
	Name     string   `json:"name"`
	Type     string   `json:"type"`      // "web", "ical", "calendar"
	TimeZone string   `json:"time_zone"` // IANA timezone
	Shifts   []string `json:"shifts"`    // IDs of on-call shifts
	Team     string   `json:"team"`      // team ID, may be empty
}

OnCallSchedule represents a schedule returned by GET /api/v1/schedules.

type OnCallShift 

type OnCallShift struct {
	ID            string     `json:"id"`
	Name          string     `json:"name"`
	Type          string     `json:"type"`           // "rolling_users", "recurrent_event", "override"
	TimeZone      string     `json:"time_zone"`      // may be empty — falls back to schedule timezone
	Level         int        `json:"level"`          // layer index (0 = primary)
	Start         string     `json:"start"`          // ISO 8601 datetime
	RotationStart string     `json:"rotation_start"` // ISO 8601 datetime; epoch of rotation
	Duration      int        `json:"duration"`       // seconds per shift slot
	Frequency     string     `json:"frequency"`      // "weekly", "daily", "hourly", "monthly"
	Interval      int        `json:"interval"`       // repeat every N frequency units
	ByDay         []string   `json:"by_day"`         // e.g. ["MO","WE","FR"]
	RollingUsers  [][]string `json:"rolling_users"`  // groups of user IDs cycling through
	Users         []string   `json:"users"`          // fixed user IDs for non-rolling shifts
	Team          string     `json:"team"`           // team ID, may be empty
}

OnCallShift represents a rotation shift returned by GET /api/v1/on_call_shifts. OnCall models every layer of a schedule as a "shift" object.

type OnCallSlackRef 

type OnCallSlackRef struct {
	UserID string `json:"user_id"`
	Name   string `json:"name"`
}

OnCallSlackRef holds the Slack identity embedded in some OnCall objects.

type OnCallTeam 

type OnCallTeam struct {
	ID   string `json:"pk"`
	Name string `json:"name"`
}

OnCallTeam represents a team returned by GET /api/v1/teams.

type OnCallUser 

type OnCallUser struct {
	ID       string          `json:"pk"`
	Email    string          `json:"email"`
	Username string          `json:"username"`
	Name     string          `json:"name"` // may be empty; fall back to Username
	Role     string          `json:"role"` // "admin", "user", "viewer"
	Slack    *OnCallSlackRef `json:"slack"`
}

OnCallUser represents a user returned by GET /api/v1/users.

type SkippedItem 

type SkippedItem struct {
	Type   string `json:"type"`
	Name   string `json:"name"`
	Reason string `json:"reason"`
}

SkippedItem describes an entity from OnCall that was intentionally not imported (e.g. unsupported type or empty data).

type WebhookMapping 

type WebhookMapping struct {
	Name        string `json:"name"`
	OnCallType  string `json:"oncall_type"`  // original OnCall integration type
	OldURL      string `json:"old_url"`      // previous OnCall inbound URL
	NewURL      string `json:"new_url"`      // new Regen webhook URL
	RegenSource string `json:"regen_source"` // "prometheus","grafana","cloudwatch","generic"
}

WebhookMapping describes an OnCall integration and the corresponding Regen webhook URL the user should point their monitoring tool at.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.