DPP Annex: Sequenz Diagram for updating DPP

documentation/IDTA-01002-3/modules/ROOT/pages/annex/dpp.adoc

@@ -125,9 +125,9 @@
 | Shall resolve the product identifier to an AAS (via `globalAssetId`) and compose the DPP document. 
 
 [Note]
-===
+====
 Multiple AAS instances might be associated with the provided product identifier.
-===
+====
 
 | ReadDPPVersionByIdAndDate
 | GetAssetAdministrationShellVersionByIdAndDate / QueryAssetAdministrationShells / QueryAssetAdministrationShellDescriptors + GetSubmodel (Value-Only or Normal) for each referenced and relevant Submodel
@@ -333,6 +333,55 @@
 ....
 
 
+== Updating DPPs including Historization
+
+EN 18222 defines the UpdateDPPById and UpdateDataElement methods for changing the DPP.
+They are mandatory to be provided in case there are recyclers or professional repairers etc. who are obliged to update the DPP.
+
+The input is a partial DPP. 
+Although not explicitly stated in EN 18222 it is assumed this partial DPP payload is conformant to link:https://datatracker.ietf.org/doc/html/rfc7396[RFC 7396 - JSON Merge Patch], 
+i.e. the patch document has the same structure as the target document but contains only the changes.
+Fields included in the patch overwrite existing ones; missing fields remain unchanged; fields explicitly set to null are deleted.
+
+
+[Note]
+====
+Although the economic operator or DPP service provider may use the same update methods this is not mandatory.
+====
+
+To implement UpdateDPPById, an implementation shall perform the following steps for the AAS affected and its Submodels:
+
+* For all  AAS and Submodels changed the administration/updatedAt date shall be set. 
+The date value shall be identical.
+* For all  AAS and Submodels changed the administration/version and administration/revision should be set by increasing the version and setting the revision to '0' 
+[Note]
+====
+It is proposed to always assume that the result is a new major version of the AAS or Submodel.
+====
+* Before calling the corresponding AAS API operations the serialization might need to be aligned.
+This also depends on the serialization format that is used for the update.
+If Value-Only serialization is used then additionally, a Normal serialization patch is needed for updating the administrative data like "createdAt" attribute.
+For details on mapping see IDTA-01001.
+* Ensure that a previous version and the new version of the AAS and the affected Submodels are stored. 
+Only then the ReadDPPVersionByIdAndDate operation for retrieving the version of a DPP that was current at a specified point in time can be supported that is used for implementing ReadDPPVersionByIdAndDate (see <<readdppversionbyidanddate>>).
+See link:https://industrialdigitaltwin.io/aas-specifications/IDTA-01001/v3.3/spec-metamodel/common.html#administrative-information-attributesIDTA-01001[information on administrative information] in IDTA-01001.
+[Note]
+====
+Former version numbers of the AAS and its Submodels shall be distinguished from their current version. 
+So in the example <<image-seq-dpp-update-repo-history>> it is assumed that there are two repositories, one containing the current versions and one for the older versions.
+Although the API interfaces are the same only the History Repository is supporting the xref:http-rest-api/service-specifications-and-profiles.adoc#submodel-repository-service-specification-ssp-007[history profile]
+whereas the "normal" Repository is for example supporting xref:http-rest-api/service-specifications-and-profiles.adoc#submodel-repository-service-specification-ssp-001[the full profile].
+
+<<image-seq-dpp-update-repo-history>> shows a possible sequence of steps to update a DPP by updating the corresponding AAS and its Submodels who are affected by the change.
+
+
+.UpdateDPPById Sequence via AAS and Submodel (History) Repository
+[[image-seq-dpp-update-repo-history]]
+[plantuml, seq-dpp-update-repo-history, svg]
+....
+include::partial$diagrams/seq-dpp-update-repo-history.puml[]
+....
+
 == HTTP API Mapping
 
 The DPP operations described above shall be exposed through an HTTP REST API following the specifications of the Asset Administration Shell Services (EN 18222, Clause 8). In-path identifiers shall be percent-encoded.

documentation/IDTA-01002-3/modules/ROOT/partials/diagrams/seq-dpp-update-repo-history.puml

@@ -0,0 +1,88 @@
+@startuml
+
+participant DPPClient as "Recycler"
+
+box "DPP Service"
+participant Client as "DPP Application"
+end box
+
+
+
+
+box "AAS Repository Service"
+  participant AASService as "AAS Repository Interface"
+end box
+
+box "Submodel Repository Service"
+  participant SMService as "Submodel Repository Interface"
+end box
+
+box "AAS Repository History Service"
+  participant AASHistoryService as "AAS Repository Interface"
+end box
+
+box "Submodel Repository History Service"
+  participant SMHistoryService as "Submodel Repository Interface"
+end box
+
+activate DPPClient
+DPPClient -> Client : UpdateDPPById(dppId, partialDPP)
+
+activate Client
+Client <- Client : map dppId to aasId
+Client <- Client : identify updatedAt value
+
+Client -> AASService : GetAssetAdministrationShellById(aasId) \n- store version of AAS
+activate AASService
+Client <-- AASService :  AAS
+Client -> AASService : set updatedAt and increase version information for AAS
+Client -> AASService :PutAssetAdministrationShellById(aasId,updated AAS)
+
+
+
+
+AASService -> AASHistoryService : PutAssetAdministrationShellById(aasId,AAS) \n- store version of AAS
+activate AASHistoryService
+AASService <-- AASHistoryService : historized AAS
+deactivate AASHistoryService
+Client <-- AASService : updated AAS incl. Submodel references
+deactivate AASService
+Client <- Client : serialize the Submodel payload
+Client -> SMService : PutSubmodelById(Submodel ID for DPP Metadata)
+activate SMService
+
+SMService -> SMHistoryService : PutSubmodelById - store version of DPP Metadata
+activate SMHistoryService
+SMService <-- SMHistoryService : historized DPP Metadata Submodel
+
+deactivate SMHistoryService
+Client <-- SMService : Submodel DPP Metadata (includes contentSpecificationIds) 
+deactivate SMService
+Client -> Client : extract relevant Submodel IDs\n for which there are changes
+
+
+note left of Client
+  i.e. content Submodels with 
+  semanticId   as specified 
+  in contentSpecificationIds
+end note
+
+loop for all relevant Submodels
+Client <- Client : serialize the Submodel payload
+Client -> SMService :PutSubmodelById(ById)
+activate SMService
+
+activate SMHistoryService
+SMService -> SMHistoryService : PutSubmodelById - store version
+SMService <-- SMHistoryService : historized content Submodel
+deactivate SMHistoryService
+Client <-- SMService : content Submodel
+deactivate SMService
+end
+
+Client <- Client : serialize and assemble DPP \ndocument (see ReadDPPByProductId)
+DPPClient <-- Client : return DPP
+deactivate Client
+deactivate DPPClient
+
+@enduml