Skip to content

Commit 8a5246e

Browse files
magnusbaeckmagnusbaeck
committed
ActT/TCT/TSS: Add ORIGINAL_TRIGGER link type
This new link type is useful to describe the relationship between the original attempt to complete a task (e.g. a build) and subsequent activities that retry the first one.
1 parent 1744681 commit 8a5246e

File tree

6 files changed

+1140
-2
lines changed

6 files changed

+1140
-2
lines changed

‎definitions/EiffelActivityTriggeredEvent/4.3.0.yml‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
# Copyright 2017-2023 Ericsson AB and others.
2+
# For a full list of individual contributors, please see the commit history.
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+
$schema: http://json-schema.org/draft-04/schema#
17+
_abbrev: ActT
18+
_description: |-
19+
The EiffelActivityTriggeredEvent declares that a certain activity - typically a build, test or analysis activity - has been triggered by some factor. Note that this is crucially different from the activity execution having _started_ (as declared by [EiffelActivityStartedEvent](./EiffelActivityStartedEvent.md)).
20+
21+
In a situation where execution follows immediately upon triggering these two events should be sent together. Where that is not the case (e.g. due to queuing) the time delta between EiffelActivityTriggeredEvent and EiffelActivityStartedEvent constitutes the queue time.
22+
type: object
23+
properties:
24+
meta:
25+
$ref: ../EiffelMetaProperty/3.1.0.yml
26+
data:
27+
type: object
28+
properties:
29+
name:
30+
_description: The name of the activity. Uniqueness is not required
31+
or checked, but is useful.
32+
type: string
33+
categories:
34+
_description: Any categorization of the activity. This can
35+
be used to group multiple similar activities for analysis
36+
and visualization purposes. Example usage is to label the
37+
similar but unique build activities of all the components
38+
of system X as "System X Component Build" (whereas the name
39+
would be e.g. "System X Component Y Build").
40+
type: array
41+
items:
42+
type: string
43+
triggers:
44+
_description: The circumstances triggering the activity.
45+
type: array
46+
items:
47+
type: object
48+
properties:
49+
type:
50+
_description: |-
51+
The type of trigger.
52+
MANUAL signifies that the activity was manually triggered.
53+
EIFFEL_EVENT signifies that the activity was triggered by one or more Eiffel events. These events should be represented via __CAUSE__ links.
54+
SOURCE_CHANGE signifies that the activity was triggered as a consequence of a detected source change __not__ represented by Eiffel events.
55+
TIMER signifies that the activity was triggered by a timer.
56+
OTHER signifies any other triggering cause.
57+
type: string
58+
enum:
59+
- MANUAL
60+
- EIFFEL_EVENT
61+
- SOURCE_CHANGE
62+
- TIMER
63+
- OTHER
64+
description:
65+
_description: A description of the trigger.
66+
type: string
67+
required:
68+
- type
69+
additionalProperties: false
70+
executionType:
71+
_description: The type of execution (often related to, but
72+
ultimately separate from, __data.triggers.type__).
73+
type: string
74+
enum:
75+
- MANUAL
76+
- SEMI_AUTOMATED
77+
- AUTOMATED
78+
- OTHER
79+
customData:
80+
type: array
81+
items:
82+
$ref: ../EiffelCustomDataProperty/1.0.0.yml
83+
required:
84+
- name
85+
additionalProperties: false
86+
links:
87+
type: array
88+
items:
89+
$ref: ../EiffelEventLink/1.1.1.yml
90+
required:
91+
- meta
92+
- data
93+
- links
94+
additionalProperties: false
95+
_links:
96+
CAUSE:
97+
description: 'Identifies a cause of the event occurring. SHOULD
98+
not be used in conjunction with __CONTEXT__: individual events
99+
providing __CAUSE__ within a larger context gives rise to ambiguity.
100+
It is instead recommended to let the root event of the context
101+
declare __CAUSE__.'
102+
required: false
103+
multiple: true
104+
targets:
105+
any_type: true
106+
types: []
107+
CONTEXT:
108+
description: 'Identifies the
109+
[activity](../eiffel-syntax-and-usage/glossary.md#activity)
110+
or test suite of which this event constitutes a part.'
111+
required: false
112+
multiple: false
113+
targets:
114+
any_type: false
115+
types:
116+
- EiffelActivityTriggeredEvent
117+
- EiffelTestSuiteStartedEvent
118+
FLOW_CONTEXT:
119+
description: 'Identifies the flow context of the event: which is
120+
the continuous integration and delivery flow in which this occurred
121+
– e.g. which product, project, track or version this is applicable
122+
to.'
123+
required: false
124+
multiple: true
125+
targets:
126+
any_type: false
127+
types:
128+
- EiffelFlowContextDefinedEvent
129+
ORIGINAL_TRIGGER:
130+
description: 'Used when the current activity is a new attempt at
131+
completing a previous activity, typically because the latter failed.
132+
Although this activity may have been manually triggered and thus
133+
lacks a cause that can be described with Eiffel, this link can be
134+
used to convey the second-order cause.'
135+
required: false
136+
multiple: false
137+
targets:
138+
any_type: false
139+
types:
140+
- EiffelActivityTriggeredEvent
141+
PRECURSOR:
142+
description: 'Used to declare temporal relationships between
143+
[activities](../eiffel-syntax-and-usage/glossary.md#activity) in a
144+
[pipeline](../eiffel-syntax-and-usage/glossary.md#pipeline), i.e. what
145+
other activity/activities preceded this activity. This link type applies
146+
primarily to non event-triggered activities. For more information on
147+
the usage of this link type please see
148+
[Activity Linking](../eiffel-syntax-and-usage/activity-linking.md).'
149+
required: false
150+
multiple: true
151+
targets:
152+
any_type: false
153+
types:
154+
- EiffelActivityTriggeredEvent
155+
_history:
156+
- version: 4.3.0
157+
changes: Add ORIGINAL_TRIGGER link (see [Issue 246](https://github.com/eiffel-community/eiffel/issues/246)).
158+
- version: 4.2.0
159+
introduced_in: edition-arica
160+
changes: Add schema URL to the meta object (see [Issue 280](https://github.com/eiffel-community/eiffel/issues/280)).
161+
- version: 4.1.0
162+
introduced_in: edition-lyon
163+
changes: Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)).
164+
- version: 4.0.0
165+
introduced_in: edition-agen-1
166+
changes: Bug fix in schema file (see [Issue 205](https://github.com/eiffel-community/eiffel/issues/205))
167+
- version: 3.0.0
168+
introduced_in: edition-agen
169+
changes: Improved information integrity protection (see [Issue
170+
185](https://github.com/eiffel-community/eiffel/issues/185))
171+
- version: 2.0.0
172+
introduced_in: edition-agen
173+
changes: Introduced purl identifiers instead of GAVs (see [Issue
174+
182](https://github.com/eiffel-community/eiffel/issues/182))
175+
- version: 1.1.0
176+
introduced_in: edition-toulouse
177+
changes: Multiple links of type FLOW_CONTEXT allowed.
178+
- version: 1.0.0
179+
introduced_in: edition-bordeaux
180+
changes: Initial version.
181+
_examples:
182+
- title: Simple example
183+
url: ../examples/events/EiffelActivityTriggeredEvent/simple.json
184+
- title: Example containing custom data
185+
url: ../examples/events/EiffelActivityTriggeredEvent/simple-customdata.json

‎eiffel-syntax-and-usage/activity-linking.md‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!---
2-
Copyright 2022 Ericsson AB.
2+
Copyright 2022-2023 Ericsson AB and others.
33
For a full list of individual contributors, please see the commit history.
44
55
Licensed under the Apache License, Version 2.0 (the "License");
@@ -71,6 +71,23 @@ __Legal targets:__ [EiffelActivityTriggeredEvent][ActT],
7171
[EiffelTestCaseTriggeredEvent][TCT], [EiffelTestSuiteStartedEvent][TSS]
7272
__Multiple allowed:__ Yes
7373

74+
### ORIGINAL_TRIGGER
75+
76+
This link type is used for sequences of (usually) failing activities where the first activity declares the "root" trigger and the subsequent activities are retries of the first activity.
77+
78+
*The image below shows how a source code change triggers a build activity. That activity fails and is retried, and the second activity (which might be manually triggered by a user) has an ORIGINAL_TRIGGER link to the first activity.*
79+
80+
![An example of using ORIGINAL_TRIGGER](./original-trigger.png "An example of using ORIGINAL_TRIGGER")
81+
82+
An ORIGINAL_TRIGGER link could be combined with a CAUSE link. For example, an activity that retries a failing build could conceivably have a CAUSE link to the ActF event that announces the failure, but an ORIGINAL_TRIGGER link would further increase the fidelity of the model by describing not just that the second activity is run after the first one but that the first activity is the original trigger of the activity sequence.
83+
84+
__Required:__ No
85+
__Legal sources:__ [EiffelActivityTriggeredEvent][ActT],
86+
[EiffelTestCaseTriggeredEvent][TCT], [EiffelTestSuiteStartedEvent][TSS]
87+
__Legal targets:__ [EiffelActivityTriggeredEvent][ActT],
88+
[EiffelTestCaseTriggeredEvent][TCT], [EiffelTestSuiteStartedEvent][TSS]
89+
__Multiple allowed:__ No
90+
7491
### CONTEXT
7592
This link type is used to declare *hierarchies* of activities within a pipeline. The CONTEXT identifies the activity or test suite of which this event constitutes a part. For example:
7693
- This *pipeline step* is executed in the *CONTEXT* of that *pipeline*, i.e. the pipeline step is part of a certain pipeline, and the ActT event of the pipeline step SHOULD have a CONTEXT link to the ActT event of the pipeline itself.

‎eiffel-syntax-and-usage/original-trigger.png‎

32.7 KB
Loading

0 commit comments

Comments
 (0)