README.txt in Webform CiviCRM Integration 7

INSTRUCTIONS FOR WEBFORM CIVICRM INTEGRATION


INTRODUCTION:

Most forms all start the same way: Name, Address, Phone Number, Email, etc. Creating those same fields over and over again can be tedious, not to mention then getting said data into your CiviCRM database. This module takes care of all that for you.


WHAT IT DOES:

-Auto create just about any CiviCRM contact field (including custom fields!)
-Auto-fill forms for logged in users.
-Auto-fill for anonymous users too if you send them a personalized link through CiviMail.
-Automatically log activities when users fill out your form.
-It uses your CiviCRM default strict deduping rule to decide whether to update an existing contact or create a new one when the form is submitted by an anonymous user.
-It imposes no restrictions on how you style, rename, nest, or edit your CiviCRM fields; you may do anything with them that you can do with any other webform field.


HOW TO USE IT

-Enable the module.
-Create a new webform (or go to edit an existing one).
-Click on the CiviCRM tab.
-Enable the fields you like, and optionally choose introduction text and activity settings.
-Your selected fields will be automatically created for you.
-Customize the webform settings for your new fields however you wish.
-If you wish to delete a field, you may do so through the standard webform interface, the same as any other webform field.


GROUPS AND TAGS

This module allows you to tag contacts and add them to groups when they submit the webform.
-ASSIGNING TAGS: From the Webform CiviCRM tab, check the box to enable the Tags field. Click save. Then from the Form Components tab, click the edit button for the Tags component. You may enter as many tags as you wish, separated by commas. If the tags you enter do not already exist in CiviCRM, they will be created for you. The tags you entered will be added to all contacts who submit this webform.
-ADDING CONTACTS TO GROUPS: Follow the instructions as for tags. There are two options for Groups -- visible checkboxes on the webform that allow contacts to add themselves to one or more groups of your choosing, and a hidden form element that just adds them. You may use both elements if you wish, to give your users a choice about some groups, but automatically add them to others.
-OPT-IN CONFIRMATION: At the bottom of the options in the Webform CiviCRM tab is a checkbox to enable confirmation emails when contacts are added to public mailing lists. It is recommended that you leave that option enabled in most situations. You may configure the text of the confirmation message using CiviCRM.


CUSTOM DATA

-This module can handle (almost) any custom fields you have created for contacts in CiviCRM. Two exceptions due to their complexity are contact references and files. To use custom fields, they must be active in CiviCRM, and used for Contacts or Individuals.


USING SPECIAL LINKS IN CIVIMAIL

CiviMail has the ability to generate links that have a unique "key" for each person it sends a message to. This module can read those keys and automatically pre-fill the webform for people who follow that link. Your constituents will thank you for not making them fill out their name, address, etc when you already know it. To send out personalized links to your form in CiviMail, simply copy and paste the provided url on the CiviCRM tab of your webform into your CiviMail message. It will look similar to this:

http://mysite.org/myform?cid={contact.contact_id}&{contact.checksum}

NOTE: If you are sending an HTML (rich-text) message, the recommended method is to highlight a piece of text in your message such as "go to my form" then click the link button (at the top of the message text editor) and paste in the above-mentioned url.

The personalized links generated by CiviMail are valid for 1 week.


ABOUT THE USER MESSAGE

This feature exists to help prevent a major CRM headache: If users view your form while logged-in as someone else, or they click to your form by following someone else's personalized link (i.e. from a forwarded email), they will see that person's details on the form. Not given any alternative, they are likely to manually clear those fields and type their own information, which would cause the existing contact to be updated with a different person's details, throwing your contact data into confusion.

When enabled, users will see a configurable message instructing them to "click here" if they are not the intended contact. The link will take the appropriate action (logging them out if they are logged in, or else getting rid of the personalized hash) and bring them  to an anonymous version of the form.


RETROFITTING AN EXISTING WEBFORM

You can pretty easily start recording CiviCRM contacts even for an existing webform. This falls into two scenarios:

1) You don't have any contact info fields on the form yet (name, address, etc). That's easy, just go to the CiviCRM tab of your webform, check the boxes, and the new fields will be created for you.

2) You already have contact info fields on your form. If people have already been using this form, you don't want to delete those fields because you'd lose data from all existing submissions! Instead, you can get webform_civicrm to start processing those fields by changing their field keys to the ones understood by webform_civicrm. For example, click to edit the "First Name" field in your webform, and then change the field key to "civicrm_first_name". Be sure to enable civicrm on that webform (which you may safely do before, during, or after renaming your field keys). For a complete list of field keys, see the function webform_civicrm_get_fields() in the webform_civicrm_utils.inc file. They are the keys of the $fields array. Or, if you don't like reading code, just create yourself a dummy webform, have webform_civicrm auto-create the fields you want, then copy and paste those field keys into your other form.


WILL CONTACTS AND ACTIVITIES BE CREATED RETROACTIVELY IF I ENABLE THIS MODULE ON AN EXISTING WEBFORM?

No. That would require some sort of batch update script, which is not part of this module.