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 to use the forms_bridge_load_workflow_jobs filter. The filter callback will receive an array with job settings and the API slug of the current 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_workflow_jobs', function ($jobs, $api) {
    if ($api === 'rest-api') {
        $jobs[] = [
             'name' => 'my-custom-job',
             'data' => [
                 '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 example 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.
2. data: Job settings data.
   • title: A title to be displayed on the job selector of the UI.
   • description: A description of the job to be displayed on the UI.
   • method: The name of the job method as string.
   • input: An array with job input fields interface definition.
   • output: An array with job output fields interface definition.
   • submission_callbacks: Optional, an array with before and after action methods to be triggered on the hooks forms_bridge_before_submission and forms_bridge_after_submission.

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.

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!