Merchant Portal feature integration

Edit on GitHub

Environment requirements

  • NodeJs v16+
  • NPM v8+
  • Spryker supported PHP version (7.3, 7.4)
  • Host for Zed application

Installing frontend dependencies

Run the following command:

$ npm install

Building frontend

Run the following command:

$ npm run mp:build

For production

$ npm run mp:build:production

Installing backend

Install the needed packages for the Merchant Portal with dependencies, see the available list here

NAME VERSION INTEGRATION GUIDE
Spryker Core 202212.0 Spryker Core feature integration
Marketplace Merchant Portal Core 202212.0 Marketplace Merchant Portal Core feature integration

Merchant Portal users

1) Create users

Create users for the Merchant Portal using Zed UI (Backoffice), or if you need them out of the box, add them into \Pyz\Zed\User\UserConfig::getInstallerUsers(), for example:

src/Pyz/Zed/User/UserConfig.php

<?php

namespace Pyz\Zed\User;

use Spryker\Zed\User\UserConfig as SprykerUserConfig;

class UserConfig extends SprykerUserConfig
{
     /**
     * @return array
     */
    public function getInstallerUsers()
    {
        return [
            [
                'firstName' => 'Michele',
                'lastName' => 'Nemeth',
                'password' => 'change123',
                'username' => 'michele@sony-experts.com',
            ],
        ];
    }
}

2) Connect users and merchants

Connect users and merchants using Zed UI (Backoffice) or using the next data import.

data/import/common/common/marketplace/merchant.csv

 merchant_key,merchant_reference,merchant_name,registration_number,status,email,is_active,url.de_DE,url.en_US
 sony-experts,MER000006,Sony Experts,HYY 134306,approved,michele@sony-experts.com,1,/de/merchant/sony-experts,/en/merchant/sony-experts

In case you don’t have merchant user data import integrated, you can find how to do it in the Marketplace Merchant feature integration guide.

data/import/common/common/marketplace/merchant_user.csv

merchant_key,username
sony-experts,michele@sony-experts.com

Import data:

console data:import merchant
console data:import merchant-user

3) ACL adjustments.

By default all newly created merchants and merchant users will automatically have group, role and segment with autogenerated names based on MerchantName, MerchantUserName and MerchantPortalKey.

Adjust AclConfig up to your needs in order to allow Merchant Portal pages (*-merchant-portal-gui) for merchant users (optionally deny access to them for Admin roles)

You can check the available list of packages for the Merchant Portal here https://github.com/spryker/?q=merchant-portal-gui

src/Pyz/Zed/Acl/AclConfig.php

<?php

namespace Pyz\Zed\Acl;

use Generated\Shared\Transfer\AclEntityRuleTransfer;
use Generated\Shared\Transfer\RuleTransfer;
use Spryker\Shared\Acl\AclConstants;
use Spryker\Zed\Acl\AclConfig as SprykerAclConfig;

class AclConfig extends SprykerAclConfig
{
    /**
     * @var string
     */
    protected const RULE_TYPE_DENY = 'deny';

    /**
     * @return array
     */
    public function getInstallerRules()
    {
        $installerRules = parent::getInstallerRules();
        $installerRules = $this->addMerchantPortalInstallerRules($installerRules);

        return $installerRules;
    }

     /**
     * @param array<array<string>> $installerRules
     *
     * @return array<array<string>>
     */
    protected function addMerchantPortalInstallerRules(array $installerRules): array
    {
        $bundleNames = [
            'dashboard-merchant-portal-gui',
            'merchant-profile-merchant-portal-gui',
            'product-merchant-portal-gui',
            'product-offer-merchant-portal-gui',
            'security-merchant-portal-gui',
            'sales-merchant-portal-gui',
            'user-merchant-portal-gui',
            'dummy-merchant-portal-gui',
        ];

        foreach ($bundleNames as $bundleName) {
            $installerRules[] = [
                'bundle' => $bundleName,
                'controller' => AclConstants::VALIDATOR_WILDCARD,
                'action' => AclConstants::VALIDATOR_WILDCARD,
                'type' => static::RULE_TYPE_DENY,
                'role' => AclConstants::ROOT_ROLE,
            ];
        }

        return $installerRules;
    }

    /**
     * @return array
     */
    public function getInstallerUsers()
    {
        return [
            'michele@sony-experts.com' => [],
            //this is related to existent username and will be searched into the database
        ];
    }
}

Create users with ACL rules:

console setup:init-db

Extending ACL entity metadata configuration.

You can use our AclEntityDummyProduct module as an example of extending AclEntityMetadata configuration.

Install the module:

composer require spryker/acl-entity-dummy-product:"^0.2.0" --update-with-dependencies

Use \Spryker\Zed\AclEntityDummyProduct\Communication\DummyProductAclEntityMetadataConfigExpanderPlugin as an example of AclEntityMetadataCollection configuration.

<?php
     namespace Pyz\Zed\AclEntity;

     use Spryker\Zed\Acl\AclDependencyProvider as SprykerAclDependencyProvider;
     use Spryker\Zed\AclEntityDummyProduct\Communication\DummyProductAclEntityMetadataConfigExpanderPlugin;

     class AclEntityDependencyProvider extends SprykerAclEntityDependencyProvider
     {
         /**
          * @return array<\Spryker\Zed\AclEntityExtension\Dependency\Plugin\AclEntityMetadataConfigExpanderPluginInterface>
          */
          protected function getAclEntityMetadataCollectionExpanderPlugins(): array
          {
              return [
                  new DummyProductAclEntityMetadataConfigExpanderPlugin(),
              ];
          }
     }

