US: User Story
A user story on a kanban board with subtasks, sprint planning, definition of done, and live status updates.
US 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 US.Entity properties
| Property | Value |
|---|---|
| Entity code | US |
| Display name | User Story |
| Plural | User Stories |
| Level | 510 |
Use cases
A user story on a kanban board with subtasks, sprint planning, definition of done, and live status updates.
US is the primary user story entity used with the kanban board system. It uses kanbanStatus and kanbanProgress custom field types that integrate with the board's column-based workflow. The board (TEAM) is preloaded and the liveUpdates flag enables real-time status synchronisation across users viewing the same board. Stories link to projects (PJ), epics (EPIC), and sprints (SPRINT) for planning context. The assigned field uses multiuser with filter:team to restrict assignment to board team members. Subtasks are STASK entities linked via comboKey SUB|US. The dynamicform row type renders custom fields defined in the board configuration, allowing each team to have different field requirements. The Development panel includes a Definition of Done checklist (checkboxGroup), technical/testing/deployment notes, and URL links for pull requests and design documents. The Plan panel provides a Gantt view (usgantt) of subtasks. AI is enabled via ai:true and context.getAgileData for intelligent story analysis.
Fields
Story Details
| Field | Type | Required | Notes |
|---|---|---|---|
ref | text | Reference. Read only. | |
name | text | Yes | Story title. |
status | kanbanStatus | Yes | Status. |
priority | enum | Yes | Valid ids: 1 (Critical), 2 (High), 3 (Normal), 4 (Low). |
description | text (multi-line) | Description. | |
acceptanceCriteria | text (multi-line) | Acceptance criteria. | |
tags | tags | Tags. |
Planning & Assignment
| Field | Type | Required | Notes |
|---|---|---|---|
board | reference → TEAM | Team. Read only. | |
ownerId | reference → user | Requested by. Read only. | |
project | reference → PJ | Project. | |
assigned | array of references → user | Assigned To. Read only. | |
duedate | date | Due Date. | |
startDate | date | Start Date. | |
completedDate | date | Completed Date. |
Technical Details
| Field | Type | Required | Notes |
|---|---|---|---|
technicalNotes | text (multi-line) | Technical Notes. | |
testingNotes | text (multi-line) | Testing Notes. | |
deploymentNotes | text (multi-line) | Deployment Notes. |
Links & References
| Field | Type | Required | Notes |
|---|---|---|---|
pullRequestUrl | text (URL) | Pull Request. URL string. | |
issueUrl | text (URL) | Issue/Ticket URL. URL string. | |
designUrl | text (URL) | Design Documents. URL string. | |
documentationUrl | text (URL) | Documentation. URL string. |
Definition of Done
| Field | Type | Required | Notes |
|---|---|---|---|
definitionOfDone | array | Checklist. |
Attachments and additional panels
- Activity timeline panel attached.
- File attachment on
attachments. Allowed types: *.
Relationships
- Lookups:
boardpoints at aTEAMrecord;projectpoints at aPJrecord. - Related lists:
STASKvia comboKey (format:SUB|US).
Creating a User Story via the API
POST /v1/objects
Authorization: Bearer <your-pat>
Content-Type: application/json
{
"entity": "US",
"level": 510,
"comboKey": "SUB:<your-sub-id>|ENT:",
"name": "Example name",
"status": "Example status",
"priority": "1"
}Listing User Stories
GET /v1/entities/US/SUB