Skip to main content

Dynamic Step Properties & Configuration

The Step Properties Panel is the engine room of the Approval Workflow system. When you click a node in the Visual Graph Designer, this panel dynamically generates configuration options based on the global state engine.

Step Properties Panel

1. Origin & Evolution​

  • The Problem: Historically, approval workflows were rigid. Button labels, routing paths, and email triggers were hardcoded into specific modules. If HR wanted to change a button from "Approve" to "Grant Leave", it required a developer. Furthermore, early iterations struggled with intermediate approvals — a manager approving step 1 of 3 would accidentally trigger a final "Document Approved" email to the employee.
  • The Evolution: To solve this, the architecture migrated to a decoupled Module State Management (MSM) system. The Step Properties panel evolved from a static form into a highly dynamic UI. Instead of storing hardcoded logic, it now acts as a listener — constantly querying MSM and Persona Management in real-time to determine what actions are legally permissible at any given node.

[!WARNING] The MSM Dependency Gotcha: Because the Workflow Designer is decoupled, you cannot create brand new buttons inside this properties panel. If you want a button called "Send to Legal", you must first navigate to the Module State Management tab, create the action SEND_TO_LEGAL and define its transition. Only then will it appear here as an Allowed Action to toggle on.

2. Current State (How it works under the hood)​

At a practical level, the panel is divided into distinct, state-aware sections:

Approval Context & Allowed Actions​

  • Context Polling: The designer queries MSM to find which status is marked as the is_approval_trigger (e.g., PENDING). This dictates when the step activates.
  • Dynamic Action Filtering: The panel automatically hides the mandatory APPROVE and REJECT actions. For the rest (e.g., Add Comment, Return), it checks the MSM transition dictionary. If an action is not a valid transition from the Trigger Status in MSM, it will not appear in the panel.
  • Canvas Routing Handles: Selecting an action reveals direction controls:
    • ⬅️ Backward: Creates a left handle (for returns).
    • ❌ None: No handle (for non-routing actions like comments).
    • ➡️ Forward: Creates a right handle (for progression).

Approver Assignment & Project Context​

The panel connects to Persona Management. If a project-based persona (like Project Manager) is selected, the UI dynamically changes:

  • Project-Aware Modules (Expenses, Timesheets): Provides a toggle between Dynamic (auto-detects project from the document) and Specific (forces routing to a hardcoded project).
  • Non-Project Modules (Leave): The system knows the module lacks project context, forcing a SPECIFIC PROJECT REQUIRED fallback.

Smart Notifications & Overrides​

  • Intermediate Step Logic: If the step is in the middle of a workflow, the frontend automatically maps the "Approve" action to STEP_APPROVE. This intentionally suppresses final "Approved" notifications to avoid confusing end-users.
  • Customization: Users can toggle off the Global MSM Defaults to explicitly rename buttons just for this step, or hand-pick from a grid of every notification template in the system.

3. Purpose & Use Case​

  • Why it exists: To give organization admins visual, no-code control over complex approval matrices while guaranteeing that their designs never violate the global business logic defined in MSM.
  • Who it is for: System Administrators and Operations Managers who need to rapidly deploy or alter business processes without writing code.
  • Differentiator: Unlike generic workflow builders (like Zapier), this panel is intrinsically bound to the platform's proprietary Persona and Module State definitions, making it completely bespoke to organizational hierarchy.

4. Future Trajectory​

  • API & Webhook Triggers: The panel is moving toward supporting automated hooks, where a specific step action could trigger an external API call (e.g., pinging an external HRMS or ERP system) rather than just sending an email.
  • AI-Assisted Routing: Future iterations signal the inclusion of LLM-based conditional logic, where a node could query an AI agent (e.g., "If receipt looks fraudulent, route to Finance Director").
  • Dynamic Persona Resolution: Enhancing the Project Context logic to pull manager hierarchies from external Active Directory (Azure AD/Okta) syncs.

5. Potential Impact​

  • The Paradigm Shift: This heavily decoupled approach shifts the burden of workflow management entirely from engineering to operations. It enables hyper-agile process updates.
  • Risks & Challenges: The primary risk is "Ghost Rules". Because the properties panel relies heavily on MSM, if an admin deletes a status or action from the global MSM dictionary, any locked workflow currently relying on that action in its Step Properties could face execution errors. The system currently handles this by locking active workflows, but managing schema drift between MSM and saved graphs remains a complex challenge.

Appendix: Field-by-Field Architecture Breakdown​

To fully understand the designer, here is exactly what every section, button, and label in the UI does under the hood when editing an approval step:

1. Module Header (Module: PEOPLE)​

  • Frontend Action: Injects the moduleCode prop into the panel's React state.
  • System Impact: Dictates which MSM dictionary to load. If this changes, the entire dropdown of allowed actions and trigger statuses swaps instantly to match the new module's rules.

2. Step Configuration (Reporting Manager)​

  • Frontend Action: Triggers the updateNodeData(id, { step_name: newName }) React hook.
  • System Impact: Updates the node label on the canvas. This is purely for display on the graph and in user-facing progress timelines; it does not alter routing logic.

3. Approval Context (PENDING)​

  • Frontend Action: Runs msmStatuses.find(s => s.is_approval_trigger).
  • System Impact: Defines the entry condition. The system actively scans the MSM dictionary to prove this step will only execute when a document's internal state matches this exact trigger status.

