From 72eed3c555a343e2d27d94b80df22bf6833f0d05 Mon Sep 17 00:00:00 2001 From: Joel Rebello Date: Fri, 28 Apr 2023 17:01:13 +0200 Subject: [PATCH] docs generated: updated statemachine docs --- .../README-action-statemachine.md | 46 +++++++++++- docs/statemachine/README-task-statemachine.md | 72 ++++++++++++------- docs/statemachine/action-statemachine.json | 8 +-- .../destination_poweredOnDevice.svg | 36 +++++----- .../source_poweredOffDevice.svg | 34 ++++----- .../transition_type_poweringOnDevice.svg | 36 +++++----- .../media-task-sm/destination_active.svg | 42 +++++++---- .../media-task-sm/destination_failed.svg | 44 ++++++------ .../media-task-sm/destination_pending.svg | 20 ++++++ .../media-task-sm/destination_succeeded.svg | 41 +++++++++++ .../media-task-sm/source_active.svg | 68 +++++++++--------- .../media-task-sm/source_pending.svg | 48 +++++++++++++ .../media-task-sm/source_succeeded.svg | 20 ++++++ .../media-task-sm/transition_type_failed.svg | 44 ++++++------ .../media-task-sm/transition_type_run.svg | 24 +++---- .../transition_type_succeeded.svg | 34 +++++++++ docs/statemachine/task-statemachine.json | 29 ++++---- 17 files changed, 443 insertions(+), 203 deletions(-) create mode 100644 docs/statemachine/media-task-sm/destination_pending.svg create mode 100644 docs/statemachine/media-task-sm/destination_succeeded.svg create mode 100644 docs/statemachine/media-task-sm/source_pending.svg create mode 100644 docs/statemachine/media-task-sm/source_succeeded.svg create mode 100644 docs/statemachine/media-task-sm/transition_type_succeeded.svg diff --git a/docs/statemachine/README-action-statemachine.md b/docs/statemachine/README-action-statemachine.md index 308e6eb3..7325718a 100644 --- a/docs/statemachine/README-action-statemachine.md +++ b/docs/statemachine/README-action-statemachine.md @@ -1,6 +1,46 @@ -# Flasher task action sub-statemachine -The Action sub-statemachine(s) is executed to install firmware for each component. - +# Flasher task action sub-state machine(s) + +The task Actions (sub-statemachines) are executed by the Task statemachine. + +Note: Note each firmware to be installed is one action state machine. + +```mermaid +graph TD; + n6("active"); + n1("checkedCurrentFirmware"); + n3("downloadedFirmware"); + n4("failed"); + n7("initiatedInstallFirmware"); + n5("pending"); + n8("polledFirmwareInstallStatus"); + n11("poweredOffDevice"); + n2("poweredOnDevice"); + n9("resetBMC"); + n10("resetDevice"); + n12("succeeded"); + n6-->|"Failed"|n4; + n6-->|"Power on device"|n2; + n1-->|"Download and verify firmware"|n3; + n1-->|"Failed"|n4; + n3-->|"Failed"|n4; + n3-->|"Initiate firmware install"|n7; + n7-->|"Failed"|n4; + n7-->|"Poll firmware install status"|n8; + n5-->|"Failed"|n4; + n8-->|"Failed"|n4; + n8-->|"Powercycle BMC"|n9; + n11-->|"Failed"|n4; + n11-->|"Success"|n12; + n2-->|"Check installed firmware"|n1; + n2-->|"Failed"|n4; + n9-->|"Failed"|n4; + n9-->|"Powercycle Device"|n10; + n10-->|"Failed"|n4; + n10-->|"Power off Device"|n11; + +``` +## Task Action (sub-statemachine) transitions + ## Table of Contents ### States diff --git a/docs/statemachine/README-task-statemachine.md b/docs/statemachine/README-task-statemachine.md index 11f74f77..7bcda179 100644 --- a/docs/statemachine/README-task-statemachine.md +++ b/docs/statemachine/README-task-statemachine.md @@ -1,6 +1,26 @@ # Flasher task state machine -The Task statemachine plans and executes Action (sub-statemachines) to install firmware. - + +The Task statemachine plans and executes Actions (sub-statemachines) to install firmware. + +Note: The Task statemachine plans and and executes [Action sub-state machine(s)](docs/statemachine/README-action-statemachine.md) for each firmware being installed. + +```mermaid +graph TD; + n1("active"); + n3("failed"); + n2("pending"); + n4("succeeded"); + n1-->|"Task failed"|n3; + n1-->|"Plan install actions"|n1; + n1-->|"Query device inventory"|n1; + n1-->|"Run install actions"|n4; + n1-->|"Task successful"|n4; + n2-->|"Initialize task"|n1; + n2-->|"Task failed"|n3; + +``` +## Task statemachine transitions + ## Table of Contents ### States @@ -8,7 +28,6 @@ The Task statemachine plans and executes Action (sub-statemachines) to install f * [Failed](#failed) * [Initial](#initial) * [Queued](#queued) -* [Requested](#requested) * [Success](#success) ### Transition Types @@ -18,11 +37,12 @@ Transition types are the events that can cause a state transition * [Plan](#plan) * [Query](#query) * [Run](#run) -* [success](#success) +* [succeeded](#succeeded) ### Transition Rules Transition rules are the rules that define the required source states and conditions needed to move to a particular destination state when a particular transition type happens +* [Initialize task](#initialize-task) * [Task failed](#task-failed) * [Plan install actions](#plan-install-actions) * [Query device inventory](#query-device-inventory) @@ -38,9 +58,10 @@ In this state the task has been initialized and begun execution in the statemach * [Plan](#plan) * [Query](#query) * [Run](#run) -* [success](#success) +* [succeeded](#succeeded) #### Transition types where this is the destination state +* [null](#null) * [Plan](#plan) * [Query](#query) @@ -56,6 +77,7 @@ In this state the task has been initialized and begun execution in the statemach #### Transition rules where this is the destination state ![destination_active](./media-task-sm/destination_active.svg) +* [Initialize task](#initialize-task) * [Plan install actions](#plan-install-actions) * [Query device inventory](#query-device-inventory) @@ -95,32 +117,19 @@ The initial state of the state machine. This is a synthetic state that is not ac In this state the task is being initialized (this is done outside of the state machine). #### Transition types where this is the source state +* [null](#null) * [failed](#failed) #### Transition types where this is the destination state #### Transition rules where this is the source state -![source_queued](./media-task-sm/source_queued.svg) +![source_pending](./media-task-sm/source_pending.svg) +* [Initialize task](#initialize-task) * [Task failed](#task-failed) #### Transition rules where this is the destination state -![destination_queued](./media-task-sm/destination_queued.svg) - - -### Requested -In this state the task has been requested (this is done outside of the state machine). - -#### Transition types where this is the source state - -#### Transition types where this is the destination state - -#### Transition rules where this is the source state -![source_requested](./media-task-sm/source_requested.svg) - - -#### Transition rules where this is the destination state -![destination_requested](./media-task-sm/destination_requested.svg) +![destination_pending](./media-task-sm/destination_pending.svg) ### Success @@ -130,14 +139,14 @@ In this state the task execution has completed successfully. #### Transition types where this is the destination state * [Run](#run) -* [success](#success) +* [succeeded](#succeeded) #### Transition rules where this is the source state -![source_success](./media-task-sm/source_success.svg) +![source_succeeded](./media-task-sm/source_succeeded.svg) #### Transition rules where this is the destination state -![destination_success](./media-task-sm/destination_success.svg) +![destination_succeeded](./media-task-sm/destination_succeeded.svg) * [Run install actions](#run-install-actions) * [Task successful](#task-successful) @@ -195,7 +204,7 @@ In this transition the actions (sub state machines) for the firmware install are ![transition_type_run](./media-task-sm/transition_type_run.svg) * [Run install actions](#run-install-actions) -### success +### succeeded In this transition the task has completed successfully and any post failure steps are being executed. #### Source states where this transition type applies @@ -204,13 +213,22 @@ In this transition the task has completed successfully and any post failure step #### Destination states where this transition type applies * [Success](#success) #### Transition rules using this transition type -![transition_type_success](./media-task-sm/transition_type_success.svg) +![transition_type_succeeded](./media-task-sm/transition_type_succeeded.svg) * [Task successful](#task-successful) ## Transition Rules Transition rules are the rules that define the required source states and conditions needed to move to a particular destination state when a particular transition type happens +### Initialize task +Performs any task initialization, and transitions the state from pending to active. + +#### Source states +* [Queued](#queued) + +#### Destination state +[Active](#active) + ### Task failed Task execution has failed because of a failed task action or task handler. diff --git a/docs/statemachine/action-statemachine.json b/docs/statemachine/action-statemachine.json index 02993261..ff178e1d 100644 --- a/docs/statemachine/action-statemachine.json +++ b/docs/statemachine/action-statemachine.json @@ -21,7 +21,7 @@ { "transition_type": "failed", "source_states": [ - "queued", + "pending", "active", "poweredOnDevice", "checkedCurrentFirmware", @@ -66,7 +66,7 @@ { "transition_type": "poweringOnDevice", "source_states": [ - "queued" + "active" ], "destination_state": "poweredOnDevice", "name": "Power on device", @@ -91,11 +91,11 @@ "description": "Powercycle Device - only when pollFirmwareInstallStatus() identifies a Device power cycle is required." }, { - "transition_type": "success", + "transition_type": "succeeded", "source_states": [ "poweredOffDevice" ], - "destination_state": "success", + "destination_state": "succeeded", "name": "Success", "description": "Firmware install on component completed successfully." } diff --git a/docs/statemachine/media-action-sm/destination_poweredOnDevice.svg b/docs/statemachine/media-action-sm/destination_poweredOnDevice.svg index cb4dd757..1ffad418 100644 --- a/docs/statemachine/media-action-sm/destination_poweredOnDevice.svg +++ b/docs/statemachine/media-action-sm/destination_poweredOnDevice.svg @@ -4,31 +4,31 @@ - + state transitions - - + + -poweredOnDevice - -poweredOnDevice - +active + +active + - + -queued - -queued - +poweredOnDevice + +poweredOnDevice + - + -queued->poweredOnDevice - - -poweringOnDevice - Power on device    +active->poweredOnDevice + + +poweringOnDevice - Power on device    diff --git a/docs/statemachine/media-action-sm/source_poweredOffDevice.svg b/docs/statemachine/media-action-sm/source_poweredOffDevice.svg index bfdbb3bc..033f5ddd 100644 --- a/docs/statemachine/media-action-sm/source_poweredOffDevice.svg +++ b/docs/statemachine/media-action-sm/source_poweredOffDevice.svg @@ -4,17 +4,17 @@ - + state transitions - + failed - -failed - + +failed + @@ -26,22 +26,22 @@ poweredOffDevice->failed - - + + null - Failed    - + -success - -success - +succeeded + +succeeded + - + -poweredOffDevice->success - - +poweredOffDevice->succeeded + + null - Success    diff --git a/docs/statemachine/media-action-sm/transition_type_poweringOnDevice.svg b/docs/statemachine/media-action-sm/transition_type_poweringOnDevice.svg index cb4dd757..1ffad418 100644 --- a/docs/statemachine/media-action-sm/transition_type_poweringOnDevice.svg +++ b/docs/statemachine/media-action-sm/transition_type_poweringOnDevice.svg @@ -4,31 +4,31 @@ - + state transitions - - + + -poweredOnDevice - -poweredOnDevice - +active + +active + - + -queued - -queued - +poweredOnDevice + +poweredOnDevice + - + -queued->poweredOnDevice - - -poweringOnDevice - Power on device    +active->poweredOnDevice + + +poweringOnDevice - Power on device    diff --git a/docs/statemachine/media-task-sm/destination_active.svg b/docs/statemachine/media-task-sm/destination_active.svg index 780e9b82..4e1a0811 100644 --- a/docs/statemachine/media-task-sm/destination_active.svg +++ b/docs/statemachine/media-task-sm/destination_active.svg @@ -4,31 +4,45 @@ - + state transitions - + active - -active - + +active + - + active->active - - -Plan - Plan install actions    + + +Plan - Plan install actions    - + active->active - - -Query - Query device inventory    + + +Query - Query device inventory    + + + +pending + +pending + + + + +pending->active + + +null - Initialize task    diff --git a/docs/statemachine/media-task-sm/destination_failed.svg b/docs/statemachine/media-task-sm/destination_failed.svg index 35314128..6787affe 100644 --- a/docs/statemachine/media-task-sm/destination_failed.svg +++ b/docs/statemachine/media-task-sm/destination_failed.svg @@ -4,45 +4,45 @@ - + state transitions - + active - -active - + +active + failed - -failed - + +failed + active->failed - - -failed - Task failed    + + +failed - Task failed    - + -queued - -queued - +pending + +pending + - + -queued->failed - - -failed - Task failed    +pending->failed + + +failed - Task failed    diff --git a/docs/statemachine/media-task-sm/destination_pending.svg b/docs/statemachine/media-task-sm/destination_pending.svg new file mode 100644 index 00000000..65b6bc1e --- /dev/null +++ b/docs/statemachine/media-task-sm/destination_pending.svg @@ -0,0 +1,20 @@ + + + + + + +state transitions + + + +pending + +pending + + + + diff --git a/docs/statemachine/media-task-sm/destination_succeeded.svg b/docs/statemachine/media-task-sm/destination_succeeded.svg new file mode 100644 index 00000000..b80ff3c2 --- /dev/null +++ b/docs/statemachine/media-task-sm/destination_succeeded.svg @@ -0,0 +1,41 @@ + + + + + + +state transitions + + + +active + +active + + + + +succeeded + +succeeded + + + + +active->succeeded + + +Run - Run install actions    + + + +active->succeeded + + +succeeded - Task successful    + + + diff --git a/docs/statemachine/media-task-sm/source_active.svg b/docs/statemachine/media-task-sm/source_active.svg index cdf171b7..2e8c7e01 100644 --- a/docs/statemachine/media-task-sm/source_active.svg +++ b/docs/statemachine/media-task-sm/source_active.svg @@ -4,66 +4,66 @@ - - + + state transitions - + active - -active - + +active + active->active - - -Plan - Plan install actions    + + +Plan - Plan install actions    active->active - - -Query - Query device inventory    + + +Query - Query device inventory    failed - -failed - + +failed + active->failed - - -failed - Task failed    + + +failed - Task failed    - + -success - -success - +succeeded + +succeeded + - + -active->success - - -Run - Run install actions    +active->succeeded + + +Run - Run install actions    - + -active->success - - -success - Task successful    +active->succeeded + + +succeeded - Task successful    diff --git a/docs/statemachine/media-task-sm/source_pending.svg b/docs/statemachine/media-task-sm/source_pending.svg new file mode 100644 index 00000000..6c542363 --- /dev/null +++ b/docs/statemachine/media-task-sm/source_pending.svg @@ -0,0 +1,48 @@ + + + + + + +state transitions + + + +active + +active + + + + +failed + +failed + + + + +pending + +pending + + + + +pending->active + + +null - Initialize task    + + + +pending->failed + + +failed - Task failed    + + + diff --git a/docs/statemachine/media-task-sm/source_succeeded.svg b/docs/statemachine/media-task-sm/source_succeeded.svg new file mode 100644 index 00000000..a9debd92 --- /dev/null +++ b/docs/statemachine/media-task-sm/source_succeeded.svg @@ -0,0 +1,20 @@ + + + + + + +state transitions + + + +succeeded + +succeeded + + + + diff --git a/docs/statemachine/media-task-sm/transition_type_failed.svg b/docs/statemachine/media-task-sm/transition_type_failed.svg index 35314128..6787affe 100644 --- a/docs/statemachine/media-task-sm/transition_type_failed.svg +++ b/docs/statemachine/media-task-sm/transition_type_failed.svg @@ -4,45 +4,45 @@ - + state transitions - + active - -active - + +active + failed - -failed - + +failed + active->failed - - -failed - Task failed    + + +failed - Task failed    - + -queued - -queued - +pending + +pending + - + -queued->failed - - -failed - Task failed    +pending->failed + + +failed - Task failed    diff --git a/docs/statemachine/media-task-sm/transition_type_run.svg b/docs/statemachine/media-task-sm/transition_type_run.svg index 2ac4a3ea..c4f0770a 100644 --- a/docs/statemachine/media-task-sm/transition_type_run.svg +++ b/docs/statemachine/media-task-sm/transition_type_run.svg @@ -4,11 +4,11 @@ - + state transitions - + active @@ -16,18 +16,18 @@ active - + -success - -success - +succeeded + +succeeded + - + -active->success - - +active->succeeded + + Run - Run install actions    diff --git a/docs/statemachine/media-task-sm/transition_type_succeeded.svg b/docs/statemachine/media-task-sm/transition_type_succeeded.svg new file mode 100644 index 00000000..90dca14a --- /dev/null +++ b/docs/statemachine/media-task-sm/transition_type_succeeded.svg @@ -0,0 +1,34 @@ + + + + + + +state transitions + + + +active + +active + + + + +succeeded + +succeeded + + + + +active->succeeded + + +succeeded - Task successful    + + + diff --git a/docs/statemachine/task-statemachine.json b/docs/statemachine/task-statemachine.json index f2e1c65b..7b54d90e 100644 --- a/docs/statemachine/task-statemachine.json +++ b/docs/statemachine/task-statemachine.json @@ -1,9 +1,18 @@ { "transition_rules": [ + { + "transition_type": "active", + "source_states": [ + "pending" + ], + "destination_state": "active", + "name": "Initialize task", + "description": "Performs any task initialization, and transitions the state from pending to active." + }, { "transition_type": "failed", "source_states": [ - "queued", + "pending", "active" ], "destination_state": "failed", @@ -33,16 +42,16 @@ "source_states": [ "active" ], - "destination_state": "success", + "destination_state": "succeeded", "name": "Run install actions", "description": "Run executes the planned Action (sub) state machines prepared in the Plan stage." }, { - "transition_type": "success", + "transition_type": "succeeded", "source_states": [ "active" ], - "destination_state": "success", + "destination_state": "succeeded", "name": "Task successful", "description": "Task execution completed successfully." } @@ -60,15 +69,11 @@ "name": "Initial", "description": "The initial state of the state machine. This is a synthetic state that is not actually part of the state machine. It appears in documentation when transition rules hold a single source state that is an empty string" }, - "queued": { + "pending": { "name": "Queued", "description": "In this state the task is being initialized (this is done outside of the state machine)." }, - "requested": { - "name": "Requested", - "description": "In this state the task has been requested (this is done outside of the state machine)." - }, - "success": { + "succeeded": { "name": "Success", "description": "In this state the task execution has completed successfully." } @@ -90,8 +95,8 @@ "name": "Run", "description": "In this transition the actions (sub state machines) for the firmware install are being executed." }, - "success": { - "name": "success", + "succeeded": { + "name": "succeeded", "description": "In this transition the task has completed successfully and any post failure steps are being executed." } }