Kmohr-soprasteria/issue1199

spec/MicroWaveDeviceInventory+config.json

@@ -1096,7 +1096,7 @@
                 "operation-name": "/v1/regard-controller-attribute-value-change"
               },
               "operation-server-interface-configuration": {
-                "life-cycle-state": "operation-server-interface-1-0:LIFE_CYCLE_STATE_TYPE_EXPERIMENTAL",
+                "life-cycle-state": "operation-server-interface-1-0:LIFE_CYCLE_STATE_TYPE_DEPRECATED",
                 "operation-key": "n.a."
               }
             }
@@ -1120,7 +1120,7 @@
                 "operation-name": "/v1/regard-device-alarm"
               },
               "operation-server-interface-configuration": {
-                "life-cycle-state": "operation-server-interface-1-0:LIFE_CYCLE_STATE_TYPE_EXPERIMENTAL",
+                "life-cycle-state": "operation-server-interface-1-0:LIFE_CYCLE_STATE_TYPE_DEPRECATED",
                 "operation-key": "n.a."
               }
             }
@@ -1144,7 +1144,7 @@
                 "operation-name": "/v1/regard-device-attribute-value-change"
               },
               "operation-server-interface-configuration": {
-                "life-cycle-state": "operation-server-interface-1-0:LIFE_CYCLE_STATE_TYPE_EXPERIMENTAL",
+                "life-cycle-state": "operation-server-interface-1-0:LIFE_CYCLE_STATE_TYPE_DEPRECATED",
                 "operation-key": "n.a."
               }
             }
@@ -1168,7 +1168,7 @@
                 "operation-name": "/v1/regard-device-object-creation"
               },
               "operation-server-interface-configuration": {
-                "life-cycle-state": "operation-server-interface-1-0:LIFE_CYCLE_STATE_TYPE_EXPERIMENTAL",
+                "life-cycle-state": "operation-server-interface-1-0:LIFE_CYCLE_STATE_TYPE_DEPRECATED",
                 "operation-key": "n.a."
               }
             }
@@ -1192,7 +1192,7 @@
                 "operation-name": "/v1/regard-device-object-deletion"
               },
               "operation-server-interface-configuration": {
-                "life-cycle-state": "operation-server-interface-1-0:LIFE_CYCLE_STATE_TYPE_EXPERIMENTAL",
+                "life-cycle-state": "operation-server-interface-1-0:LIFE_CYCLE_STATE_TYPE_DEPRECATED",
                 "operation-key": "n.a."
               }
             }

spec/MicroWaveDeviceInventory+services.yaml

@@ -57,7 +57,7 @@ servers:
           uuid: mwdi-1-3-0-op-s-bs-005
           operation-key: n.a.
       individual:
-        # receivers for notifications from NotificationProxy
+        # receivers for notifications from NotificationProxy: deprecated since v1.3.0
         - operation-name: /v1/regard-controller-attribute-value-change
           uuid: mwdi-1-3-0-op-s-is-000
           operation-key: n.a.

spec/MicroWaveDeviceInventory.yaml

@@ -841,6 +841,10 @@ paths:
                   $ref: '#/components/responses/responseForErroredServiceRequests'
 
   /v1/regard-controller-attribute-value-change:
+    description: >
+      'DEPRECATED
+      Service shall be deleted with MWDI v2.0.0
+      Starting from MWDI v1.3.0, service shall no longer be used'
     parameters:
       - $ref: '#/components/parameters/user'
       - $ref: '#/components/parameters/originator'
@@ -1009,6 +1013,10 @@ paths:
                 default:
                   $ref: '#/components/responses/responseForErroredServiceRequests'
   /v1/regard-device-alarm:
+    description: >
+      'DEPRECATED
+      Service shall be deleted with MWDI v2.0.0
+      Starting from MWDI v1.3.0, service shall no longer be used'
     parameters:
       - $ref: '#/components/parameters/user'
       - $ref: '#/components/parameters/originator'
@@ -1181,6 +1189,10 @@ paths:
                 default:
                   $ref: '#/components/responses/responseForErroredServiceRequests'
   /v1/regard-device-attribute-value-change:
