Documentation

Custom fields

Custom fields are data that will be added to the bridge payload on runtime. Use them to store private data you don’t want to place on your public forms, like user emails, or config values, like product IDs or lead tags.

Each bridge has its own custom fields. A custom field is a pair of key-value, with the name on the left side, and the value on the right. Click on the Custom fields button of a bridge to open the fields table.

If it is possible, Forms Bridge will introspect the bridge API schema each time the custom fields panel is opened. This introspection will return the list of the API endpoint fields. To access this list simply click on the {…} button and select an option to set its value as the field name. With this feature, Forms Bridge helps to map your submission fields to the API schema.

For the values, you can define constant values –simply type it on the value input of the field–, or make use of meta tags. Each meta tag will be replaced with its context value on runtime. Click on the $ button to see all available tags. You can add more than one tag to the field value, or combine tags with strings into a composed value.

Available meta tags

Workflows

With workflows you can combine multiple jobs to mutate your form submissions before them were sent over the wire to your backend.

The workflow input is the form submission and the output is the bridge payload. If you don’t set up a workflow, the form submissions without mutations will be used as bridge payloads.

A job is a function that runs on the backend and receives the payload as input and returns the payload with mutations as the output. In addition to data mutations, jobs can perform actions like databases writes or backend requests.

Each addon comes with a predefined set of jobs you can combine to set up your custom workflows. In addition, you can register your own workflow jobs. Take a look to our tutorial about how to register custom workflow jobs.

A workflow can have an arbitrary number of jobs. The submissions will go through the jobs in a sequential order, from the first job to the last one. The output of the last job will be the bridge’s payload.

To set up a bridge workflow go to your bridge and click on the Workflow button to open the workflow panel.

The panel is divided in two columns: On the left side you can add, remove or replace jobs from the line. On the right, the panel will show you the current job title, description, fields interface and a representation of the payload schema at this point of the workflow.

By default, a workflow line has one step called Form submission. This step is the start point of every workflow.

The last item of the workflow line is the Output payload step. Go to this step to inspect the schema of the output payload.

Between the form submission and the output payload step, you can add workflow jobs. To add a new job to the chain, the output of the previous step has to fit the next job interface. The job interface is a declaration of required fields and its data types. If the input payload does not fit this interface, the job will be skipped.

To the output of each job it is possible to apply mutation layers to transform the output structure to fit the next job interface, or the backend API interface if it is the latter.

Mutation layers

Mutation layers are part of the workflow module but it deserve its own chapter. A mutation layer is a mapping from one field to a new one with a value mutation pipe.

With mutation pipes you can transform the field value. There are three types of mutation pipes:

1. Type mutations: With type mutations you can transform your value type to one basic type to another, like string to integer conversions.
2. Implode mutations: With implode mutations you can combine multiple values from a data structure into one composed string.
3. Structure mutations: With structure mutations you can transform your submission structure by adding, removing or renaming its attributes.

Mutation layers works as a chain of mutations applied sequentially to the submission payload. This means that for each new mutation layer you add to the chain, its input is the result of the output of the previous layer. Take a look at our Deep dive into mutation layers tutorial to see this behavior in action with some examples.

You can apply mutation layers to every workflow job output. To set up mutation layers you have to open the workflow panel, go to the desired job step and click on the Show output mutations toggle button on the bottom right corner.

When you activate the output mutation layers mode, a table with mutations will be visible. Use this table to add as many mutation layers as you want to the payload.

Templates

Templates are blueprints of bridges you can use to set up your form integrations. To use a template go to the Add bridge tab of your addon and click on the Use a template button. After that, the template wizard will be displayed.

The first step is to choose an integration (if you have more than one) and a template to use. The integration is the plugin with which you want to create the new form and the template the blueprint of this form. In addition, the template wizard will ask you for required settings to setup the backend, if required, some kind of credentials, and the bridge.

Each addon has its own templates to solve common use cases of its API. Open the templates selector to see all options and choose one. After that, the wizard will guide you on the process.

