Add PRECURSOR link type and clarify activity linking

README.md

@@ -45,6 +45,7 @@ Visit [Eiffel Community](https://eiffel-community.github.io) to get started and
    1. [Versioning](./eiffel-syntax-and-usage/versioning.md)
    1. [Compositions and Validity Checking](./eiffel-syntax-and-usage/compositions-and-validity-checking.md)
    1. [Security](./eiffel-syntax-and-usage/security.md)
+   1. [Activity Linking](./eiffel-syntax-and-usage/activity-linking.md)
 1. The Eiffel Vocabulary
    1. [EiffelActivityTriggeredEvent (ActT)](./eiffel-vocabulary/EiffelActivityTriggeredEvent.md)
    1. [EiffelActivityCanceledEvent (ActC)](./eiffel-vocabulary/EiffelActivityCanceledEvent.md)
@@ -75,6 +76,7 @@ Visit [Eiffel Community](https://eiffel-community.github.io) to get started and
    1. [Build Avoidance](./usage-examples/build-avoidance.md)
    1. [Pipeline Monitoring](./usage-examples/pipeline-monitoring.md)
    1. [Test Execution](./usage-examples/test-execution.md)
+   1. [Orchestrated Pipelines](./usage-examples/orchestrated-pipelines.md)
    1. Reference Data Sets
       1. [Default](./usage-examples/reference-data-sets/default.md)
 1. Customization

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

@@ -0,0 +1,30 @@
+<!---
+   Copyright 2021 Ericsson AB.
+   For a full list of individual contributors, please see the commit history.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+--->
+
+# Activity Linking
+TBD
+
+## Event Driven vs Orchestrated Activities
+TBD
+
+## Link Types Involved
+- CONTEXT
+- CAUSE
+- PRECURSOR
+
+## Details
+TBD

eiffel-syntax-and-usage/glossary.md

@@ -31,6 +31,7 @@ This a non-exhaustive, alphabetical list of terms used in the [Eiffel vocabulary
    - [Submit](#submit)
 
  - [Terms Used in Documentation](#terms-used-in-documentation)
+   - [Occurrence](#occurrence)
    - [Pipeline](#pipeline)
 
 ## Terms Used in Event Definitions
@@ -90,12 +91,17 @@ An Eiffel _environment_ defines the environment in which an [activity](#activity
 - [EiffelEnvironmentDefinedEvent](../eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md)
 
 ### Event
-An Eiffel _event_ is a broadcast notification telling any consumer about an event occurring in the CI/CD [pipeline](#pipeline). As opposed to a _message_, that is addressed to a certain receiver, an event is not aimed at a specific consumer. An event is also _descriptive_ rather than _prescriptive_, meaning that it does not expect a certain action to happen but it instead notifies on actions performed.
+An Eiffel _event_ is a broadcast notification telling any consumer about an [occurrence](#occurrence) in the CI/CD [pipeline](#pipeline). As opposed to a _message_, that is addressed to a certain receiver, an event is not aimed at a specific consumer. An event is also _descriptive_ rather than _prescriptive_, meaning that it does not expect a certain action to happen but it instead notifies on actions performed.
+
+An Eiffel event contains three types of information: A _meta_ object providing contextual information about the [occurence](#occurrence), a _data_ object representing the specific occurrence, and a _[link](#link)s_ object describing relationships between this event and previously sent events.
 
 An event should not carry any data that is already provided by events sent earlier in the CI/CD pipeline. Instead those earlier events should be [linked](#link) from this event, making it possible to aggregate all relevant data connected to the CI/CD pipeline execution.
 
+A single [occurrence](#occurrence) may result in more than one event, for example a build activity being started would result in both [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md) and [EiffelActivityStartedEvent](../eiffel-vocabulary/EiffelActivityStartedEvent.md) being sent if there is no build queue present.
+
 More about what an event is supposed to be can be read in the [event design guidelines](./event-design-guidelines.md).
 
+
 ### Link
 A _link_ is a directed connection between two [events](#event). With linked events you will get a directed acyclic graph of actions performed in your CI/CD [pipeline](#pipeline). Links are also semantic, as each link has a type describing the relationship between the link source and its target. Having linked events enables generic data aggregations and visualizations to be implemented. Together with the timestamps provided in each event, the directed semantic links enable the possibility to create generic pipeline measurements and other analytics compilations.
 
@@ -117,5 +123,8 @@ A _submit_ is the action of merging a [source change](#source-change) to its int
 ## Terms Used in Documentation
 The terms below are not used in any events in the Eiffel protocol. They are added here to enable a homogenous and easy read of the protocol documentation. These terms are subject to change without notice if a better name is found or defined elsewhere. Their names should reflect the most commonly used terms elsewhere in the industry.
 
+### Occurrence
+An _occurrence_ is the capture of a statement of fact during the execution of a CI/CD [pipeline](#pipeline). This might occur because of for example a source change being created/updated, an artifact being built, an upstream artifact being delivered, or any other activity relevant to a CI/CD pipeline.
+
 ### Pipeline
 A _pipeline_ is an ordered set of [activities](#activity) often triggered by a [source change](#source-change) being created or [submitted](#submit).

eiffel-vocabulary/EiffelActivityTriggeredEvent.md

@@ -73,7 +73,13 @@ __Required:__ No
 __Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md),
 [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md)  
 __Multiple allowed:__ No  
-__Description:__ Identifies the activity or test suite of which this event constitutes a part.
+__Description:__ Identifies the [activity](https://github.com/eiffel-community/eiffel/blob/master/eiffel-syntax-and-usage/glossary.md#activity) or test suite of which this event constitutes a part.
+
+### PRECURSOR
+__Required:__ No  
+__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md)  
+__Multiple allowed:__ Yes  
+__Description:__ Used to declare what was the event(s) that occurred before this event occurred, for example describing the relationship between [activities](https://github.com/eiffel-community/eiffel/blob/master/eiffel-syntax-and-usage/glossary.md#activity) in a [pipeline](https://github.com/eiffel-community/eiffel/blob/master/eiffel-syntax-and-usage/glossary.md#pipeline). Applicable primarily for non event-triggered activities.
 
 ### FLOW_CONTEXT
 __Required:__ No  

usage-examples/orchestrated-pipelines.md

@@ -0,0 +1,19 @@
+<!---
+   Copyright 2021 Ericsson AB.
+   For a full list of individual contributors, please see the commit history.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+--->
+
+# Orchestrated Pipelines
+TBD