The EiffelEnvironmentDefinedEvent declares an environment which may be referenced from other events in order to secure traceability to the conditions under which an artifact was created or a test was executed. Depending on the technology domain, the nature of an environment varies greatly however: it may be a virtual image, a complete mechatronic system of millions of independent parts, or anything in between. Consequently, a concise yet complete and generic syntax for describing any environment is futile.
From Eiffel's point of view, however, the prioritized concern is not description of the environment, but rather unambiguous identification of it. Consequently, the EiffelEnvironmentDefinedEvent syntax offers several alternatives to be selected from depending on the use case at hand: an environment may be described using data.image, data.host or data.uri. Exactly one of these properties SHOULD be included in any one event. In certain situations where an actual description of the environment is deemed redundant or its nature is implicit, the event MAY be used without any of these properties; it should be noted, however, that explicit practices are always encouraged over implicit ones.
Type: String
Required: Yes
Description: The name of the environment.
Type: String
Required: No
Description: The version of the environment, if any. This is in a sense redundant, as relationships between compositions can be tracked via the PREVIOUS_VERSION link type, but can be used for improved clarity and semantics.
Type: String
Required: No
Description: A string identifying e.g. a Docker image. While not a perfect description of an environment, in many cases it is both sufficient and conducive.
Type: Object
Required: No
Description: An object identifying a host. This object is included for pragmatic reasons, as this method of environment identification is often used in practice. It is discouraged, however, as it is highly unreliable both in terms of consistency and traceability. Consistency because consecutive executions on the same host may produce different results, as there are no inherent guarantees that it will stay the same over time. Traceability because when analyzing the historical record you want a static description of the environment as it was at the time of execution, not a pointer to a dynamic entity which may or may not have changed since then (and may or may not have changed again the next time you inspect it).
Type: String
Required: Yes
Description: The hostname.
Type: String
Required: Yes
Description: The user name on the host.
Type: String
Required: No
Description: A URI identifying the environment description. This is the catch-all method of environment descriptions. Eiffel does not concern itself with the format or nature of the description, but merely points to its location.
Required: No
Legal targets: EiffelEnvironmentDefinedEvent
Multiple allowed: Yes
Description: Identifies a latest previous version (there may be more than one in case of merges) of the environment.
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.
Required: No
Legal targets: EiffelActivityTriggeredEvent,
EiffelTestSuiteStartedEvent
Multiple allowed: No
Description: Identifies the activity or test suite of which this event constitutes a part.
Required: No
Legal targets: EiffelFlowContextDefinedEvent
Multiple allowed: Yes
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.
Type: String
Format: UUID
Required: Yes
Description: The unique identity of the event, generated at event creation.
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.
Type: String
Format: Semantic Versioning 2.0.0
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 for more information.
Type: Integer
Format: UNIX Epoch time, in milliseconds.
Required: Yes
Description: The event creation timestamp.
Type: String[]
Format: Free text
Required: No
Description: Any tags or keywords associated with the events, for searchability purposes.
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.
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.
Type: String
Format: Hostname
Required: No
Description: The hostname of the event sender.
Type: String
Format: Free text
Required: No
Description: The name of the event sender.
Type: String
Format: purl specification
Required: No
Description: The identity of the serializer software used to construct the event, in purl format.
Type: String
Format: URI
Required: No
Description: The URI of, related to or describing the event sender.
Type: Object
Format:
Required: No
Description: An optional object for enclosing security related information, particularly supporting data integrity. See Security for further information.
Type: Object
Format:
Required: No
Description: An optional object for properties supporting the Strong Distribution Model. Note that this only addressed the integrity of the Eiffel event, not its confidentiality or availability.
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.
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 | Introduced in | Changes |
---|---|---|
2.0.0 | Current version | Introduced purl identifiers instead of GAVs (see Issue 182) |
1.1.0 | edition-toulouse | Multiple links of type FLOW_CONTEXT allowed. |
1.0.0 | edition-bordeaux | Initial version. |