+    description: >
+      'DEPRECATED
+      Service shall be deleted with MWDI v2.0.0
+      Starting from MWDI v1.3.0, service shall no longer be used'
     parameters:
       - $ref: '#/components/parameters/user'
       - $ref: '#/components/parameters/originator'
@@ -1313,6 +1325,10 @@ paths:
                 default:
                   $ref: '#/components/responses/responseForErroredServiceRequests'
   /v1/regard-device-object-creation:
+    description: >
+      'DEPRECATED
+      Service shall be deleted with MWDI v2.0.0
+      Starting from MWDI v1.3.0, service shall no longer be used'
     parameters:
       - $ref: '#/components/parameters/user'
       - $ref: '#/components/parameters/originator'
@@ -1417,6 +1433,10 @@ paths:
                 default:
                   $ref: '#/components/responses/responseForErroredServiceRequests'
   /v1/regard-device-object-deletion:
+    description: >
+      'DEPRECATED
+      Service shall be deleted with MWDI v2.0.0
+      Starting from MWDI v1.3.0, service shall no longer be used'
     parameters:
       - $ref: '#/components/parameters/user'
       - $ref: '#/components/parameters/originator'

spec/diagrams/diagrams_for_deprecated_regard_services_(notifications)/deprecated_-1020_NotificationBasedDeviceListSyncAdd.plantuml

@@ -0,0 +1,36 @@
+@startuml -1020_NotificationBasedDeviceListSyncAdd
+skinparam responseMessageBelowArrow true
+
+title  
+  NotifiedNewDeviceCausesSelfCallingForLoadingOfControlConstruct
+  NotifiedNewDeviceCausesMetadataTableUpdate
+end title
+
+participant "NP://v1/notify-controller-attribute-value-changes" as subscription
+participant "MWDI://v1/regard-controller-attribute-value-change" as regardNewDevice
+participant "MWDI://core-model-1-4:network-control-domain=live/control-construct={mountName}" as liveControlConstruct
+participant "ElasticSearch\n(metadataTable)" as es
+
+subscription -> regardNewDevice: AttributeValueChangedNotification (apiKeyAuth)
+activate regardNewDevice
+
+note over regardNewDevice
+IF attribute-name == 'connection-status' 
+AND IF new-value == 'connected'
+end note
+
+regardNewDevice -> liveControlConstruct: {path = first part of resource incl. control-construct} (apiKeyAuth)
+
+note over regardNewDevice
+  <u>UpdateMetadataTable</u>
+      Either add the device to the metadataTable,
+      if it is not included yet, or update the existing 
+      entry.
+      (see description under <i>spec/additionalDescription/</i>
+      <i>MetadataTableUpdateProcess.md</i>)  
+end note
+regardNewDevice -> es: {mountName from notification}
+
+deactivate regardNewDevice
+
+@enduml

spec/diagrams/diagrams_for_deprecated_regard_services_(notifications)/deprecated_-1021_NotificationBasedDeviceListSyncDelete.plantuml

@@ -0,0 +1,35 @@
+@startuml -1021_NotificationBasedDeviceListSyncDelete
+skinparam responseMessageBelowArrow true
+
+title  
+  NotifiedDisconnectedDeviceCausesDeviceDeletionFromCache
+  NotifiedDisconnectedDeviceCausesMetadataTableUpdate
+end title
+
+participant "NP://v1/notify-controller-attribute-value-changes" as subscription
+participant "MWDI://v1/regard-controller-attribute-value-change" as regardDisconnectedDevice
+participant "ElasticSearch://control-construct={mountName}" as es
+participant "ElasticSearch\n(metadataTable)" as es
+
+subscription -> regardDisconnectedDevice: notification {mount-name} (apiKeyAuth)
+activate regardDisconnectedDevice
+
+note over regardDisconnectedDevice
+IF attribute-name == 'connection-status' 
+AND IF new-value != 'connected'
+end note
+
+regardDisconnectedDevice -> es: delete {mount-name = value behind control-construct= in resource}
+
+
+note over regardDisconnectedDevice
+  <u>UpdateMetadataTable</u>
+      Update the device record according to the description in
+      <i>spec/additionalDescription/MetadataTableUpdateProcess.md</i>.
+end note
+regardDisconnectedDevice -> es: {mountName from notification}
+
+
+deactivate regardDisconnectedDevice
+
+@enduml

