Entity Lifecycle

Concept

Entity Lifecycle is a concept feature. It's still being developed and can change before it's released.

Audience: Low-code Engineers

Skill Prerequisites: Entities, Workflows

General Description

Many records move through steps: a purchase request is drafted, submitted, approved, ordered and received. Entity Lifecycle lets you define those steps on the entity itself. You add a State property, draw its states and the transitions between them, and say who may run each transition and what it needs. The platform then keeps every record in a valid state.

When you save a lifecycle, Plant an App:

• Starts every new record in the initial state, and refuses any change of the state that doesn't go through a transition, whether it comes from a form, a workflow, an import or the API.
• Adds a state badge and one button per transition to the generated detail page, and a button per transition to each row of the list page. Each button shows only to the people who may run the transition, and only while the record is in the transition's starting state.
• Opens a popup for transitions that need fields or a comment.
• Generates an action per transition, for your workflows, and, when the entity has API Access, a transition method in its generated API.
• Applies field rules per state, for example Rejection Reason is read-only once a request is rejected.
• Creates a workflow contract for the transitions' Before and After workflows.

Use a lifecycle instead of a plain text "Status" property when the order of the steps matters, when only some people may move a record on, or when you need to know who moved it and when.

How the Parts Fit Together

Part	What it does	Page
State property and Lifecycle tab	Define the states, the transitions, the field rules and the permissions of each state.	Lifecycle Designer
Generated buttons, popups, actions and API	Move records through the lifecycle, from the pages, workflows and other systems.	Running Transitions
Record History	Keep an audit trail of who created, changed, moved or deleted each record.	Record History
Record owners and Can Read	Decide whose records "own records" means, and let people run a transition without editing the record.	Record Owners and Can Read
Checklists	Create tasks when a record enters a state. Needs Built-in Tasks.	Checklists on Lifecycle States

Key Concepts

State property: a property of type State. It stores the key of the record's current state. An entity can have more than one State property; each has its own lifecycle, and transitions never cross from one to another.

State: a step in the lifecycle, with a name, a key and a color. One state is the initial state, where new records start. States where a record's lifecycle ends can be marked final. The key is what's stored in the record, so you can rename a state at any time without touching data.

Transition: a named move from one state to another, for example Approve from Submitted to Approved. A transition decides who may run it, under which condition, which fields need a value, whether it asks for a comment, and which workflows run before and after it.

Field rules: how each property behaves while a record is in a state: as on any form, required, read-only or hidden.

Permissions by state: narrow a role's Read, Edit and Delete permissions while records are in a state, for example drafts readable only by their author.

Example: Purchase Requests

The pages in this section use a Purchase Request entity with a State property named State. Its lifecycle is:

Transition	From	To	Notes
Submit	Draft (initial)	Submitted	Run by Employees.
Approve	Submitted	Approved	Run by Line Managers.
Reject	Submitted	Draft	Run by Line Managers. Rejection Reason is required.
Order	Approved	Ordered	Run by Buyers.
Receive	Ordered	Received
Close	Received	Closed (final)

A new request starts in Draft. An employee fills it in and clicks Submit. A line manager either clicks Approve, or clicks Reject, types a reason in the popup and sends the request back to Draft. A buyer then orders the goods, and the request moves on until it's closed.

Getting Started

1. In Configuration > Entities, open the entity and go to the Properties tab.
2. Add a property, click its type and choose Custom Lifecycle or one of the templates in the Lifecycle category. See Adding a State Property.
3. Open the Lifecycle tab. Add states, drag between them to add transitions, and set each transition's roles and required fields.
4. Save the entity. The lifecycle is saved with it, and the generated pages get their badge and buttons.
5. Open the entity's page as a user in one of the transition's roles, and move a record through the lifecycle.

Plans and Licensing

Entity Lifecycle works on every plan: the State property, the Lifecycle tab, transitions, conditions, field rules, the generated buttons, actions and API, and the Before and After workflows. These parts are part of the Enterprise plan:

Feature	License feature	Without it
Record History	Lifecycle.History	The History tab shows a lock and nothing is recorded.
Permissions by state	Lifecycle.Permissions	The state panel shows a lock. Saved permissions by state are kept but do nothing.
The transition contract in the Before and After workflow pickers	Workflows.Contracts	The pickers list every workflow, and the workflows receive the transition's values by input name.

See also Enterprise Workflows for how Entity Lifecycle works with Built-in Tasks and BPMN 2.0 workflows.

Considerations

• An existing property can't become a State property. The type of a saved property can't change, so add a new State property instead of converting an existing text "Status" property.
• States have no time limits. A lifecycle doesn't track how long a record stays in a state or raise an event when it stays too long.
• There's no token listing the transitions available on a record. The generated buttons already show only the available ones.

Revised 11/12/2026