--- /dev/null
+// Copyright 2018 Google LLC.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+syntax = "proto3";
+
+package google.cloud.irm.v1alpha2;
+
+import "google/api/annotations.proto";
+import "google/monitoring/v3/metric_service.proto";
+import "google/protobuf/duration.proto";
+import "google/protobuf/timestamp.proto";
+
+option cc_enable_arenas = true;
+option go_package = "google.golang.org/genproto/googleapis/cloud/irm/v1alpha2;irm";
+option java_multiple_files = true;
+option java_package = "com.google.irm.service.v1alpha2.api";
+
+// A user of the IRM app.
+message User {
+ // One of several ways to uniquely identify a user.
+ oneof user {
+ // Output only. User id that will allow to get additional information from
+ // People API. This field will be populated implicitly if the caller creates
+ // or edits a resource (for example, posts an annotation).
+ string user_id = 1;
+
+ // Email address of the user. This must be associated with a Google account.
+ // This field will be set if the user is explicitly identified (verbatim) by
+ // email address in an API request (potentially sometime in the past). It
+ // will not be populated based on the credentials of a caller of the API.
+ string email = 2;
+ }
+}
+
+// A signal is a message calling attention to a (potential) incident. An example
+// is a page based on a Stackdriver Alerting policy.
+message Signal {
+ // An artifact associated with the Signal.
+ message SignalArtifact {
+ // The type of resource linked to
+ oneof artifact_type {
+ // A custom user type
+ string user_type = 2;
+ }
+
+ // The URI for the artifact.
+ string uri = 3;
+ }
+
+ // Describes whether the alerting condition is still firing.
+ enum State {
+ // Unspecified
+ STATE_UNSPECIFIED = 0;
+
+ // Firing
+ STATE_OPEN = 1;
+
+ // Non-firing
+ STATE_CLOSED = 2;
+ }
+
+ // Resource name of the signal, for example,
+ // "projects/{project_id}/signals/{signal_id}".
+ string name = 1;
+
+ // Etag to validate the object is unchanged for a read-modify-write operation.
+ // An empty etag will overwrite other changes.
+ string etag = 2;
+
+ // Resource name of the incident this signal is currently assigned to.
+ // May be empty if signal is unassigned.
+ string incident = 3;
+
+ // Output only. Time this signal was created.
+ google.protobuf.Timestamp create_time = 4;
+
+ // Output only. Time this signal was closed. This field is not populated
+ // while the signal is still firing.
+ google.protobuf.Timestamp close_time = 10;
+
+ // The time this Signal was first detected. This is identical to create_time
+ // for Signals created by Stackdriver Alerting.
+ google.protobuf.Timestamp detect_time = 15;
+
+ // Output only. The user that created this signal for manually created
+ // signals. Empty if this signal was generated by a system (for example,
+ // Stackdriver Alerting).
+ User creator = 5;
+
+ // One-line summary of the signal.
+ // Immutable.
+ string title = 6;
+
+ // Content type string, for example, 'text/plain' or'text/html'.
+ string content_type = 7;
+
+ // Full message of the signal.
+ // Immutable for Signals created by Stackdriver Alerting.
+ string content = 8;
+
+ // The state of this signal.
+ // For Signals created by Stackdriver Alerting this field is output only.
+ State signal_state = 9;
+
+ // A set of artifacts to additional resources for this Signal. For example, a
+ // link to Stackdriver logging for the Signal.
+ // Immutable for Signals created by Stackdriver Alerting.
+ repeated SignalArtifact signal_artifacts = 16;
+}
+
+// A text annotation by a user.
+message Annotation {
+ // Resource name of the annotation, for example,
+ // "projects/{project_id}/incidents/{incident_id}/annotations/{annotation_id}".
+ string name = 1;
+
+ // Output only. Author of the annotation.
+ User author = 2;
+
+ // Output only. Time the annotation was created.
+ google.protobuf.Timestamp create_time = 3;
+
+ // Content of the annotation. Immutable.
+ string content = 4;
+}
+
+// A tag by a user.
+message Tag {
+ // Resource name of a tag, for example,
+ // "projects/{project_id}/incidents/{incident_id}/tags/{tag_id}"
+ string name = 1;
+
+ // Display name of the resource (for example, "cause:rollout"). Immutable.
+ string display_name = 2;
+}
+
+// Synopsis is a summary of an incident and it contains a textual content,
+// an author and a last updated timestamp.
+message Synopsis {
+ // Content type string, for example, 'text/plain' or 'text/html'.
+ string content_type = 1;
+
+ // Textual content of the synopsis. It can be plain text or markdown as
+ // indicated by the content_type.
+ string content = 2;
+
+ // Last updated timestamp.
+ google.protobuf.Timestamp update_time = 3;
+
+ // Author of the synopsis.
+ User author = 4;
+}
+
+// Representation of an incident.
+message Incident {
+ // CommunicationVenue is a record of where conversations about an incident
+ // are happening.
+ message CommunicationVenue {
+ // The type of channel/venue for incident communications.
+ enum ChannelType {
+ // An unspecified communication channel.
+ CHANNEL_TYPE_UNSPECIFIED = 0;
+
+ // A communication channel that is represented by a generic URI.
+ CHANNEL_TYPE_URI = 1;
+
+ // A communication channel that represents a Slack channel.
+ CHANNEL_TYPE_SLACK = 5;
+ }
+
+ // A URI to the web interface of the channel.
+ string uri = 1;
+
+ // A name representing the channel in IRM UI.
+ string display_name = 2;
+
+ // The type of channel/venue for incident communications.
+ ChannelType channel_type = 3;
+ }
+
+ // Specifies the escalation level of this incident, within the IRM protocol
+ // for handling incidents.
+ enum EscalationLevel {
+ // The incident has not been escalated. This is the value used by all new
+ // and legacy incidents.
+ ESCALATION_LEVEL_UNSPECIFIED = 0;
+
+ // The incident has been escalated to the organizational level.
+ ESCALATION_LEVEL_ORGANIZATION = 1;
+ }
+
+ // Severity of an incident.
+ enum Severity {
+ // Severity is not specified.
+ SEVERITY_UNSPECIFIED = 0;
+
+ // Huge incident.
+ SEVERITY_HUGE = 1;
+
+ // Major incident.
+ SEVERITY_MAJOR = 2;
+
+ // Medium incident.
+ SEVERITY_MEDIUM = 3;
+
+ // Minor incident.
+ SEVERITY_MINOR = 4;
+
+ // Negligible incident.
+ SEVERITY_NEGLIGIBLE = 5;
+ }
+
+ // Stage of an incident.
+ enum Stage {
+ // This is the default value if no stage has been specified.
+ // Note: The caller of the API should set the stage to DETECTED.
+ STAGE_UNSPECIFIED = 0;
+
+ // The incident has been detected. This is the initial stage of a new
+ // incident.
+ // Note: The caller still has to set the stage manually.
+ STAGE_DETECTED = 4;
+
+ // This incident has been formally characterized.
+ STAGE_TRIAGED = 1;
+
+ // This incident has been mitigated, i.e. does not affect the service level
+ // anymore.
+ STAGE_MITIGATED = 2;
+
+ // This incident has been fully resolved, i.e. there are no immediate
+ // follow-up tasks.
+ STAGE_RESOLVED = 3;
+
+ // Postmortem for the incident was written.
+ STAGE_DOCUMENTED = 5;
+
+ // Stage for an incident with `duplicate_incident`. This incident is not
+ // authoritative anymore and the `duplicate_incident` should be used to
+ // determine the stage.
+ STAGE_DUPLICATE = 6;
+ }
+
+ // Output only. Resource name of the incident, for example,
+ // "projects/{project_id}/incidents/{incident_id}".
+ string name = 1;
+
+ // One-line summary of the incident.
+ string title = 2;
+
+ // Escalation level of the incident.
+ EscalationLevel escalation_level = 3;
+
+ // Etag to validate the object is unchanged for a read-modify-write operation.
+ // An empty etag will overwrite other changes.
+ string etag = 4;
+
+ // Severity of the incident.
+ Severity severity = 5;
+
+ // Stage of the incident.
+ Stage stage = 6;
+
+ // Resource name of the incident this incident is a duplicate of. Empty if
+ // this incident is not a duplicate.
+ // An incident can only be a duplicate of an incident that is not marked as a
+ // duplicate already. Setting this to a non-empty value must also set the
+ // stage to `STAGE_DUPLICATE`. Unsetting this value value must also update
+ // `stage` to a value other than `STAGE_DUPLICATE`.
+ string duplicate_incident = 9;
+
+ // Output only. Time this incident started. Used to measure the 'elapsed
+ // time'. Start time of an incident is the earliest creation time of any of
+ // its Signals or the create time of the incident if no Signals are assigned.
+ google.protobuf.Timestamp start_time = 7;
+
+ // Output only. Synopsis of this incident.
+ Synopsis synopsis = 8;
+
+ // Location of communications for this incident. This is informational
+ // only; IRM does not use this to send messages.
+ CommunicationVenue communication_venue = 10;
+}
+
+// Describes a role that can be assigned to an incident.
+message IncidentRole {
+ // List of possible roles.
+ enum Type {
+ // The role is unspecified.
+ TYPE_UNSPECIFIED = 0;
+
+ // Incident Commander: Manages response plan, near-term and long-term
+ // objectives, establishes priorities, and delegates tasks as needed.
+ TYPE_INCIDENT_COMMANDER = 1;
+
+ // Communications Lead: Keeps everybody outside and within the response team
+ // informed.
+ TYPE_COMMUNICATIONS_LEAD = 2;
+
+ // Operations Lead: Figures out what to do, and gets it done.
+ TYPE_OPERATIONS_LEAD = 3;
+
+ // External Customer Communications Lead: Responsible for communicating
+ // incident details to customers/public.
+ TYPE_EXTERNAL_CUSTOMER_COMMUNICATIONS_LEAD = 4;
+
+ // Primary Oncall: Responds to the initial page and handles all
+ // responsibilities for pre-escalated incidents.
+ TYPE_PRIMARY_ONCALL = 5;
+
+ // Secondary Oncall: Helps the primary oncall if necessary; mostly useful
+ // for pre-escalated incidents.
+ TYPE_SECONDARY_ONCALL = 6;
+
+ // User-specified roles. One example is a Planning Lead, who keeps track of
+ // the incident. Another is an assistant Incident Commander.
+ TYPE_OTHER = 7;
+ }
+
+ // The type of role. The role type is immutable in role assignments. Each role
+ // type can only be used once per incident, except for TYPE_OTHER.
+ Type type = 1;
+
+ // Output only unless TYPE_OTHER is used. Title of the role. For TYPE_OTHER,
+ // must be unique within an incident.
+ string title = 2;
+
+ // Output only unless TYPE_OTHER is used. Description of the role.
+ string description = 3;
+}
+
+// Stores the assignee of a role as well as the proposed next assignee.
+message IncidentRoleAssignment {
+ // Output only. Resource name such as
+ // "projects/{project_id}/incidents/{incident_id}/role_assignments/{role_id}".
+ string name = 1;
+
+ // Output only. Etag for this version of the resource. Must be specified in
+ // update requests and match the current version in storage. Must not be
+ // modified by the client.
+ string etag = 2;
+
+ // The role that is or will be assigned.
+ IncidentRole role = 3;
+
+ // The user this role is assigned to. This field can only be directly set
+ // during creation request. Subsequent updates are done via the
+ // IncidentRoleHandover methods.
+ User assignee = 4;
+
+ // The recipient of a requested role handoff. This field can only be directly
+ // set during creation request. Subsequent updates are done via the
+ // IncidentRoleHandover methods.
+ //
+ // `assignee` is always the current role-holder, and `proposed_assignee` is
+ // used to track unfinished assignments and handoffs. Let's say Bob assigns
+ // Alice to a role. Then the fields are:
+ // `assignee`: nil, `proposed_assignee`: Alice
+ // If Alice accepts, then the fields are:
+ // `assignee`: Alice, `proposed_assignee`: nil
+ // If she cancels, then the RoleAssignment is deleted.
+ // Let's say Alice has the role. Then the fields are:
+ // `assignee`: Alice, `proposed_assignee`: nil
+ // If Alice becomes incapacitated and Bob requests Carol to take over, then
+ // the fields are:
+ // `assignee`: Alice, `proposed_assignee`: Carol
+ // After Carol accepts the handover, the fields are:
+ // `assignee`: Carol, `proposed_assignee`: nil
+ // Or if Carol refuses the handover, the fields are:
+ // `assignee`: Alice, `proposed_assignee`: nil
+ User proposed_assignee = 5;
+}
+
+// External artifact associated to an incident.
+message Artifact {
+ // Possible types of an artifact.
+ enum Type {
+ // External type is unspecified.
+ TYPE_UNSPECIFIED = 0;
+
+ // URL.
+ TYPE_URL = 1;
+
+ // A JIRA issue.
+ TYPE_JIRA_ISSUE = 4;
+ }
+
+ // Output only. Resource name such as
+ // "projects/{project_id}/incidents/{incident_id}/artifacts/{artifact_id}".
+ string name = 1;
+
+ // User provided name of an artifact.
+ string display_name = 2;
+
+ // Output only. Etag for this version of the resource. Must be specified in
+ // update requests and match the current version in storage. Must not be
+ // modified by the client.
+ string etag = 3;
+
+ // URL to access the artifact.
+ string url = 4;
+
+ // Type of this artifact.
+ Type type = 5;
+}
+
+// Communication Channels are mechanisms used to receive notifications
+// about changes to incidents.
+message CommunicationChannel {
+ // A communication channel that delivers messages to an email address.
+ message Email {
+ // The email address, for example, "user@example.com".
+ string address = 1;
+ }
+
+ // A communication channel that delivers messages to a Stackdriver
+ // notification channel.
+ message NotificationChannel {
+ // Stackdriver notification channel name.
+ string name = 1;
+ }
+
+ // An endpoint describes how messages will be delivered.
+ oneof endpoint {
+ // Messages will be delivered via email.
+ Email email = 1;
+
+ // Messages will be delivered via a Stackdriver notification channel.
+ NotificationChannel notification_channel = 2;
+ }
+}
+
+// A subscription allows users to get notifications about changes to
+// an incident.
+message Subscription {
+ // Types of changes that users can subscribe to in an incident.
+ enum EventType {
+ // An event_type that's not specified is an error.
+ EVENT_TYPE_UNSPECIFIED = 0;
+
+ // The incident's title has changed.
+ EVENT_TYPE_TITLE_CHANGE = 1;
+
+ // The incident's synopsis has changed.
+ EVENT_TYPE_SYNOPSIS_CHANGE = 2;
+
+ // The incident's stage has changed.
+ EVENT_TYPE_STAGE_CHANGE = 3;
+
+ // The incident's severity has changed.
+ EVENT_TYPE_SEVERITY_CHANGE = 4;
+
+ // A new annotation has been added to the incident.
+ EVENT_TYPE_ANNOTATION_ADD = 5;
+
+ // An annotation has been modified.
+ EVENT_TYPE_ANNOTATION_CHANGE = 6;
+ }
+
+ // Output only. Resource name such as
+ // "projects/{project_id}/incidents/{incident_id}/subscriptions/{subscription_id}".
+ string name = 1;
+
+ // Output only. Etag for this version of the resource. Must be specified in
+ // update requests and match the current version in storage. Must not be
+ // modified by the client.
+ string etag = 2;
+
+ // A communications channel to send subscription messages to.
+ CommunicationChannel subscription_channel = 3;
+
+ // Types of events this subscription receives notifications for.
+ repeated EventType event_types = 4;
+}