Configuration

Lime Admin

Configuration for each action in the form is configured in Lime Admin. This configuration will differ depending on the use case.

Example of transferring a submission

Before starting off, let's have a look at some "best practice" pointers that should be followed. The table below describes what Lime CRM field expects which format, and the appropriate Lime Forms field type to use for that specific type of property. All values are parsed to their correct format, that's why in the table you will see that both String and Number works for some of the fields.

Lime Field	Type	Format	Forms field that works
yesno	String, Number	1, '1', true, 'true' 0, '0', false, 'false'	Radio, Hidden, Text, Number
date (time, month...)	String.	YYYY-MM-DD, YYYY-MM-DD HH:mm:ss	Date, Hidden, Text
string	String, Number		Date, Hidden, Text, Number
integer	String, Number		Hidden, Text, Number
option	String.	The option key	Radio Button, Select, Hidden
decimal	String, Number		Text, Hidden, Number
percent	String, Number	Number between 0-100	Text, Hidden, Number
xml	String		Text, Hidden
link	String		Text, Hidden
set	Array, List	A list of the option keys, e.g. ['key1', 'key2']	Checkbox

Let's get to the example, in Lime Forms there might be a form that collects some type of information. To better keep track of it, and to represent it better, it can be transferred to Lime CRM.

As a first step, identify what information the form collects. This will give an idea of what should be created in Lime CRM. As an example, let's say we have a "Contact Me" form that customers use to show their interest in a product. In this case it makes sense to create the following objects in CRM:

• Deal. Store general information about the submission here
• Person. To get back to the customer, store their information here.

Lime Admin

Now that it has been identified what should be created, a configuration is needed to transfer the information. Go to Lime Admin and look for Forms2CRM under the settings. Add a config and give it a name, so it can easily be identified later. This name will be visible in Lime Forms, where the config is selected.

Add a command by press the + Commands section. Give it a name, a good practice is to name it depending on the command, e.g. "create deal". In the field below there will be an option to select the command type.

Create deal

Following the example, we will select create-or-update-limeobject as the command type. As stated previously, a deal should be created so that limetype is selected. A new deal should be created, so the Target or find existing limeobject option is skipped.

Property mapping

Next step is to add the mapping between fields in Lime Forms, and the properties that exist on the limetype. Add a property mapping for each property on the limetype, that should be filled with data. Required properties are denoted with an asterisk(*). There are four options available. relation only in the table below, means that the property being set needs to be a BelongsTo relation field.

type	relation only	description
constant	no	A constant value that is used all the time
form_field	no	Get the value from a forms field, by providing the name
lookup	yes	Search for an existing object and link it, by querying a specific property on the existing object. E.g. company.name. The search value is always defined as coming from a forms field
reference	yes	Link an object that was previously created in the same configuration. Note: this is sensitive to order of commands. Only objects that are already created can be linked

Important note for lookup

By default lookup needs to find exactly one match, or the command will fail. If you're not sure the object exists, check the "Require single match" option. In this case the field will be excluded, if not found.

For deal in this solution, there are four required properties which can all be predefined, i.e. no form field value is needed. Constant is selected as type, so that any value can be put.

Create person

To create person, another command is added to the configuration. In this case, a person could exist since before. If so, the person should be updated and not created again. For this the Target or find existing limeobject option is checked. This shows another two fields, the first one being the property to search on the limetype. The second one is the form field name, which holds the value to search for. For person, it makes sense to search for email since that is unique.

If the person is not found based on the search, a new object is then created.

There is a chance that the person does not exist, so for that reason adding the required properties in the mapping is mandatory. If not, whenever a person is not found an error will occur.

Lastly, the person should be related to the deal. Since the relation between the two is "One deal belongs to a person", the mapping is defined on the deal object. Since deal was created first, the order of the commands needs to be swapped so that it can be linked by command reference. In this case the command that creates the person, needs to be executed first. Add the mapping on the deal and select reference as the command type. This allows a reference from a previous command to be selected.

Documents

