oro-workflow

name

oro-workflow

description

Use when creating OroCommerce v6.1 approval workflows, customizing checkout flow, defining workflow steps and transitions, configuring transition conditions and actions, setting up operations, or working with workflow scopes. Relevant when the user mentions 'workflow', 'checkout customization', 'approval process', 'state machine', 'transitions', 'operations.yml', 'workflows.yml', or any OroCommerce business process automation.

OroCommerce v6.1 Workflow Configuration Skill

File Locations

• Workflow definitions: Resources/config/oro/workflows.yml
• Operations: Resources/config/oro/operations.yml

Basic Workflow Structure

Each workflow requires label, entity, start_step, steps, and transitions:

workflows:
    document_approval:
        label: Document Approval
        entity: Acme\Bundle\DemoBundle\Entity\Document
        start_step: submitted

        steps:
            submitted:
                label: Submitted
                allowed_transitions: [approve, reject]
            approved:
                label: Approved
                allowed_transitions: [publish, reject]
            rejected:
                label: Rejected
                allowed_transitions: [resubmit]
            published:
                label: Published

        transitions:
            approve:
                label: Approve
                step_to: approved
                message: Document approved
            reject:
                label: Reject
                step_to: rejected
            resubmit:
                label: Resubmit
                step_to: submitted
            publish:
                label: Publish
                step_to: published

Steps without allowed_transitions are terminal states. Step names must be unique across all active workflows on the same entity.

Transition Definitions with Conditions and Actions

transition_definitions:
    approve_definition:
        preconditions:
            '@and':
                - '@eq': [$is_manager, true]
                - '@gte': [$document_priority, 3]
        actions:
            - '@assign_value': [$approved_at, $.now]
            - '@call_method':
                object: $entity
                method: markApproved

transitions:
    approve:
        label: Approve
        step_to: approved
        definition: approve_definition

Preconditions block the transition if false. Actions execute only on success. See references/condition-expressions.md for the full expression list.

Checkout Workflow Customization

Customize checkout by importing and overriding b2b_flow_checkout:

workflows:
    custom_checkout:
        import:
            - workflow: b2b_flow_checkout
        label: Custom Checkout
        metadata:
            is_checkout_workflow: true

CRITICAL: Preserve is_checkout_workflow: true in metadata. Without it, checkout breaks silently. Override individual steps or transitions by redeclaring them under the same key.

Key Pitfalls

1. Step/transition name uniqueness: Names must be unique across ALL active workflows on the same entity type. Use prefixes: document_pending, order_pending.

2. Import path correctness: Reference the original workflow name exactly. Typos silently fail without error.

3. Condition syntax: Conditions use @ prefix for functions and $ prefix for attributes. Missing either causes parsing errors:

   - '@eq': [$is_manager, true]  # Correct
   - 'eq': [$is_manager, true]   # Wrong — no @ prefix
   - '@eq': [is_manager, true]   # Wrong — missing $ prefix
   

See Also

• references/workflow-patterns.md — Attributes, operations, event-triggered transitions, scopes, common patterns, testing/debugging, WorkflowManager API
• references/condition-expressions.md — Full expression reference
• v6.1 notes