Agent Assist feature integration

Last updated:
Edit on GitHub

This document describes how to integrate the Agent Assist feature into a Spryker project.

Install feature core

Follow the steps below to install the feature core.

Prerequisites

To start feature integration, overview and install the necessary features:

NAME VERSION INTEGRATION GUIDE
Spryker Core 202108.0 Spryker core feature integration
Product 202108.0 Spryker Core Back Office feature integration
Cart 202108.0 Customer Account Management

1) Install the required modules using Composer

Run the following command to install the required modules:

composer require spryker-feature/agent-assist:"202108.0" --update-with-dependencies
Verification

Ensure that the following modules have been installed:

MODULE EXPECTED DIRECTORY
Agent vendor/spryker/agent
AgentGui vendor/spryker/agent-gui

2) Set up the database schema

Run the following commands to apply database changes and to generate entity and transfer changes:

console transfer:generate
console propel:install
console transfer:generate
Verification

Verify the following changes by checking your database:

DATABASE ENTITY TYPE EVENT
spy_user.is_agent column created

3) Set up behavior

Set up the following behaviors.

Configure user Zed UI for agent handling

Enable the following behaviors by registering the plugins:

PLUGIN DESCRIPTION PREREQUISITES NAMESPACE
UserAgentFormExpanderPlugin Adds the is an agent checkbox to the Zed User form. None Spryker\Zed\AgentGui\Communication\Plugin
UserAgentTableConfigExpanderPlugin Adds the is an agent column to the Zed Users table. None Spryker\Zed\AgentGui\Communication\Plugin
UserAgentTableDataExpanderPlugin Fills the is an agent column in the Zed Users table. Expects the is an agent checkbox in the Zed User form. Spryker\Zed\AgentGui\Communication\Plugin

src/Pyz/Zed/User/UserDependencyProvider.php

<?php

namespace Pyz\Zed\User;

use Spryker\Zed\AgentGui\Communication\Plugin\UserAgentFormExpanderPlugin;
use Spryker\Zed\AgentGui\Communication\Plugin\UserAgentTableConfigExpanderPlugin;
use Spryker\Zed\AgentGui\Communication\Plugin\UserAgentTableDataExpanderPlugin;
use Spryker\Zed\User\UserDependencyProvider as SprykerUserDependencyProvider;

class UserDependencyProvider extends SprykerUserDependencyProvider
{
    /**
     * @return \Spryker\Zed\UserExtension\Dependency\Plugin\UserFormExpanderPluginInterface[]
     */
    protected function getUserFormExpanderPlugins(): array
    {
        return [
            new UserAgentFormExpanderPlugin(),
        ];
    }

    /**
     * @return \Spryker\Zed\UserExtension\Dependency\Plugin\UserTableConfigExpanderPluginInterface[]
     */
    protected function getUserTableConfigExpanderPlugins(): array
    {
        return [
            new UserAgentTableConfigExpanderPlugin(),
        ];
    }

    /**
     * @return \Spryker\Zed\UserExtension\Dependency\Plugin\UserTableDataExpanderPluginInterface[]
     */
    protected function getUserTableDataExpanderPlugins(): array
    {
        return [
            new UserAgentTableDataExpanderPlugin(),
        ];
    }
}
Verification

Ensure that the following plugins have been registered:

MODULE TEST
UserAgentFormExpanderPlugin 1. In the Back Office, go to Users > Users.
2. Select Edit next to a user.
3. Ensure that the This user is an agent checkbox exists.
UserAgentTableConfigExpanderPlugin 1. In the Back Office, go to Users > Users.
2. Ensure that the Agent column exists.
UserAgentTableDataExpanderPlugin 1. In the Back Office, go to Users > Users.
2. Select Edit next to a non-agent user.
3. Select the This user is an agent checkbox.
4. Select Update. This takes you to the Users List page with the message about successful update displayed.
5. Ensure that in the Agent column next to the user you’ve updated, the Agent tag is displayed.

Install feature frontend

Follow the steps below to install the feature front end.

Prerequisites

To start feature integration, overview and install the necessary features:

NAME VERSION
Spryker Core 202108.0

1) Install the required modules using Composer

Run the following command to install the required modules:

composer require spryker-feature/agent-assist:"202108.0" --update-with-dependencies
Verification

Ensure that the following modules have been installed:

MODULE EXPECTED DIRECTORY
AgentPage vendor/spryker-shop/agent-page
AgentWidget vendor/spryker-shop/agent-widget

2) Set up configuration

By default, in Spryker, posting login form (where SecurityBlocker will make its check and block agents who made too many failed login attempts) is locale-independent. So, to be able to see error messages translated into different languages, you need to configure the locale to be added to the agent login path. You can do this by modifying the following configs:

src/Pyz/Yves/AgentPage/AgentPageConfig.php

<?php

namespace Pyz\Yves\AgentPage;

use SprykerShop\Yves\AgentPage\AgentPageConfig as SprykerAgentPageConfig;

class AgentPageConfig extends SprykerAgentPageConfig
{
    /**
     * @return bool
     */
    public function isLocaleInLoginCheckPath(): bool
    {
        return true;
    }
}
Verification

Make sure that when the login form for the agent is submitted, the URL it uses contains a locale code. For example, /de/agent/login_check would be the default value for the agent.

3) Add translations

Add translations as follows:

  1. Append the glossary according to your configuration:

src/data/import/glossary.csv