The form allows the user to upload a file containg a blueprint for what they are interested in ordering. This needs to be added to the deal as well. Let's add a new command with the type attach-documents. In the form we have a field called files, which results in the following config for the command:

A type for the document is selected, and attached to a limeobject created by a previous command (the deal). There are no required properties, so that section will be left empty.

Linking existing objects

In the form your are able to select which department you will get in contact with. This is a radiobutton field, where the values behind it are emails to the responsible at each department. To link it, select coworker on the deal and choose lookup. This allows to set the relation based on a property on the coworker. In this case it's email, so the config looks like this:

Lime Forms

Now that the configuration is ready, head over to Lime Forms to configure it. Open the form editor and go to the "Actions" tab. If everything was configured correctly (make sure the feature flag was added, see here), there should be an option called "Form submission to Lime CRM".

For this action, it requires the URL for the CRM application to be added, ending with the database name. Secondly an API-key is needed.

Important about API-key

Best practice is always to use an API-key that has the minimum permissions to execute the specific configuration. E.g. if there is no creation of company, that permission should not exist.

Once the API-key and URL has been set, configs are fetched from Lime Admin by pressing "Fetch configs". Select the configuration that was created earlier. The configuration shows up as a preview below. Closing the modal, will cause the API-key to be partially masked.

Postback

Once the form has been submitted and the command has finished, there is a possibility to configure a postback endpoint. Output from the commands will be posted to this particular endpoint. This is useful in case you want to react to something being created, e.g. send an email to the admin of the form that is has been submitted.

For the settings, there are a total of three fields, the first one being URL to the endpoint. The second one is the authentication method that should be used, this has three options:

• Bearer token, more info here
• X-API-Key header, more info here
• No authentication. This option means the endpoint should be public.

If Bearer token or X-API-Key header was chosen, a key/token is also required. See example in the image below.

Wrapping up

All set! Submitting the form will now result in the appropriate objects being created/updated in Lime CRM, based on the configuration. For a live preview, the configs used are available for copy & paste:

• forms_config.json

• lime_admin_config.json

Target limeobject

For create-or-update-limeobject, there is an option to use "Target existing limeobject". Per default, this will try to find an existing limeobject by searching a specific property. If found it will update, else it will create it. The sections below will explain the settings available

Tip

If you already know the ID of the object that you want to update, choose "Record ID" as "Limeobject property to search". A good use case for this is when the form contains some type of search, where the user chooses the object, therefore the ID is known. In this case, the checkboxes are disabled since it implies that the object exists without doubt.

Update only

There is an option to perform updates only, i.e. it will never create it. To configure this check the "Update only" checkbox. The prerequisite for an object to be updated, is that there is only one exact match. This means all of the data mapped to the properties, and any potential refs will not be stored in Lime, if not one exact match is found. If multiple matches are found, the command will throw an error. For some use cases this is wanted, but it can be prevented by configuration explained in the section below.

Excluding if multiple matches

As the option indicates, using this setting will exclude the object completely from being created/updated, if multiple matches are found. This also means any data mapped will be lost, and potential references to this object will be excluded.

The table below shows some uses cases depending on the settings made.

matches	update only	exclude if multiple matches	result
2	yes	no	error
0	yes	yes	excludes
0	no	yes	creates
1	no	yes	updates
1	yes	no	updates
2	yes	yes	excludes

Creating multiple limeobjects of the same type

To create several objects of the same type, you will most likely use the Multi entry field in Lime Forms. This field allows you to add multiple items, that have the same structure. To make use of this function, you should use the command type create-or-update-multiple-limeobjects. This command is very similar to create-or-update-limeobject. The only difference is that for the whole command, you have to specify the name of the Multi entry field.

Then just like for create-or-update-limeobjects, add property mapping for each of the form fields to match a property on the limetype. It also has support for using Target limeobject

In the image above, we can see that the structure matches in Lime Forms and the command, so it's ready to be used!

Using as reference

This command can not be referenced to, like explained in property mapping. It does however work to reference another command, in this case the relation will be set for all of the objects created.