Skip to content

Commit f5f82c7

Browse files
magnusbaeckmagnusbaeck
authored
Add domain id for links (#269)
To make cross-domain links unambiguous and make it easier and more performant to locate the target events of such links we introduce a domainId member to the link object. This is a backwards-compatible change since the absence of the new member means that the target event can be assumed to exist in the same domain as the source event. Since we're now using the domain term in another place apart from the description of meta.source.domainId in each event we centralize the definition in a new glossary term.
1 parent 6ffca23 commit f5f82c7

File tree

48 files changed

+4930
-57
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

48 files changed

+4930
-57
lines changed

‎eiffel-syntax-and-usage/glossary.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!---
2-
Copyright 2020 Ericsson AB.
2+
Copyright 2020-2021 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");
@@ -76,6 +76,12 @@ Confidence levels frequently figure in automated delivery interfaces within a ti
7676
#### Examples of events related to confidence levels:
7777
- [EiffelConfidenceLevelModifiedEvent](../eiffel-vocabulary/EiffelConfidenceLevelModifiedEvent.md)
7878

79+
### Domain
80+
81+
An Eiffel _domain_ is an infrastructure topological concept, which may or may not correspond to an organization or product structure. A good example would be Java packages notation, ex. com.mycompany.product.component or mycompany.site.division. Domains can be used to implement Eiffel namespaces when different companies, business units, or similar exchange Eiffel events. An Eiffel event may include a member that specifies the event's domain association.
82+
83+
Also, keep in mind that all names are more or less prone to change. Particularly, it is recommended to avoid organizational names or site names, as organizations tend to be volatile and development is easily relocated. Relatively speaking, product and component names tend to be more stable and are therefore encouraged, while code names may be an option. You need to decide what is the most sensible option in your case.
84+
7985
### Environment
8086
An Eiffel _environment_ defines the environment in which an [activity](#activity) is executed. Could be for example a host, node, service name/uri, a Docker image or some other kind of machine configuration definition.
8187

‎eiffel-syntax-and-usage/the-links-object.md‎

Lines changed: 24 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!---
2-
Copyright 2017-2018 Ericsson AB.
2+
Copyright 2017-2021 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");
@@ -16,15 +16,35 @@
1616
--->
1717

1818
# The Links Object
19-
The __links__ object is an array of trace links to other Eiffel events. These trace links by definition always reference backwards in time – it is only possible to reference an event that has already occurred. Each trace link is a tuple consisting of a type and a UUID corresponding to the __meta.id__ of the target event, on String format.
19+
The __links__ object is an array of trace links to other Eiffel events. These trace links by definition always reference backwards in time – it is only possible to reference an event that has already occurred. Each trace link is an object consisting of
20+
21+
- a type,
22+
- a UUID corresponding to the __meta.id__ of the target event, on string format, and
23+
- optionally the id of the [domain](glossary.md#domain) where the target event was published (i.e. its __meta.source.domainId__ member). The absence of a domain id means that the target event was sent in, or can at least be retrieved from, the same domain as the current event.
2024

2125
Some link types allow multiple trace links, whereas others only allow one.
2226

2327
Example syntax of a simple __links__ object:
2428

2529
"links": [
26-
{"type": "CAUSE", "target": "8f3e0f94-5d11-46e7-ae02-91efa15d2329"},
27-
{"type": "COMPOSITION", "target": "43ee71d2-6d91-496a-b9cf-d121ff1d1bcf"}
30+
{
31+
"type": "CAUSE",
32+
"target": "8f3e0f94-5d11-46e7-ae02-91efa15d2329"
33+
},
34+
{
35+
"type": "COMPOSITION",
36+
"target": "43ee71d2-6d91-496a-b9cf-d121ff1d1bcf"
37+
}
38+
]
39+
40+
Example syntax of a __links__ object that references an event in another domain:
41+
42+
"links": [
43+
{
44+
"type": "CAUSE",
45+
"target": "a3bf3f06-a0e0-4595-a117-3393c178eb81",
46+
"domainId": "com.example"
47+
}
2848
]
2949

3050
The full list of optional and required links is described in the documentation of each respective event type.

‎eiffel-vocabulary/EiffelActivityCanceledEvent.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!---
2-
Copyright 2017-2018 Ericsson AB.
2+
Copyright 2017-2021 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");
@@ -91,7 +91,7 @@ __Description:__ A description of the source of the event. This object is primar
9191
__Type:__ String
9292
__Format:__ Free text
9393
__Required:__ No
94-
__Description:__ Identifies the domain that produced an event. A domain is an infrastructure topological concept, which may or may not corresponds to an organization or product structures. A good example would be Java packages notation, ex. com.mycompany.product.component or mycompany.site.division. Also, keep in mind that all names are more or less prone to change. Particularly, it is recommended to avoid organizational names or site names, as organizations tend to be volatile and development is easily relocated. Relatively speaking, product and component names tend to be more stable and are therefore encouraged, while code names may be an option. You need to decide what is the most sensible option in your case.
94+
__Description:__ Identifies the [domain](../eiffel-syntax-and-usage/glossary.md#domain) that produced an event.
9595

9696
#### meta.source.host
9797
__Type:__ String
@@ -179,6 +179,7 @@ __Description:__ The number of the event within the named sequence.
179179
## Version History
180180
| Version | Introduced in | Changes |
181181
| --------- | ------------------------------------------------------ | --------------------------------------- |
182+
| 3.1.0 | Current version | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). |
182183
| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection | (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)) |
183184
| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelActivityCanceledEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) |
184185
| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. |

‎eiffel-vocabulary/EiffelActivityFinishedEvent.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!---
2-
Copyright 2017-2018 Ericsson AB.
2+
Copyright 2017-2021 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");
@@ -133,7 +133,7 @@ __Description:__ A description of the source of the event. This object is primar
133133
__Type:__ String
134134
__Format:__ Free text
135135
__Required:__ No
136-
__Description:__ Identifies the domain that produced an event. A domain is an infrastructure topological concept, which may or may not corresponds to an organization or product structures. A good example would be Java packages notation, ex. com.mycompany.product.component or mycompany.site.division. Also, keep in mind that all names are more or less prone to change. Particularly, it is recommended to avoid organizational names or site names, as organizations tend to be volatile and development is easily relocated. Relatively speaking, product and component names tend to be more stable and are therefore encouraged, while code names may be an option. You need to decide what is the most sensible option in your case.
136+
__Description:__ Identifies the [domain](../eiffel-syntax-and-usage/glossary.md#domain) that produced an event.
137137

138138
#### meta.source.host
139139
__Type:__ String
@@ -221,6 +221,7 @@ __Description:__ The number of the event within the named sequence.
221221
## Version History
222222
| Version | Introduced in | Changes |
223223
| --------- | ------------------------------------------------------ | --------------------------------------- |
224+
| 3.2.0 | Current version | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). |
224225
| 3.1.0 | Current version | Add `data.persistentLogs.{mediaType,tags}`. |
225226
| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection | (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)) |
226227
| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelActivityFinishedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) |

