Basic Concept of the Form Processor Extension

The Form Processor extension allows you to specify the data that will be processed with a form on your public website. In CiviCRM you specify what data you want to display on the form, if and what default values you want to load and what should happen with the data that is submitted with the form.

For example: I want a form that allows me to enter my name and email address so I can sign up for the newsletter. You can specify all that in the Form Processor and also specify that a new contact should be created if one can not be found with the email address, and that the contact found or created should be added to the newsletter group in CiviCRM.

In this chapter we will briefly discuss the forms and screens you need to go through if you are specifying a form with the Form Processor.

We will start with a fairly basic Form Processor and in further sections explain how you can get a form prefilled with data, how you can validate data before it is processed in CiviCRM and how you can prepopulate input fields with calculated values (like the number of participants * the price, the age of the contact or stuff like that).

Techie stuff

On a technical level: the extension actually generates an API action for the FormProcessor API entity.

Form Processors Page

Once you installed the Form Processor extension you will have an additional option in the Administer>Automation>Form processors option which will lead you to the first view of all the form processors in your installation. This will be empty if you just installed the extension.

The actions you can perform with each form processor will be in the little menu after each entry.

Import button

With the import button you can import a form processor from a JSON file. For each form processor you have an action Export which exports the definition to a JSON file. This allows you to easily move defined Form Processors from for example a test to a live environment.

New Form Processor - define form processor

On this page you can click on the Add Form Processor button to create a new form processor. If you do this you will see a form like the one below:

On this form you specify generic information about your form. You can enter the general form processor information:

• have to specify a title for the form processor
• a name will be suggested based on the title but can be changed if you click on the lock behind the field first!

Note

A name can not contain any spaces! And should be unique!

• you can specify a detailed description (and it makes sense to do so if you expect to build a few forms!)
• you can tick if the form processor should be enabled (on by default)
• you can select what permissions are required to be able to process the form. For example you could decide you can only send your address details if you have the CiviCRM:edit my contact permission.

It will look something like this:

When you are happy you hit Save to create your form processor and move to the next bit of configuration.

Input fields on your form processor

Once saved your form will look like the one below. You can still change title, name, description and the other generic information if you want to (make sure to hit the Save button then before you do anything else) but you can also do much more.

In the next part under the heading Inputs you can specify the input fields that should be on your form.

For each field you can select the type of field (short text, numeric no decimal, date, yes/no, option group etc.), specify a title for the input field, check if the input is required for the form processor, check if you want a formatted value (for example when you want to use the input in an email in a HTML-formatted fashion), a default value and potentially change the generated system name. Let's for example take the first name, last name and email.

Adding the input field for the email will probably have to look like this:

Once I have added all the fields the list will look something like this:

What I have done now is specify that I expect my form to show 4 fields for the website visitor to enter: First Name, Last Name and Email and Newsletter. I have entered them in a different sequence but I used the arrows behind the inputs in the list to put them in the sequence I want.

Actions on your form processor

In the bottom part of the form (under the heading Actions) you can specify what needs to happen once CiviCRM receives the data from the form. We do that by adding actions to the form processor.

So in our example, we should find a contact by the email. Next the contact found should be added to the newsletter group if they specified they want to. Initially the part of the form where we can specify actions will look like this:

If you click on the Add action button you will get a form where you can enter the details of the action In this example we have a first step: find the contact with the data from the form or create a new one.

If you click on the select box for the Type you will get a list of all the actions that have been developed so far.

They are there because organizations funded the development of actions they needed. As time goes by and more people start using and enhancing the Action Provider extension, the list will grow but there are quite a few useful ones already.

In this example we select the action Contact:Get or Create By Email and Names.

You can also add a Title for the action. A system name will be generated based on that title (which you can change if you want to). Depending on the action you will be able to configure values that will be used for the action under the Configuration tab or enter the inputs or action results under the Parameter mapping tab. In this example you can see that I use the inputs First Name, Last Name and Email.

Create your own

It is possible to develop your own specific actions, or indeed generic ones that others can use too! Check the relevant sections in Example of Email Preferences

Once I have found the contact it should be added to the newsletter group. If I select the add to group action I can select the group and specify that I want to use the contact ID found in the previous action:

Obviously I only want to add the contact to the newsletter group if they have said they want to. To achieve that I want to add a condition:

When I click the Add condition link I get to enter the configuration for my condition. As you can see here I want to use the type Parameter has value, the value should be TRUE and the input in question is the Newsletter. Meaning this action is ONLY executed if the Newsletter input has the value TRUE.

