Events emitted by AAS Repositories

Events emitted by Submodel Repositories

SubmodelElement-level Events emitted by Submodel Repositories

Specification for Messaging with the Asset Administration Shell

Introduction

The aim of this specification is to define a messaging mechanism through which events concerning resources from the Asset Administration Shell specification (IDTA-01001, IDTA-01002) can be communicated to interested data consumers.

This specification complements the AAS REST API by introducing a message payload for the events. While the REST API is designed to specify the synchronous retrieval and manipulation of data, the events enable notifications to data consumers. Specifically, it ensures that data consumers are immediately informed of any changes to the data in the AAS repository, thereby enhancing responsiveness and eliminating the need for frequent polling/scraping of the repository to discover data updates.

MQTT Concept

Normative Disclaimer

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY in this document are to be interpreted as described in RFC 2119.

Message Semantics

All messages in this specification conform to the CloudEvents 1.0 envelope format and carry a payload indicating a state change in an AAS repository. Each message is classified by the resource type it concerns and the lifecycle event that triggered it. Providers MUST use the payload#39;s type field to signal the nature of the event to the consumers allowing them to decide on processing it without inspecting the rest of the payload.

Events

Events represent notifications about changes that occur in an AAS repository. They are generated whenever the state of an AAS, a Submodel (SM), or a SubmodelElement (SME) changes.

Events allow external systems to observe these changes without continuously polling the repository. Instead, subscribers receive notifications through the messaging infrastructure whenever relevant updates occur.

An implementation MUST trigger an event whenever an observable state of the AAS repository changes. An event SHOULD NOT be triggered if an operation does not actually change the stored data.

Generic Event Types

The messaging model distinguishes several event types that describe the type of change that occurred.

The following event types are used:

The chosen event type should reflect the semantic meaning of the change.

Generic AAS Interfaces

IDTA has specified generic interfaces for AAS and its corresponding software: Details of the AAS, Part 2: Application Programming Interfaces. The events in this repo are based on these abstract interfaces. This section summarizes the spec. The specified generic interface methods are (based on, but not limited to, HTTP REST):

These interface methods are applied to all kinds of AAS-related resources, i.e. including Asset Administration Shells, Asset, Submodels, Submodel Elements, Descriptors, References, etc. - forming interface operations, e.g. GetAllSubmodels.
Qualifiers define how the operation is carried out, e.g. ById or ByPath. For instance, the operation for replacing a Submodel Element builds the operation PutSubmodelElementByPath (Creates a new or replaces an existing submodel element at a specified path within the submodel element hierarchy). The operation DeleteAssetAdministrationShellById deletes an AAS based on the unique AAS identifier.

Relations of Event Types to AAS Interfaces

As specified before, this event-based messaging method for the AAS addresses following events: ElementCreated, ElementDeleted, ElementUpdated, ValueChanged. That means that some of the generic AAS interfaces are not utilized in this project, e.g. every operation featuring GET. Relevant for the asyncrounous event messaging remain:

However, a simple matching between the event ElementUpdated amp; the interface PUT (as well as between ElementDeleted amp; DELETE, ElementCreated amp; POST and ValueCahnged amp; PATCH) is not feasible. Example: PutAssetAdministrationShell could cause ElementUpdated or ElementDeleted amp; ElementCreated, depending on whether ID of the AAS is new.

Asset Administration Shell Events

AAS Element Created

io.admin-shell.events.v1.created — Triggered when a new AAS is persisted in the repository. If present, the data property contains the full representation of the newly created AAS, allowing consumers to immediately act on it without issuing a follow-up retrieval request. This event MUST be triggered exactly once per AAS creation and MUST NOT be triggered for subsequent modifications to the same AAS. The dataschema property can only reference the AAS metamodel element.

The following interface operations will trigger this event:

(quot;*quot; indicates a mandatory parameter)

HTTP REST Example:

POST /shells

Headers: 
Accept: aaplication/json
Content-Type: application/json

Body:
{
   quot;idquot;:quot;aas-idquot;,
   quot;idShortquot;:quot;aas-short-idquot;,
   quot;assetInformationquot;:{
      quot;assetKindquot;:quot;Instancequot;,
      quot;globalAssetIdquot;:quot;asset-idquot;
   }
}

AAS Element Updated

io.admin-shell.events.v1.updated — Triggered when the metadata or structural composition of an existing AAS changes. Changes that trigger this event include modifications to the AAS#39;s administrative information, asset information, or the set of SM references it holds. If present, the data property contains the updated element in its entirety after the change. Consumers SHOULD treat receipt of this event as an authoritative replacement for any previously held state of the element identified by the same identifier. The dataschema property can only reference elements with their own HTTP endpoint and schema, for example asset-information or submodel-refs.

The following interface operations will trigger this event:

(quot;*quot; indicates a mandatory parameter)

HTTP REST Example:

PUT /shells/{aas-id-base64}/asset-information

Headers: 
Accept: aaplication/json
Content-Type: application/json

Body:
{
  quot;assetKindquot;: quot;Instancequot;,
  quot;globalAssetIdquot;: quot;new-asset-idquot;
}

Submodel Events

Submodel Created

io.admin-shell.events.v1.created — Triggered when a new SM is persisted in the repository. If present, the data property contains the full SM representation, including its semantic identification and all SM elements present at creation time. This event MUST be triggered exactly once when a SM is first created and MUST NOT be triggered for subsequent changes to that SM. The dataschema property can only reference the SM metamodel element.

