In this blog post I want to show how you could use the new form processor extension to handle form submissions from an external website.
My (imaginary) organisation provides buddies for young people and the form on our website is submitted when somebody is interested in becoming a buddy for a teenager. We ask for the name, address, e-mail, telephone number, birth date and gender.
After the person has submitted the form one of our employees should make an intake phone call with the person and this should happen within a month.
When the form is submitted we want to have the following situation in CiviCRM:
- A new individual with subtype Buddy is created
- The new individual is added to the group 'Interested in becoming a buddy'
- An activity of type 'Intake' is added and scheduled a month ahead
In this blog post I am going to show how you could create this form on a Drupal 7 website and on a Wordpress website. But first lets create the form processor in CiviCRM. The form processor in CiviCRM does the backend handling of the incoming data.
Configuring CiviCRM and the form processor
Install the required extensions
Install the following extensions:
- action provider: https://lab.civicrm.org/extensions/action-provider
- form processor: https://lab.civicrm.org/extensions/form-processor
Make sure we have the right CiviCRM configuration:
- Add a contact type for Buddy
- Add an activity type Intake phone call
- Add a group with the name Interested in becoming a buddy
Configure the form processor to handle the form submission
Go to Administer --> Automation --> Form Processor --> Add New. Give the form processor a name and a description, and a permission, for now 'access CiviCRM' permission will do. If you are on CiviCRM 5.4.0 or newer: 'access CiviCRM backend and API' permission will do. (I will explain later the permission).
See screenshot below for the first steps.
After this create the inputs. The inputs are the fields on the form which need to be handled by the form processor.
So start by adding inputs of type short text with the following names first_name, last_name, street_address, postal_code, city and telephone_number. Mark first_name, last_name and city as required.
Next add the e-mail field of type short text and name email and add a validation on valid email address. The validation rule will validate the input whether it is a valid e-mail address and when invalid will stop any further processing.
Next add the birth date field of type Date and name birth_date, add the format Y-m-d (this means the input format of the date is yyyy-mm-dd e.g. 1983-05-19, this is the format Contact Form 7 in wordpress uses for date fields).
Next add the gender field of type OptionGroup and name gender, select the gender option group to use and set Use Label as Value to Yes. This makes it easier to submit an option list from Contact Form 7 in wordpress. If you set this to no then the value is used and validated meaning that 1 is female, 2 is male.
After configuring the inputs, create the actions. Start with an action to create the inidvidual. Give the action the name Create Buddy.
Select the contact sub type buddy, and select the right location types for the address, telephone and e-mail address. And select No for update existing address, telephone and e-mail address.
Map the inputs to the fields for creating a contact:
- Contact ID: leave empty. If you map this to an input field an existing contact will be updated.
- First name: input.first_name
- Last name: input.last_name
- Birth date: input.birth_date
- Gender: input.gender
- Street address: input.street_address
- Postal code: input.postal_code
- City: input.city
- Phonenumber: input.telephone_number
- E-mail: input.email
Leave all other mappings empty. With the mapping you send the data from the input fields to the action.
Next step is to add the contact to the group. Add the Add to group action, and select the group 'Interested in becoming a buddy' and give the following mapping:
- Contact ID: Action::Create Buddy::Contact ID
This will map the output of the Create Buddy action to the contact ID field for the action Add to group. The Create, Update Individual action outputs the IDs of the cretaed contact, created address, created phonenumber and created e-mail.
Next create the Intake Phone Call activity, but before we can do that we need an action to determine what the deadline is for the Intake Phone Call.
We have said that the deadline is within a month after signing up. So add an action of type Set Date Value and give it the name 'Intake phone call deadline', and set the date to '+1 month'.
Then create the action for the Intake Phone Call activity. So add an action of Create activity. Set the activity type to 'Intake phone call', status to 'Scheduled' and subject to 'Buddy signup'.
Add the following mapping:
- Source contact ID: Action::Create Buddy::Contact ID
- Target contact ID: Action::Create Buddy::Contact ID
- Activity Date Time: Action::Intake deadline::Date
This will create an activity with the date set to the deadline date, and source and target contacts are set to the newly created contact.
Test the form processor with the api explorer
Optional you could test your form processor with the API exploer. Be careful it manilpulates the data in your system.
See below for an example.
Configure an api user
Add a new user who has the same permission as the formprocessor, Which is access CiviCRM, or access CiviCRM backend and API when your civicrm is 5.4.0 or newer.
Set the API key for this user. If you don' know how to do this follow this answer from StackExchange.
Take a note of the api key and your site key (you can find your site key in the civicrm.settings.php file, which could be found at sites/default/civicrm.settings.php when you are on Drupal).
Next steps is to created the forms on the external website. First I will explain how to do this on an external Wordpress website, after that I will explain how to do this on an external Drupal 7 website.
the External Wordpress website
On your external Wordpress website install the following plugins:
- Contact Form 7
- Contact Form 7 CiviCRM integration
Configure Contact Form 7 CiviCRM integration.
Go to settings --> CiviCRM settings and enther the following settings:
- CiviCRM Host - the url to your civicrm installation
- CiviCRM path - the path to the file civicrm/extern/rest.php, you can find this path in the api explorer. If you installed CiviCRM in Drupal this path is correct by default.
- CiviCRM Site Key - the site key you have noted earlier
- CiviCRM API key - the api key you have noted earlier
Next create the form in Wordpress go to Contact --> Add new
Give your form the name Buddy signup
And enter the following content:
<label> First Name (required)
[text* first_name] </label>
<label> Last Name (required)
[text* last_name] </label>
<label> Your Email (required)
[email* email] </label>
<label> You phone number
[text telephone_number] </label>
<label> Address
[text street_address] </label>
<label> Postal code
[text postal_code] </label>
<label> City
[text* city] </label>
<label> Birth date
[date* birth_date] </label>
<label> Gender
[select* gender "Male" "Female"] </label>
[submit "Send"]
Above code snippet is in the markup for Contact Form 7. I wont explain it here but documentation could be found at https://contactform7.com/editing-form-template/
Next open the tab CiviCRM and enable CiviCRM processing. At the entity field enter: FormProcessor, At the action field enter buddy_signup (this is the name of your form processor). Levae additional parameters empty.
The last thing we have to do is to insert the Short Code of the Contact Form in a wordpress page. You find this short code at the top of the screen.
Create a new page and paste the short code for the contact form in this page. That is it. Now you can use your form.
See below for an example:
The external drupal 7 website
In the example below we configure an external drupal 7 website to submit a webform to CiviCRM.
In Drupal 7 You need the CiviMRF module (which stands for CiviMcRestFace inspired by BoatyMcBoatFace), CiviMRF Form Processor and Webform modules.
Install the neccessary modules
- Webform
- cmrf_core: https://github.com/CiviMRF/cmrf_core/releases/download/7.x-0.5/cmrf_core.zip
- cmrf_form_processor: https://github.com/CiviMRF/cmrf_form_processor
Setup CiviMRF
Go to configuration --> CiviMRF Connection Profiles and add a new profile.
Give your profile a name and add the url to the rest.php of your civicrm, add your site key and your api key. You have noted the api key and site key earlier on.
Create the webform
Go to Content --> Add Content --> Webform and give your webform the name Buddy Signp.
After you have created the webform go to the CiviMRF tab and enable the CiviMRF Form Processing and select the form processor Buddy Signup.
Next add the fields to your webform:
- First name, Type: text field, key: first_name, required
- Last name, Type: text field, key: last_name, required
- Street address, Type: text field, key: street_address
- Postal code, Type: text field, key: postal_code,
- City, Type: text field, key: city, required
- E-mail, Type: e-mail, key: email, required
- Telephone number, Type: text field, key: telephone_number
- Birth date, Type: text field, key: birth_date, description: 'Enter in yyyy-mm-dd format'
- Gender, Type: select options, key: gender, check Load Options From CiviMRF, Select Gender field, Check Listbox
It is important to set the key of the field to the name of the inputs of your form processor.
See the screenshot below for the cofiguration:
Now your form is ready to be used, see below for a working example:
More in depth
Why did I need to set the permission?
If you dont specify a permission, the system assumes the API users has the permission Administer CiviCRM. But we dont want the api user be able to configure our CiviCRM. We want it to be able to submit data, so thats why we set it to 'access CiviCRM'.
Why do I need the action-provider extension?
Because the action provider extension contains all the actions. The reason for not having those in the form processor extension is that those actions could be used in other extensions as well (e.g. CiviRules, SQLTasks, etc...).
I am a developer can I develop my own actions?
Yes you can! You can add the actions to the action-provider extension or you can develop them in your own extension. See https://lab.civicrm.org/extensions/action-provider/blob/master/docs/howto_create_an_action.md for an how to.
