Record Lifecycle – managing state transitions in trellispark

by | Sep 30, 2022 | Blog, Dev Team

Records model information about real-world objects.

Some real-world objects have a distinct lifecycle that need to be modelled by the records that represent them. For example, an Order might initially exist in a Draft state, it is then Submitted, goes through Fulfillment, before finally being Closed.

The trellispark UX Creator contains a State Transition model so that we can fully model the lifecycle of the records we manage. We did this because the user experience, fields, actions, and events available on a record generally vary based on its state. Adding a State Transition model to our UX Creator greatly extended the range of user experience we could create using configuration data rather than having to write custom user experience pages.

In trellispark, a record state transition follows this general pattern:

State transition general flow

At the start of the process, if the user and record meet some form of Gateway test, then the user is presented with a triggering event. The Gateway could be simply that the record is in the Initial State and that the user has a role that allows them to initiate the Event Trigger. The Gateway may impose additional checks as required to support business rules. For example, a general user might be able to Submit an Order under $10k, but only managers can submit Orders over $10K.

If the user meets the gateway criteria and triggers the event, then the record is locked, and a check is made to ensure that the user has access to the record and the record is still in the Initial state. If any of these checks fail, then the transition is aborted, and the record is unlocked.

If the transition is proceeding, then an optional set of Before Change Actions is applied against the locked record. If these actions fail, then any changes are rolled back before reporting the failure, aborting the transition and unlocking the record.

Once the Before Change Actions have been successfully completed (if required at all), then the State of the record can be changed. At this stage, it may be necessary to cascade a State Transition to dependent child records. In our Order example, we may need to change the state of Order Line Items from Draft to Locked so that the user can’t change an Order once Submitted.

The After Change Actions are then executed once the record has been transitioned to the Final State. If these actions fail, then the changes need to be rolled back as necessary. Note this does not always mean that the record reverts back to the Initial State.

Completion of the After Change Actions signals that the state transition is complete so that the record can be unlocked and the underlying user experience can be refreshed to display the updated record in its Final State.

In trellispark, the Lifecycle of a Concept is defined on its Lifecycle tab:

Individual State Transitions are defined using the following form:

This simple State Transition model is fully integrated into the trellispark user experience, interacting with the Service layer and Open APIs. The functionality is generic so that it will work with any type of concept record.

Being able to funnel all state transitions through the same process makes it easy to extend the security and functionality of the pipeline. For example, we added logging of state transitions to the instance record as a series of tracked Milestones.

In practice, we have found that many workflow tasks revolve around simple record state changes that can be handled purely through the configuration data collected on the Concept’s Lifecycle tab. The ability to inject custom logic for Gateway, Before/After Change Actions enables the creation of sophisticated workflow without the need to create complex custom user experience pages. The custom logic can directly access the underlying records in the Data Agnostic Storage and be deployed as separate configuration units in either the database or as Open APIs.