GuideAPI

Creating and Managing Scenarios via API

Testing complex, conditional Blueprints requires realistic data. Scenarios are reusable packets of test data (Entity objects) that allow you to quickly test or preview how your Blueprints behave under different conditions.

While you can manage Scenarios in the SignStack dashboard, this guide shows how to create and manage them programmatically using the API. This is useful for integrating SignStack testing into automated QA processes or for managing large sets of test data.

What is a Scenario?

A Scenario is a simple, named resource containing a collection of Entity data objects. Each data object is keyed by a local identifier that you can later map to a Blueprint's entitySlot when simulating.

Key Scenario Properties:

  • key: Unique identifier for the Scenario itself (e.g., fhaLoan2Buyers).
  • displayName: Human-readable name (e.g., "FHA Loan - 2 Buyers, 10% Down").
  • entityData: An array where each object contains:
    • entitySlotKey: A local key identifying this piece of data within the scenario (e.g., primaryBuyerData).
    • data: The actual JSON entity object.

Note: Unlike Blueprints or Templates, Scenarios are not versioned using SemVer. If you need a different version, simply create a new Scenario with a different key or update the existing one.

API for Managing Scenarios

The API follows standard RESTful CRUD patterns.

1. Create a Scenario

  • Endpoint: POST /v1/orgs/{orgId}/scenarios
  • Authentication: Requires a valid SignStack JWT Access Token.
  • Request Body: The full Scenario definition.
{
  "key": "fhaLoan2Buyers",
  "displayName": "FHA Loan - 2 Buyers, 10% Down",
  "description": "Test case for an FHA loan with two primary buyers.",
  "entityData": [
    {
      "entitySlotKey": "buyer1Info", // Local key for this data packet
      "data": { "firstName": "Jane", "lastName": "Doe", "creditScore": 720 }
    },
    {
      "entitySlotKey": "buyer2Info",
      "data": { "firstName": "John", "lastName": "Doe", "creditScore": 740 }
    },
    {
      "entitySlotKey": "dealInfo",
      "data": { "loanType": "FHA", "downPaymentPercent": 10, "propertyValue": 500000 }
    }
  ]
}
  • Response: 201 Created with the full, newly created Scenario object (including its system id).

2. List Scenarios

  • Endpoint: GET /v1/orgs/{orgId}/scenarios
    • Authentication: Requires a valid SignStack JWT Access Token.
  • Query Params: limit, offset, sort (e.g., ?sort=displayName:asc).
  • Response: 200 OK with a standard paginated list object containing Scenario summaries (e.g., id, key, displayName, updatedAt).

3. Get a Specific Scenario

  • Endpoint: GET /v1/orgs/{orgId}/scenarios/{scenarioKey}
  • Authentication: Requires a valid SignStack JWT Access Token.
  • Response: 200 OK with the full Scenario object, including the complete entityData.

4. Update a Scenario

Updates an existing scenario in place. Use PUT for a full replacement.

  • Endpoint: PUT /v1/orgs/{orgId}/scenarios/{scenarioKey}
  • Authentication: Requires a valid SignStack JWT Access Token.
  • Request Body: The full, updated Scenario object (including all properties). Use a DTO to ensure only editable fields are accepted (e.g., key should likely be immutable).
  • Response: 200 OK with the updated Scenario object.

5. Delete a Scenario

  • Endpoint: DELETE /v1/orgs/{orgId}/scenarios/{scenarioKey}
  • Authentication: Requires a valid SignStack JWT Access Token.
  • Response: 204 No Content.

Managing Scenarios via the API allows you to integrate workflow testing into your automated development and QA pipelines, ensuring your Blueprints behave correctly across various data conditions.