Pending State Management

The Pending State Management in the OCS.io solution is a crucial component designed to orchestrate and control state transitions for entities like Customer, Account, Subscriber, and Subscription. This chapter offers a comprehensive exploration of how these transitions are scheduled, managed, and executed within the system.

Pending States act as placeholders for future state changes, allowing for planned updates to be made at a predetermined time. This system ensures that changes are made smoothly and with full visibility, reducing errors and enhancing the ability to manage customer and account states effectively.

Setting the Pending State

To initiate a pending state, external systems, such as CRM, use the UpdateXState API, where "X" denotes the entity type. This API facilitates the scheduling of state changes, which are not immediately applied but are instead queued for future activation.

Parameters Required:

  • State: Indicates the final state the entity will transition to, such as Active, Suspended, or Deactivated.

  • State Reason: Provides a rationale for the state change, which aids in auditing and tracking changes.

  • State Valid From: Specifies the exact date and time when the new state should come into effect, ensuring that changes occur at appropriate times.

  • Pending: Specifies that operation will be scheduled with pending state.

Example: Scheduling a Future Deactivation
{
  ...
  "state" : {
    "state" : "DEACTIVATED",
    "stateReason" : "dfltDeactivated",
    "stateValidFrom" : "2024-05-31T22:00:00.000Z",
    "pending" : true
  },
  ...
}

Managing Pending States

The management of pending states is versatile, providing multiple operations that can be performed to adapt to changing circumstances or decisions.

Operations:

  • CANCEL: This operation cancels the pending state transition, and the entity remains in its current state unless another change is initiated.

  • CONFIRM: Solidifies the pending change, scheduling the system to update the entity’s state on the indicated State Valid From date.

  • CONFIRM with Date Override: Offers the flexibility to move the effective date forward or back, accommodating changes in strategy or customer needs.

  • Override Pending with New State: Replaces an existing pending state with a new one, either immediately or at a future date, ensuring continuous alignment with current conditions.

Automated Processing

OCS.io can handle pending states automatically according to predefined rules set within the system. This automation is crucial for maintaining operational efficiency and ensuring that state changes are executed as planned without manual oversight.

Automatic Operations:

  • Confirm Pending States: Entities are transitioned to their new states automatically if the State Valid From falls on or before the current date, adjusted by a configured grace period. This is typically set to allow for last-minute changes or cancellations.

  • Cancel Pending States: Pending states that have not been confirmed or adjusted are automatically cancelled if they reach the end of a defined period, helping to clean up old or irrelevant pending changes.

Pending State Management Flow

The timing diagram illustrates the sequence of interactions between the CRM system and OCS.io concerning the management of a subscription’s state over time.

Sequence Diagram - Pending State Management

Detailed breakdown of each segment within the timeline:

  1. Initial Setup:

    • The CRM system initiates a request to set a pending state for a subscription to be deactivated at the end of the month.

  2. Interactions:

    • The CRM system may choose to cancel this pending state a few days after setting it.

    • Alternatively, the CRM system can set a new pending state with a different state and a future effective date, such as changing the state to suspended due to collection processes.

    • The CRM system can confirm a pending state to make it effective immediately on the newly specified date or continue as originally planned.

  3. Automated Processes:

    • As the original 'Valid From' date approaches, OCS.io performs automated checks to decide whether to confirm or cancel the pending state. This decision is based on whether the state valid from date is less than or equal to the current system date minus a configured grace period (e.g., one day).

    • Depending on the outcome of these checks, the subscription state is either confirmed or canceled automatically.