In the tutorial we will explain in detail mutation layers and json fingers. The tutorial includes tips and tricks for its use and advanced use examples.
Forms Bridge use workflows to process form submission data before it is sent over the wire. A workflow is a chain of jobs that receive a form submission payload as an input and returns the same payload with mutations as the output. Form data flows through the workflow jobs of a bridge and is mutated on each step. The output of the entire workflow is the bridge payload to be sent to the backend.
For each job of the workflow, you can set up a set of mutation layers that will receive the job output payload and will mutate it before it is sent to the next link on the chain.
A mutation layer is a mapping from one field to a new one with a value mutation pipe.
Field mapping
Field mapping is the simple action to rename a field. A basic example is the renaming of the field Your name to name. With field mapping you can rename your form field names to fit the schema of your backend endpoints.
In addition to this plain mapping, you can use json fingers to apply structure mutations to the payload. For example, you can rename firstname to contact.firstname and lastname to contact.lastname as field mappings to create a nested object with two keys as the value of the contact field of the payload.
Mutation pipes
With mutation pipes you can transform the field values of the payload. There are three types of mutation pipes:
- Type mutations: With type mutations you can transform your value type from one basic type to another, like string to integer conversions.
- Implode mutations: With implode mutations you can combine multiple values from a data structure into a new composed value.
- Structure mutations: With structure mutations you can transform your submission structure by adding, removing or renaming its attributes.
| Mutation | Description |
|---|---|
| TYPE | |
| String | Converts to value type String |
| Integer | Converts to value type Integer |
| Decimal | Converts to value type Float |
| Boolean | Converts to value type Boolean |
| IMPLODE | |
| JSON | Encode array value as JSON strings |
| CSV | Concat array values into a string spaced by commas |
| Spaced | Concat array values into a string with spaces |
| Join | Concat array values into a string without spaces |
| Sum | Sum the numeric values of an array |
| Count | Get the number of items in an array |
| STRUCTURE | |
| Rename | Rename a field and inherits its value type |
| Copy | Create a copy of the value under a new field |
| Ignore | Remove the field from the payload |
Mutation layers
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.
Examples
Now we will explain some examples to illustrate the potential of mutation layers.
1. Contact’s full name
Suppose you have a contact form on your website. The form has First name, Last name and Email fields. Suppose you want to store any entry on this form as a contact on your ERP, but the contact interface of the ERP has only the fields name and email.
To solve this mapping problem you will need a table of mutation layers like this:
| First Name | name[0] | String |
| Last Name | name[1] | String |
| name | name | Spaced |
| String |
On the first two lines of the table we are mapping the First Name and the Last Name fields of the payload to the field name with a list with two string as its value.
On the third line we use an implode mutation to concatenate the two values into a single string with first name and last name separated by a space.
The fourth line is a plain field mapping where we replace the Email by its lowercased counterpart.
2. Subscription attributes
An other hypothetical case where you have a subscription form to a mailing list. In addition to the Email, the form has First Name, Last Name and Preferred Language fields, and a Privacy Policy checkbox. With the except of the email field, the rest of the fields should be passed to the platform API as an object. In addition, the Privacy Policy value should be ignored by the bridge.
To solve this mapping problem you will need a table of mutation layers like this:
| String | ||
| First Name | attributes.FNAME | String |
| Last Name | attributes.LNAME | String |
| Preferred Language | attributes.LANG | String |
| Privacy Policy | Privacy Policy | Ignore |
3. Plain text metadata
Suppose you have a lead form where you ask users for certain technical details about the service they are looking for, but the lead layout of your CRM does not support custom fields. To solve the problem, you decide to store this values as plain text on the notes field of the lead object.
To solve this mapping problem you will need a table of mutation layers like this:
| CUPS Number | meta[“CUPS Number”] | String |
| KW/h | meta[“KW/h”] | String |
| Number of stations | meta[“Number of stations”] | String |
| Last revision | meta[“Last revision”] | String |
| meta | notes | JSON |
From the first to the forth line we are structuring the meta field as an object with four attributes. On the last line, we encode this object as a JSON string and rename it to notes.
4. List of attendees
Imagine you have a sign up form that allows people to register up to three persons to a meeting. At the same time, imagine your CRM API requires this attendees data to be an array of objects with email and name attributes.
To solve this mapping problem you will need a table of mutation layers like this:
| Person 1 | attendees[0].name | String |
| Email 1 | attendees[0].email | String |
| Person 2 | attendees[1].name | String |
| Email 2 | attendees[1].email | String |
| Person 3 | attendees[2].name | String |
| Email 3 | attendees[2].email | String |
5. Order lines
To conclude, lets see an example of array expansions. Suppose we have a site with a WooCommerce store and we want to get our orders into an ERP. On each completed order, Forms Bridge gets the order data and let us to manipulate it with mutation layers before it is sent to the ERP. This is our mutation layers table:
| billing.first_name | name[0] | String |
| billing.last_name | name[1] | String |
| name | name | Spaced |
| billing.email | String | |
| billing.address_1 | billAddress.address | String |
| billing.city | billAddress.city | String |
| billing.postcode | billAddress.postalCode | String |
| line_items[].name | items[].name[] | String |
| line_items[].subtotal | items[].subtotal[] | Decimal |
| line_items[].quantity | items[].units[] | Integer |
| line_items[].product.sku | items[].sku[] | String |
| line_items | line_items | Ignore |
Lets see what’s going on on this mutation layers stack:
- The first three lines are familiar to us because it’s the same schema that we were covering on the first example.
- From the fourth to the seventh line we are mapping the attributes from the
billingobject of the order to a newbillAddressobject and casting them as Strings. - From here on, the mutation layers are dealing with array expansions. Array expansions are used when a json pointer has an array subscription without an index. This kind of expansions can be used on both sides of the mutation, as the getter pointer to get an array of values as the input of the mutation pipe, or as the setter pointer, to store the result of the mutation as an array of values. If the mutation pipe you want to use is a type cast pipe, you have to suffix the setter pointer with the
[]to apply the cast to each items on the array, otherwise, Forms Bridge will try to cast the arrays object as a simple value type. - On the last line, and after our expansion mappings, we remove the rest of the
line_itemsdata from the payload, as we have enough to fulfill our endpoint interface.