Skip to content

Latest commit

 

History

History
240 lines (194 loc) · 13.6 KB

EiffelConfidenceLevelModifiedEvent.md

File metadata and controls

240 lines (194 loc) · 13.6 KB

EiffelConfidenceLevelModifiedEvent (CLM)

The EiffelConfidenceLevelModifiedEvent declares that an entity has achieved (or failed to achieve) a certain level of confidence, or in a broader sense to annotate it as being applicable or relevant to a certain case (e.g. fit for release to a certain customer segment or having passed certain criteria). This is particularly useful for promoting various engineering artifacts, such as product revisions, through the continuous integration and delivery pipeline.

Confidence levels may operate at high or low levels of abstraction - ranging from "smokeTestsOk" to "releasable" or "released" - and they may group other confidence levels of lower abstraction levels. They may also be general or very niched, e.g. "releasable" or "releasableToCustomerX". Confidence levels frequently figure in automated delivery interfaces within a tiered system context: lower level tiers issue an agreed confidence level signaling that a new version is ready for integration in a higher level tier.

Data Members

data.name

Type: String
Required: Yes
Description: The name of the confidence level. It is recommended for confidence level names to conform with camelCase formatting, in line with the format of key names of the Eiffel protocol as a whole.

data.value

Type: String
Required: Yes
Legal values: SUCCESS, FAILURE, INCONCLUSIVE
Description: The value of the confidence level. SUCCESS signifies that the confidence level has been successfully achieved.
FAILURE signifies that the confidence level could not be achieved. INCONCLUSIVE signifies that achievement of the confidence level could not be determined.

data.issuer

Type: Object
Required: No
Description: The individual or entity issuing the confidence level.

data.issuer.name

Type: String
Required: No
Description: The name of the issuer.

data.issuer.email

Type: String
Required: No
Description: The e-mail address of the issuer.

data.issuer.id

Type: String
Required: No
Description: Any identity, alias or handle of the issuer, such as a corporate id or username.

data.issuer.group

Type: String
Required: No
Description: Any group, such as a development team, committee or test group, to which the issuer belongs.

Links

This section describes which link types are valid for this event type. For details on how to express the link objects themselves see The Links Object.

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.

CONFIDENCE_BASIS

Required: No
Legal targets: EiffelConfidenceLevelModifiedEvent, EiffelTestCaseFinishedEvent, EiffelTestSuiteFinishedEvent
Multiple allowed: Yes
Description: Used to declare the basis for which confidence statement(s) this event have used. The CAUSE link tells what caused the event sending whereas CONFIDENCE_BASIS declares the reason for selecting the provided data.name and/or data.value.

CONTEXT

Required: No
Legal targets: EiffelActivityTriggeredEvent, EiffelTestSuiteStartedEvent
Multiple allowed: No
Description: Identifies the activity or test suite of which this event constitutes a part.

FLOW_CONTEXT

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.

SUBJECT

Required: Yes
Legal targets: EiffelArtifactCreatedEvent, EiffelArtifactDeployedEvent, EiffelCompositionDefinedEvent, EiffelSourceChangeCreatedEvent, EiffelSourceChangeSubmittedEvent
Multiple allowed: Yes
Description: Identifies a subject of the confidence level; in other words, what the confidence level applies to.

SUB_CONFIDENCE_LEVEL

Required: No
Legal targets: EiffelConfidenceLevelModifiedEvent
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. Future editions might deprecate this link in favour of CONFIDENCE_BASIS.

Meta Members

meta.id

Type: String
Format: UUID
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
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.

meta.time

Type: Integer
Format: UNIX Epoch time, in milliseconds.
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
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.

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: String
Format: purl specification
Required: No
Description: The identity of the serializer software used to construct the event, in purl format.

meta.source.uri

Type: String
Format: URI
Required: No
Description: The URI of, related to or describing the event sender.

meta.security

Type: Object
Required: No
Description: An optional object for enclosing security related information, particularly supporting data integrity. See Security for further information.

meta.security.authorIdentity

Type: String
Format: Distinguished Name
Required: Yes
Description: The identity of the author of the event. This property is intended to enable the recipient to identify the author of the event contents and/or look up the appropriate public key for decrypting the meta.security.integrityProtection.signature value and thereby verifying author identity and data integrity.

meta.security.integrityProtection

Type: Object
Required: No
Description: An optional object for enabling information integrity protection via cryptographic signing. To generate a correct meta.security.integrityProtection object:

  1. Generate the entire event, but with the meta.security.integrityProtection.signature value set to an empty string.
  2. Serialize the event on Canonical JSON Form.
  3. Generate the signature using the meta.security.integrityProtection.alg algorithm.
  4. Set the meta.security.integrityProtection.signature value to the resulting signature while maintaining Canonical JSON Form. To verify the integrity of the event, the consumer then resets meta.security.integrityProtection.signature to an empty string and ensures Canonical JSON Form before verifying the signature.
meta.security.integrityProtection.signature

Type: String
Required: Yes
Description: The signature produced by the signing algorithm.

meta.security.integrityProtection.alg

Type: String
Format: A valid JWA RFC 7518 alg parameter value, excluding "none"
Required: Yes
Description: The cryptographic algorithm used to digitally sign the event. If no signing is performed, the meta.security.integrityProtection SHALL be omitted rather than setting meta.security.integrityProtection.alg to "none".

meta.security.integrityProtection.publicKey

Type: String
Required: No
Description: The producer of the event may include the relevant public key for convenience, rather than relying a separate key distribution mechanism. Note that this property, along with the rest of the event, is encompassed by the integrity protection offered via meta.security.integrityProtection.

meta.security.sequenceProtection

Type: Object[]
Required: No
Description: An optional object for enabling verification of intact event sequences in a distributed environment, thereby protecting against data loss, race conditions and replay attacks. It allows event publishers to state the order in which they produce a certain set of events. In other words, it cannot provide any global guarantees as to event sequencing, but rather per-publisher guarantees. Every object in the array represents a named sequence of which this event forms a part. For every event including a given named sequence, the publisher SHALL increment meta.security.sequenceProtection.position by 1. The first event produced in a given named sequence SHALL numbered 1.

meta.security.sequenceProtection.sequenceName

Type: String
Required: Yes
Description: The name of the sequence. There MUST not be two identical meta.security.sequenceProtection.sequenceName values in the same event.

meta.security.sequenceProtection.position

Type: Integer
Required: Yes
Description: The number of the event within the named sequence.

meta.schemaUri

Type: String
Format: URI
Required: No
Description: A URI pointing at a location from where the schema used when creating this event can be retrieved. It can be used to parse event data for validation and extraction purposes, for example. Note, that the schema on that URI should be considered immutable.

Version History

Version Introduced in Changes
4.0.0 Not yet released in an edition Update meta schema to Draft 2020-12 and add link validation.
3.4.0 Not yet released in an edition Add CONFIDENCE_BASIS link (see Issue 323).
3.3.0 edition-orizaba Add EiffelArtifactDeployedEvent as legal target type for SUBJECT link (see Issue 239).
3.2.0 edition-arica Add schema URL to the meta object (see Issue 280).
3.1.0 edition-lyon Add links.domainId member (see Issue 233).
3.0.0 edition-agen Improved information integrity protection (see Issue 185).
2.0.0 edition-agen 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.

Examples