---
title: "Manage Processes — Spiff Arena 0.1 documentation"
description: "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…"
source_url: https://spiff.works/docs/spiff-arena/how_to_guides/manage_processes.html
---

☰ Menu

# Manage Processes[](#manage-processes "Link to this heading")

| ⚙ How do I get there | Menu Hierarchy |
| --- |
| Follow steps to find a process instance |

## Suspend a Process Instance[](#suspend-a-process-instance "Link to this heading")

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.

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 |

## Resume a Process Instance[](#resume-a-process-instance "Link to this heading")

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 |

## Manually Execute or Skip an Active Task[](#manually-execute-or-skip-an-active-task "Link to this heading")

Administrators can manually move a suspended process instance past an active task when normal task completion is not possible.
Use this only after confirming the task is the active task shown for the suspended process instance.

> **Step 1: Suspend the Process Instance**

Follow the suspend steps above and confirm that the process instance status is `suspended`.

> **Step 2: Open the Active Task**

On the process instance detail page, select the currently active task.
Active tasks are shown in yellow.

> **Step 3: Choose the Recovery Action**

Select **Execute Task** to run the task through the workflow engine, or select **Skip Task** to mark the task complete without running its normal behavior.
For human tasks, both actions move the workflow past the task; for automated tasks, **Execute Task** runs the task behavior and **Skip Task** bypasses it.

> **Step 4: Review and Resume**

After the action completes, review the process instance state and events.
The process instance remains suspended until you resume it.

Note

Manual execution changes process history and can affect downstream data.

## Terminate a Process Instance[](#terminate-a-process-instance "Link to this heading")

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 |

## Reset a Process Instance[](#reset-a-process-instance "Link to this heading")

> **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[](#migrate-process-instance "Link to this heading")

The process instance migration feature allows users to migrate a process instance to a different version of the associated process model.

### How to use[](#how-to-use "Link to this heading")

Let’s say you have a process model like this and you start a process instance:

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:

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.

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.

### Caveats[](#caveats "Link to this heading")

#### Cannot migrate in these situations[](#cannot-migrate-in-these-situations "Link to this heading")

Migration is not possible when the following activities are active (started/ready/waiting):

- Call activity/Sub-process - The task itself cannot be changed once it is active.
  Tasks inside the call activity or sub-process can be updated if they have not been reached.
  Tasks that directly follow one of these activities are special, and you cannot migrate an instance if you add or remove one of these.
- Multi Instance tasks
- Loop tasks
- Signal boundary event - add/remove signals
- Looping back through a part of a process which has already completed once

#### Forms[](#forms "Link to this heading")

Forms are not serialized as part of the process model specification, and therefore are not considered during migration.
Instead, they rely on the git revision to determine what version of the file to use.
Therefore, if you change only a form, the system will not allow you to migrate the process instance.

### APIS[](#apis "Link to this heading")

- `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.