‎eiffel-vocabulary/EiffelActivityStartedEvent.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!---
2-
Copyright 2017-2018 Ericsson AB.
2+
Copyright 2017-2021 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");
@@ -122,7 +122,7 @@ __Description:__ A description of the source of the event. This object is primar
122122
__Type:__ String
123123
__Format:__ Free text
124124
__Required:__ No
125-
__Description:__ Identifies the domain that produced an event. A domain is an infrastructure topological concept, which may or may not corresponds to an organization or product structures. A good example would be Java packages notation, ex. com.mycompany.product.component or mycompany.site.division. Also, keep in mind that all names are more or less prone to change. Particularly, it is recommended to avoid organizational names or site names, as organizations tend to be volatile and development is easily relocated. Relatively speaking, product and component names tend to be more stable and are therefore encouraged, while code names may be an option. You need to decide what is the most sensible option in your case.
125+
__Description:__ Identifies the [domain](../eiffel-syntax-and-usage/glossary.md#domain) that produced an event.
126126

127127
#### meta.source.host
128128
__Type:__ String
@@ -210,6 +210,7 @@ __Description:__ The number of the event within the named sequence.
210210
## Version History
211211
| Version | Introduced in | Changes |
212212
| --------- | ------------------------------------------------------ | --------------------------------------- |
213+
| 4.2.0 | Current version | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). |
213214
| 4.1.0 | Current version | Add `data.liveLogs.{mediaType,tags}`. |
214215
| 4.0.0 | [edition-agen-1](../../../tree/edition-agen-1) | Bug fix in schema file (see [Issue 205](https://github.com/eiffel-community/eiffel/issues/205)) |
215216
| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)) |

‎eiffel-vocabulary/EiffelActivityTriggeredEvent.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!---
2-
Copyright 2017-2018 Ericsson AB.
2+
Copyright 2017-2021 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");
@@ -119,7 +119,7 @@ __Description:__ A description of the source of the event. This object is primar
119119
__Type:__ String
120120
__Format:__ Free text
121121
__Required:__ No
122-
__Description:__ Identifies the domain that produced an event. A domain is an infrastructure topological concept, which may or may not corresponds to an organization or product structures. A good example would be Java packages notation, ex. com.mycompany.product.component or mycompany.site.division. Also, keep in mind that all names are more or less prone to change. Particularly, it is recommended to avoid organizational names or site names, as organizations tend to be volatile and development is easily relocated. Relatively speaking, product and component names tend to be more stable and are therefore encouraged, while code names may be an option. You need to decide what is the most sensible option in your case.
122+
__Description:__ Identifies the [domain](../eiffel-syntax-and-usage/glossary.md#domain) that produced an event.
123123

124124
#### meta.source.host
125125
__Type:__ String
@@ -207,6 +207,7 @@ __Description:__ The number of the event within the named sequence.
207207
## Version History
208208
| Version | Introduced in | Changes |
209209
| --------- | ------------------------------------------------------ | --------------------------------------- |
210+
| 4.1.0 | Current version | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). |
210211
| 4.0.0 | [edition-agen-1](../../../tree/edition-agen-1) | Bug fix in schema file (see [Issue 205](https://github.com/eiffel-community/eiffel/issues/205)) |
211212
| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)) |
212213
| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelActivityTriggeredEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) |