spec/diagrams/diagrams_for_deprecated_regard_services_(notifications)/deprecated_-1022_NotificationBasedAlarmListUpdate.plantuml

@@ -0,0 +1,69 @@
+@startuml -1022_NotificationBasedAlarmListUpdate
+
+skinparam responseMessageBelowArrow true
+
+title 
+  NotifiedDeviceAlarmCausesUpdatingTheEntryInCurrentAlarmListOfCache
+  NotifiedDeviceAlarmCausesMetadataTableUpdate
+end title
+
+participant "NP://v1/notify-device-alarms" as subscription
+participant "MWDI://v1/regard-device-alarm" as regardAlarm
+participant "ElasticSearch://control-construct={mountName}/alarms-1-0:alarm-pac/current-alarms" as CurrentAlarms
+participant "ElasticSearch\n(metadataTable)" as es
+
+subscription -> regardAlarm: {counter, timestamp, resource, alarm-type-id, alarm-type-qualifier, severity} (apiKeyAuth)
+activate regardAlarm
+
+regardAlarm -> CurrentAlarms: GET {mount-name = value behind control-construct= in resource}
+CurrentAlarms --> regardAlarm: {currentAlarmList, numberOfCurrentAlarms, timeOfLatestChange}
+
+note over regardAlarm
+Entry in CurrentAlarmList is identified by 3 key attribute values:
+1. alarm-type-id
+2. alarm-type-qualifier
+3. resource
+It might make sense to read the entire list, search for the notified entry, change the list and write it back to cache
+
+IF request.body.problem-severity != CLEARED:
+- currentAlarmList to be complemented by content of AlarmNotification
+- numberOfCurrentAlarms++
+- timeOfLatestChange=request.body.timestamp
+
+IF request.body.problem-severity == CLEARED:
+- content of Alarmnotification to be removed from currentAlarmList
+- numberOfCurrentAlarms--
+- timeOfLatestChange=request.body.timestamp
+end note
+
+regardAlarm -> CurrentAlarms: PUT {currentAlarmList, numberOfCurrentAlarms, timeOfLatestChange}
+
+note over regardAlarm
+  <u>UpdateMetadataTable</u>
+    Upon update completion of the CC data in the cache,
+    update the metadata table for the device
+    (last-control-construct-notification-update-time,
+    number-of-partial-updates-since-last-complete-update)
+end note
+regardAlarm -> es: {mount-name}
+
+deactivate regardAlarm
+
+note over CurrentAlarms
+Remark 1: 
+MWDI://v1/regard-device-alarm 
+initiates ObjectCreationNotifications and ObjectDeletionNotifications, 
+but no AlarmNotifications 
+at MWDI NBI
+end note
+
+note over CurrentAlarms
+Remark 2: 
+There would be an alternative way.
+Instead of loading the list of current alarms from cache, updating it, and writing it back into the cache,
+self-calling of MWDI://core-model-1-4:network-control-domain=live/control-construct={mountName}/alarms-1-0:alarm-pac/current-alarms would lead to the same result.
+The latter way would be slower, but probably compensate missed alarm notifications.
+The implementer to comment on the preferred way.
+end note
+
+@enduml

spec/diagrams/diagrams_for_deprecated_regard_services_(notifications)/deprecated_-1023_NotificationBasedAttributeUpdate.plantuml

