How to register custom workflow jobs

Forms Bridge has a variety of workflow jobs out of the box. At the same time, its possible to register custom workflow jobs from your theme or plugin using PHP.

A workflow job is nothing more than a function that gets a submission payload and a bridge instance as input parameters and returns the payload as its output.

The idea behind the workflow jobs is to perform mutations on the payload or to dispatch some requests to the backend before the submission is sent.

An example

To illustrate the concept we can use the example of an existing workflow job. Lets see what Next code client job from the Dolibarr addon does:

function forms_bridge_dolibarr_get_next_code_client($payload, $bridge)
{
    $response = $bridge
        ->patch([
            'name' => 'dolibarr-get-next-code-client',
            'endpoint' => '/api/index.php/thirdparties',
            'method' => 'GET',
        ])
        ->submit([
            'sortfield' => 't.rowid',
            'sortorder' => 'DESC',
            'limit' => 1,
        ]);

    if (is_wp_error($response)) {
        return $response;
    }

    $previous_code_client = $response['data'][0]['code_client'];

    [$prefix, $number] = explode('-', $previous_code_client);

    $next = strval($number + 1);
    while (strlen($next) < strlen($number)) {
        $next = '0' . $next;
    }

    $payload['code_client'] = $prefix . '-' . $next;
    return $payload;
}

The job patches the bridge instance to overwrite its HTTP method and endpoint and then triggers a GET requests to get the last registered thirdparty registry from Dolibarr. From the response reads the code_client field, increase the sequence value by 1 and the sets the result as the code_client of the payload. To conclude, returns the mutated payload.

Register a new job

To register a new job you have two options:

Theme folders

Forms Bridge will scan the directory of the current theme of the WordPress site and search for folders using the pattern forms-bridge/jobs/${addon} replacing the addon parameter by each of the addons enabled.

If some directories are found, Forms Bridge will try to include all PHP and JSON files inside the directories.

For each included files, Forms Bridge waits an array as the return value of the inclusion. This array should contain the Job configuration.

After a validation, this configuration will be registered as a new job.

This is how a workflow job script should looks like:

function prefix_my_custom_job_method($payload, $bridge)
{
    return $payload;
}

return [
    'title' => 'Custom Job',
    'description' => 'Workflow job description',
    'method' => 'prefix_my_custom_job_method',
    'input' => [],
    'output' => [],
];

This data will be validated using schema validation methods. To learn more about the workflow schema and schema validation take a look to the Workflow Job Schema entry of the blog.

Loading hooks

The other available option to register custom workflow jobs is tu use the forms_bridge_load_jobs hook. The filter callback will receive an array with job settings and the slug of the target addon. It’s important to return the list of jobs at the end of the callback to don’t break the filters chain.

function prefix_my_custom_job_method($payload, $bridge)
{
    return $payload;
}

add_filter('forms_bridge_load_jobs', function ($jobs, $addon) {
    if ($addon === 'brevo') {
        $jobs[] = [
             'name' => 'my-custom-job',
             'title' => 'Custom Job',
             'description' => 'Workflow job description',
             'method' => 'prefix_my_custom_job_method',
             'input' => [],
             'output' => [],
        ];
    }

    return $jobs;
}, 10, 2);

Place this snippet on the functions.php of your theme and replace the values with your own values.

Registration settings

As you can see in the examples above, to register a job you have to add to the jobs registry a new array containing certain information. This array has the following schema:

1. name: Internal name of the job, should be unique to avoid collisions with other jobs (it’s the file name without its extension if you are registering the job using the directories method).
2. title: A title to be displayed on the job selector of the UI.
3. description: A description of the job to be displayed on the UI.
4. method: The name of the job method as string.
5. input: An array with job input fields interface definition.
6. output: An array with job output fields interface definition.

Using the workflow job

If the registration goes well, you can go to the workflow panel of one of your bridges and click on the + button to add a new job to the workflow. On the job selector you will find your custom job as an available option. Select and click on save at the end. That’s it!