Scenarios & Plans
Scenarios are isolated workspaces for modeling workforce changes without affecting live data. They are the foundation of Flowstate's what-if planning capabilities -- every headcount plan, budget proposal, and restructuring exercise lives inside a scenario until it is approved and merged.
What Is a Scenario?
A scenario (referred to as a "plan" in the UI and data model) is a self-contained copy-on-write workspace. When you create a scenario, Flowstate does not duplicate your entire workforce dataset. Instead, it creates a thin layer of changes -- additions, modifications, and deletions -- that are applied on top of your live data when viewed through that scenario.
This design means:
- Creating a scenario is instant. There is no data duplication overhead.
- Multiple scenarios can exist simultaneously. A headcount plan and a restructuring proposal can coexist without interfering with each other.
- Live data remains untouched until a scenario is explicitly merged.
The Merged View
When you open a scenario, Flowstate presents a merged view -- your live data with the scenario's changes layered on top. This gives you a complete picture of what the organization would look like if the scenario were approved.
The merged view handles three types of changes:
| Change Type | How It Works |
|---|---|
| Addition | A new entity (employee, team, vacancy) exists only in the scenario. It has no liveCorrelationId -- there is no live counterpart. |
| Modification | An existing live entity has been changed in the scenario. The scenario record has a liveCorrelationId pointing to the original live entity. The merged view shows the scenario version. |
| Deletion | An existing live entity has been marked as removed in the scenario. The scenario record has isDeleted set to true. The merged view excludes it. |
TIP
The merged view is read-only from the perspective of integrations. External systems always interact with live data unless they explicitly pass a scenarioId parameter.
Plan Statuses
Every scenario progresses through a lifecycle tracked by its status:
| Status | Meaning |
|---|---|
DRAFT | The scenario is actively being worked on. Changes can be freely added, modified, or removed. This is the default status for new scenarios. |
TARGETED | The scenario has been marked as a target plan. It represents the intended future state but has not yet been formally approved and merged. |
MERGED | The scenario has been approved and its changes have been applied to live data. A merged scenario is immutable -- it serves as a historical record of what was changed and when. |
DISCARDED | The scenario was rejected or abandoned. Its changes were never applied. Like merged scenarios, discarded scenarios are kept for audit purposes. |
ARCHIVED | The scenario has been archived for long-term storage. It is no longer actively referenced but remains available for historical review. |
DRAFT --> TARGETED --> MERGED
| |
v v
DISCARDED DISCARDED --> ARCHIVEDWARNING
Merging a scenario is a one-way operation. Once merged, the changes become part of live data and the scenario cannot be unmerged. Review changes carefully before merging.
Plan Visibility
Scenarios have a visibility setting that controls who can see them:
| Visibility | Who Can Access |
|---|---|
PRIVATE | Only the creator and users with explicit access. Use this for early-stage explorations and sensitive restructuring plans. |
OPEN | All users in the organization with appropriate role permissions. Use this for plans that need broad review and input. |
Plan Types
The plan type indicates the purpose of the scenario and affects how it is displayed and filtered in the UI:
| Type | Purpose |
|---|---|
BUDGET | Financial planning scenarios focused on cost projections and budget allocation. |
HEADCOUNT | Workforce sizing scenarios focused on hiring, attrition, and team composition. |
RESTRUCTURE | Organizational change scenarios involving team reorganization, role changes, or reporting line adjustments. |
The Live vs Plan Data Model
Under the hood, Flowstate maintains paired tables for every entity that supports scenario planning:
| Live Table | Plan Table | Entity |
|---|---|---|
LiveEmployee | PlanEmployee | Employee records |
LiveContractor | PlanContractor | Contractor records |
LiveVacancy | PlanVacancy | Vacancy records |
LiveTeam | PlanTeam | Team structure |
LiveProject | PlanProject | Project records |
LiveEmployeeTeamAllocation | PlanEmployeeTeamAllocation | Employee-team assignments |
LiveEmployeeProjectAllocation | PlanEmployeeProjectAllocation | Employee-project assignments |
LiveSalaryAdjustment | PlanSalaryAdjustment | Salary history |
LiveBonus | PlanBonus | Bonus records |
Plan tables include additional fields that do not exist on live tables:
| Field | Purpose |
|---|---|
planId | Foreign key linking this record to its parent scenario. |
liveCorrelationId | Foreign key pointing to the original live entity. NULL if this entity was created within the scenario (an addition). |
isDeleted | Boolean tombstone. When true, the merged view treats the corresponding live entity as removed. |
createdByUserId | The user who created this scenario change, used for audit trails. |
Live tables include sync metadata fields (sourceSystem, sourceSystemId, lastSyncedAt) that are not present on plan tables, since scenario data is never synced from external systems.
Using Scenarios via the API
The Flowstate REST API operates on live data by default. To read or write within a scenario, append the scenarioId query parameter to any request:
# Read employees from live data
curl "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/employees" \
-H "Authorization: Bearer {api-key}"
# Read employees as they appear in a specific scenario
curl "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/employees?scenarioId=cls_abc123" \
-H "Authorization: Bearer {api-key}"When querying with a scenarioId, the API returns the merged view -- live data with scenario changes applied.
TIP
Scenario IDs are prefixed with cls_ and can be found in the Flowstate UI on the plan detail page, or by listing plans through the API.
Key Concepts to Remember
- Scenarios are cheap. Create as many as you need for different planning exercises.
- Live data is sacred. Nothing changes in the live layer until a scenario is explicitly merged.
- The merged view is the planning lens. It shows you the future state as if all scenario changes were applied.
- Merging is permanent. Once a scenario is merged, its changes are committed to live data.
- Discarded scenarios are preserved. They serve as an audit trail of plans that were considered but not adopted.
Related Documentation
- Introduction to Flowstate -- Overview of the data model and cost calculation chain
- Employees -- How employee records work in live and scenario contexts
- Vacancies -- Modeling the hiring pipeline in scenarios
- API Reference -- REST API overview including scenario query parameters
- Roles & Permissions -- Who can create, view, and merge scenarios