4. Approver Assignment (f0ea1caa-a254-45fa...)​

  • Frontend Action: Binds the raw persona_id UUID from the dropdown to the node's state (approver_persona_id).
  • System Impact: At runtime, the backend will resolve this UUID against the document owner (e.g., querying the org chart to dynamically find the document owner's direct boss).

5. Step Action Notifications (Approve / Reject -> Customize)​

  • Toggle OFF: Falls back to defaultEvents mapped from msmTransition?.notification_event_codes. If the UI says "No default notifications defined", it means the global MSM dictionary is completely empty for this specific transition.
  • Toggle ON (Customize): Mutates the transitions array on the node data. It allows you to inject an override button_label and an explicit array of event_codes (templates) that bypass global rules strictly for this specific step.

6. Transition Buttons Warning​

  • UI Label: "Buttons, labels, and status transitions are now managed globally..."
  • System Impact: A static UI warning preventing admins from creating buttons directly in the designer. It forces admins to define buttons in the global MSM dictionary first, ensuring absolute database consistency across the platform.

7. SLA & Timeout Configuration (72h -> AUTO_APPROVE)​

  • Frontend Action: The SLAEscalationBuilder component writes to an array called sla_escalation_rules.
  • System Impact: Saves a JSON payload (e.g., Hours: 72, Action: AUTO_APPROVE) to the node. A backend cron job reads this array to fire automated actions exactly 72 hours after the step started.

8. Conditional Logic​

  • Frontend Action: The ConditionLogicBuilder generates a new routing handle on the node colored Amber (CONDITION NOT MET).
  • System Impact: Saves a JSON object containing a logic_operator and an array of rules to the node. When a document arrives, the backend evaluates the rules; if they fail, the document routes down the Amber path, completely bypassing the step.

Allowed Actions Logic (Deep Dive)​

The Allowed Actions section acts as a strict gatekeeper for which buttons appear to the approver. Here is exactly what you will see, what you won't see, and why:

1. What you will NEVER see: APPROVE and REJECT​

  • Why they are hidden: The system explicitly filters these out (.filter(a => !['APPROVE', 'REJECT'].includes(a.action_code))). Because this is an Approval Node, the system treats Approve and Reject as mandatory, indestructible actions. Since you cannot delete them from an approval step, they are hidden from this toggle list. Their configuration happens further down in the Step Action Notifications section instead.

(Note: While APPROVE is hidden, if your MSM dictionary explicitly defines a STEP_APPROVE transition, it will appear as an optional toggle, as it is treated as a distinct routing action.)

2. What you WILL see (The MSM Filter)​

You will only see actions that are mathematically possible based on your Module State Management (MSM) dictionary.

  • How it works: The UI looks at the "Approval Context" at the top to find the trigger status (e.g., PENDING). It then scans the entire MSM Transitions database and filters out any action that does not have a valid transition starting from PENDING.

Because an Approval Step usually triggers when a document enters PENDING, here are the standard actions you will typically see available to toggle:

  • Step Approve (STEP_APPROVE): Used explicitly for multi-stage workflows to push a document to the next manager without triggering the final "Approved" state.
  • Return for Correction (RETURN): Sends the document backwards from PENDING back to DRAFT.
  • Add Comment (COMMENT): Creates a loop transition from PENDING back to PENDING so the approver can ask questions without changing the state.
  • Withdraw Application (WITHDRAW): Moves the document from PENDING to WITHDRAWN (typically assigned to the original Requestor).

Why you won't see other common buttons:

  • You will not see Submit for Approval because that transitions from DRAFT to PENDING. By the time the document reaches this node, it is already PENDING.
  • You will not see Cancel, Mark as Paid, or Process. Those are post-approval actions that only happen after the document reaches the APPROVED status, making them invalid for a PENDING approval step. This dynamic filtering prevents admins from accidentally putting a "Mark as Paid" button in the middle of a manager's approval flow.

3. Visual States & Routing Controls​

When an action does show up, it has two states:

  • Unselected (Grey Outlined): The action is legally allowed by MSM, but you have chosen not to give it to the Approver for this specific step.
  • Selected (Solid Primary Color): The action is enabled. When you click it, the frontend pushes the action into the node's JSON array.

Once an action is Selected, the routing controls (⬅️ ❌ ➡️) appear:

  • ⬅️ Backward (Left Handle): Generates a connection dot on the left side of the node. Used for actions like RETURN where you need to draw a line backwards.
  • ❌ None (No Handle): Deletes the connection dot entirely. Used for actions like ADD_COMMENT where the document stays on the exact same workflow step.
  • ➡️ Forward (Right Handle): Generates a connection dot on the right side. This is the default when you first select an action.

Dynamic UI States (What might not show up)​

The Step Properties panel heavily utilizes conditional rendering. Depending on your configuration, certain buttons and sections will disappear entirely. Here is what to look out for:

  • Missing "Project Context" Section: This section only appears if you select Project Manager or Project Leader in the Approver Persona dropdown. For any other persona (like Reporting Manager or Department Head), the UI completely hides this section because project contexts are irrelevant to them.
  • Missing "Dynamic / Specific" Toggle: If you do see the Project Context section, but the toggle buttons are missing (replaced by a blue SPECIFIC PROJECT REQUIRED badge), it means your current Module (e.g., Leave) is not "Project Aware." The UI removes the dynamic option because there is no project data to extract from the document.
  • Missing Action Direction Handles (⬅️ ❌ ➡️): These three mini-buttons will only appear after you click to enable an Allowed Action. If an action is not selected (greyed out), its routing controls remain hidden.
  • "No additional actions defined..." Warning: Under Allowed Actions, if you see this italicized text, it means your global MSM dictionary has absolutely zero transitions configured for the trigger status (other than the mandatory Approve/Reject).
  • Hidden Notification Overrides: The text inputs for "Button Label Override" and the grid of notification checkboxes will remain completely hidden until you flip the "Customize" switch to ON.