agent.authentication.failed,Authentication failed,en_US
agent.authentication.failed,Authentifizierung fehlgeschlagen,de_DE
agent.login.title,Access your account,en_US
agent.login.title,Ich bin bereits Kunde,de_DE
agent.confirm_user_selection,Confirm,en_US
agent.confirm_user_selection,Bestätigen,de_DE
agent.login.email,Email,en_US
agent.login.email,E-Mail,de_DE
agent.login.password,Password,en_US
agent.login.password,Passwort,de_DE
agent.control_bar.username,Agent: %username%,en_US
agent.control_bar.username,Agent: %username%,de_DE
agent.control_bar.customer_name,Customer: %username%,en_US
agent.control_bar.customer_name,Kunde: %username%,de_DE
agent.control_bar.logout_as_customer,End Customer Assistance,en_US
agent.control_bar.logout_as_customer,Kunden-Assistenz beenden,de_DE
agent.control_bar.logout,Logout,en_US
agent.control_bar.logout,Abmelden,de_DE
agent.autocomplete.no_results,No results found,en_US
agent.autocomplete.no_results,Keine Ergebnisse gefunden,de_DE
autocomplete.placeholder,Search,en_US
autocomplete.placeholder,Suche,de_DE
  1. Run the following command to add the glossary keys:
console data:import:glossary

4) Enable controllers

Enable the following controllers.

Service provider list

Register the service provider in the Yves application:

PROVIDER NAMESPACE SPECIFICATION
AgentPageSecurityServiceProvider SprykerShop\Yves\AgentPage\Plugin\Provider Registers security firewalls, access rules, impersonate rules, login and logout handlers for Agent users.

src/Pyz/Yves/ShopApplication/YvesBootstrap.php

<?php

namespace Pyz\Yves\ShopApplication;

use SprykerShop\Yves\AgentPage\Plugin\Provider\AgentPageSecurityServiceProvider;
use SprykerShop\Yves\ShopApplication\YvesBootstrap as SprykerYvesBootstrap;

class YvesBootstrap extends SprykerYvesBootstrap
{
    /**
     * @return void
     */
    protected function registerServiceProviders()
    {
        $this->application->register(new AgentPageSecurityServiceProvider()); # AgentFeature
    }
}
Verification

Ensure that you’ve registered the providers correctly:

  1. Open http://mysprykershop.com/agent/secured.
  2. This should redirect you to http://mysprykershop.com/agent/login.

Controller provider list

Register the controller provider(s) in the Yves application:

PROVIDER NAMESPACE ENABLED CONTROLLER CONTROLLER SPECIFICATION
AgentPageControllerProvider SprykerShop\Yves\AgentPage\Plugin\Provider AgentPage\AuthController Provides Login and Logout actions for the agent user.
AgentWidgetControllerProvider SprykerShop\Yves\AgentWidget\Plugin\Provider AgentWidget\CustomerAutocompleteController Provides the customer autocomplete action for the agent control bar.

src/Pyz/Yves/ShopApplication/YvesBootstrap.php

<?php

namespace Pyz\Yves\ShopApplication;

use SprykerShop\Yves\AgentPage\Plugin\Provider\AgentPageControllerProvider;
use SprykerShop\Yves\AgentWidget\Plugin\Provider\AgentWidgetControllerProvider;
use SprykerShop\Yves\ShopApplication\YvesBootstrap as SprykerYvesBootstrap;

class YvesBootstrap extends SprykerYvesBootstrap
{
    /**
     * @param bool|null $isSsl
     *
     * @return \SprykerShop\Yves\ShopApplication\Plugin\Provider\AbstractYvesControllerProvider[]
     */
    protected function getControllerProviderStack($isSsl)
    {
        return [
            new AgentPageControllerProvider($isSsl), #AgentFeature
            new AgentWidgetControllerProvider($isSsl), #AgentFeature
        ];
    }
}
Verification

Ensure that you have registered the providers correctly:

PROVIDER TEST
AgentPageControllerProvider Ensure that you can open https://mysprykershop.com/agent/login.
AgentWidgetControllerProvider 1. Log in as an agent.
2. Ensure that you can search by customers using the Agent control bar.

5) Set up widgets

Set up widgets as follows:

  1. Register the following global widget(s):
WIDGET SPECIFICATION NAMESPACE
AgentControlBarWidget Allows agents to select and impersonate customers. SprykerShop\Yves\AgentWidget\Widget

src/Pyz/Yves/ShopApplication/ShopApplicationDependencyProvider.php

<?php

namespace Pyz\Yves\ShopApplication;

use SprykerShop\Yves\AgentWidget\Widget\AgentControlBarWidget;
use SprykerShop\Yves\ShopApplication\ShopApplicationDependencyProvider as SprykerShopApplicationDependencyProvider;

class ShopApplicationDependencyProvider extends SprykerShopApplicationDependencyProvider
{
    /**
     * @return string[]
     */
    protected function getGlobalWidgets(): array
    {
        return [
            AgentControlBarWidget::class,
        ];
    }
}
  1. Enable Javascript and CSS changes:
console frontend:yves:build
  1. If you have a custom layout template, place the Agent widget above the site header:
{% widget 'AgentControlBarWidget' only %}{% endwidget %}
Verification

Ensure that the following widgets have been registered:

MODULE TEST
AgentControlBarWidget Log in as an agent. The control bar widget should appear above the site header.