Update documentation for timeout in system level dialogues

Issue-ID: POLICY-4936
Change-Id: I525c33f3d8ac0847676f185c5a8173c41cba9aff
Signed-off-by: FrancescoFioraEst <francesco.fiora@est.tech>

7 files changed, 99 insertions, 5 deletions

diff --git a/docs/clamp/acm/api-protocol/system-level-dialogues.rst b/docs/clamp/acm/api-protocol/system-level-dialogues.rst
index a2efdc36..0ef5f200 100644
--- a/docs/clamp/acm/api-protocol/system-level-dialogues.rst
+++ b/docs/clamp/acm/api-protocol/system-level-dialogues.rst
@@ -241,14 +241,13 @@ If the operation succeeds, the participant is required to update the result valu
 .. image:: ../images/system-dialogues/SuccessAcmResult.png
 
 The result value should be updated as 'FAILED' by the participants when any failures occurred.
-Also in case of failures, the overall state of the composition remains in any of the transitioning states (DEPLOYING, UNDEPLOYING, PRIMING, UPDATING)
+Also in case of failures, the overall state of the composition/instance remains in any of the transitioning states (DEPLOYING, UNDEPLOYING, PRIMING, DEPRIMING, UPDATING, MIGRATING)
 with the appropriate result values updated by the participant.
 
 .. image:: ../images/system-dialogues/FailedAcmResult.png
 
-Runtime marks the operation result with the value 'TIMEOUT' when the participant gets disconnected from the ACM-R in the middle of any ACM operation.
-When the participant fails to report the periodic heartbeat during an ACM operation, the operation result is then marked as 'TIMEOUT' by the ACM-R after the configured waiting limit is
-reached.
+Runtime marks the operation result with the value 'TIMEOUT' when the participant fails to report the message back during an ACM operation,
+the operation result is then marked as 'TIMEOUT' by the ACM-R after the configured waiting limit is reached.
 
 .. image:: ../images/system-dialogues/TimeoutAcmResult.png
 
@@ -263,9 +262,26 @@ The following parameter is set in the application properties for the runtime to
 An ACM operation has to be completed and updated with any of the above specified result values in order to allow the user to trigger subsequent requests.
 The user cannot trigger any state change events before the operation gets completed. When an operation is marked 'TIMEOUT', the following scenarios are applicable.
 
- - The participant might come back ONLINE and complete the operation to mark the result with 'NO_ERROR' or 'FAILED'
+ - The participant might complete the operation to mark the result with 'NO_ERROR' or 'FAILED'
  - The user can trigger another state change event to the ACM.
 
+The following flow shown and example of deployment that get stuck, and the user decide to undeploy.
+
+.. image:: ../images/system-dialogues/TimeoutParticipant.png
+
+
+3.13 OFF_LINE handling in ACM
+-----------------------------
+Runtime marks the participant state with the value 'OFF_LINE' when the participant fails to report the periodic heartbeat,
+the participant state is then marked as 'OFF_LINE' by the ACM-R after the configured waiting limit is reached.
+That scenario might happen when participant is shutdown, in that scenario all on going operations with that participant are marked 'TIMEOUT' due the missing messages back.
+
+The user cannot trigger any state change events when participant state is 'OFF_LINE'.
+
+.. image:: ../images/system-dialogues/OfflineAcmResult.png
+
+When a participant state is marked 'OFF_LINE', it might come back ONLINE and the user can trigger state change events to the ACM.
+
 End of Document
 
 
