Merchant Portal feature integration

Edit on GitHub

Environment requirements

  • NodeJs v12+
  • Yarn v2 (or latest Yarn v1)
  • Spryker supported PHP version (7.3, 7.4)
  • Host for Zed application

Installing frontend dependencies

Run the following command:

$ yarn install

Building front end

Run the following command:

$ yarn mp:build

For production

$ yarn mp:build:production

Installing back end

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

NAME VERSION LINK
Spryker Core 202108.0 Spryker Core feature integration
Marketplace Merchant Portal Core 202108.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 been 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

Run the following commands to 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 string[][] $installerRules
     *
     * @return 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
        ];
    }
}

Run the following command to 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.

Run the following command to 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 \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>

Run the following command to 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 \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 next modules to 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 should look like on the picture:

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