Obviously there are more types of conditions, have a play with them to find out which one suits your needs the best.

Try out - testing the Form Processor in CiviCRM

In the action menu behind each Form Processor as well as in the tab you have the Try out option:

With this option you can try your form processor to check if the actions are performed correctly in CiviCRM with everything you have configured. It should really be part of your testing process, making sure the form processor does what you expect in CiviCRM before you test it with a form on your website (or any other data coming in from outside).

Export and import - moving form processors around

Once you have created a nice working form processor on your test environment you do not want to re-develop it in your live environment. And the other way around too, if there is a problem with a live form processor you would want to take it to your test environment and make sure it is exactly that same.

This is where the export and import comes in.

In the list of form processors you will have an export action link in the menu behind each form processor:

This will export the definition of your form processor to a JSON file which you can then save on your computer or on the network.

You also have the Import option in your form processor page which allows you to import a JSON file into a form processor.

New Form Processor - retrieval of defaults

With the Form Processor extension it is possible to pre-populate your form with default data, for example for a My Address Data form. We could pass a parameter (a checksum for example) in the URL of the form and based on that retrieve the current values from CiviCRM and prepopulate the form with this data.

First step is to click on the Retrieval of defaults tab and then check the box in there to enable the defaults.

Once I have done that I will get a form to configure my retrieval of defaults.

As you can see the input fields from my form processor have already been loaded. I can specify here what criteria I want to use, fore example a text input for a checksum.

At the retrieval methods part I can select how I want to retrieve my data. Here I would like an action called Find contact with checksum. Unfortunately that is not available yet because it has not been developed yet, but you get the gist. And it will be developed in the section Email Preferences.

For each of my input fields I can finally specify what data should be loaded here, which should come from the result of my action.

Techie stuff

On a technical level: If you have enabled default data retrieval it actually generates an API action for the FormProcessorDefaults API entity.

New Form Processor - Using the Validator

With the Form Processor extension it is possible to validate data on the website form before it is actually processed in CiviCRM. For example you could validate if a contact exists, an event is still open for registration or a certain activity type exists before you process the contact, event registration or activity in CiviCRM.

The error message you specify with the validator will appear on your Webform in Drupal before the data is actually sent to CiviCRM.

Only with Drupal 8 and later

Please note that the validator option currently only works with Drupal 8, 9 and 10. In theory it could also work with other CMS's but it would require a specific customization for that CMS to process the validation data from the Form Processor. So it could work for example for Caldera Forms in Wordpress if Caldera Forms is updated to proces the Form Processor validation.

The validation can be added by clicking on the Validation tab in the Form Processor screen. Once I do that I will get a form looking like this:

On this tab you can add actions like you can for the inputs part of the Form Processor and use the results of these actions in the validation under the heading Actions.

Under the heading Validators you can add the actual validations you like. In my example I am going to create a validator that checks if a parameter is not empty.

First I will click on the Add Validator button:

First I select the type of validator, in this case Parameter is empty. Next is the title, from which a system name is generated (which you can change if you want to).

At Show messages for inputs I can select which of the inputs is the one that sort of caused the error, which should be flagged by the CMS as the field in error. As in this case I want make sure that the Campaign ID is not empty I select the input Campaign ID.

Under the Configuration tab I can specify the error message I want to use for my validation if it fails.

Under the tab Parameter Mapping I can select the parameter I want to validate.

Little side note

Obviously I could also have achieved this by making the parameter required but it suffices as an example.

The list of possible validators is still relatively empty, we expect this to grow as more and more people in the community start using this and adding validators, for example if a campaign actually exists or if an event is still active etc.

New Form Processor - Using the Calculator

With the Form Processor extension you can prepopulate fields with calculated data, and whenever something on your form is changed it will check if the calculated value needs to be changed.

For example you could have a form where you can register for an event and there will be a calculated field for the total amount which will initally show a value of 0. If you change the number of people you want to register the total amount will change (the number of participant * the registration fee).

Unfortunately at this point in time you can not use the Try out option for calculated data yet.

Only with Drupal 8 and later

Please note that the calculator option currently only works with Drupal 8, 9 and 10. In theory it could also work with other CMS's but it would require a specific customization for that CMS to process the calculated data from the Form Processor. So it could work for example for Caldera Forms in Wordpress if Caldera Forms is updated to proces the Form Processor calculations.

That's it!

So far the basic concept. Obviously the public website part needs to be done too, check the Example Sign Up Newsletter section for that part, this section just covers the basis principles.