diff --git a/docs/clamp/acm/images/system-dialogues/OfflineAcmResult.png b/docs/clamp/acm/images/system-dialogues/OfflineAcmResult.png
new file mode 100644
index 00000000..c56d935c
--- /dev/null
+++ b/docs/clamp/acm/images/system-dialogues/OfflineAcmResult.png
diff --git a/docs/clamp/acm/images/system-dialogues/TimeoutAcmResult.png b/docs/clamp/acm/images/system-dialogues/TimeoutAcmResult.png
index d27cfdd4..dee4708b 100644
--- a/docs/clamp/acm/images/system-dialogues/TimeoutAcmResult.png
+++ b/docs/clamp/acm/images/system-dialogues/TimeoutAcmResult.png
diff --git a/docs/clamp/acm/images/system-dialogues/TimeoutParticipant.png b/docs/clamp/acm/images/system-dialogues/TimeoutParticipant.png
new file mode 100644
index 00000000..2f6f8bd3
--- /dev/null
+++ b/docs/clamp/acm/images/system-dialogues/TimeoutParticipant.png
diff --git a/docs/clamp/acm/plantuml/system-dialogues/OfflineAcmResult.puml b/docs/clamp/acm/plantuml/system-dialogues/OfflineAcmResult.puml
new file mode 100644
index 00000000..1cbdaa51
--- /dev/null
+++ b/docs/clamp/acm/plantuml/system-dialogues/OfflineAcmResult.puml
@@ -0,0 +1,19 @@
+@startuml
+
+  Rest -> "ACM Runtime": ACM operation triggered by the user
+  activate "ACM Runtime"
+  "ACM Runtime" -> "ACM Database": Read Automation Composition information
+  activate Participant
+  "ACM Runtime" -> Participant : [ASYNC] Send the state change event to the participant
+  "ACM Runtime" -> "ACM Database": Mark the AC element into transitioning state
+  deactivate  "ACM Runtime"
+  Participant -> Participant: Goes OFF_LINE due to an unexpected error
+  deactivate Participant
+
+  activate "ACM Runtime"
+  "ACM Runtime" -> "ACM Database": Mark OFF_LINE reached for the participant status report
+  "ACM Runtime" -> "ACM Database": Mark TIMEOUT reached for the AC instance
+  deactivate  "ACM Runtime"
+
+
+@enduml
diff --git a/docs/clamp/acm/plantuml/system-dialogues/TimeoutAcmResult.puml b/docs/clamp/acm/plantuml/system-dialogues/TimeoutAcmResult.puml
new file mode 100644
index 00000000..25209d0d
--- /dev/null
+++ b/docs/clamp/acm/plantuml/system-dialogues/TimeoutAcmResult.puml
@@ -0,0 +1,17 @@
+@startuml
+
+  Rest -> "ACM Runtime": ACM operation triggered by the user
+  activate "ACM Runtime"
+  "ACM Runtime" -> "ACM Database": Read Automation Composition information
+  activate Participant
+  "ACM Runtime" -> Participant : [ASYNC] Send the state change event to the participant
+  "ACM Runtime" -> "ACM Database": Mark the AC element into transitioning state
+  deactivate  "ACM Runtime"
+  Participant -> Participant: state change operation get stuck
+  deactivate Participant
+
+  activate "ACM Runtime"
+  "ACM Runtime" -> "ACM Database": Mark TIMEOUT reached for the AC instance
+  deactivate  "ACM Runtime"
+
+@enduml
diff --git a/docs/clamp/acm/plantuml/system-dialogues/TimeoutParticipant.puml b/docs/clamp/acm/plantuml/system-dialogues/TimeoutParticipant.puml
new file mode 100644
index 00000000..c88cd04b
--- /dev/null
+++ b/docs/clamp/acm/plantuml/system-dialogues/TimeoutParticipant.puml
@@ -0,0 +1,42 @@
+@startuml
+
+alt "Deploying the instance"
+  Rest -> "ACM Runtime": Deploy triggered by the user
+  activate "ACM Runtime"
+  "ACM Runtime" -> "Participant-intermediary" : [ASYNC] Deploying the instance
+  deactivate  "ACM Runtime"
+
+  activate "Participant-intermediary"
+  activate Participant
+  "Participant-intermediary" -> Participant : Create Deploy thread
+  deactivate "Participant-intermediary"
+  note right
+  Deploy thread is stuck
+  end note
+end
+
+alt "Instance in Timeout"
+  activate "ACM Runtime"
+  "ACM Runtime" -> "ACM Runtime" : set instance in Timeout
+  deactivate  "ACM Runtime"
+end
+
+alt "Undeploying the instance"
+  Rest -> "ACM Runtime": Undeploy triggered by the user
+  activate "ACM Runtime"
+  activate "Participant-intermediary"
+  "ACM Runtime" -> "Participant-intermediary" : [ASYNC] Undeploying the instance
+  deactivate  "ACM Runtime"
+  "Participant-intermediary" -> Participant : Terminate Deploy thread
+  deactivate Participant
+  "Participant-intermediary" -> Participant : Create Undeploy thread
+  activate Participant
+  deactivate "Participant-intermediary"
+  Participant -> "Participant-intermediary" : instance Undeployed
+  activate "Participant-intermediary"
+  deactivate Participant
+  "Participant-intermediary" -> "ACM Runtime" : [ASYNC] instance Undeployed
+  deactivate "Participant-intermediary"
+end
+
+@enduml