You are browsing the documentation for version 3.1 of OroCommerce, OroCRM and OroPlatform, which is no longer maintained. Read version 5.1 (the latest LTS version) of the Oro documentation to get up-to-date information.

See our Release Process documentation for more information on the currently supported and upcoming releases.

Workflow Transition Forms


Sometimes the data available in the system is not enough to progress the workflow automatically by clicking one button. Therefore, users have to provide additional data in UI forms to be able to proceed (from several fields to complex entities).

Workflow transitions can be configured to handle custom data provided by a user by displaying a form on the UI before a transition commit happens. Examples below illustrate the common ways to configure transition forms.

Simple Example

Suppose we have a workflow that handles only one required data input from a user.

 1 workflows:
 2     greeting_flow:
 3         entity: Oro\Bundle\UserBundle\Entity\User
 4         entity_attribute: user
 5         defaults: { active: true }
 6         attributes:
 7             the_message:
 8                 type: string
 9         steps:
10             congratulated:
11                 allowed_transitions: [ congratulate_with ]
12         transitions:
13             congratulate_with:
14                 is_start: true
15                 step_to: congratulated
16                 form_options:
17                     attribute_fields:
18                         the_message:
19                             options:
20                                 constraints:
21                                     - NotBlank: ~
22                 destination_page: view
23                 transition_definition: message_definition
24         transition_definitions:
25             message_definition:
26                 actions:
27                     - '@flash_message': {message: $.data.the_message, type: success}

Above is a simple working example of a cycled workflow with one step and one transition. On transition congratulate_with, we should force the user to fill a text input in the the_message field that corresponds to our configured workflow attribute. The field is also required by constraints in form attribute_fields options. Then, we can submit it as a transition payload. Next, we should see a @flash_message with the text we prompt on the dialog (the default for transition display_type) that is flashed on the entity view page.

Extended Example

Custom types and form_init:

 1 workflows:
 2     user_update_flow:
 3         entity: Oro\Bundle\UserBundle\Entity\User
 4         entity_attribute: user
 5         defaults: { active: true }
 6         attributes:
 7             my_message:
 8                 type: string
 9             my_dote:
10                 type: object
11                 options:
12                     class: DateTime
13         steps:
14             congratulated:
15                 allowed_transitions: [ congratulate_with ]
16         transitions:
17             congratulate_with:
18                 is_start: true
19                 step_to: congratulated
20                 form_options:
21                     form_init:
22                         - '@create_object':
23                             class: \DateTime
24                             attribute: $.data.my_date
25                             parameters: ['tomorrow']
26                     attribute_fields:
27                         my_message:
28                             options:
29                                 constraints:
30                                     - NotBlank: ~
31                         my_date:
32                             form_type: my_date_picker #here your custom date picker
33                 destination_page: view
34                 transition_definition: message_definition
35         transition_definitions:
36             message_definition:
37                 actions:
38                     - '@flash_message': {message: $my_message, type: success}

If we need a more complex form to be filled by a user who is performing a transition, we need to specify fields for the data that we need. But before that, let us prepare the data that will be displayed to a user in form_init.


The form_init node is under form_options. It is an action that will be performed before form rendering (see Action Component for more details). Here, you can prepare your data before form rendering. In the sample configuration we are creating, a new DateTime object is pre-configured to tomorrow. So that on our custom “my_date_picker” type we will see the day after today predefined on the form.

Custom Form Type Example

You can also use your custom form type for the whole transition handling. Have a look at the example below:

 1 workflows:
 2     quote_update_circular:
 3         entity: Oro\Bundle\CustomerBundle\Entity\CustomerUser
 4         entity_attribute: customer_user
 5         defaults: {active: true}
 6         attributes:
 7            quote: #here we will store our form data result
 8                type:  entity
 9                options:
