Skip to content
Hantera OMS Developer Portal Developer Portal

Checkpoints & Rewind

All actors in Hantera automatically maintain checkpoints of their state. These checkpoints can be used to view historical states or restore an actor to a previous point in time. This functionality is available on all actor types including Order, Payment, Ticket, Asset, and SKU.

What are Checkpoints?

Every time commands are applied to an actor, a mutation set is created and persisted. Each mutation set represents a checkpoint containing:

  • Checkpoint ID: A unique UUID identifier
  • Timestamp: When the mutation set was created
  • Metadata: Optional information about the changes (e.g., which commands were applied)

These mutation sets form a complete history of all changes made to the actor over time. By replaying mutations up to a specific checkpoint, the system can reconstruct the exact state of the actor at that point in time.

Viewing Available Checkpoints

Use the getCheckpoints message to retrieve all available checkpoints for an actor:

POST https://<hantera-hostname>/resources/actors/order/ec806cf5-d976-49de-b390-03b303da8117
Authorization: Bearer <YOUR TOKEN>
Content-Type: application/json


[{
  "type": "getCheckpoints",
  "body": {}
}]

Response:

[
  {
    "checkpointId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "timestamp": "2025-01-15T10:30:00Z",
    "metadata": {}
  },
  {
    "checkpointId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "timestamp": "2025-01-15T14:45:00Z",
    "metadata": {
      "commands": [{"type": "addTag", "key": "priority"}]
    }
  }
]

Checkpoints are returned in chronological order, from earliest to most recent.

Rewinding to a Checkpoint

The rewind message restores an actor to the state it had at a specific checkpoint.

POST https://<hantera-hostname>/resources/actors/order/ec806cf5-d976-49de-b390-03b303da8117
Authorization: Bearer <YOUR TOKEN>
Content-Type: application/json


[{
  "type": "rewind",
  "body": {
    "checkpointId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}]

Response:

{
  "success": true,
  "checkpointId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": "2025-01-15T10:30:00Z",
  "checkpointsAffected": 1
}

How Rewind Works

Rewind is a non-destructive operation:

  1. The system finds the target checkpoint in the mutation history
  2. It rebuilds the state by replaying all mutations up to that checkpoint
  3. It calculates the difference between the current state and the checkpoint state
  4. A new mutation set is appended that transforms the current state to match the checkpoint state
  5. An activity log entry is added recording the rewind operation

The original mutation history is preserved, and the rewind itself becomes a new checkpoint in the history. This means you can even rewind a rewind if needed.

Activity Log Preservation

When rewinding, activity logs are preserved. A new entry is automatically added to document the rewind:

"Rewound order to checkpoint at {timestamp}"

This ensures full traceability of state changes.

Previewing Old States

You can preview what an actor’s state looked like at a previous checkpoint without actually performing a rewind. This is done by combining the rewind message with preview mode:

POST https://<hantera-hostname>/resources/actors/order/ec806cf5-d976-49de-b390-03b303da8117?preview
Authorization: Bearer <YOUR TOKEN>
Content-Type: application/json


[{
  "type": "rewind",
  "body": {
    "checkpointId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
},{
  "type": "query",
  "body": {
    "query": {
      "fields": ["orderId", "orderNumber", "orderState", "total"],
      "navigate: [{
        "edge": "deliveries",
        "node": {
          "fields": ["deliveryId", "deliveryState"]
        }
      }]
    }
  }
}]

In preview mode:

  • The rewind is performed in an isolated transaction
  • Subsequent messages (like query) see the rewound state
  • All changes are automatically rolled back at the end
  • No data is persisted

This is useful for:

  • Debugging issues by inspecting historical state
  • Auditing changes over time
  • Comparing current state with previous states
  • Customer support scenarios where you need to understand what happened

Access Control

Rewind operations require specific permissions:

PermissionDescription
actors/<type>:rewindFull rewind permission. Allows actual rewind operations that persist state changes.
actors/<type>:rewind:previewPreview-only permission. Allows rewinding in preview mode to view historical states, but changes are not persisted.

For example:

  • actors/order:rewind - Can rewind orders
  • actors/ticket:rewind:preview - Can only preview historical ticket states

The preview permission is useful for support personnel or auditors who need to investigate historical states without the ability to modify data.

Use Cases

Reverting Mistakes

If incorrect commands were applied to an actor, you can rewind to a checkpoint before those changes:

  1. Call getCheckpoints to find the appropriate checkpoint
  2. Call rewind with the checkpoint ID
  3. The actor returns to its previous state

Auditing and Debugging

Use preview mode to investigate what an actor looked like at any point in time:

  1. Call getCheckpoints to see the history
  2. Use rewind with ?preview to view the historical state
  3. Query the state to inspect specific fields

Comparing States

You can compare an actor’s current state with a historical state:

  1. Query the current state
  2. In preview mode, rewind and query the historical state
  3. Compare the two results
  • getCheckpoints - Returns available checkpoints for an actor
  • rewind - Rewinds an actor to a specific checkpoint