BENEFIT: Benefit
A specific expected benefit defined at initiative approval and tracked through realisation: baseline -> target -> actual with variance, status, and review cycle.
BENEFIT definition shipped with DemandFlow. Administrators can add, remove, rename, or re-type fields, change which ones are required, and alter the layout from the Definitions screen in Settings. Your tenant's current schema may differ from what is shown here. To read the current definition at any time, GET the DEFINITION object whose id matches BENEFIT.Entity properties
| Property | Value |
|---|---|
| Entity code | BENEFIT |
| Display name | Benefit |
| Plural | Benefits |
| Level | 12500 |
Use cases
BENEFIT is a child of INI (comboKey SUB|INI|BENEFIT) and represents a single, measurable benefit that an initiative promised to deliver. Benefits progress through lifecycle states (Expected -> Tracking -> Partially/Fully Realised / Not Realised / Cancelled). Each benefit captures a baseline (before-state), a target value, and an actual value once realised, from which variance and variancePercent are derived. Benefits may optionally link to a KPI (same metric tracked via KPI entity) and to a delivering PJ for portfolio roll-ups.
Fields
Benefit Definition: Basic Information
| Field | Type | Required | Notes |
|---|---|---|---|
name | text | Yes | Benefit Name. |
description | text (multi-line) | Description. Placeholder: What benefit does the initiative promise?. | |
category | enum | Yes | Category. Valid ids: costSaving (Cost Saving), revenueIncrease (Revenue Increase), efficiencyGain (Efficiency Gain), riskReduction (Risk Reduction), customerSat (Customer Satisfaction), compliance (Compliance), brand (Brand), other (Other). |
owner | reference → user | Benefit Owner. |
Benefit Definition: Measurement & Targets
| Field | Type | Required | Notes |
|---|---|---|---|
measureType | enum | Yes | Measure Type. Valid ids: currency (Currency), percentage (Percentage), number (Number), boolean (Boolean). |
unit | text | Unit. Placeholder: e.g. GBP, %, hours. | |
baselineValue | number | The value before the initiative delivers (the 'from') | |
targetValue | number | The value we expect to reach (the 'to') | |
targetDate | date | Target Date. |
Benefit Definition: Links
| Field | Type | Required | Notes |
|---|---|---|---|
kpi | reference → KPI | KPI tracking the same metric, if any |
Realisation
| Field | Type | Required | Notes |
|---|---|---|---|
status | enum | Yes | Status. Valid ids: expected (Expected), tracking (Tracking), partial (Partially Realised), full (Fully Realised), notRealised (Not Realised), cancelled (Cancelled). |
actualValue | number | Actual Value. | |
realisedDate | date | Realised Date. | |
variance | number | Read-only. Variance (actual - target). | |
variancePercent | number | Read-only. % of planned improvement achieved vs baseline |
Realisation: Evidence
| Field | Type | Required | Notes |
|---|---|---|---|
evidence | text (multi-line) | How was realisation measured?. Placeholder: Data source, calculation, audit trail.... |
Review: Review Cycle
| Field | Type | Required | Notes |
|---|---|---|---|
reviewFrequency | enum | Yes | Review Frequency. Valid ids: monthly (Monthly), quarterly (Quarterly), annually (Annually). |
nextReviewDate | date | Flagged when overdue | |
reviewNotes | text (multi-line) | Review Notes. |
Relationships
- Lookups:
kpipoints at aKPIrecord. - Related lists:
PJ. - Activity: activity timeline panel attached.
Creating a Benefit via the API
POST /v1/objects
Authorization: Bearer <your-pat>
Content-Type: application/json
{
"entity": "BENEFIT",
"level": 12500,
"comboKey": "SUB:<your-sub-id>|ENT:",
"name": "Benefit Name",
"category": "costSaving",
"measureType": "currency",
"description": "Description"
}Listing Benefits records
GET /v1/entities/BENEFIT/SUB