The following interface operations will trigger this event:

(quot;*quot; indicates a mandatory parameter)

HTTP REST Example:

POST /submodels

Headers: 
Accept: aaplication/json
Content-Type: application/json

Body:
{
  quot;idquot;: quot;sm-idquot;,
  quot;idShortquot;: quot;sm-id-shortquot;,
  quot;submodelElementsquot;: []
}

Submodel Updated

io.admin-shell.events.v1.updated — Triggered when the metadata of an existing SM changes. This event concerns structural or descriptive changes at the SM level itself — such as changes to its semantic identification, administrative information, or kind — and is distinct from any changes to individual SME within it. If present, the data property contains the updated SM representation. Consumers SHOULD treat receipt of this event as an authoritative replacement for any previously held state of the shell identified by the same identifier. The dataschema property can only reference the SM metamodel element as SMEs are handled elsewhere.

The following interface operations will trigger this event:

(quot;*quot; indicates a mandatory parameter)

HTTP REST Example:

PUT /submodels/{sm-id-base64}

Headers: 
Accept: aaplication/json
Content-Type: application/json

Body:
{
  quot;idquot;: quot;sm-idquot;,
  quot;idShortquot;: quot;new-sm-id-shortquot;,
  quot;submodelElementsquot;: []
}

Submodel Deleted

io.admin-shell.events.v1.deleted — Triggered when a SM is permanently removed from the repository. The AAS payload is absent; the identity of the deleted resource is conveyed through the source property in the envelope. Consumers MUST consider any locally cached state for the identified SM invalid upon receipt of this event.

The following interface operations will trigger this event:

(quot;*quot; indicates a mandatory parameter)

HTTP REST Example:

DELETE /submodels/{sm-id-base64}

Headers: 
Accept: aaplication/json
Content-Type: application/json

SubmodelElement Events

SubmodelElement Created

io.admin-shell.events.v1.created — Triggered when a new SME is added to an existing Submodel. The source reference in the envelope identifies the containing element or Submodel into which the new element was inserted. The data property contains the full representation of the newly created SME. This event MUST be triggered exactly once per element creation.

The following interface operations will trigger this event:

(quot;*quot; indicates a mandatory parameter)

HTTP REST Example:

POST /submodels/{sm-id-base64}/submodelElements

Headers: 
Accept: aaplication/json
Content-Type: application/json

Body:
{
  quot;idShortquot;: quot;test-propertyquot;,
  quot;modelTypequot;: quot;Propertyquot;,
  quot;valueTypequot;: quot;xs:doublequot;,
  quot;valuequot;: quot;25.0quot;
}

Value Changed

io.admin-shell.events.v1.valueChanged — Triggered when the value of a DataElement changes while the element itself remains structurally unmodified. If any other attribute changes, a SME Updated event is triggered. If present, the data property contains the SME in its updated state. Consumers SHOULD use this event as the primary mechanism for tracking live data updates in an AAS deployment.

The following interface operations will trigger this event:

(quot;*quot; indicates a mandatory parameter)

HTTP REST Example:

PATCH /submodels/{sm-id-base64}/submodel-elements/{sme}/value

Headers: 
Accept: aaplication/json
Content-Type: application/json

Body:
10.0

SubmodelElement Updated

io.admin-shell.events.v1.updated — Triggered when the structure or metadata of an existing SME changes in a way other than a pure value change. This includes changes to semantic identification, qualifiers, or category. If present, the data property contains the updated element representation. Consumers SHOULD replace any previously held state of the identified element upon receipt.

The following interface operations will trigger this event:

(quot;*quot; indicates a mandatory parameter)

HTTP REST Example:

PUT /submodels/{sm-id-base64}/submodel-elements/{sme}

Headers: 
Accept: aaplication/json
Content-Type: application/json

Body: 
{
  quot;idShortquot;: quot;new-test-propertyquot;,
  quot;modelTypequot;: quot;Propertyquot;,
  quot;valueTypequot;: quot;xs:doublequot;,
  quot;valuequot;: quot;25.0quot;
}

SubmodelElement Deleted

io.admin-shell.events.v1.deleted — Triggered when a SME is removed from its containing Submodel, SubmodelElementList or SubmodelElementCollection. The source property in the envelope identifies the deleted SME. The SME payload is absent from the event. Consumers MUST invalidate any locally cached state for the deleted element upon receipt.

The following interface operations will trigger this event:

(quot;*quot; indicates a mandatory parameter)

HTTP REST Example:

DELETE /submodels/{sm-id-base64}/submodel-elements/{sme}

Headers: 
Accept: aaplication/json
Content-Type: application/json

Operation Invoked

io.admin-shell.events.v1.invoked — Triggered when an Operation SME is invoked by a client. If present, the data property contains the Operation element including the InputArguments and InoutputArguments supplied by the invoking client. Receipt of this event does not imply that the Operation has completed or succeeded.

The following interface operations will trigger this event:

(quot;*quot; indicates a mandatory parameter)

Operation Finished

io.admin-shell.events.v1.finished — Triggered when an Operation completes, regardless of whether it succeeded or failed. If present, the data property contains the InoutputArguments and OutputArguments as produced as the operation result. Consumers correlate this event with a Operation using the source property in the envelope. This event MUST be triggered exactly once per completed Operation.

The following interface operations will trigger this event:

(quot;*quot; indicates a mandatory parameter)