@@ -0,0 +1,46 @@
+@startuml -1023_NotificationBasedAttributeUpdate
+skinparam responseMessageBelowArrow true
+
+title 
+  NotifiedDeviceAttributeValueChangeCausesUpdateOfCache
+  NotifiedDeviceAttributeValueChangeCausesMetadataTableUpdate
+end title
+
+participant "NP://v1/notify-device-attribute-value-changes" as subscription
+participant "MWDI://v1/regard-device-attribute-value-change" as regardAttributeChange
+participant "ElasticSearch://{resource}" as es
+participant "ElasticSearch\n(metadataTable)" as mtab
+
+subscription -> regardAttributeChange: {counter, timestamp, resource, attributeName, newValue} (apiKeyAuth)
+activate regardAttributeChange
+
+regardAttributeChange -> es: GET
+es --> regardAttributeChange: class
+
+note over regardAttributeChange
+Value of the {attributeName} attribute to be replaced by {newValue}
+end note
+
+regardAttributeChange -> es: PUT
+deactivate regardAttributeChange
+
+note over regardAttributeChange
+  <u>UpdateMetadataTable</u>
+    Upon update completion of the CC data in the cache,
+    update the metadata table for the device
+    (last-control-construct-notification-update-time,
+    number-of-partial-updates-since-last-complete-update)
+end note
+regardAttributeChange -> es: {mount-name}
+
+
+note over es
+Remark: 
+There would be an alternative way.
+Instead of loading the class from cache, updating the changed attribute, and writing the class back into the cache,
+self-calling of MWDI://{resource} would lead to the same result.
+The latter way would be slower, but probably compensate missed notifications.
+The implementer to comment on the preferred way.
+end note
+
+@enduml

spec/diagrams/diagrams_for_deprecated_regard_services_(notifications)/deprecated_-1024_NotificationBasedObjectCreation.plantuml

@@ -0,0 +1,29 @@
+@startuml -1024_NotificationBasedObjectCreation
+skinparam responseMessageBelowArrow true
+
+title 
+  NotifiedDeviceObjectCreationCausesSelfCallingOfLiveResourcePath
+  NotifiedDeviceObjectCreationCausesMetadataTableUpdate
+end title
+
+participant "NP://v1/notify-device-object-creations" as subscription
+participant "MWDI://v1/regard-device-object-creation" as regardObjectCreation
+participant "MWDI://{resource}" as odlCreatedObject
+participant "ElasticSearch\n(metadataTable)" as es
+
+subscription -> regardObjectCreation: {counter, timestamp, resource, objectType} (apiKeyAuth)
+activate regardObjectCreation
+
+regardObjectCreation -> odlCreatedObject: {path = resource potentially shortened to a supported live path}
+
+note over regardObjectCreation
+  <u>UpdateMetadataTable</u>
+    Upon update completion of the CC data in the cache,
+    update the metadata table for the device
+    (last-control-construct-notification-update-time,
+    number-of-partial-updates-since-last-complete-update)
+end note
+regardObjectCreation -> es: {mount-name}
+
+deactivate regardObjectCreation
+@enduml

spec/diagrams/diagrams_for_deprecated_regard_services_(notifications)/deprecated_-1026_NotificationBasedObjectDeletion.plantuml

@@ -0,0 +1,31 @@
+@startuml -1026_NotificationBasedObjectDeletion
+skinparam responseMessageBelowArrow true
+
+title 
+  NotifiedDeviceObjectDeletionCausesDeletingTheObjectInCache
+  NotifiedDeviceObjectDeletionCausesMetadataTableUpdate
+end title
+
+participant "NP://v1/notify-device-object-deletions" as subscription
+participant "MWDI://v1/regard-device-object-deletion" as regardObjectDeletion
+participant "ElasticSearch://{resource}" as es
+participant "ElasticSearch\n(metadataTable)" as mtab
+
+subscription -> regardObjectDeletion: {counter, timestamp, resource} (apiKeyAuth)
+
+activate regardObjectDeletion
+
+regardObjectDeletion -> es: delete object {path = resource, but shortened by /core-model-1-4:network-control-domain=live}
+
+note over regardObjectDeletion
+  <u>UpdateMetadataTable</u>
+    Upon update completion of the CC data in the cache,
+    update the metadata table for the device
+    (last-control-construct-notification-update-time,
+    number-of-partial-updates-since-last-complete-update)
+end note
+regardObjectDeletion -> mtab: {mount-name}
+
+deactivate regardObjectDeletion
+
+@enduml

spec/diagrams/diagrams_for_deprecated_regard_services_(notifications)/info.txt

@@ -0,0 +1,4 @@
+The regard-services /v1/regard-* used to receive notifications from NotificationProxy (up to MWDI v1.2.x),
+will no longer be used (starting from v1.3.0); instead MWDI will pull notifications from Kafka.
+
+The old diagrams using regard-services are kept until v2.0.0 (then the deprecated services will be removed).