# Technical Specification for Single Active Instance Enforcement in Workflow

## Objective
To ensure that a user can only have one active instance of a specific workflow at any given time, thereby preventing multiple registrations or redundant processes.

## Background
Currently, users can initiate multiple instances of the same workflow, such as `user-register-flow`, using the same `user_reference`. This can lead to duplicate registrations and other inconsistencies. The solution involves introducing a mechanism to enforce single active instances for specified workflows.

## Solution Overview

1. **Property Introduction**:
- Introduce a property named `IsAllowOneActiveInstance` in the workflow configuration.
- This property determines whether multiple instances of the workflow can be initiated for the same `user_reference`.

2. **Instance Check During Initialization**:
- When initializing a workflow, check if there is already an active instance for the given `user_reference`.
- If an active instance exists, return its `instanceId` in the response.

3. **State Transition Management**:
- Ensure state transitions use the correct `instanceId`.
- If a transition is attempted with an incorrect or already active `instanceId`, return an error response.

4. **Set-State Considerations**:
- Handle scenarios where workflows with `IsAllowOneActiveInstance=false` need to transition into workflows with `IsAllowOneActiveInstance=true`.

## Detailed Specifications

### Workflow Configuration

Add a new boolean property `IsAllowOneActiveInstance` to the workflow configuration.

#### Example Workflow Configuration

{
  "name": "user-register-flow",
  "title": [
    {
      "language": "en-EN",
      "label": "User Register Flow"
    }
  ],
  "IsAllowOneActiveInstance": true
}

#### Initialization Process
During the workflow initialization, check for an active instance using the provided user_reference.

#### Initialization Request Example

curl --location 'https://test-pubagw6.burgan.com.tr/ebanking/flow/instance/workflow/user-register-flow/init' \
--header 'Authorization: Bearer YOUR_AUTH_TOKEN' \
--header 'Cookie: YOUR_COOKIE'

#### Initialization Response Example (No Active Instance)

{
  "state": "user-register-start-state",
  "view-source": "state",
  "transition": [
    {
      "transition": "user-register-transition",
      "type": "Forward",
      "require-data": null,
      "has-view-variant": false
    }
  ],
  "init-page-name": "user-register-start-state-page"
}

#### Initialization Response Example (Active Instance Exists)

{
  "state": "user-register-start-state",
  "view-source": "state",
  "transition": [
    {
      "transition": "user-register-transition",
      "type": "Forward",
      "require-data": null,
      "has-view-variant": false
    }
  ],
  "init-page-name": "checking-account-opening-input-page",
  "instanceId": "650c0ab5-7e1d-4d06-a7ce-f75e6857da68"
}

#### Error Handling for Incorrect Instance ID
If a transition is attempted with an instance ID that does not match the active instance for the user, return an error.

#### Error Response Example

{
  "result": {
    "status": "Error",
    "message": "There is an active workflow exists with instanceId: 650c0ab5-7e1d-4d06-a7ce-f75e6857da68",
    "messageDetail": ""
  },
  "data": null
}

#### Set-State Handling
When a workflow with **IsAllowOneActiveInstance=false** needs to transition to a state in a workflow with **IsAllowOneActiveInstance=true**, ensure the **user_reference** is checked, and the state is updated accordingly.

### Implementation Steps
#### Update Workflow Configuration:

* Modify the workflow configuration schema to include **IsAllowOneActiveInstance**.
#### Modify Initialization Logic:

* Implement logic to check for active instances during workflow initialization.
* Return the existing **instanceId** if an active instance is found.
#### Enhance State Transition Logic:

* Ensure state transitions use the correct **instanceId**.
* Implement error handling for transitions attempted with incorrect instance IDs.
#### Adjust Set-State Logic:

* Ensure compatibility between workflows with different **IsAllowOneActiveInstance** settings during state transitions.
#### Testing:

* Thoroughly test the new functionality with various scenarios to ensure it works as expected.
* Test cases should include:
** Initializing a workflow with no active instance.
** Initializing a workflow with an existing active instance.
** Attempting transitions with correct and incorrect instance IDs.
** Set-state transitions between workflows with different IsAllowOneActiveInstance settings.
### Conclusion
By implementing the **IsAllowOneActiveInstance** property and the associated checks during workflow initialization and state transitions, we can ensure that users will not have multiple active instances of the same workflow, thereby maintaining data integrity and consistency.