diff --git a/eiffel-syntax-and-usage/event-structure.md b/eiffel-syntax-and-usage/event-structure.md index 8ed0024a..c04bcca1 100644 --- a/eiffel-syntax-and-usage/event-structure.md +++ b/eiffel-syntax-and-usage/event-structure.md @@ -31,4 +31,4 @@ __Description:__ This object contains all fields specific to the event type – ## links __Type:__ Object __Required:__ Yes -__Description:__ This object contains all trace links to other Eiffel events. It is described in detail [here](./the-links-object.md). +__Description:__ This object contains all types of links to other Eiffel events. Its usage and syntax is described [here](./the-links-object.md), while the full list of optional and required links is described in the documentation of each respective event type.. diff --git a/eiffel-syntax-and-usage/the-links-object.md b/eiffel-syntax-and-usage/the-links-object.md index 74cf356b..8242c98e 100644 --- a/eiffel-syntax-and-usage/the-links-object.md +++ b/eiffel-syntax-and-usage/the-links-object.md @@ -1,5 +1,5 @@ # The Links Object -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 occured. 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. +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. Some link types allow multiple trace links, whereas others only allow one. @@ -27,170 +27,4 @@ Example syntax of a simple __links__ object: {"type": "COMPOSITION", "target": "43ee71d2-6d91-496a-b9cf-d121ff1d1bcf"} ] -## Legal Link Types -### CAUSE -__Required in:__ None -__Optional in:__ Any -__Legal targets:__ Any -__Multiple allowed:__ Yes -__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. - -### CONTEXT -__Required in:__ None -__Optional in:__ Any -__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), -[EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) -__Multiple allowed:__ No -__Description:__ Identifies the activity or test suite of which the event constitutes a part. SHOULD not be used in conjunction with __CAUSE__, see above. Note that multiple layers may be modeled using __CONTEXT__, e.g. an activity being part of another activity. - -### FLOW_CONTEXT -__Required in:__ None -__Optional in:__ Any -__Legal targets:__ [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFlowContextDefinedEvent.md) -__Multiple allowed:__ No -__Description:__ Identifies the flow context of the event: which is the continuous integration and delivery flow in which this occurred – e.g. which product, project, track or version this is applicable to. - -### ACTIVITY_EXECUTION -__Required in:__ [EiffelActivityCanceledEvent](../eiffel-vocabulary/EiffelActivityCanceledEvent.md), -[EiffelActivityStartedEvent](../eiffel-vocabulary/EiffelActivityStartedEvent.md), -[EiffelActivityFinishedEvent](../eiffel-vocabulary/EiffelActivityFinishedEvent.md) -__Optional in:__ None -__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md) -__Multiple allowed:__ No -__Description:__ Declares the activity execution the event relates to. In other words, [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md) acts as a handle for the activity execution. This differs from __CONTEXT__. In __ACTIVITY_EXECUTION__ the source carries information pertaining to the target (i.e. the activity started, finished or was canceled). In __CONTEXT__, on the other hand, the source constitutes a subset of the target (e.g. this test case was executed as part of that activity or test suite). - -### PREVIOUS_ACTIVITY_EXECUTION -__Required in:__ None -__Optional in:__ [EiffelActivityStartedEvent](../eiffel-vocabulary/EiffelActivityStartedEvent.md) -__Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md) -__Multiple allowed:__ No -__Description:__ Identifies the latest previous execution of the activity. - -### PREVIOUS_VERSION -__Required in:__ None -__Optional in:__ [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md), -[EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md), -[EiffelEnvironmentDefinedEvent](../eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md), -[EiffelSourceChangeCreatedEvent](../eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md), -[EiffelSourceChangeSubmittedEvent](../eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md) -__Legal targets:__ [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md), -[EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md), -[EiffelEnvironmentDefinedEvent](../eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md), -[EiffelSourceChangeCreatedEvent](../eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md), -[EiffelSourceChangeSubmittedEvent](../eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md) -__Multiple allowed:__ Yes -__Description:__ Identifies a latest previous version (there may be more than one in case of merges) of the engineering artifact the event represents, e.g. the previous version of the artifact, the previous version of the composition etc. The target event type SHALL be the same as the source event type. - -### COMPOSITION -__Required in:__ [EiffelArtifactReusedEvent](../eiffel-vocabulary/EiffelArtifactReusedEvent.md) -__Optional in:__ [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md) -__Legal targets:__ [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md) -__Multiple allowed:__ No -__Description:__ Identifies the composition from which an artifact declared by [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md) was built, or the composition for which an already existing artifact is declared reused by [EiffelArtifactReusedEvent](../eiffel-vocabulary/EiffelArtifactReusedEvent.md). - -### ENVIRONMENT -__Required in:__ None -__Optional in:__ [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md), -[EiffelTestCaseStartedEvent](../eiffel-vocabulary/EiffelTestCaseStartedEvent.md), -[EiffelIssueVerifiedEvent](../eiffel-vocabulary/EiffelIssueVerifiedEvent.md) -__Legal targets:__ [EiffelEnvironmentDefinedEvent](../eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md) -__Multiple allowed:__ No -__Description:__ Identifies the environment in which an event occurred, e.g. in which environment an artifact was built or an issue was verified. - -### ARTIFACT -__Required in:__ [EiffelArtifactPublishedEvent](../eiffel-vocabulary/EiffelArtifactPublishedEvent.md) -__Optional in:__ None -__Legal targets:__ [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md) -__Multiple allowed:__ No -__Description:__ Identifies the artifact that was published. - -### SUBJECT -__Required in:__ [EiffelConfidenceLevelModifiedEvent](../eiffel-vocabulary/EiffelConfidenceLevelModifiedEvent.md) -__Optional in:__ None -__Legal targets:__ [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md), -[EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md), -[EiffelSourceChangeCreatedEvent](../eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md), -[EiffelSourceChangeSubmittedEvent](../eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md) -__Multiple allowed:__ Yes -__Description:__ Identifies a subject of the confidence level. - -### ELEMENT -__Required in:__ None -__Optional in:__ [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md) -__Legal targets:__ [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md), -[EiffelSourceChangeSubmittedEvent](../eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md), -[EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md) -__Multiple allowed:__ Yes -__Description:__ Identifies an element and/or sub-composition of the composition. The latter is particularly useful for documenting large and potentially decentralized compositions, and may be used to reduce the need to repeat large compositions in which only small parts are subject to frequent change. - -### BASE -__Required in:__ None -__Optional in:__ [EiffelSourceChangeCreatedEvent](../eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md) -__Legal targets:__ [EiffelSourceChangeSubmittedEvent](../eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md) -__Multiple allowed:__ No -__Description:__ Identifies the base revision of the proposed change. - -### CHANGE -__Required in:__ None -__Optional in:__ [EiffelSourceChangeSubmittedEvent](../eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md) -__Legal targets:__ [EiffelSourceChangeCreatedEvent](../eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md) -__Multiple allowed:__ No -__Description:__ Identifies the change that was submitted. - -### TEST_SUITE_EXECUTION -__Required in:__ [EiffelTestSuiteFinishedEvent](../eiffel-vocabulary/EiffelTestSuiteFinishedEvent.md) -__Optional in:__ None -__Legal targets:__ [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) -__Multiple allowed:__ No -__Description:__ Identifies the relevant test suite execution. In other words, [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) acts as a handle for a particular test suite execution. - -### TEST_CASE_EXECUTION -__Required in:__ [EiffelTestCaseStartedEvent](../eiffel-vocabulary/EiffelTestCaseStartedEvent.md), [EiffelTestCaseFinishedEvent](../eiffel-vocabulary/EiffelTestCaseFinishedEvent.md), [EiffelTestCaseCanceledEvent](../eiffel-vocabulary/EiffelTestCaseCanceledEvent.md) -__Optional in:__ None -__Legal targets:__ [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) -__Multiple allowed:__ No -__Description:__ Identifies the relevant test case execution. In other words, [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) acts as a handle for a particular test case execution. This differs from __CONTEXT__. In __TEST_CASE_EXECUTION__ the source carries information pertaining to the target (i.e. the test case execution started, finished or was canceled). In __CONTEXT__, on the other hand, the source constitutes a subset of the target (e.g. this test case was executed as part of that activity or test suite). - -### IUT -__Required in:__ [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md), -[EiffelIssueVerifiedEvent](../eiffel-vocabulary/EiffelIssueVerifiedEvent.md) -__Optional in:__ None -__Legal targets:__ [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md), -[EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md) -__Multiple allowed:__ No -__Description:__ Identifies the Item Under Test: what is about to be tested and/or has been verified to address an issue, respectively. - -### TERC -__Required in:__ None -__Optional in:__ [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) -__Legal targets:__ [EiffelTestExecutionRecipeCollectionCreatedEvent](../eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md) -__Multiple allowed:__ No -__Description:__ When declared in an [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md), this link signifies that the test suite groups all test case executions resulting from the [EiffelTestExecutionRecipeCollectionCreatedEvent](../eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md). - -### MODIFIED_ANNOUNCEMENT -__Required in:__ None -__Optional in:__ [EiffelAnnouncementPublishedEvent](../eiffel-vocabulary/EiffelAnnouncementPublishedEvent.md) -__Legal targets:__ [EiffelAnnouncementPublishedEvent](../eiffel-vocabulary/EiffelAnnouncementPublishedEvent.md) -__Multiple allowed:__ No -__Description:__ Identifies an announcement of which this event represents an update or modification, if any. Example usage is to declare the end to a previously announced situation. - -### SUB_CONFIDENCE_LEVEL -__Required in:__ None -__Optional in:__ [EiffelConfidenceLevelModifiedEvent](../eiffel-vocabulary/EiffelConfidenceLevelModifiedEvent.md) -__Legal targets:__ [EiffelConfidenceLevelModifiedEvent](../eiffel-vocabulary/EiffelConfidenceLevelModifiedEvent.md) -__Multiple allowed:__ Yes -__Description:__ Used in events summarizing multiple confidence levels. Example use case: the confidence level "allTestsOk" summarizes the confidence levels "unitTestsOk, "scenarioTestsOk" and "deploymentTestsOk", and consequently links to them via __SUB_CONFIDENCE_LEVEL__. This is intended for purely descriptive, rather than prescriptive, use. - -### REUSED_ARTIFACT -__Required in:__ [EiffelArtifactReusedEvent](../eiffel-vocabulary/EiffelArtifactReusedEvent.md) -__Optional in:__ None -__Legal targets:__ [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md) -__Multiple allowed:__ No -__Description:__ This link identifies the [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md) that is reused; in other words, the artifact that is not rebuilt for a given composition. - -### VERIFICATION_BASIS -__Required in:__ None -__Optional in:__ [EiffelIssueVerifiedEvent](../eiffel-vocabulary/EiffelIssueVerifiedEvent.md) -__Legal targets:__ [EiffelTestCaseFinishedEvent](../eiffel-vocabulary/EiffelTestCaseFinishedEvent.md), [EiffelTestSuiteFinishedEvent](../eiffel-vocabulary/EiffelTestSuiteFinishedEvent.md) -__Multiple allowed:__ Yes -__Description:__ Used to declare the basis on which the verification statement(s) of [EiffelIssueVerifiedEvent](../eiffel-vocabulary/EiffelIssueVerifiedEvent.md) have been issued. +The full list of optional and required links is described in the documentation of each respective event type. diff --git a/eiffel-syntax-and-usage/the-meta-object.md b/eiffel-syntax-and-usage/the-meta-object.md index c0917b63..4950acd8 100644 --- a/eiffel-syntax-and-usage/the-meta-object.md +++ b/eiffel-syntax-and-usage/the-meta-object.md @@ -1,5 +1,5 @@ # EiffelFlowContextDefined (FCD) -The EiffelFlowContextDefined describes the context of other events, answering questions such as "Which project is change part of?" or "Which track does artifact belong to?". In this way it offers a method of classifying and structuring one's continuous integration and delivery system and thereby facilitaring traceability and searchability. +The EiffelFlowContextDefined describes the context of other events, answering questions such as "Which project is change part of?" or "Which track does artifact belong to?". In this way it offers a method of classifying and structuring one's continuous integration and delivery system and thereby facilitaring traceability and searchability. The nature of the described context can vary. The event consequently offers a high degree of flexibility in its description, and none of its member fields are mandatory. Instead they can picked and mixed to fit the situation. @@ -46,10 +46,139 @@ __Type:__ String __Required:__ No __Description:__ A version context which other events can relate to. This member SHOULD be used in tandem with one of the other optional members - a version by itself is not very informative. +## Links +### CAUSE +__Required:__ No +__Legal targets:__ Any +__Multiple allowed:__ Yes +__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. + +### CONTEXT +__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. + +### FLOW_CONTEXT +__Required:__ No +__Legal targets:__ [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFlowContextDefinedEvent.md) +__Multiple allowed:__ No +__Description:__ Identifies the flow context of the event: which is the continuous integration and delivery flow in which this occurred – e.g. which product, project, track or version this is applicable to. + +## Meta Members +### meta.id +__Type:__ String +__Format:__ [UUID](http://tools.ietf.org/html/rfc4122) +__Required:__ Yes +__Description:__ The unique identity of the event, generated at event creation. + +### meta.type +__Type:__ String +__Format:__ An event type name +__Required:__ Yes +__Description:__ The type of event. This field is required by the recipient of the event, as each event type has a specific meaning and a specific set of members in the __data__ and __links__ objects. + +### meta.version +__Type:__ String +__Format:__ [Semantic Versioning 2.0.0](http://semver.org/spec/v2.0.0.html) +__Required:__ Yes +__Description:__ The version of the event type. This field is required by the recipient of the event to interpret the contents. Please see [Versioning](../eiffel-syntax-and-usage/versioning.md) for more information. + +### meta.time +__Type:__ Integer +__Format:__ Milliseconds since epoch. +__Required:__ Yes +__Description:__ The event creation timestamp. + +### meta.tags +__Type:__ String[] +__Format:__ Free text +__Required:__ No +__Description:__ Any tags or keywords associated with the events, for searchability purposes. + +### meta.source +__Type:__ Object +__Format:__ +__Required:__ No +__Description:__ A description of the source of the event. This object is primarily for traceability purposes, and while optional, some form of identification of the source is __HIGHLY RECOMMENDED__. It offers multiple methods of identifying the source of the event, techniques which may be select from based on the technology domain and needs in any particular use case. + +#### meta.source.domainId +__Type:__ String +__Format:__ Free text +__Required:__ No +__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. + +#### meta.source.host +__Type:__ String +__Format:__ Hostname +__Required:__ No +__Description:__ The hostname of the event sender. + +#### meta.source.name +__Type:__ String +__Format:__ Free text +__Required:__ No +__Description:__ The name of the event sender. + +#### meta.source.serializer +__Type:__ Object +__Format:__ +__Required:__ No +__Description:__ The [GAV](https://maven.apache.org/guides/mini/guide-naming-conventions.html) coordinates of the serializer software used to construct the event. + +##### meta.source.serializer.groupId +__Type:__ String +__Format:__ groupId +__Required:__ Yes +__Description:__ The groupId of the serializer software. + +##### meta.source.serializer.artifactId +__Type:__ String +__Format:__ artifactId +__Required:__ Yes +__Description:__ The artifactId of the serializer software. + +##### meta.source.serializer.version +__Type:__ String +__Format:__ version +__Required:__ Yes +__Description:__ The version of the serializer software. + +#### meta.source.uri +__Type:__ String +__Format:__ URI +__Required:__ No +__Description:__ The URI of, related to or describing the event sender. + +### meta.security +__Type:__ Object +__Format:__ +__Required:__ No +__Description:__ An optional object for enclosing security related information, particularly supporting data integrity. See [Security](../eiffel-syntax-and-usage/security.md) for further information. + +#### meta.security.sdm +__Type:__ Object +__Format:__ +__Required:__ No +__Description:__ An optional object for properties supporting the [Strong Distribution Model](http://www.cryptnet.net/fdp/crypto/strong_distro.html). Note that this only addressed the _integrity_ of the Eiffel event, not its _confidentiality_ or _availability_. + +##### meta.security.sdm.authorIdentity +__Type:__ String +__Format:__ +__Required:__ Yes +__Description:__ The identity of the author of the event. This property is intended to enable the recipient to look up the appropriate public key for decrypting the digest and thereby verifying author identity and data integrity. The format of the author identity varies depending on the key infrastructure solution used. Note that this requires the presence of a Trusted Authority (TA) which the recipient can query for the correct public key. The identity and location of the TA must never be included in the event itself, as this would compromise the security of the solution. + +##### meta.security.sdm.encryptedDigest +__Type:__ String +__Format:__ +__Required:__ Yes +__Description:__ The encrypted digest. The cryptographic hash function and the decryption algorithm to use, similarly to the Trusted Authority (TA), must be known to the recipient. Note that the digest of the entire event is affected by the value of this property. For this reason the input to the hash function SHALL be the entire event unaltered in all parts except for this property, which SHALL be replaced by an empty string. + ## Version History | Version | Introduced in | Changes | | --------- | ------------------------------------------------------ | --------------------------------------- | | 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | ## Examples -* [Simple example](../examples/events/EiffelFlowContextDefinedEvent/simple.json) \ No newline at end of file +* [Simple example](../examples/events/EiffelFlowContextDefinedEvent/simple.json) diff --git a/eiffel-vocabulary/EiffelIssueVerifiedEvent.md b/eiffel-vocabulary/EiffelIssueVerifiedEvent.md index a0a8e083..7db15094 100644 --- a/eiffel-vocabulary/EiffelIssueVerifiedEvent.md +++ b/eiffel-vocabulary/EiffelIssueVerifiedEvent.md @@ -1,5 +1,5 @@ # EiffelTestSuiteStartedEvent (TSS) -The EiffelTestSuiteStartedEvent declares that the execution of a test suite has started. This can either be declared stand-alone or as part of an activity or other test suite, using either a __CAUSE__ or a __CONTEXT__ link type, respectively. +The EiffelTestSuiteStartedEvent declares that the execution of a test suite has started. This can either be declared stand-alone or as part of an activity or other test suite, using either a __CAUSE__ or a __CONTEXT__ link type, respectively. In Eiffel, a test suite is nothing more or less than a collection of test case executions (see [EiffelTestCaseStartedEvent](./EiffelTestCaseStartedEvent.md)) and/or other test suite executions. The executed test suite may be an ad-hoc transient grouping of test cases that were executed at a particular time or place or for a particular purpose or a persistent entity tracked in a test management system - Eiffel makes no distinction or assumptions either way. @@ -52,10 +52,145 @@ __Type:__ String __Required:__ Yes __Description:__ The URI at which the log can be retrieved. +## Links +### TERC +__Required:__ No +__Legal targets:__ [EiffelTestExecutionRecipeCollectionCreatedEvent](../eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md) +__Multiple allowed:__ No +__Description:__ This link signifies that the test suite represented by this event groups all test case executions resulting from the [EiffelTestExecutionRecipeCollectionCreatedEvent](../eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md). + +### CAUSE +__Required:__ No +__Legal targets:__ Any +__Multiple allowed:__ Yes +__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__. + +### CONTEXT +__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. + +### FLOW_CONTEXT +__Required:__ No +__Legal targets:__ [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFlowContextDefinedEvent.md) +__Multiple allowed:__ No +__Description:__ Identifies the flow context of the event: which is the continuous integration and delivery flow in which this occurred – e.g. which product, project, track or version this is applicable to. + +## Meta Members +### meta.id +__Type:__ String +__Format:__ [UUID](http://tools.ietf.org/html/rfc4122) +__Required:__ Yes +__Description:__ The unique identity of the event, generated at event creation. + +### meta.type +__Type:__ String +__Format:__ An event type name +__Required:__ Yes +__Description:__ The type of event. This field is required by the recipient of the event, as each event type has a specific meaning and a specific set of members in the __data__ and __links__ objects. + +### meta.version +__Type:__ String +__Format:__ [Semantic Versioning 2.0.0](http://semver.org/spec/v2.0.0.html) +__Required:__ Yes +__Description:__ The version of the event type. This field is required by the recipient of the event to interpret the contents. Please see [Versioning](../eiffel-syntax-and-usage/versioning.md) for more information. + +### meta.time +__Type:__ Integer +__Format:__ Milliseconds since epoch. +__Required:__ Yes +__Description:__ The event creation timestamp. + +### meta.tags +__Type:__ String[] +__Format:__ Free text +__Required:__ No +__Description:__ Any tags or keywords associated with the events, for searchability purposes. + +### meta.source +__Type:__ Object +__Format:__ +__Required:__ No +__Description:__ A description of the source of the event. This object is primarily for traceability purposes, and while optional, some form of identification of the source is __HIGHLY RECOMMENDED__. It offers multiple methods of identifying the source of the event, techniques which may be select from based on the technology domain and needs in any particular use case. + +#### meta.source.domainId +__Type:__ String +__Format:__ Free text +__Required:__ No +__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. + +#### meta.source.host +__Type:__ String +__Format:__ Hostname +__Required:__ No +__Description:__ The hostname of the event sender. + +#### meta.source.name +__Type:__ String +__Format:__ Free text +__Required:__ No +__Description:__ The name of the event sender. + +#### meta.source.serializer +__Type:__ Object +__Format:__ +__Required:__ No +__Description:__ The [GAV](https://maven.apache.org/guides/mini/guide-naming-conventions.html) coordinates of the serializer software used to construct the event. + +##### meta.source.serializer.groupId +__Type:__ String +__Format:__ groupId +__Required:__ Yes +__Description:__ The groupId of the serializer software. + +##### meta.source.serializer.artifactId +__Type:__ String +__Format:__ artifactId +__Required:__ Yes +__Description:__ The artifactId of the serializer software. + +##### meta.source.serializer.version +__Type:__ String +__Format:__ version +__Required:__ Yes +__Description:__ The version of the serializer software. + +#### meta.source.uri +__Type:__ String +__Format:__ URI +__Required:__ No +__Description:__ The URI of, related to or describing the event sender. + +### meta.security +__Type:__ Object +__Format:__ +__Required:__ No +__Description:__ An optional object for enclosing security related information, particularly supporting data integrity. See [Security](../eiffel-syntax-and-usage/security.md) for further information. + +#### meta.security.sdm +__Type:__ Object +__Format:__ +__Required:__ No +__Description:__ An optional object for properties supporting the [Strong Distribution Model](http://www.cryptnet.net/fdp/crypto/strong_distro.html). Note that this only addressed the _integrity_ of the Eiffel event, not its _confidentiality_ or _availability_. + +##### meta.security.sdm.authorIdentity +__Type:__ String +__Format:__ +__Required:__ Yes +__Description:__ The identity of the author of the event. This property is intended to enable the recipient to look up the appropriate public key for decrypting the digest and thereby verifying author identity and data integrity. The format of the author identity varies depending on the key infrastructure solution used. Note that this requires the presence of a Trusted Authority (TA) which the recipient can query for the correct public key. The identity and location of the TA must never be included in the event itself, as this would compromise the security of the solution. + +##### meta.security.sdm.encryptedDigest +__Type:__ String +__Format:__ +__Required:__ Yes +__Description:__ The encrypted digest. The cryptographic hash function and the decryption algorithm to use, similarly to the Trusted Authority (TA), must be known to the recipient. Note that the digest of the entire event is affected by the value of this property. For this reason the input to the hash function SHALL be the entire event unaltered in all parts except for this property, which SHALL be replaced by an empty string. + ## Version History | Version | Introduced in | Changes | | --------- | ------------------------------------------------------ | --------------------------------------- | | 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. | ## Examples -* [Simple example](../examples/events/EiffelTestSuiteStartedEvent/simple.json) \ No newline at end of file +* [Simple example](../examples/events/EiffelTestSuiteStartedEvent/simple.json)