How are Drupal or Joomla Users Linked to Engage Contact Records¶
Every Engage instance sits within a "User Framework" — a CMS (Backdrop, Drupal, Joomla or WordPress) that handles user authentication (logging in) and gives users various levels of access to Engage features (permissions).
Contacts are the individuals, organizations and households in Engage. Users, on the other hand, are defined in this context as people who have a username and password to log into Engage via the User Framework/CMS. You probably won't have a User account for every Contact in your Engage instance.
Drupal behavior:¶
Whenever a new user registers , Engage checks for an existing contact with the same email address.
- If a match is found, the new user is linked to the existing Engage contact.
- If no match is found, a new Engage contact is created with the new user's primary email address.
Whenever an existing user logs in , Engage checks for a linked contact record. If none exists, the same logic applies - either link the user to an existing contact or create a new contact. This case applies when Engage is installed or enabled for an existing Drupal site. However, we recommend that you run the batch synchronization utility (next section) in this situation.
Joomla behavior:¶
Engage does not natively use the hooks and APIs of Joomla to facilitate hooking into the user registration and login pages. As a result, in com_user neither a new user registration nor an existing user login alone will trigger the above check for a corresponding Engage contact. Instead, this check is made whenever a logged in Joomla user engages in a transaction with the Engage system, such as editing a Engage Profile form, making a Contribution or registering a Membership. You can, however, replace the Joomla registration form with a form that using a Engage profile that has registration enabled.
Tip
Thus, for example, if a contact has been entered in the Engage database manually by an administrator, or as a result of a transaction as the anonymous Joomla user (eg in a contribution or membership transaction, or a "quick registration"), then the user needs to do more than merely create a Joomla account with matching criteria (eg email) to get linked to their Engage record. They need also to engage in a Engage transaction while they are logged in. Thus a process might look like:
- User makes a Contribution as the anonymous Joomla user i.e. no login required. Their email address and any custom Profile fields from the Contribution form is recorded in a Engage record.
- User subsequently returns to site and registers as a Joomla user using the same email address as previously used.
- User logs in as the above Joomla user and is now presented with a menu item (visible to registered users only) to eg "Edit my details" which links to a Engage Profile.
- Clicking on this menu link performs the match between the Joomla user and Engage contact record, and the user is taken to their Profile edit page. The Joomla user account and Engage record are now linked.
However, you can create a user plugin that responds to one or more of the user events. In Joomla 1.5 those are:
- onBeforeStoreUser
- onAfterStoreUser
- onBeforeDeleteUser
- onAfterDeleteUse
- onLoginUser
- onLogouUser
In 1.6 those are
- onUserAfterDelete
- onUserAfterSave
- onUserBeforeDelete
- onUserBeforeSave
- onUserLogin
- onUserLogout
WordPress Behavior¶
Engage used the add_action function to listen to the wordpress functions: 'user_register' and 'profile_update'. In both cases Engage synchronizes the WP user account with the Engage contact. Currently Engage only sync the WP email field with the Engage contact.
Synchronize Users-to-Contacts¶
Synchronize Users-to-Contacts Overview¶
The Synchronize Users-to-Contacts feature is most often used when an organization has a pre-existing Drupal or Joomla site and is adding Engage for the first time. This allows all users of the existing Drupal or Joomla site to have Engage contact records automatically generated.
In Drupal and Joomla, when someone registers with a site (or an administrator adds them), a user record is created. A user is the person who is logging into the Drupal or Joomla CMS (Content Management System). This is different from Engage contact records, which usually include a much broader range of information about individuals, organizations and households.
When Engage is "turned on" in Drupal or Joomla, a contact record is automatically created every time a user record is created. Engage often has many additional contact records that are not user records (read more...).
Synchronize Users-to-Contacts¶
Go to Administer Engage. In the Users and Permissions section, choose Synchronize Users to Contacts.
- User records are records generated by Drupal when someone creates a login and password for themselves to use on your Drupal Website.
- Contact records are records created in Engage either through an import, data entry or the synchronize users-to-contacts function.
Synchronize Users-to-Contacts checks each user record for a contact record. If there is no corresponding contact record for a user, a new one will be generated.
Click on Synchronize Users-to-Contacts and you will see the message:
Click OK to proceed.
Once complete, you will see a message like this:
Synchronize Users to Contacts completed. Checked 5 user records. Found 3 matching contact records. Created 2 new contact records.
You can then search your contact records to view or edit the new contact records. Go to Advanced Search , >>Change Log section and enter dates that include the date when the synchronization was performed.