10                    class: 'Oro\Bundle\SaleBundle\Entity\Quote'
11         steps:
12             quote:
13                 allowed_transitions:
14                     - transit_quote
15         transitions:
16             transit_quote:
17                 step_to: quote
18                 is_start: true
19                 transition_definition: quote_update_definition
20                 display_type: dialog
21                 form_type: 'Oro\Bundle\SaleBundle\Form\Type\QuoteType' #define a custom form type to use for transit
22                 form_options:
23                     configuration: #define configuration for the custom form type
24                         handler: 'default' #which handler should process the from (custom form transition handler)
25                         template: 'OroSaleBundle:Quote:update.html.twig' #our complex form page template
26                         data_provider: 'quote_update' #template context data provider that will provide data for the template
27                         data_attribute: 'quote' #attribute to store form data and get from
28                     form_init: #here we will prepare our form
29                         - '@tree':
30                             conditions: #if no quote is defined in our worfklow data ... ->
31                                 '@empty': [$quote]
32                             actions:
33                                 - '@create_object': #.. -> we will create it
34                                     class: Oro\Bundle\SaleBundle\Entity\Quote
35                                     attribute: $.data.quote # and set to our data_attribute defined in configuration
36                                     parameters: ~
37                         - '@assign_value': #add some more preparation of the form data object below by WF entity data
38                             attribute: $.data.quote.customerUser
39                             value: $customer_user
40                         - '@assign_value':
41                             attribute: $.data.quote.customer
42                             value: $customer_user.customer
43                     attribute_fields: ~ #attribute fields should be ommited as we use totally custom form type
44         transition_definitions:
45             quote_update_definition:
46                 actions:
47                     - '@flash_message':
48                         message: 'Workflow transited. Entity updated!'
49                         type: 'success'
50                     - '@redirect': {route: 'oro_sale_quote_index'}

Here, the configured workflow creates a new Quote from the start on Customer User page and performs updates for the Quote circularly in each transition, because it brings us back to the same step.

Now, let’s look at configuration specific moments.

To use your custom form type that replaces the default transition form, set the type in form_type option to your custom type.


FQCN should be used as the value for form_type when defining custom form type and this form must be resolvable by “Form Registry”. Together with that, you must specify the correct configuration for the type customization (handler, template, data_provider, data_attribute options). Here, we have Oro\Bundle\SaleBundle\Form\Type\QuoteType form type. But to handle this complex form type properly, specify additional options in the form_options.configuration node.

They are:

  • handler - an alias of a registered service by tag oro_form.registry.form_handler. You can use the default one by passing ‘default’. See more about form update handler in Update Handler.

  • template - the name of a template that should be used for the custom form, the default value is OroWorkflowBundle:actions:update.html.twig, and this template can be used as a starting point for customizations.


It should be extended from OroUIBundle:actions:update.html.twig for compatibility with transition form page (usually all Oro update templates do so).

  • data_provider - an alias of a registered service by tag oro_form.form_template_data_provider that implements Oro\Bundle\FormBundle\Provider\FormTemplateDataProviderInterface. It should return all necessary data for specified template as controllers usually do.

  • data_attribute - the name of data attribute where form data payload should be taken from by workflow engine to pass into form and put to as result of handling.

Form Reuse Recommendation

The best approach when creating a new entity management (entity controller) while developing is to use the Oro\Bundle\FormBundle\Model\UpdateHandler::update method functionality. So that if you encapsulate your logic into proper parts of the form handling process, then you should easily be able to create a workflow with the custom form type. As custom form workflow transition handling is based on reusing those parts in transition configuration.

Transition Forms and Layouts

For layout based sites, use the Layout Update functionality to the UI customization capabilities of a transition form.

First, make sure you are familiar with the type of interface build, so that you could proceed with managing layout-based transition forms.

Layout Imports for New Controllers

There are several major imports that can handle the next types of transition forms:

Please consider adding them to your custom transition form controller.

Context Data

The following layout context variables are available for the transition forms:

  • workflowName - the name of a workflow

  • transitionName - the name of a transition

  • transitionFormView - the form view instance (used in rendering)

  • transition - the instance of Transition class that current transit corresponds to

  • workflowItem - the instance of WorkflowItem - current workflow record representation

  • formRouteName - the route that should be populated by LayoutTransitionContext processor in TransitionContext


A workflow transition form does not have layout form provider. So you cannot reuse it in other layouts. It is a known drawback, but the transition process is quite complex, and transition form reusage could make data dependency management quite complicated.