‎eiffel-vocabulary/EiffelAnnouncementPublishedEvent.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!---
2-
Copyright 2017-2018 Ericsson AB.
2+
Copyright 2017-2021 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");
@@ -107,7 +107,7 @@ __Description:__ A description of the source of the event. This object is primar
107107
__Type:__ String
108108
__Format:__ Free text
109109
__Required:__ No
110-
__Description:__ Identifies the domain that produced an event. A domain is an infrastructure topological concept, which may or may not corresponds to an organization or product structures. A good example would be Java packages notation, ex. com.mycompany.product.component or mycompany.site.division. Also, keep in mind that all names are more or less prone to change. Particularly, it is recommended to avoid organizational names or site names, as organizations tend to be volatile and development is easily relocated. Relatively speaking, product and component names tend to be more stable and are therefore encouraged, while code names may be an option. You need to decide what is the most sensible option in your case.
110+
__Description:__ Identifies the [domain](../eiffel-syntax-and-usage/glossary.md#domain) that produced an event.
111111

112112
#### meta.source.host
113113
__Type:__ String
@@ -195,6 +195,7 @@ __Description:__ The number of the event within the named sequence.
195195
## Version History
196196
| Version | Introduced in | Changes |
197197
| --------- | ------------------------------------------------------ | --------------------------------------- |
198+
| 3.1.0 | Current version | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). |
198199
| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection | (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)) |
199200
| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelAnnouncementPublishedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) |
200201
| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. |

‎eiffel-vocabulary/EiffelArtifactCreatedEvent.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!---
2-
Copyright 2017-2018 Ericsson AB.
2+
Copyright 2017-2021 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");
@@ -151,7 +151,7 @@ __Description:__ A description of the source of the event. This object is primar
151151
__Type:__ String
152152
__Format:__ Free text
153153
__Required:__ No
154-
__Description:__ Identifies the domain that produced an event. A domain is an infrastructure topological concept, which may or may not corresponds to an organization or product structures. A good example would be Java packages notation, ex. com.mycompany.product.component or mycompany.site.division. Also, keep in mind that all names are more or less prone to change. Particularly, it is recommended to avoid organizational names or site names, as organizations tend to be volatile and development is easily relocated. Relatively speaking, product and component names tend to be more stable and are therefore encouraged, while code names may be an option. You need to decide what is the most sensible option in your case.
154+
__Description:__ Identifies the [domain](../eiffel-syntax-and-usage/glossary.md#domain) that produced an event.
155155

156156
#### meta.source.host
157157
__Type:__ String
@@ -239,6 +239,7 @@ __Description:__ The number of the event within the named sequence.
239239
## Version History
240240
| Version | Introduced in | Changes |
241241
| --------- | ------------------------------------------------------ | --------------------------------------- |
242+
| 3.1.0 | Current version | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). |
242243
| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection | (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)) |
243244
| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelArtifactCreatedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) |
244245
| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. |

‎eiffel-vocabulary/EiffelArtifactPublishedEvent.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@ __Description:__ A description of the source of the event. This object is primar
111111
__Type:__ String
112112
__Format:__ Free text
113113
__Required:__ No
114-
__Description:__ Identifies the domain that produced an event. A domain is an infrastructure topological concept, which may or may not corresponds to an organization or product structures. A good example would be Java packages notation, ex. com.mycompany.product.component or mycompany.site.division. Also, keep in mind that all names are more or less prone to change. Particularly, it is recommended to avoid organizational names or site names, as organizations tend to be volatile and development is easily relocated. Relatively speaking, product and component names tend to be more stable and are therefore encouraged, while code names may be an option. You need to decide what is the most sensible option in your case.
114+
__Description:__ Identifies the [domain](../eiffel-syntax-and-usage/glossary.md#domain) that produced an event.
115115

116116
#### meta.source.host
117117
__Type:__ String
@@ -199,6 +199,7 @@ __Description:__ The number of the event within the named sequence.
199199
## Version History
200200
| Version | Introduced in | Changes |
201201
| --------- | ------------------------------------------------------ | --------------------------------------- |
202+
| 3.2.0 | Current version | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). |
202203
| 3.1.0 | [edition-paris](../../../tree/edition-paris) | Added name qualifier for artifact locations (see [Issue 248](https://github.com/eiffel-community/eiffel/issues/248)) |
203204
| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection | (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)) |
204205
| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelArtifactPublishedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) |

0 commit comments

Comments
 (0)