Skip to content

CRM User Integration

The CRM User Integration system provides a mechanism to associate Drupal user accounts with CRM contact entities. This creates a bridge between the user management system and the contact relationship management functionality.

Overview

The crm_user_contact_mapping entity type creates a one-to-one relationship between a Drupal user account and a CRM contact record (specifically limited to the 'person' type). This mapping enables the system to:

  • Automatically create contact records when users are created
  • Link existing users to contact records
  • Provide unified access to user and contact information
  • Enable contact-based permissions for users

Documentation

  • Entity – The crm_user_contact_mapping entity: database schema, fields, constraints, permissions, administrative interface, direct CRUD, and security.
  • Event – The user integration event and uniform flow for mapping new or existing users to contacts: configuration, the create-contact override, event system, service API, and troubleshooting.
  • Field mapping – Exposing contact fields on the user entity: computed field wrappers, access control plugin system, configuration, and form integration.
  • Views integration – UserContactMappingField and user–contact Views relationships.
  • Hooks – Field-mapping exclusions and mapped-contact grant records.

Permissions

Permission Description
administer crm Full administrative access to CRM functionality, including user integrations
view mapped crm contact View contact records that are mapped to the current user
edit mapped crm contact Edit contact records that are mapped to the current user
create any crm contact Create new contact records
alter crm user display name Customize display name format using associated contact information
override crm user contact mapping Change CRM contact mapping options when creating a user

The user integration system integrates with Drupal's access control through entity access handlers, relationship-based permissions (mapped vs. any), and optional grant_* fields on the mapping entity. See Entity and Hooks.

Display name override

When the global display_name setting is enabled in crm.user_contact_mapping.settings, user display names can be overridden with the associated contact's name. Users with the alter crm user display name permission can choose a name format (via the Name module) on their profile edit form when the feature is enabled and the user has a mapped contact. Configure the feature at /admin/config/crm/user/settings.

Use cases

  • Automatic user registration – Create a person when users register, when Create contact is enabled and that email is not already on a contact.
  • Optional create override – Users with override crm user contact mapping can uncheck Create contact on the user add form so that account is created without a mapping. See Event.
  • Existing person – Attach a user to an existing person from the mapping form at /admin/config/crm/user/add. A matching email never claims an existing person.
  • Permission-based access – Allow users to view and edit their own contact information through the CRM interface.
  • Data synchronization – Keep user account information synchronized with CRM contact data.

Testing

The system includes test coverage in:

  • tests/src/Kernel/UserContactMappingCreationTest.php – Core mapping functionality
  • tests/src/Kernel/EventSubscriber/UserContactMappingSubscriberTest.php – Event system
  • tests/src/Kernel/Form/UserContactMappingFormTest.php – Form handling
  • tests/src/Functional/UserContactMappingTest.php – End-to-end workflows
  • tests/src/Functional/UserContactMappingOverrideFormTest.php – Create-contact override on the user add form