Complex Workflow Entity - Subscription with Multi-Step Business Process
Description
This example showcases a sophisticated business entity with an extensive workflow definition. The Subscription entity demonstrates how Stack9 handles complex business processes with multiple states, conditional transitions, and automated actions. It includes over 90 fields covering customer information, payment details, marketing attribution, and business-specific data. The workflow contains 10 states with various transitions including validation, customer matching, welcome pack sending, deferrals, and suspensions. This pattern is ideal for entities that require strict state management and business process enforcement.
Use Case
Manages lottery and donation subscriptions in a comprehensive CRM system. The entity handles the entire subscription lifecycle from initial creation through validation, customer matching, activation, deferrals, suspensions, and eventual completion or cancellation. Each state transition can trigger automated processes and requires specific conditions to be met.
Key Features
- Extensive field set including customer details, payment information, and business attributes
- Complex workflow with 10 states and multiple conditional transitions
- Workflow conditions that must be met before certain transitions
- Integration with related entities (customer, sales_order_items, clubs)
- Support for both success (Ended) and failure (Cancelled) outcomes
- Workflow actions can be system-triggered or user-initiated
- State ownership controls for different user groups
JSON Definition
{
"head": {
"name": "Subscription",
"key": "subscription",
"pluralisedName": "Subscriptions",
"allowComments": true,
"allowTasks": true,
"isActive": true
},
"fields": [
{
"label": "Customer",
"key": "customer_id",
"validateRules": {},
"behaviourOptions": {},
"relationshipOptions": {
"ref": "customer"
},
"typeOptions": {
"label": "crn"
},
"type": "SingleDropDown"
},
{
"label": "Customer name",
"key": "customer_name",
"validateRules": {
"minLength": 0,
"maxLength": 100
},
"behaviourOptions": {},
"type": "TextField"
},
{
"label": "Customer Type",
"key": "customer_type",
"description": "Identifies if the customer is a person or a business entity",
"validateRules": {
"required": false
},
"behaviourOptions": {},
"typeOptions": {
"values": ["Individual", "Business"]
},
"type": "OptionSet"
},
{
"label": "Frequency",
"key": "frequency",
"validateRules": {},
"behaviourOptions": {},
"typeOptions": {
"values": ["Monthly", "Quarterly", "Annual"]
},
"type": "OptionSet"
},
{
"label": "Business unit",
"key": "business_unit",
"validateRules": {
"required": true
},
"behaviourOptions": {},
"typeOptions": {
"values": ["Lottery", "Donor"]
},
"type": "OptionSet"
},
{
"label": "Sales Order Items",
"key": "sales_order_items",
"validateRules": {},
"behaviourOptions": {},
"relationshipOptions": {
"ref": "sales_order_item"
},
"typeOptions": {
"relationshipField": "subscription_id"
},
"type": "Grid"
},
{
"label": "Payment method",
"key": "payment_method",
"validateRules": {},
"behaviourOptions": {},
"typeOptions": {
"values": ["Credit card", "Direct debit"]
},
"type": "OptionSet"
},
{
"label": "Subscription number",
"key": "subscription_number",
"placeholder": "System generated",
"description": "Unique subscription number",
"validateRules": {
"required": false
},
"index": true,
"behaviourOptions": {},
"type": "NumericField"
}
],
"hooks": [],
"folderKey": "sub",
"workflowDefinition": {
"steps": [
{
"key": "pending_validation",
"name": "Pending validation",
"description": "Customer subscription details need to be verified and confirmed",
"color": "yellow",
"order": 1
},
{
"key": "pending_customer_matching",
"name": "Pending customer matching",
"color": "darkgrey",
"order": 2
},
{
"key": "send_welcome_pack",
"name": "Send welcome pack",
"color": "darkgrey",
"order": 3
},
{
"key": "active",
"name": "Active",
"description": "Customer subscription is active",
"color": "darkgrey",
"order": 4
},
{
"key": "validation_failed",
"name": "Validation failed",
"color": "darkgrey",
"order": 5,
"ownershipDetails": {
"userGroups": ["css"],
"userFields": []
}
},
{
"key": "deferred",
"name": "Deferred",
"description": "Customer subscription has been deferred",
"color": "darkgrey",
"order": 10
}
],
"outcome": {
"success": {
"label": "Ended"
},
"failure": {
"label": "Cancelled"
}
},
"actions": [
{
"key": "pending_customer_match",
"name": "Pending customer match.",
"default": true,
"preventUserInteraction": true,
"from": {
"step": ["pending_validation"]
},
"to": {
"step": "pending_customer_matching"
}
},
{
"key": "validation_failed",
"name": "Validation failed",
"default": false,
"preventUserInteraction": true,
"from": {
"step": ["pending_validation"]
},
"to": {
"step": "validation_failed",
"reasonRequired": true
}
},
{
"key": "cancel",
"name": "Cancel",
"default": false,
"from": {
"step": [
"validation_failed",
"pending_sale_confirmation",
"customer_matching_failed",
"send_welcome_failed"
]
},
"to": {
"outcome": 2
}
},
{
"key": "defer",
"name": "Defer",
"default": false,
"preventUserInteraction": true,
"from": {
"step": ["active"]
},
"to": {
"step": "deferred"
}
},
{
"key": "customer_end_subscription",
"name": "Customer end subscription",
"default": true,
"preventUserInteraction": true,
"from": {
"step": ["active", "deferred"]
},
"to": {
"outcome": 1,
"reasonRequired": true
}
}
],
"conditions": [
{
"key": "customer_required",
"name": "Customer is required",
"description": "Subscription must have a linked customer",
"action": "subscription_confirmed",
"required": true
}
]
}
}
Notes
- The workflow uses
preventUserInteraction: truefor system-triggered transitions - State ownership can be assigned to specific user groups (e.g., "css" for customer service)
- The
reasonRequired: trueflag enforces documentation for certain transitions - Workflow conditions provide additional validation before state changes
- The entity uses indexed fields for performance optimization on frequently queried data
- Grid fields establish one-to-many relationships with related entities