Install the B2B Customer Groups feature

This document describes how to install the B2B Customer Groups feature. The feature lets a customer group hold companies and business units in addition to customers. It adds the following:

• The Companies and Business Units tabs on the Back Office pages that create and edit a customer group, and the matching panels on the page that shows a customer group.
• Two Backend API resources that list, add, replace, and remove the companies and business units of a customer group.
• Four data importers that create customer groups and assign companies, business units, and customers to them.

Discounts and other rules that target a customer group evaluate only its customers: company and business unit memberships do not affect them. For how the memberships behave, see Customer Groups overview.

Prerequisites

Install the required features:

Install feature core

1) Install the required modules

Install the feature using Composer:

composer require spryker-feature/customer-experience-management --update-with-dependencies

2) Set up the database schema and transfer objects

The feature stores the memberships in two new tables. For the data importers, it also declares the key columns of spy_company and spy_company_business_unit, which the company and business unit data importers already add in most projects, and a unique key on the business unit key.

SELECT unit.key, COUNT(*) FROM spy_company_business_unit unit WHERE unit.key IS NOT NULL GROUP BY unit.key HAVING COUNT(*) > 1;

Apply the database schema changes and generate the transfer objects:

docker/sdk console propel:install
docker/sdk console transfer:generate

The two spy_company_user indexes back the Customers column of the Back Office tables, which counts the company users of each company and business unit. They have the same names as the indexes that the index generator creates, so a project that already has them does not get duplicates.

3) Add Zed translations

Generate a new translation cache for Zed:

docker/sdk console translator:generate-cache

4) Set up behavior

The customer group pages and the customer group save run plugin stacks of the CustomerGroup module. Register the following plugins to add the Companies and Business Units tabs, save their selections, and show the memberships on the page that displays a customer group:

src/Pyz/Zed/CustomerGroup/CustomerGroupDependencyProvider.php

<?php

namespace Pyz\Zed\CustomerGroup;

use Spryker\Zed\CustomerGroup\CustomerGroupDependencyProvider as SprykerCustomerGroupDependencyProvider;
use SprykerFeature\Zed\CustomerExperienceManagement\Communication\Plugin\CustomerGroup\CompanyBusinessUnitCustomerGroupFormExpanderPlugin;
use SprykerFeature\Zed\CustomerExperienceManagement\Communication\Plugin\CustomerGroup\CompanyBusinessUnitCustomerGroupFormTabExpanderPlugin;
use SprykerFeature\Zed\CustomerExperienceManagement\Communication\Plugin\CustomerGroup\CompanyBusinessUnitCustomerGroupPostSavePlugin;
use SprykerFeature\Zed\CustomerExperienceManagement\Communication\Plugin\CustomerGroup\CompanyBusinessUnitCustomerGroupViewExpanderPlugin;
use SprykerFeature\Zed\CustomerExperienceManagement\Communication\Plugin\CustomerGroup\CompanyCustomerGroupFormExpanderPlugin;
use SprykerFeature\Zed\CustomerExperienceManagement\Communication\Plugin\CustomerGroup\CompanyCustomerGroupFormTabExpanderPlugin;
use SprykerFeature\Zed\CustomerExperienceManagement\Communication\Plugin\CustomerGroup\CompanyCustomerGroupPostSavePlugin;
use SprykerFeature\Zed\CustomerExperienceManagement\Communication\Plugin\CustomerGroup\CompanyCustomerGroupViewExpanderPlugin;

class CustomerGroupDependencyProvider extends SprykerCustomerGroupDependencyProvider
{
    /**
     * @return list<\Spryker\Zed\CustomerGroupExtension\Dependency\Plugin\CustomerGroupPostSavePluginInterface>
     */
    protected function getCustomerGroupPostSavePlugins(): array
    {
        return [
            new CompanyCustomerGroupPostSavePlugin(),
            new CompanyBusinessUnitCustomerGroupPostSavePlugin(),
        ];
    }

    /**
     * @return list<\Spryker\Zed\CustomerGroupExtension\Dependency\Plugin\CustomerGroupFormTabExpanderPluginInterface>
     */
    protected function getCustomerGroupFormTabExpanderPlugins(): array
    {
        return [
            new CompanyCustomerGroupFormTabExpanderPlugin(),
            new CompanyBusinessUnitCustomerGroupFormTabExpanderPlugin(),
        ];
    }

