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 cases.
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 to 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 one composed string.
- 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 value as JSON string |
| 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 |
| STRUCTURE | |
| Rename | Rename a field and inherits the value type |
| Copy | Copy the value to a new field |
| Ignore | Remove the field |
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 three 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 have this fields. To solve the problem, you decide to store this values as plain text on the notes field of the lead.
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 |