backstage

1
/*
2
 * Copyright 2021 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 type { EntityMeta, UserEntity } from '@backstage/catalog-model';
18
import type { JsonArray, JsonObject, JsonValue } from '@backstage/types';
19

20
/**
21
 * Information about a template that is stored on a task specification.
22
 * Includes a stringified entityRef, and the baseUrl which is usually the relative path of the template definition
23
 *
24
 * @public
25
 */
26
export type TemplateInfo = {
27
  /**
28
   * The entityRef of the template
29
   */
30
  entityRef: string;
31
  /**
32
   * Where the template is stored, so we can resolve relative paths for things like `fetch:template` paths.
33
   */
34
  baseUrl?: string;
35

36
  /**
37
   * the Template entity
38
   */
39
  entity?: {
40
    /**
41
     * The metadata of the Template
42
     */
43
    metadata: EntityMeta;
44
  };
45
};
46

47
/**
48
 *
49
 * none - not recover, let the task be marked as failed
50
 * startOver - do recover, start the execution of the task from the first step.
51
 *
52
 * @public
53
 */
54
export type TaskRecoverStrategy = 'none' | 'startOver';
55

56
/**
57
 * When task didn't have a chance to complete due to system restart you can define the strategy what to do with such tasks,
58
 * by defining a strategy.
59
 *
60
 * By default, it is none, what means to not recover but updating the status from 'processing' to 'failed'.
61
 *
62
 * @public
63
 */
64
export interface TaskRecovery {
65
  /**
66
   * Depends on how you designed your task you might tailor the behaviour for each of them.
67
   */
68
  EXPERIMENTAL_strategy?: TaskRecoverStrategy;
69
}
70

71
/**
72
 * An individual step of a scaffolder task, as stored in the database.
73
 *
74
 * @public
75
 */
76
export interface TaskStep {
77
  /**
78
   * A unique identifier for this step.
79
   */
80
  id: string;
81
  /**
82
   * A display name to show the user.
83
   */
84
  name: string;
85
  /**
86
   * The underlying action ID that will be called as part of running this step.
87
   */
88
  action: string;
89
  /**
90
   * Additional data that will be passed to the action.
91
   */
92
  input?: JsonObject;
93
  /**
94
   * When this is false, or if the templated value string evaluates to something that is falsy the step will be skipped.
95
   */
96
  if?: string | boolean;
97
  /**
98
   * Run step repeatedly
99
   */
100
  each?: string | JsonArray;
101
}
102

103
/**
104
 * A scaffolder task as stored in the database, generated from a v1beta3
105
 * apiVersion Template.
106
 *
107
 * @public
108
 */
109
export interface TaskSpecV1beta3 {
110
  /**
111
   * The apiVersion string of the TaskSpec.
112
   */
113
  apiVersion: 'scaffolder.backstage.io/v1beta3';
114
  /**
115
   * This is a JSONSchema which is used to render a form in the frontend
116
   * to collect user input and validate it against that schema. This can then be used in the `steps` part below to template
117
   * variables passed from the user into each action in the template.
118
   */
119
  parameters: JsonObject;
120
  /**
121
   * A list of steps to be executed in sequence which are defined by the template. These steps are a list of the underlying
122
   * javascript action and some optional input parameters that may or may not have been collected from the end user.
123
   */
124
  steps: TaskStep[];
125
  /**
126
   * The output is an object where template authors can pull out information from template actions and return them in a known standard way.
127
   */
128
  output: { [name: string]: JsonValue };
129
  /**
130
   * Some information about the template that is stored on the task spec.
131
   */
132
  templateInfo?: TemplateInfo;
133
  /**
134
   * Some decoration of the author of the task that should be available in the context
135
   */
136
  user?: {
137
    /**
138
     * The decorated entity from the Catalog
139
     */
140
    entity?: UserEntity;
141
    /**
142
     * An entity ref for the author of the task
143
     */
144
    ref?: string;
145
  };
146
  /**
147
   * How to recover the task after system restart or system crash.
148
   */
149
  EXPERIMENTAL_recovery?: TaskRecovery;
150
}
151

152
/**
153
 * A scaffolder task as stored in the database, generated from a Template.
154
 *
155
 * @public
156
 */
157
export type TaskSpec = TaskSpecV1beta3;
158