    /**
     * @return list<\Spryker\Zed\CustomerGroupExtension\Dependency\Plugin\CustomerGroupFormExpanderPluginInterface>
     */
    protected function getCustomerGroupFormExpanderPlugins(): array
    {
        return [
            new CompanyCustomerGroupFormExpanderPlugin(),
            new CompanyBusinessUnitCustomerGroupFormExpanderPlugin(),
        ];
    }

    /**
     * @return list<\Spryker\Zed\CustomerGroupExtension\Dependency\Plugin\CustomerGroupViewExpanderPluginInterface>
     */
    protected function getCustomerGroupViewExpanderPlugins(): array
    {
        return [
            new CompanyCustomerGroupViewExpanderPlugin(),
            new CompanyBusinessUnitCustomerGroupViewExpanderPlugin(),
        ];
    }
}

Register the tab, form, and post-save plugins of a company or business unit together:

• A tab plugin without its form plugin breaks the page, because the tab renders the fields that the form plugin adds.
• A form plugin without its post-save plugin accepts selections that are never saved.

The view plugins are independent of the others. Without them, the page that shows a customer group displays only the General Information and Customers panels.

Grant access to restricted Back Office roles

The tables of the new tabs and panels load their rows from the customer-experience-management module, not from customer-group. A Back Office role that has access to every module, such as the root role, needs no changes. A role with restricted access rules shows empty tables until you allow the following:

The Edit buttons of the Companies and Business Units panels open the edit pages of the company and the business unit, so the role also needs access to company-gui/edit-company/index and company-business-unit-gui/edit-company-business-unit. To add rules to a role, see Edit user roles.

If your project uses Persistence ACL for Back Office users, also allow the SpyCustomerGroupToCompany and SpyCustomerGroupToCompanyBusinessUnit entities.

Optional: Reopen the edit page after a save

By default, saving a customer group on its edit page opens the page that shows the group. To reopen the edit page instead, on the tab that was open when the form was submitted, enable the following setting:

src/Pyz/Zed/CustomerGroup/CustomerGroupConfig.php

<?php

namespace Pyz\Zed\CustomerGroup;

use Spryker\Zed\CustomerGroup\CustomerGroupConfig as SprykerCustomerGroupConfig;

class CustomerGroupConfig extends SprykerCustomerGroupConfig
{
    public function isRedirectToEditPageAfterUpdateEnabled(): bool
    {
        return true;
    }
}

This setting affects only the edit page. Saving a new customer group always opens the Customer Groups page.

Optional: Change the order of the tabs

By default, the pages that create and edit a customer group render the General Information, Customers, Companies, and Business Units tabs, and the page that shows a customer group renders its panels in the same order. To use another order on all three pages, list the tab names. Tabs that you do not list follow the listed ones, and the first listed tab opens when the page loads.

src/Pyz/Zed/CustomerGroup/CustomerGroupConfig.php

<?php

namespace Pyz\Zed\CustomerGroup;

use Spryker\Zed\CustomerGroup\CustomerGroupConfig as SprykerCustomerGroupConfig;
use SprykerFeature\Zed\CustomerExperienceManagement\Communication\Plugin\CustomerGroup\CompanyBusinessUnitCustomerGroupFormTabExpanderPlugin;
use SprykerFeature\Zed\CustomerExperienceManagement\Communication\Plugin\CustomerGroup\CompanyCustomerGroupFormTabExpanderPlugin;

class CustomerGroupConfig extends SprykerCustomerGroupConfig
{
    /**
     * @return list<string>
     */
    public function getFormTabOrder(): array
    {
        return [
            static::FORM_TAB_NAME_GENERAL,
            CompanyCustomerGroupFormTabExpanderPlugin::TAB_NAME,
            CompanyBusinessUnitCustomerGroupFormTabExpanderPlugin::TAB_NAME,
            static::FORM_TAB_NAME_CUSTOMER_ASSIGNMENT,
        ];
    }
}

5) Build Zed UI frontend

The feature relies on the Back Office scripts of the Gui and CustomerGroup modules: the selectable tables of the new tabs restore their selection after a save fails validation, and the edit page reopens on the tab that was open. Rebuild the Back Office assets:

docker/sdk console frontend:zed:build

6) Set up the Backend API

The customer-group-companies and customer-group-company-business-units resources are generated by API Platform. They write the memberships through the customer group save, so they rely on the post-save plugins from Set up behavior: without those plugins, a write answers 204 and changes nothing.

The resource schemas ship inside the installed package, in vendor/spryker-feature/customer-experience-management/resources/api/backend/. In config/GlueBackend/packages/spryker_api_platform.php, confirm that apiTypes() includes backend, and leave sourceDirectories() unchanged unless your project overrides it. For details, see Configuration.

