Installation and First Configuration

This section describes the installation of the Customer Management Framework (CMF) and the first configuration steps.

info

The Customer Management Framework requires MariaDB. It does not work with plain MySQL, because activities are stored using the MariaDB Dynamic Columns feature. See the MariaDB Dynamic Columns documentation for details.

Server Requirements

Database Permissions

The database user needs all permissions from the platform's System Requirements - Permissions, plus:

• Create routine
• Alter routine

Installation Process

Install the Customer Management Framework in three steps.

1. Install the required dependencies:

composer require pimcore/customer-management-framework-bundle

2. Enable the bundle in config/bundles.php:

use CustomerManagementFrameworkBundle\PimcoreCustomerManagementFrameworkBundle;
use Pimcore\Bundle\ObjectMergerBundle\ObjectMergerBundle;
// ...
return [
    // ...
    PimcoreCustomerManagementFrameworkBundle::class => ['all' => true],
    ObjectMergerBundle::class => ['all' => true],
    // ...
];

3. Install the bundle:

bin/console pimcore:bundle:install PimcoreCustomerManagementFrameworkBundle

The installer:

• Installs several data object classes.
• Creates additional tables for activities, deletions, segment building, actions, triggers, rules, duplicates, and the newsletter export queue.
• Registers the permissions listed below.

After installation, reload Pimcore Studio. The Customer Management Framework's menu entries (Customers, Customer duplicates, Customer automation rules) become available to users who hold the corresponding permission.

Permissions

CMF registers the following permissions during installation. Grant them to the roles or users who need access to the corresponding feature.

Permission key	Studio label	Grants
plugin_cmf_perm_customerview	CMF Customer View	Read access to customers (including the customer list export), segments, segment groups, duplicates, term segment builder definitions, and helper lookups. Also required to create, update, delete, and share filter definitions, to decline a potential duplicate, and to read and change the segments assigned to a Pimcore element (the Segment Assignment tab).
plugin_cmf_perm_customerview_admin	CMF Customer Filter-Admin	Write access: create, update, and delete customers, activities, segments, and segment groups; change the segments assigned to a customer; read the newsletter queue size and manage the webservice API key settings; update all filter definitions shared with the user (see List Views).
plugin_cmf_perm_activityview	CMF Activity View	Read-only access to activities and the deletions log.
plugin_cmf_perm_customer_automation_rules	CMF Customer Automation Rules	Full access (list, get, create, update, delete) to ActionTrigger automation rules.
plugin_cmf_perm_newsletter_enqueue_all_customers	CMF Newsletter Enqueue Customers	Permission to trigger a bulk newsletter enqueue for all eligible customers.

Two related features rely on permissions defined outside the CMF bundle:

• Sharing a saved customer filter with other users or roles additionally requires the Pimcore core permission Share configurations (share_configurations). See List Views.
• GDPR data extraction for customers is exposed through the Studio GDPR framework's customers data provider. The provider itself is gated by plugin_cmf_perm_customerview_admin, the same permission used for all other write operations on customers. CMF defines an additional gdpr_data_extractor constant, but no code in the bundle currently checks it.

Configure the Customer Class

The CMF installer does not create a data object class for customers, because the framework does not limit you to a specific class or class structure. The only requirement is that the customer class is prepared for use in a CMF context. Choose one of the following options.

• For all basic CMF functionality, extend the customer class from CustomerManagementFrameworkBundle\Model\AbstractCustomer. The class also needs these data attributes:

  • active: checkbox
  • gender: gender field
  • firstname: firstname field
  • lastname: lastname field
  • street: input field
  • zip: input field
  • city: input field
  • countryCode: country selection
  • customerLanguage: language selection
  • email: email field
  • phone: input field
  • manualSegments: an object relation to CustomerSegments, or an object relation with metadata to CustomerSegments using created_timestamp and application_counter as numeric metadata fields
  • calculatedSegments: same options as manualSegments
  • idEncoded: input field
  • profilingConsent: consent field (optional)

  Use this class definition as a starting point.

  The attributes do not have to be field definitions on the class itself. You can instead implement them as getters on your class implementation:

  class AppBundleCustomer extends Pimcore\Model\DataObject\Customer
  {
      /** Implementation for firstname */
      public function getFirstname()
      {
          return $this->getCustomerAddress()->getFirstname();
      }
  
      // ...
  }

• When using customer objects as Symfony security users, extend the customer class from CustomerManagementFrameworkBundle\Model\AbstractCustomer\DefaultAbstractUserawareCustomer and add one more data attribute:

  • password: password field

  When extending from DefaultAbstractUserawareCustomer, the customer class must also provide the getters/setters required by CustomerManagementFrameworkBundle\Model\CustomerInterface. Either add them directly to the class, or use a trait that implements them.

• Minimal requirements (not recommended): to stay independent of the base classes above, implement CustomerManagementFrameworkBundle\Model\CustomerInterface directly on your customer class.

tip

Name the customer class Customer. Any other name works too, but then set general.customerPimcoreClass to that name in the Configuration chapter.

Add any further attributes your project needs on top of this baseline.

Segment Assignment Stored Functions

The installer creates database stored functions for auto-assigning segments to assets, documents, and data objects. If that step fails, import the stored functions manually. Set a delimiter other than ; when running these files:

/Resources/sql/segmentAssignment/storedFunctionDocument.sql
/Resources/sql/segmentAssignment/storedFunctionAsset.sql
/Resources/sql/segmentAssignment/storedFunctionObject.sql

Configuration

CMF ships with a default configuration that covers basic functionality, so no further configuration is required to get started. To enable or customize additional functionality, see the Configuration chapter.

Configure the Webservice Firewall

The REST webservice authenticates requests with WebserviceAuthenticator (CustomerManagementFrameworkBundle\Security\Authenticator\WebserviceAuthenticator), which accepts either an API key or an existing Pimcore Studio session. The bundle ships the complete firewall definition as the customer_management_framework.firewall_settings container parameter, so registering the firewall is a single line:

security:
    firewalls:
        # ... your other firewalls, e.g. pimcore_studio
        cmf_webservice: '%customer_management_framework.firewall_settings%'

The parameter sets the route pattern (^/__customermanagementframework/webservice(/.*)?$), stateless: true, the pimcore_admin user provider, and the WebserviceAuthenticator as custom authenticator.

caution

Spelling the firewall out by hand instead of using the parameter is possible but not recommended, as it may break in future versions when the bundle changes the route pattern or the authenticator wiring.

Set Up the Required Cron Jobs

CMF needs several cron jobs configured to keep segment building, action triggers, duplicate detection, maintenance tasks, and the newsletter sync running. See the Cron Jobs chapter for the full list.