To configure the Merchant Portal Sidebar add installed MP GUI modules into config/Zed/navigation.xml.

config/Zed/navigation.xml

<?xml version="1.0"?>
<config>
    <merchant-portal-dashboard>
        <label>Dashboard</label>
        <title>Merchant Dashboard</title>
        <icon>dashboard</icon>
        <bundle>dashboard-merchant-portal-gui</bundle>
        <controller>dashboard</controller>
        <action>index</action>
    </merchant-portal-dashboard>
    <merchant-portal-profile>
        <label>Profile</label>
        <title>Profile</title>
        <icon>profile</icon>
        <bundle>merchant-profile-merchant-portal-gui</bundle>
        <controller>profile</controller>
        <action>index</action>
    </merchant-portal-profile>
    <product-offer-merchant-portal-gui>
        <label>Offers</label>
        <title>Offers</title>
        <icon>offers</icon>
        <bundle>product-offer-merchant-portal-gui</bundle>
        <controller>product-offers</controller>
        <action>index</action>
        <pages>
            <create-offer>
                <label>Create Offer</label>
                <title>Create Offer</title>
                <bundle>product-offer-merchant-portal-gui</bundle>
                <controller>product-list</controller>
                <action>index</action>
                <visible>0</visible>
            </create-offer>
        </pages>
    </product-offer-merchant-portal-gui>
    <sales-merchant-portal-gui>
        <label>Orders</label>
        <title>Orders</title>
        <icon>orders</icon>
        <bundle>sales-merchant-portal-gui</bundle>
        <controller>orders</controller>
        <action>index</action>
    </sales-merchant-portal-gui>
    <product-merchant-portal-gui>
        <label>Products</label>
        <title>Products</title>
        <icon>offers</icon>
        <bundle>product-merchant-portal-gui</bundle>
        <controller>products</controller>
        <action>index</action>
    </product-merchant-portal-gui>
    <security-merchant-portal-gui>
        <label>Logout</label>
        <title>Logout</title>
        <icon>logout</icon>
        <bundle>security-merchant-portal-gui</bundle>
        <controller>logout</controller>
        <action>index</action>
    </security-merchant-portal-gui>
</config>

Build navigation cache:

console navigation:build-cache
Verification

Make sure that all configured items are present in the Merchant Portal Sidebar and route you accordingly.

Make sure that you have enabled \Spryker\Zed\Acl\Communication\Plugin\Navigation\AclNavigationItemCollectionFilterPlugin in \Pyz\Zed\ZedNavigation\ZedNavigationDependencyProvider.

<?php

namespace Pyz\Zed\ZedNavigation;

use Spryker\Zed\Acl\Communication\Plugin\Navigation\AclNavigationItemCollectionFilterPlugin;
use Spryker\Zed\ZedNavigation\ZedNavigationDependencyProvider as SprykerZedNavigationDependencyProvider;

class ZedNavigationDependencyProvider extends SprykerZedNavigationDependencyProvider
{
    /**
     * @return array<\Spryker\Zed\ZedNavigationExtension\Dependency\Plugin\NavigationItemCollectionFilterPluginInterface>
     */
    protected function getNavigationItemCollectionFilterPlugins(): array
    {
        return [
            new AclNavigationItemCollectionFilterPlugin(),
        ];
    }
}

5) Separate Login feature setup (security firewalls).

It requires upgrading spryker/smyfony:3.5.0 and applying some changes on the project, see Symfony 5 integration.

Install the required modules:

composer remove spryker/auth spryker/auth-mail-connector spryker/auth-mail-connector-extension spryker/authentication-merchant-portal-gui
composer require spryker/security-gui:"^1.0.0" spryker/security-merchant-portal-gui:"^1.0.0" spryker/security-system-user:"^1.0.0" spryker/user-password-reset:"^1.0.0" spryker/user-password-reset-extension:"^1.0.0" spryker/user-password-reset-mail:"^1.0.0" --update-with-dependencies

Update the following modules to the latest minors.

MODULE DIRECTORY
Application vendor/spryker/application
MerchantUser vendor/spryker/merchant-user
Security vendor/spryker/security
Session vendor/spryker/session
User vendor/spryker/user
ZedUi vendor/spryker/zed-ui

Apply changes from https://github.com/spryker-shop/suite/pull/681/files.

Verification

Go to http://mp.de.spryker.local/security-merchant-portal-gui/login

The Merchant Portal looks as follows:

Merchant Portal login

After login, you should be redirected to the Dashboard. The contents of the Sidebar will depend on the installed features and their configuration.

Merchant Portal dashboard

Integrate the following related features:

FEATURE REQUIRED FOR THE CURRENT FEATURE INTEGRATION GUIDE
Merchant Portal - Marketplace Merchant Merchant Portal - Marketplace Merchant feature integration
Merchant Portal - Marketplace Product Merchant Portal - Marketplace Product feature integration
Merchant Portal - Marketplace Order Management Merchant Portal - Marketplace Order Management feature integration
Merchant Portal - Marketplace Merchant Portal Product Offer Management + Merchant Portal Order Management Merchant Portal - Marketplace Merchant Portal Product Offer Management + Merchant Portal Order Management feature integration
Merchant Portal - Marketplace Product + Inventory Management Merchant Portal - Marketplace Product + Inventory Management feature integration
Merchant Portal - Marketplace Product Options Management Merchant Portal - Marketplace Product Options Management integration
Merchant Portal - Marketplace Product + Tax Merchant Portal - Marketplace Product + Tax feature integration