1import { Observable } from 'rxjs';
2import { ComponentType } from 'react';
3
4import { QueryEditorProps } from './datasource';
5import { DataFrame } from './dataFrame';
6import { DataQuery, DataSourceRef } from './query';
7
8/**
9 * This JSON object is stored in the dashboard json model.
10 */
11export interface AnnotationQuery<TQuery extends DataQuery = DataQuery> {
12  datasource?: DataSourceRef | string | null;
13
14  enable: boolean;
15  name: string;
16  iconColor: string;
17  hide?: boolean;
18  builtIn?: number;
19  type?: string;
20  snapshotData?: any;
21
22  // Standard datasource query
23  target?: TQuery;
24
25  // Convert a dataframe to an AnnotationEvent
26  mappings?: AnnotationEventMappings;
27
28  // Sadly plugins can set any propery directly on the main object
29  [key: string]: any;
30}
31
32export interface AnnotationEvent {
33  id?: string;
34  annotation?: any;
35  dashboardId?: number;
36  panelId?: number;
37  userId?: number;
38  login?: string;
39  email?: string;
40  avatarUrl?: string;
41  time?: number;
42  timeEnd?: number;
43  isRegion?: boolean;
44  title?: string;
45  text?: string;
46  type?: string;
47  tags?: string[];
48  color?: string;
49  alertId?: number;
50  newState?: string;
51
52  // Currently used to merge annotations from alerts and dashboard
53  source?: any; // source.type === 'dashboard'
54}
55
56export interface AnnotationEventUIModel {
57  id?: string;
58  from: number;
59  to: number;
60  tags: string[];
61  description: string;
62}
63
64/**
65 * @alpha -- any value other than `field` is experimental
66 */
67export enum AnnotationEventFieldSource {
68  Field = 'field', // Default -- find the value with a matching key
69  Text = 'text', // Write a constant string into the value
70  Skip = 'skip', // Do not include the field
71}
72
73export interface AnnotationEventFieldMapping {
74  source?: AnnotationEventFieldSource; // defaults to 'field'
75  value?: string;
76  regex?: string;
77}
78
79export type AnnotationEventMappings = Partial<Record<keyof AnnotationEvent, AnnotationEventFieldMapping>>;
80
81/**
82 * Since Grafana 7.2
83 *
84 * This offers a generic approach to annotation processing
85 */
86export interface AnnotationSupport<TQuery extends DataQuery = DataQuery, TAnno = AnnotationQuery<TQuery>> {
87  /**
88   * This hook lets you manipulate any existing stored values before running them though the processor.
89   * This is particularly helpful when dealing with migrating old formats.  ie query as a string vs object
90   */
91  prepareAnnotation?(json: any): TAnno;
92
93  /**
94   * Convert the stored JSON model to a standard datasource query object.
95   * This query will be executed in the datasource and the results converted into events.
96   * Returning an undefined result will quietly skip query execution
97   */
98  prepareQuery?(anno: TAnno): TQuery | undefined;
99
100  /**
101   * When the standard frame > event processing is insufficient, this allows explicit control of the mappings
102   */
103  processEvents?(anno: TAnno, data: DataFrame[]): Observable<AnnotationEvent[] | undefined>;
104
105  /**
106   * Specify a custom QueryEditor for the annotation page.  If not specified, the standard one will be used
107   */
108  QueryEditor?: ComponentType<QueryEditorProps<any, TQuery>>;
109}
110