The 3 (+1) steps of the template wizard are:

1. Backend: Setup a new backend connection or reuse an existing one. On this step Forms Bridge performs a ping request to check the connection health before it lets you go forward.
2. Form: Fulfill required fields to complete the form blueprint and convert it to a new form. The form will be created after the template submit.
3. Bridge: With the backend and the form ready, the wizard will ask you for the bridge. Each bridge’s wizard will ask you for different kind of information to set up the bridge.

To finish the process click on the submit button and a new bridge will be created! If you didn’t reuse a backend connection or a form, these ones will be already created. The new bridge will bind the form with the backend in a ready to use bridge.

With templates you can get ready to use bridges. You can achieve the same result doing it manually, but with templates you can save a lot of time! We strongly recommend you to check for templates before start creating new bridges, and use them as starter point if your use case its not completely covered by the template result.

Json fingers

A json finger is a hierarchical pointer to data structures like children[0].name.rendered.

Json fingers are used by Forms Bridge as field names to allow the user to manipulate complex data structures on the form submission payload processing.

The syntax is inspired on the JSON standard, hence the name. If JSON is unknown to you, start by reading about the JSON syntax and then, a good playground to learn the concept is the jsonpathfinder project, give it a whirl.

Json fingers are used on custom field names and on mutation layer target names. If your json finger is simple (without path hierarchy), it works as a simple field name, but a the same time, you can break the name into hierarchy levels to create nested objects or items on an array.

For example, if your backend waits for an payload like this:

{
  "name": "Bob",
  "address": {
    "street": "Carrer de Balmes, 250",
	"city": "Barcelona"
  }
}

Then you can use address.street and address.city fingers to point to this nested attributes.

Use them as custom field names to add nested attributes, or as mutation layer target names to transform your plain form submissions into nested data structures.

Take a look at our Deep dive into mutation layers tutorial if you want to realize the full potential of json fingers.

Getters

$form_data = apply_filters('forms_bridge_form', null);
if (!empty($form)) {
	# do something
}

$forms_data = apply_filters('forms_bridge_forms', []);
foreach ($forms_data as $form_data) {
  # do something
} 

$bridges = apply_filters('forms_bridge_bridges', [], 'wpcf7:31');
foreach ($bridges as $bridge) {
  # do something
}

$submission = apply_filters('forms_bridge_submission', null);
if ($submission) {
  # do something
}

$uploads = apply_filters('forms_bridge_uploads', null);
if ($uploads) {
  # do something
} 

$backends = apply_filters('forms_bridge_backends', []);
foreach ($backends as $backend) {
  # do something
} 

$backend = apply_filters('forms_bridge_backend', null);
if ($backend) {
  # do something
} 

Filters

add_filter('forms_bridge_payload', function ($payload, $bridge) {
  return $payload;
}, 10, 2);

add_filter('forms_bridge_attachments', function ($attachments, $bridge) {
  return $attachments;
}, 10, 2);

add_filter('forms_bridge_backend_headers', function ($headers, $backend) {
  return $headers;
}, 10, 2);

add_filter('forms_bridge_backend_url', function ($url, $backend) {
  return $url;
}, 10, 2);

add_filter('forms_bridge_request', function ($request) {
  return $request;
}, 10, 1);

add_filter('forms_bridge_response', function ($response) {
  return $response;
}, 10, 1);

add_filter('forms_bridge_prune_empties', '__return_false');

add_filter('forms_bridge_skip_submission', function ($skip, $bridge) {
  if ($bridge->name === 'skip') {
    return true;
  }

  return $skip;
}, 10, 2);

Actions

add_action('forms_bridge_before_submission', function ($bridge, $payload, $attachments) {
  # do something
}, 10, 3);

add_action('forms_bridge_after_submission', function ($bridge, $response, $payload, $attachments) {
  # do something
}, 10, 4);

add_action('forms_bridge_on_failure', function ($bridge, $error, $payload, $attachments) {
  # do something
}, 10, 4);