Skip to content

CRM User Contact Mapping

The CRM User Contact Mapping 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 mapping event and uniform flow for mapping new or existing users to contacts: configuration, 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.

Permissions

Permission Description
administer crm Full administrative access to CRM functionality, including user contact mappings
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

The mapping system integrates with Drupal's access control through entity access handlers and relationship-based permissions (mapped vs. any). See Entity for full detail.

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. The CRM section appears on user edit forms at /admin/config/crm/user/settings when the feature is enabled and the user has a mapped contact.

Use cases

  • Automatic user registration – Create corresponding contact records when users register.
  • Existing contact integration – Link existing CRM contacts to user accounts when users register with matching email addresses.
  • 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