Generate the API resources, then clear the Glue Backend kernel cache:

docker/sdk cli "GLUE_APPLICATION=GLUE_BACKEND vendor/bin/glue api:generate"
rm -rf data/cache/GlueBackend/*

The resources address a customer group by its UUID. If your project had customer groups before it installed the customer group UUIDs, generate the missing ones as described in Backend API: Manage customer groups.

curl -X POST "https://glue-backend.mysprykershop.com/customer-groups/{customer_group_uuid}/companies" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{"data":{"type":"customer-group-companies","attributes":{"companyUuids":["{company_uuid}"]}}}'

curl "https://glue-backend.mysprykershop.com/customer-groups/{customer_group_uuid}/companies?include=companies" \
  -H "Authorization: Bearer {access_token}" \
  -H "Accept: application/vnd.api+json"

If the endpoints return 404 while the generated resource classes exist, see API Platform troubleshooting.

7) Import data

The feature provides four data importers. Use them to load customer groups and their members in bulk, for example, from an ERP export:

The membership importers only add memberships: they never remove a membership, and they never create or change a company, business unit, or customer. The file details pages describe the columns and the rows that are rejected.

1. Prepare your data according to your requirements. For example, data/import/common/common/customer_group_to_company.csv:

>customer_group_name,company_key
Key Accounts,acme_corporation
Key Accounts,Ottom_ltd
Hospitality,BoB-Hotel-Jim
Hospitality,BoB-Hotel-Mitte

2. Register the following plugins to enable data import:

src/Pyz/Zed/DataImport/DataImportDependencyProvider.php

<?php

namespace Pyz\Zed\DataImport;

use Spryker\Zed\DataImport\DataImportDependencyProvider as SprykerDataImportDependencyProvider;
use SprykerFeature\Zed\CustomerExperienceManagement\Communication\Plugin\DataImport\CustomerGroupCompanyBusinessUnitDataImportPlugin;
use SprykerFeature\Zed\CustomerExperienceManagement\Communication\Plugin\DataImport\CustomerGroupCompanyDataImportPlugin;
use SprykerFeature\Zed\CustomerExperienceManagement\Communication\Plugin\DataImport\CustomerGroupCustomerDataImportPlugin;
use SprykerFeature\Zed\CustomerExperienceManagement\Communication\Plugin\DataImport\CustomerGroupDataImportPlugin;

class DataImportDependencyProvider extends SprykerDataImportDependencyProvider
{
    protected function getDataImporterPlugins(): array
    {
        return [
            new CustomerGroupDataImportPlugin(),
            new CustomerGroupCompanyDataImportPlugin(),
            new CustomerGroupCompanyBusinessUnitDataImportPlugin(),
            new CustomerGroupCustomerDataImportPlugin(),
        ];
    }
}

3. Add the four data entities to the data import configuration, after company-business-unit, with customer-group first. The customer groups, companies, business units, and customers that the membership files refer to must be imported before the membership files.

data/import/local/full_EU.yml

    - data_entity: company-business-unit
      source: data/import/common/common/company_business_unit.csv
    - data_entity: customer-group
      source: data/import/common/common/customer_group.csv
    - data_entity: customer-group-company
      source: data/import/common/common/customer_group_to_company.csv
    - data_entity: customer-group-company-business-unit
      source: data/import/common/common/customer_group_to_company_business_unit.csv
    - data_entity: customer-group-customer
      source: data/import/common/common/customer_group_to_customer.csv

A data entity in the configuration without its registered plugin fails the whole import, so add the entities and the plugins together. Repeat the change for every data import configuration file your project uses.

4. Import data:

docker/sdk console data:import --config=data/import/local/full_EU.yml customer-group
docker/sdk console data:import --config=data/import/local/full_EU.yml customer-group-company
docker/sdk console data:import --config=data/import/local/full_EU.yml customer-group-company-business-unit
docker/sdk console data:import --config=data/import/local/full_EU.yml customer-group-customer

A membership row whose customer group, key, or customer reference does not exist is rejected. The other rows are still imported, the run is reported as failed, and the import command exits with code 1. Because a deployment stops at a failed import, make sure every customer group that a membership file names is in customer_group.csv or exists before the import.

Optional: Adjust the limits

The following methods of SprykerFeature\Zed\CustomerExperienceManagement\CustomerExperienceManagementConfig set the limits of the feature. To change a limit, override the method in src/Pyz/Zed/CustomerExperienceManagement/CustomerExperienceManagementConfig.php.