From fd6e5e6a052bf6e01e6d44030e9474587063153d Mon Sep 17 00:00:00 2001 From: jasquat <2487833+jasquat@users.noreply.github.com> Date: Fri, 19 Jul 2024 15:21:35 -0400 Subject: [PATCH] added docs for process instance migration w/ burnettk (#1960) Co-authored-by: jasquat --- docs/Support/manage_processes.md | 202 +++++++++++++++++++++++ docs/Support/suspend_resume_terminate.md | 141 ---------------- docs/index.md | 44 ++--- 3 files changed, 224 insertions(+), 163 deletions(-) create mode 100644 docs/Support/manage_processes.md delete mode 100644 docs/Support/suspend_resume_terminate.md diff --git a/docs/Support/manage_processes.md b/docs/Support/manage_processes.md new file mode 100644 index 000000000..89e321c24 --- /dev/null +++ b/docs/Support/manage_processes.md @@ -0,0 +1,202 @@ +# Manage Processes + +| ⚙ How do I get there \| Menu Hierarchy | +| --------------------------------------- | +| Follow steps to find a process instance | + +## Suspend a Process Instance + +By suspending a process instance, you temporarily halt its execution, allowing you to access and modify the necessary data or configurations associated with that specific instance. +This feature is not only useful for making updates, but also enables the possibility to redo a previous step with different metadata if needed. + +> **Step 1: Find the Active Process Instance** + +- In order to locate the active process instance, have a look at these pages to find an instance to suspend. + +```{admonition} Note + +⚠ Note that the suspension of a process instance is only applicable to active instances. +If an instance is not active, it indicates that the process has already been completed, and therefore, it cannot be suspended. + +``` + +> **Step 2: Locate Suspend Icon** + +![suspend](images/suspend.png) + +- Next to the Process Instance Id, look for the icon that resembles the 'Suspend' icon and select it to initiate the suspension of the process instance. + +> **Step 3: Select Suspend Button** + +Click on the 'Suspend' icon. +This action will pause the process instance, granting you the ability to make edits and modifications. +When ready, the process instance can be resumed. +The process instance remains highlighted in yellow. + +![suspend](images/active_process_instance.png) + +| ✅ Success | +| :---------------------------------------------------------------: | +| Confirm that the status has changed from ‘waiting’ to ‘suspended’ | +| ![suspended](images/suspended.png) | + +## Resume a Process Instance + +Resuming a process is essential for ensuring that the process can continue its execution, recover from interruptions, and proceed with the necessary updates or corrections. + +> **Step 1: Locate Resume Icon** + +![resume](images/resume.png) + +- Next to the Process Instance Id, look for the icon that resembles the 'Resume' icon and select it to resume the suspended process instance. + +> **Step 2: Select Resume Button** + +- Click on the 'Resume' button. + This action will cause the process instance to go back to its active state, allowing the process instance to continue. + Depending on where the process instance is in its journey, the status might be waiting or some other active status. + The process instance remains highlighted in yellow. + +![suspend](images/active_process_instance.png) + +| ✅ Success | +| :-----------------------------------------------------------------------: | +| Confirm that the status has changed from ‘suspended’ to an active status. | +| ![waiting](images/waiting.png) | + +## Terminate a Process Instance + +Terminating refers to ending the execution of a specific occurrence of a process before it reaches its natural completion or final outcome. +There are various reasons for terminating a process instance such as the instance is no longer required or it's in an error state. + +> **Step 1: Locate Terminate Icon** + +![terminate](images/terminate.png) + +- Next to the Process Instance Id, look for the icon that resembles the 'Terminate' icon and select it to terminate the process instance. + +> **Step 2: Select Terminate Button** + +- Click on the 'Terminate' button. + Note that the process instance will be terminated permanently, and this action cannot be undone. + +> **Step 3: Confirm Termination** + +- Before proceeding with the termination, it is essential to be absolutely certain about your decision. + ![terminate_warning](images/terminate_warning.png) + +- The process status will now be 'Terminated' and the last active task will be highlighted in purple. + ![suspend](images/terminated_process_instance.png) + +| ✅ Success | +| :------------------------------------------------------------------: | +| Confirm that the status has changed from ‘suspended’ to 'terminated' | +| ![suspend](images/terminated.png) | + +## Reset a Process Instance + +> **Step 1: Find the active Process Instance** + +> **Step 2: Navigate to the active User Task** + +👤 Note that you need Admin rights to complete the following steps. + +> **Step 3: Suspend the Process** + +Ensure the status has changed from _user_input_required_ to _suspended_ +![Reset](images/reset_process2.png) + +> **Step 4: Go to the relevant past activity** + +Only a previously completed section highlighted in grey can be chosen. + +> **Step 5: Select 'View process instance at the time when this task was active. +> '** + +![Reset](images/reset_process3.png) + +> **Step 6: Observe the task once highlighted in grey should now be yellow. +> ** + +A previously completed section is now active and shown in yellow. + +> **Step 7: Select 'Reset Process Here' icon in the popup window. +> ** + +![Reset](images/reset_process5.png) + +> **Step 8: "Resume" process instance. +> ** + +The process instance should be resumed by selecting the ‘Resume’ icon next to the Process Instance Id. + +![Reset](images/reset_process6.png) + +> **Step 9: Refresh page** + +Wait for Resume action to complete, this may take some time. +Refresh the page to ensure it has transitioned to the next activity, replacing the current one. + +| ✅ Success | +| :----------------------------------------------------------------------------: | +| From this point onward, the remaining part of the process can smoothly proceed | + +## Migrate Process Instance + +The process instance migration feature allows users to migrate a process instance to a different version of the associated process model. + +### How to use + +Let's say you have a process model like this and you start a process instance: + +```mermaid +graph LR + A(( )) --> B[Manual Task A] + B --> C(( )) +``` + +Let's assume A is a manual task, so flow stops there. + +Then you want to update the process model, like this: + +```mermaid +graph LR + A(( )) --> B[Manual Task A] + B --> D[Manual Task B] + D --> C(( )) +``` + +If you want your existing process instance to execute Manual Task B, it calls for a migration. +First, suspend your process instance. +Next, click on the migration icon. +You will be presented with information about whether your process instance is allowed to migrate to the newest process model version. + +```{admonition} Note +You can migrate a process instance as long as the tasks that are added/updated/deleted have not yet been executed by your process instance. +``` + +If the process instance is allowed to migrate, you can click the button to migrate your process instance. +In the case of the example, once you resume the instance and complete Manual Task A, you will be presented with Manual Task B. + +### APIS + +- `GET /process-instances/{modified_process_model_identifier}/{process_instance_id}/check-can-migrate` + - Checks if the process instance can be migrated to the newest version of the process model or the target_bpmn_process_hash if given. + - Query params: + - **target_bpmn_process_hash** OPTIONAL + - the hash value of the bpmn process serialized form + - this can be found from the migration events listed in the migration event list api +- `POST /process-instance-migrate/{modified_process_model_identifier}/{process_instance_id}` + - Performs the migration of the process instance to newest version of the process model or the target_bpmn_process_hash if given. + - The process instance must be suspended to do this. + - Query params: + - **target_bpmn_process_hash** OPTIONAL + - the hash value of the bpmn process serialized form + - this can be found from the migration events listed in the migration event list api +- `GET /process-instance-events/{modified_process_model_identifier}/{process_instance_id}/migration` + - Get a list of migrations that have already been performed on the process instance. + +General path params: + +- **modified_process_model_identifier**: the process model identifier separated by colons - `:` - instead of slashes +- **process_instance_id**: the id of the process instance to run on. diff --git a/docs/Support/suspend_resume_terminate.md b/docs/Support/suspend_resume_terminate.md deleted file mode 100644 index 8334e54f4..000000000 --- a/docs/Support/suspend_resume_terminate.md +++ /dev/null @@ -1,141 +0,0 @@ -# Suspend, Resume, and Terminate a Process - -| ⚙ How do I get there \| Menu Hierarchy | -| -------------------------------------- | -| Follow steps to find a process instance | - -## Suspend a Process - -By suspending a process instance, you temporarily halt its execution, allowing you to access and modify the necessary data or configurations associated with that specific instance. -This feature is not only useful for making updates, but also enables the possibility to redo a previous step with different metadata if needed. - -> **Step 1: Find the Active Process Instance** - -- In order to locate the active process instance, have a look at these pages to find an instance to suspend. - -```{admonition} Note - -⚠ Note that the suspension of a process instance is only applicable to active instances. -If an instance is not active, it indicates that the process has already been completed, and therefore, it cannot be suspended. - -``` - -> **Step 2: Locate Suspend Icon** - -![suspend](images/suspend.png) - -- Next to the Process Instance Id, look for the icon that resembles the 'Suspend' icon and select it to initiate the suspension of the process instance. - -> **Step 3: Select Suspend Button** - -Click on the 'Suspend' icon. -This action will pause the process instance, granting you the ability to make edits and modifications. -When ready, the process instance can be resumed. -The process instance remains highlighted in yellow. - -![suspend](images/active_process_instance.png) - -| ✅ Success | -| :----: | -| Confirm that the status has changed from ‘waiting’ to ‘suspended’| -|![suspended](images/suspended.png)| - -## Resume a Process - -Resuming a process is essential for ensuring that the process can continue its execution, recover from interruptions, and proceed with the necessary updates or corrections. - -> **Step 1: Locate Resume Icon** - -![resume](images/resume.png) - -- Next to the Process Instance Id, look for the icon that resembles the 'Resume' icon and select it to resume the suspended process instance. - -> **Step 2: Select Resume Button** - -- Click on the 'Resume' button. -This action will cause the process instance to go back to its active state, allowing the process instance to continue. -Depending on where the process instance is in its journey, the status might be waiting or some other active status. -The process instance remains highlighted in yellow. - -![suspend](images/active_process_instance.png) - -| ✅ Success | -| :----: | -| Confirm that the status has changed from ‘suspended’ to an active status.| -![waiting](images/waiting.png)| - -## Terminate a Process Instance - -Terminating refers to ending the execution of a specific occurrence of a process before it reaches its natural completion or final outcome. -There are various reasons for terminating a process instance such as the instance is no longer required or it's in an error state. - -> **Step 1: Locate Terminate Icon** - -![terminate](images/terminate.png) - -- Next to the Process Instance Id, look for the icon that resembles the 'Terminate' icon and select it to terminate the process instance. - -> **Step 2: Select Terminate Button** - -- Click on the 'Terminate' button. -Note that the process instance will be terminated permanently, and this action cannot be undone. - -> **Step 3: Confirm Termination** - -- Before proceeding with the termination, it is essential to be absolutely certain about your decision. -![terminate_warning](images/terminate_warning.png) - -- The process status will now be 'Terminated' and the last active task will be highlighted in purple. -![suspend](images/terminated_process_instance.png) - -| ✅ Success | -| :----: | -| Confirm that the status has changed from ‘suspended’ to 'terminated' | -![suspend](images/terminated.png) | - -## Reset a Process - -> **Step 1: Find the active Process Instance** - -> **Step 2: Navigate to the active User Task** - -👤 Note that you need Admin rights to complete the following steps. - -> **Step 3: Suspend the Process** - -Ensure the status has changed from *user_input_required* to *suspended* -![Reset](images/reset_process2.png) - -> **Step 4: Go to the relevant past activity** - -Only a previously completed section highlighted in grey can be chosen. - -> **Step 5: Select 'View process instance at the time when this task was active. -'** - -![Reset](images/reset_process3.png) - -> **Step 6: Observe the task once highlighted in grey should now be yellow. -** - -A previously completed section is now active and shown in yellow. - -> **Step 7: Select 'Reset Process Here' icon in the popup window. -** - -![Reset](images/reset_process5.png) - -> **Step 8: "Resume" process instance. -** - -The process instance should be resumed by selecting the ‘Resume’ icon next to the Process Instance Id. - -![Reset](images/reset_process6.png) - -> **Step 9: Refresh page** - -Wait for Resume action to complete, this may take some time. -Refresh the page to ensure it has transitioned to the next activity, replacing the current one. - - diff --git a/docs/index.md b/docs/index.md index f96d06ba6..f2d3eda70 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,19 +6,6 @@ Getting_Started/quick_start.md ``` -```{toctree} -:maxdepth: 1 -:caption: Technical Docs -dev/index.md -dev/setup.md -dev/backend.md -dev/frontend.md -dev/connector_proxy.md -dev/how_to_build_a_connector.md -dev/extensions.md -dev/process.md -``` - ```{toctree} :maxdepth: 1 :caption: Building Diagrams @@ -51,6 +38,28 @@ Debugging_Diagrams/process_error_handling.md Debugging_Diagrams/Private_data.md ``` +```{toctree} +:maxdepth: 1 +:caption: Support & Administration +Support/manage_processes.md +Support/Welcome_Messages.md +Support/Running_Server_Locally.md +Support/FAQ.md +``` + +```{toctree} +:maxdepth: 1 +:caption: Technical Docs +dev/index.md +dev/setup.md +dev/backend.md +dev/frontend.md +dev/connector_proxy.md +dev/how_to_build_a_connector.md +dev/extensions.md +dev/process.md +``` + ```{toctree} :maxdepth: 1 :caption: DevOps - Installation & Integration @@ -65,15 +74,6 @@ DevOps_installation_integration/path_based_routing.md DevOps_installation_integration/process_model_management.md ``` -```{toctree} -:maxdepth: 1 -:caption: Support & Administration -Support/suspend_resume_terminate.md -Support/Welcome_Messages.md -Support/Running_Server_Locally.md -Support/FAQ.md -``` - ```{toctree} :maxdepth: 1 :caption: Appendices