Form finisher

Target group: Integrators, Developers

Configuring JobRouter®

Before you can start instances successfully you have to configure your JobRouter® installation to execute steps automatically. The command for starting instances only saves the step. To send the step you need a JobRobot configuration and add the robot user to the Job Function of the start step.

  1. Configure JobRobot module

    If you haven’t an activated JobRobot configuration create a new user in your JobRouter® installation and configure it under System > Configuration > Modules > JobRobot. You see the following screen:

    JobRobot configuration

    JobRobot configuration

    After activating and saving the form the JobRobot user is available.

  2. Add JobRobot user to Job Function of start step

    Then add the robot user to the Job Function of the start step. It can then look like this:

    Robot user in Job Function of start step

    Robot user in Job Function of start step

Start instances

A form finisher JobRouterStartInstance is available to start a JobRouter® process instance. After submitting a form, the form values are stored in a transfer table. A command, hopefully executed regularly, takes these transfer records and start a process instance. This is due the fact, that a JobRouter® installation can temporarily not available due to maintenance or network problems. Also the submitting of a form on the website should be as fast as possible for a good user experience.

Note

The finisher can only be used in the yaml form definition, not in the Form backend module.

Start one instance

So, let’s start with an example. The form finisher is defined in the YAML configuration of the specific form:

 1finishers:
 2   -
 3      identifier: JobRouterStartInstance
 4      options:
 5         handle: 'start_website_contact'
 6         type: 'Demo'
 7         summary: 'Demo Contact'
 8         processtable:
 9            name: '{preName} {lastName}'
10            company: '{company}'
11            email_address: '{email}'
12            phone_number: '{phone}'
13            message: '{message}'
14            form_identifier: 'www.example.com/demo'

As you can see, you can define some options. These are:

  • handle (required): The step handle defined in the Processes module.

  • type: The type can be used for statistical evaluation in the according dashboard widget.

  • summary: The summary of the instance.

  • initiator: The initiator of the instance.

  • username: The username the instance should be assigned to.

  • jobfunction: The Job Function the instance should be assigned to.

  • priority: The priority of the instance (number between 1 and 3).

  • pool: The pool of the instance (positive number).

  • processtable: You can map the form fields to the process table fields. As you can see in the example above, you define the process table field as the key (e.g email_address) and then map it with the to the form field identifier which is enclosed in curly brackets (e.g. {email}). You can also set a static value, combine a static value with a form field or map multiple form fields to a process table field.

Note

Only process table fields that are configured in the process link are possible. If a process table field is used that is not defined, an exception is thrown.

Inputs that are longer than the defined process table field length are shortened to the maximum length.

If the value of a form field is an array, like from a multi checkbox, the array is converted to a csv string and stored in the given process table field. The value can be reconverted to an array, e.g. in a JobRouter® rule, with the PHP function str_getcsv().

Start multiple instances

It is also possible to start multiple instances – even on different JobRouter® installations. Just use the array notation in options:

 1finishers:
 2   -
 3      identifier: JobRouterStartInstance
 4      options:
 5         -
 6            handle: 'start_website_contact'
 7            summary: 'Demo Contact'
 8            processtable:
 9               name: '{preName} {lastName}'
10               company: '{company}'
11               email_address: '{email}'
12               phone_number: '{phone}'
13               message: '{message}'
14               form_identifier: 'www.example.com/demo'
15         -
16            handle: 'collect_anonymous_messages'
17            summary: 'Demo Contact'
18            processtable:
19               ANON_MESSAGE: '{message}'
20               FROM_URL: 'https://www.example.com/demo'

Variables

You can use variables in the common parameters, such as summary or initiator, and in the process table fields.

For more information have a look into the available variable resolvers. You can also write your own variable resolvers.