backstage

1
/*
2
 * Copyright 2020 The Backstage Authors
3
 *
4
 * Licensed under the Apache License, Version 2.0 (the "License");
5
 * you may not use this file except in compliance with the License.
6
 * You may obtain a copy of the License at
7
 *
8
 *     http://www.apache.org/licenses/LICENSE-2.0
9
 *
10
 * Unless required by applicable law or agreed to in writing, software
11
 * distributed under the License is distributed on an "AS IS" BASIS,
12
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
 * See the License for the specific language governing permissions and
14
 * limitations under the License.
15
 */
16

17
import {
18
  Entity,
19
  entityKindSchemaValidator,
20
  KindValidator,
21
} from '@backstage/catalog-model';
22
import { JsonObject } from '@backstage/types';
23
import schema from './Template.v1beta3.schema.json';
24

25
/**
26
 * Backstage catalog Template kind Entity. Templates are used by the Scaffolder
27
 * plugin to create new entities, such as Components.
28
 *
29
 * @public
30
 */
31
export interface TemplateEntityV1beta3 extends Entity {
32
  /**
33
   * The apiVersion string of the TaskSpec.
34
   */
35
  apiVersion: 'scaffolder.backstage.io/v1beta3';
36
  /**
37
   * The kind of the entity
38
   */
39
  kind: 'Template';
40
  /**
41
   * The specification of the Template Entity
42
   */
43
  spec: {
44
    /**
45
     * The type that the Template will create. For example service, website or library.
46
     */
47
    type: string;
48

49
    /**
50
     * Template specific configuration of the presentation layer.
51
     */
52
    presentation?: TemplatePresentationV1beta3;
53

54
    /**
55
     * Recovery strategy for the template
56
     */
57
    EXPERIMENTAL_recovery?: TemplateRecoveryV1beta3;
58

59
    /**
60
     * This is a JSONSchema or an array of JSONSchema's which is used to render a form in the frontend
61
     * to collect user input and validate it against that schema. This can then be used in the `steps` part below to template
62
     * variables passed from the user into each action in the template.
63
     */
64
    parameters?: TemplateParametersV1beta3 | TemplateParametersV1beta3[];
65
    /**
66
     * A list of steps to be executed in sequence which are defined by the template. These steps are a list of the underlying
67
     * javascript action and some optional input parameters that may or may not have been collected from the end user.
68
     */
69
    steps: Array<TemplateEntityStepV1beta3>;
70
    /**
71
     * The output is an object where template authors can pull out information from template actions and return them in a known standard way.
72
     */
73
    output?: { [name: string]: string };
74
    /**
75
     * The owner entityRef of the TemplateEntity
76
     */
77
    owner?: string;
78
  };
79
}
80

81
/**
82
 * Depends on how you designed your task you might tailor the behaviour for each of them.
83
 *
84
 * @public
85
 */
86
export interface TemplateRecoveryV1beta3 extends JsonObject {
87
  /**
88
   *
89
   * none - not recover, let the task be marked as failed
90
   * startOver - do recover, start the execution of the task from the first step.
91
   *
92
   * @public
93
   */
94
  EXPERIMENTAL_strategy?: 'none' | 'startOver';
95
}
96

97
/**
98
 * The presentation of the template.
99
 *
100
 * @public
101
 */
102
export interface TemplatePresentationV1beta3 extends JsonObject {
103
  /**
104
   * Overrides default buttons' text
105
   */
106
  buttonLabels?: {
107
    /**
108
     * The text for the button which leads to the previous template page
109
     */
110
    backButtonText?: string;
111
    /**
112
     * The text for the button which starts the execution of the template
113
     */
114
    createButtonText?: string;
115
    /**
116
     * The text for the button which opens template's review/summary
117
     */
118
    reviewButtonText?: string;
119
  };
120
}
121

122
/**
123
 * Step that is part of a Template Entity.
124
 *
125
 * @public
126
 */
127
export interface TemplateEntityStepV1beta3 extends JsonObject {
128
  id?: string;
129
  name?: string;
130
  action: string;
131
  input?: JsonObject;
132
  if?: string | boolean;
133
  'backstage:permissions'?: TemplatePermissionsV1beta3;
134
}
135

136
/**
137
 * Parameter that is part of a Template Entity.
138
 *
139
 * @public
140
 */
141
export interface TemplateParametersV1beta3 extends JsonObject {
142
  'backstage:permissions'?: TemplatePermissionsV1beta3;
143
}
144

145
/**
146
 *  Access control properties for parts of a template.
147
 *
148
 * @public
149
 */
150
export interface TemplatePermissionsV1beta3 extends JsonObject {
151
  tags?: string[];
152
}
153

154
const validator = entityKindSchemaValidator(schema);
155

156
/**
157
 * Entity data validator for {@link TemplateEntityV1beta3}.
158
 *
159
 * @public
160
 */
161
export const templateEntityV1beta3Validator: KindValidator = {
162
  // TODO(freben): Emulate the old KindValidator until we fix that type
163
  async check(data: Entity) {
164
    return validator(data) === data;
165
  },
166
};
167

168
/**
169
 * Typeguard for filtering entities and ensuring v1beta3 entities
170
 * @public
171
 */
172
export const isTemplateEntityV1beta3 = (
173
  entity: Entity,
174
): entity is TemplateEntityV1beta3 =>
175
  entity.apiVersion === 'scaffolder.backstage.io/v1beta3' &&
176
  entity.kind === 'Template';
177