FirstSpirit Connect

FirstSpirit Connect enables editors to do the following:

The corresponding functions are made available when the module is installed and configured in ContentCreator.

Familiar FirstSpirit tools are used to maintain the content, meaning that editors who are already familiar with FirstSpirit do not require any additional knowledge. The content is made available to Spryker as part of a deployment so that it can be imported. Spryker then integrates the information into the shop.

Consequently there is no difference for Spryker in the delivering of editorial contents to the live state. Even if the FirstSpirit server is shut down due to maintenance work, for example, this does not affect Spryker.

The connection of FirstSpirit and Spryker is realized by an architecture made up of a range of components (see figure Architecture).

These components are:

Figure 1. Architecture

The individual components always interact according to the following schema:

Spryker thus represents the main component of this architecture. In addition to providing all shop functionality, it imports the content created or maintained in FirstSpirit from the Online CaaS and integrates it into the shop. There is only a loose link between FirstSpirit and Spryker. They primarily work in parallel with one another.

The FirstSpirit Connect module offers the possibility to maintain editorial contents in FirstSpirit and to transfer them afterwards via deployment to Spryker. For this, content processing in both systems must be coordinated and compatible with each other. The subchapters below describe the underlying concept used to archieve this compatibility.

1.3.1. Pages

Similar to FirstSpirit, pages in Spryker are based on a structure of different components. In order to exchange editorial content between the two systems, these components must be coordinated.

Within the reference project FirstSpirit Connect Reference Project included in the delivery, the CMS slots from Spryker are represented by the content areas of a page template in FirstSpirit. Sections corresponding to a CMS block can be added to them.

Figure 2. Page Rendering

With FirstSpirit, CMS blocks can be generated that are displayed in a page via CMS slots.

To use the FirstSpirit Connect module, the following technical requirements must be met:

When using the supplied reference project FirstSpirit Connect Reference Project, the current version of the BasicWorkflows module is also required.

This chapter contains information that should be observed when using the FirstSpirit Connect module.

1.5.2. Configuration of the FirstSpirit project settings page

The CaaS generations assume that a template for the project settings is maintained in the FirstSpirit project. Otherwise, the generation job terminates early and reports the following error in the job logs:

Exception with missing project settings page. 

error during script execution : java.lang.IllegalStateException:
Invalid value for key 'usedCaasProjects' - Value is not a HashMap (zero).
This can happen when a deployment does not include a single PageRef (blue), which is not supported (e.g. remote-media-project).

For this reason, a template must exist in the project and be configured in the project options in ServerManager, even if it has no content.

Figure 3. Configuration of the project settings page in the project options

[...]
set memory_limit=-1
[...]

Both the retrieval of the CaaS contents by Spryker and their display and editing in ContentCreator is done using various Spryker modules. These modules require an installation in Spryker and an extension of the configuration. They also require various JavaScript and CSS files to be included in Spryker.

The following chapters describe how to perform the necessary steps.

composer config repo.espirit artifact ./PATH-TO-DIRECTORY

$config[KernelConstants::CORE_NAMESPACES] = [
   'SprykerShop',
   'SprykerEco',
   'Spryker',
   'Generated',
   'ESpirit'
];

$config[SessionConstants::YVES_SESSION_COOKIE_SAMESITE] = 'None';

$config[KernelConstants::DOMAIN_WHITELIST] = array_merge($trustedHosts, [
    ...
    'demo-spryker.e-spirit.hosting',
]);

docker:

    ssl:
        enabled: true
        redirect: true

composer require e-spirit/firstspirit-caas
composer require e-spirit/firstspirit-preview
composer require e-spirit/firstspirit-preview-navigation
composer require e-spirit/firstspirit-data-state-writer
composer require e-spirit/firstspirit-data-cleanup
composer require e-spirit/firstspirit-data-import
composer require e-spirit/firstspirit-data-inconsistency-check
composer require e-spirit/firstspirit-data-rest-api
composer require e-spirit/firstspirit-cms-data-connector
composer require e-spirit/firstspirit-cms-data-storage

vendor/bin/console transfer:generate
vendor/bin/console propel:install

composer require e-spirit/firstspirit-reference-components

[...]

dirs: [
   join(globalSettings.context, paths.core),
   join(globalSettings.context, './vendor/e-spirit'),
   join(globalSettings.context, paths.eco),
   join(globalSettings.context, paths.project)
],

[...]

"include": [
   "./vendor/spryker-shop/**/*",
   "./vendor/spryker-eco/**/*",
   "./src/Pyz/Yves/**/*",
   "./vendor/e-spirit/**/*"
],

npm run yves

template_path,slot_key,content_provider,name,description,is_active
[...]
@HomePage/views/home/home.twig,fs-slt-2,FirstSpiritCmsSlotBlock,Banner,Banner content section for the homepage.,1
@HomePage/views/home/home.twig,fs-slt-3,FirstSpiritCmsSlotBlock,Homepage Content,Homepage main content section.,1

vendor/bin/console data:import cms-slot

// ----------- FirstSpirit Preview Configurations
$config[FirstSpiritPreviewConstants::FIRSTSPIRIT_PREVIEW_AUTHENTICATION_INIT_TOKEN] = '<ADD TOKEN>';
$config[FirstSpiritPreviewConstants::FIRSTSPIRIT_PREVIEW_WEB_HOST] = '<ADD FS PREVIEW HOST>';
$config[FirstSpiritPreviewConstants::FIRSTSPIRIT_PREVIEW_CAAS_CONTENT_PAGE_COLLECTION] = '<CAAS COLLECTION>';
$config[FirstSpiritPreviewConstants::FIRSTSPIRIT_PREVIEW_CAAS_CATEGORY_PAGE_COLLECTION] = '<CAAS COLLECTION>';
$config[FirstSpiritPreviewConstants::FIRSTSPIRIT_PREVIEW_CAAS_PRODUCT_PAGE_COLLECTION] = '<CAAS COLLECTION>';
$config[FirstSpiritPreviewConstants::FIRSTSPIRIT_PREVIEW_DISPLAY_BLOCK_RENDER_ERRORS] = true;

// ----------- FirstSpirit Data Import Configurations
$config[FirstSpiritDataImportConstants::FIRSTSPIRIT_DATA_IMPORT_BLOCK_DATA_CAAS_PATH] = '/_aggrs/blocks';
$config[FirstSpiritDataImportConstants::FIRSTSPIRIT_CAAS_REQUEST_PAGESIZE] = <VALUE>;
$config[FirstSpiritDataImportConstants::FIRSTSPIRIT_DATA_IMPORT_URL_TEMPLATE] = '/{locale}/{url}';

// ----------- FirstSpirit CaaS Configurations
$config[FirstSpiritCaaSConstants::FIRSTSPIRIT_CAAS_HOSTNAME_PREVIEW] = '<ADD CAAS HOST>';
$config[FirstSpiritCaaSConstants::FIRSTSPIRIT_CAAS_PORT_PREVIEW] = '<ADD CAAS PORT>';
$config[FirstSpiritCaaSConstants::FIRSTSPIRIT_CAAS_SCHEME_PREVIEW] = '<ADD CAAS SCHEME>';
$config[FirstSpiritCaaSConstants::FIRSTSPIRIT_CAAS_APIKEY_PREVIEW] = '<ADD APIKEY>';
$config[FirstSpiritCaaSConstants::FIRSTSPIRIT_CAAS_DATABASE_PREVIEW] = '<ADD CAAS DATABASE>';

$config[FirstSpiritCaaSConstants::FIRSTSPIRIT_CAAS_HOSTNAME_ONLINE] = '<ADD CAAS HOST>';
$config[FirstSpiritCaaSConstants::FIRSTSPIRIT_CAAS_PORT_ONLINE] = '<ADD CAAS PORT>';
$config[FirstSpiritCaaSConstants::FIRSTSPIRIT_CAAS_SCHEME_ONLINE] = '<ADD CAAS SCHEME>';
$config[FirstSpiritCaaSConstants::FIRSTSPIRIT_CAAS_APIKEY_ONLINE] = '<ADD APIKEY>';
$config[FirstSpiritCaaSConstants::FIRSTSPIRIT_CAAS_DATABASE_ONLINE] = '<ADD CAAS DATABASE>';

<?php

use ESpirit\Shared\FirstSpiritCaaS\FirstSpiritCaaSConstants;
use ESpirit\Shared\FirstSpiritDataImport\FirstSpiritDataImportConstants;

$config[FirstSpiritCaaSConstants::FIRSTSPIRIT_CAAS_DATABASE_PREVIEW] = '<ADD CAAS DATABASE FOR SPECIFIC STORE>';
$config[FirstSpiritCaaSConstants::FIRSTSPIRIT_CAAS_DATABASE_ONLINE] = '<ADD CAAS DATABASE FOR SPECIFIC STORE>';

$config[FirstSpiritDataImportConstants::FIRSTSPIRIT_DATA_IMPORT_URL_TEMPLATE] = '/{locale}/{store}/{url}';

use ESpirit\Shared\FirstSpiritPreview\FirstSpiritPreviewConstants;
use ESpirit\Shared\FirstSpiritDataImport\FirstSpiritDataImportConstants;
use ESpirit\Shared\FirstSpiritCaaS\FirstSpiritCaaSConstants;

{% extends template('page-blank', '@SprykerShop:ShopUi') %}

{% block attributes %}
    {{ fsIncludeDataAttributes() }}
{% endblock %}

{% block template %}
   {% set isNewFrontendBuildSupported = true %}

[...]

{% block footerScripts %}
   {% include molecule('check-touch') only %}
      {{ fsIncludeOcmScript() }}
   {{ parent() }}
{% endblock %}

Further adjustments are necessary, which are described in the following paragraph.

All CMS related types need to be added to the DataImportConfig file in the src/Pyz/Zed/DataImport directory to avoid issues with the request aggregation loop.

Extension of the DataImportConfig. 

[...]
public const IMPORT_TYPE_CMS_BLOCK_STORE = 'cms-block-store';
public const IMPORT_TYPE_CMS_BLOCK_CATEGORY_POSITION = 'cms-block-category-position';
public const IMPORT_TYPE_DISCOUNT = 'discount';
[...]

    $customImportTypes = [
        StockAddressDataImportConfig::IMPORT_TYPE_STOCK_ADDRESS,
        static::IMPORT_TYPE_CMS_PAGE,
        static::IMPORT_TYPE_CMS_BLOCK,
        static::IMPORT_TYPE_NAVIGATION,
    ];

[...]

Disable the append prefix for CMS page URLs by adjusting the CmsConfig file in the src/Pyz/Zed/Cms directory.

Adjustment of the CmsConfig. 

[...]

public function appendPrefixToCmsPageUrl(): bool
{
    return false;
}

[...]

Create a PHP file called CmsSlotGuiCommunicationFactory in the to be created src/Pyz/Zed/CmsSlotGui/Communication directory and another PHP file called PyzSlotTable in the to be created src/Pyz/Zed/CmsSlotGui/Communication/Table directory with the following content to override the backoffice table.

CmsSlotGuiCommunicationFactory. 

<?php

/**
 * Copyright © 2016-present Spryker Systems GmbH. All rights reserved.
 * Use of this software requires acceptance of the Evaluation License Agreement. See LICENSE file.
 */

namespace Pyz\Zed\CmsSlotGui\Communication;

use Pyz\Zed\CmsSlotGui\Communication\Table\PyzSlotTable;
use Spryker\Zed\CmsSlotGui\Communication\Table\SlotTable;
use Spryker\Zed\CmsSlotGui\Communication\CmsSlotGuiCommunicationFactory as SprykerCmsSlotGuiCommunicationFactory;

class CmsSlotGuiCommunicationFactory extends SprykerCmsSlotGuiCommunicationFactory
{
    /**
     * @param int|null $idSlotTemplate
     *
     * @return \Spryker\Zed\CmsSlotGui\Communication\Table\SlotTable
     */
    public function createSlotListTable(?int $idSlotTemplate = null): SlotTable
    {
        return new PyzSlotTable(
            $this->getCmsSlotQuery(),
            $this->getTranslatorFacade(),
            $idSlotTemplate
        );
    }
}

PyzSlotTable. 

<?php

/**
 * Copyright © 2016-present Spryker Systems GmbH. All rights reserved.
 * Use of this software requires acceptance of the Evaluation License Agreement. See LICENSE file.
 */

namespace Pyz\Zed\CmsSlotGui\Communication\Table;

use Spryker\Zed\CmsSlotGui\Communication\Table\SlotTable as SprykerSlotTable;

class PyzSlotTable extends SprykerSlotTable
{
    /**
     * @return bool
     */
    protected function isContentProviderColumnVisible(): bool
    {
        if ($this->contentProviderTypesNumber === null) {
            $this->contentProviderTypesNumber = (clone $this->cmsSlotQuery)
                ->select(static::COL_CONTENT_PROVIDER)
                ->distinct()
                ->count();
        }

        return $this->contentProviderTypesNumber > 1;
    }
}

Due to issues with the bar code

PyzSlotTable. 

<?php

/**
 * Copyright © 2016-present Spryker Systems GmbH. All rights reserved.
 * Use of this software requires acceptance of the Evaluation License Agreement. See LICENSE file.
 */

namespace Pyz\Zed\CmsSlotGui\Communication\Table;

use Spryker\Zed\CmsSlotGui\Communication\Table\SlotTable as SprykerSlotTable;

class PyzSlotTable extends SprykerSlotTable
{
    /**
     * @return bool
     */
    protected function isContentProviderColumnVisible(): bool
    {
        if ($this->contentProviderTypesNumber === null) {
            $this->contentProviderTypesNumber = (clone $this->cmsSlotQuery)
                ->select(static::COL_CONTENT_PROVIDER)
                ->distinct()
                ->count();
        }

        return $this->contentProviderTypesNumber > 1;
    }
}

In addition to the installation of the Spryker modules, the following plugins must be included:

Extension of the ShopApplicationDependencyProvider. 

use ESpirit\Yves\FirstSpiritPreview\Plugin\FsTwigExtensionPlugin;
use ESpirit\Yves\FirstSpiritPreview\Plugin\HeadersSecurityExtensionPlugin;
use ESpirit\Yves\FirstSpiritPreview\Widget\FirstSpiritCategoryLinkWidget;
use ESpirit\Yves\FirstSpiritPreview\Widget\FirstSpiritContentLinkWidget;
use ESpirit\Yves\FirstSpiritPreview\Widget\FirstSpiritExternalLinkWidget;
use ESpirit\Yves\FirstSpiritPreview\Widget\FirstSpiritProductFlyoutWidget;
use ESpirit\Yves\FirstSpiritPreview\Widget\FirstSpiritProductLinkWidget;

[...]

protected function getGlobalWidgets(): array
{
   return [
      [...]
      FirstSpiritCategoryLinkWidget::class,
      FirstSpiritProductLinkWidget::class,
      FirstSpiritContentLinkWidget::class,
      FirstSpiritExternalLinkWidget::class,
      FirstSpiritProductFlyoutWidget::class,
   ];
}

[...]

protected function getApplicationPlugins(): array
{
   return [
      [...]
      new FsTwigExtensionPlugin()
   ];
}

In addition to the Spryker modules and the plugins the delivery contains the following widgets. They enable the expandability of the navigations contained in the shop, as well as the usage of the DOM references and the Shoppable Image contained in the reference project. Only if these elements are used a registration of the widgets is required.

FirstSpiritPreviewContentNavigationWidget
The FirstSpiritPreviewContentNavigationWidget creates the possibility to maintain the navigations contained in the store with FirstSpirit and to add further menu items. It replaces the existing ContentNavigationWidget in Spryker and provides various attributes required for displaying the corresponding navigation in the preview. Therefore the existing ContentNavigationWidget, which is stored under the path /src/Pyz/Yves in Spryker, has to be replaced by the FirstSpiritPreviewContentNavigationWidget included in the delivery. Finally, the use of the FirstSpiritPreviewContentNavigationWidget requires a registration. This is done by modifying the TwigDependencyProvider in the directory /src/Pyz/Yves/Twig/, in which the ContentNavigationTwigPlugin has to be replaced by the FirstSpiritPreviewNavigationWidgetTwigPlugin.

Adaptation of the TwigDependencyProviders. 

<?php

namespace Pyz\Yves\Twig;

use ESpirit\Yves\FirstSpiritPreviewNavigationWidget\Plugin\Twig\FirstSpiritPreviewNavigationWidgetTwigPlugin;
[...]

class TwigDependencyProvider extends SprykerTwigDependencyProvider
{
   [...]

   protected function getTwigPlugins(): array
   {
      return [
         [...]
         // new ContentNavigationTwigPlugin(),
         new FirstSpiritPreviewNavigationWidgetTwigPlugin(),
      ];
   }

   [...]
}

FirstSpiritCategoryLinkWidget und FirstSpiritProductLinkWidget
The FirstSpiritCategoryLinkWidget and the FirstSpiritProductLinkWidget are used to display editorial DOM links to category or product detail pages. In both cases, the widget determines the corresponding category or product using a unique identifier and passes the result to the Twig template that controls the display of the respective link in Spryker. Each of the two widgets references its corresponding Twig template. The Twig templates are provided by the previously installed FirstSpiritPreview module.

FirstSpiritContentLinkWidget und FirstSpiritExternalLinkWidget
The FirstSpiritContentLinkWidget and the FirstSpiritExternalLinkWidget enable DOM links to editorial content, whereby the type of content differs in each case. The FirstSpiritExternalLinkWidget only allows the referencing of external content. In contrast, the FirstSpiritContentLinkWidget is used to display internal DOM links to dynamic content pages or magazine articles maintained within the FirstSpirit project. An important aspect is that the target URL of the internal links to dynamic content pages depends on the output: While the link in the live state refers to the published CMS page, the corresponding preview URL must be used in the preview. In both cases, the widget controls the determination of the required URL.

FirstSpiritProductFlyoutWidgets
The registration of the FirstSpiritProductFlyoutWidget is only required if the Shoppable Image provided with the delivery is used in the project. The widget controls the display of flyouts for the products linked to the Shoppable Image.

Registration
The four link widgets and the flyout widget are registered using the following code, which must be added to the ShopApplicationDependencyProvider in the folder src/Pyz/Yves/ShopApplication.

Extension of the ShopApplicationDependencyProvider. 

use ESpirit\Yves\FirstSpiritPreview\Widget\FirstSpiritCategoryLinkWidget;
use ESpirit\Yves\FirstSpiritPreview\Widget\FirstSpiritProductLinkWidget;
use ESpirit\Yves\FirstSpiritPreview\Widget\FirstSpiritContentLinkWidget;
use ESpirit\Yves\FirstSpiritPreview\Widget\FirstSpiritExternalLinkWidget;
use ESpirit\Yves\FirstSpiritPreview\Widget\FirstSpiritProductFlyoutWidget;

[...]

protected function getGlobalWidgets(): array
{
   return [
      [...]
      FirstSpiritCategoryLinkWidget::class,
      FirstSpiritProductLinkWidget::class,
      FirstSpiritContentLinkWidget::class,
      FirstSpiritExternalLinkWidget::class,
      FirstSpiritProductFlyoutWidget::class
   ];
}

The previously installed CmsBlockTwigFunctionPlugin allows mapping between the content stored in FirstSpirit and in Spryker. For this, it assumes that the view data of a page contains its ID and type. The controllers of Spryker do not provide this information by default. For this reason, the following controllers must be overwritten both for content and category pages and in the case of the homepage, which corresponds to a static page:

The overwriting is done by creating the corresponding classes, which are all part of the zip file b2c-demo-shop-extensions-<VERSION>.zip included in the delivery. They must be copied into the directory Controller to be created below src/Pyz/Yves/HomePage|CatalogPage|CmsPage.

In contrast to the other pages, the product pages require the adaptation of the ProductController which already exists in Spryker. It is contained in the directory src/Pyz/Yves/ProductDetailPage/Controller/ProductController and must be extended by the definition of the page type and the Product SKU. The following code snippet shows the changes to be made:

Extension of the ProductController. 

<?php
namespace Pyz\Yves\ProductDetailPage\Controller;

[...]
use ESpirit\Shared\FirstSpiritPreview\FirstSpiritPreviewConstants;

class ProductController extends SprykerShopProductController
{
   protected function executeDetailAction(array $productData, Request $request): array
   {
      [...]

       $viewData['cart'] = $quoteTransfer;
       $viewData[FirstSpiritPreviewConstants::VIEW_DATA_PAGE_TYPE_KEY] = FirstSpiritPreviewConstants::PRODUCT_PAGE_TYPE;
       $viewData[FirstSpiritPreviewConstants::VIEW_DATA_PAGE_ID_KEY] = $productData['sku'];

       return $viewData;
   }
}

In addition to the controllers mentioned above, the delivery includes further render controllers which enable individual CMS elements to be updated in the preview. They are addressed by the FirstSpiritPreviewRoutePlugin which initially does not exist in Spryker and therefore requires registration in the RouterDependencyProvider file in the Pyz/Yves/Router directory. Within the file, the method getRouteProvider has to be extended as follows.

Extension of the method getRouteProvider. 

use ESpirit\Yves\FirstSpiritPreview\Plugin\Route\FirstSpiritPreviewRoutePlugin;

[...]
protected function getRouteProvider(): array
{
   return [
      [...]
      new FirstSpiritPreviewRoutePlugin()
   ];
}

An adjustment of the RouterConfig file in the src/Pyz/Zed/Router directory is required to enable gateway routing.

RouterConfig. 

public function getControllerDirectories(): array
{
   [...]
   $controllerDirectories[] = sprintf('%s/e-spirit/*/src/*/Zed/*/Communication/Controller/', APPLICATION_VENDOR_DIR);

   return array_filter($controllerDirectories, 'glob');
}

By default, the Spryker B2C Demo Shop contains different navigations, which can be created and edited in Spryker. The integration realised with the FirstSpirit Connect module offers the possibility to maintain these navigations with FirstSpirit and to add further menu items.

Within the reference project the functionality is implemented exemplarily for the main navigation. Its usage requires the already described referencing of the FirstSpiritPreviewContentNavigationWidgets, the creation of a placeholder, and the addition of a preview ID.

The placeholder to be created corresponds to another menu item. This is required to display the navigation in the preview and must be added to the navigation-header.twig file in the src/Pyz/Yves/ShopUi/Theme/default/components/molecules/navigation-header directory:

Adjustment of the navigation-header.twig file. 

[..]
<ul class="menu {{ menuClass }} grid grid--center grid--no-wrap">
   {% for node in data.nodes %}
      [..]
   {% endfor %}

   {% if isFsPreview() %}
      <li class="fs-navigation-extension"
         style="padding-left: 1rem; transform: translate(0,15% );">
      </li>
   {% endif %}
</ul>
[..]

In addition, a preview ID is required to display the main navigation in the preview. This preview ID is to be defined in the navigation-multilevel-node.twig file in the directory src/Pyz/Yves/ShopUi/Theme/default/components/molecules/navigation-multilevel-node:

Adjustment of the navigation-multilevel-node.twig file. 

[...]

{% block attributes %}
   {% if isFsPreview() and data.node.previewId is defined and data.node.previewId is not empty %}
      data-preview-id="{{ data.node.previewId }}" style="min-height: unset;"
   {% endif %}
{% endblock %}

Add the following code to the atom to fix the twig exception in the navigation-list.twig file:

Adjustment of the navigation-list.twig file. 

{% block body %}
   [...]
   {% import _self as component %}
   {% block url %}
   [...]
{% endblock %}

The previously installed <sp_install_module,Cms Block Data Connector module>> creates a Zed table. During the import, the editorial contents determined from the Online CaaS are stored in this table. The CMS blocks are persisted in another table.

Since the CMS blocks do not contain placeholders, they are not published by Spryker by default. For this reason, it is necessary to overwrite the CmsBlockStorageQueryContainer and thus adapt the standard behavior of Spryker for publishing CMS blocks. The query container is overwritten by creating the class CmsBlockStorageQueryContainer.php. It is part of the zip file b2c-demo-shop-extensions-<VERSION>.zip included in the delivery and must be copied into the directory src/Pyz/Zed/CmsBlockStorage/Persistence to be created.

The integration realized with the FirstSpirit Connect module only allows FirstSpirit to create and maintain editorial content and to publish it in the form of JSON objects. The integration of these contents and the creation of the preview, however, still takes place in Spryker.

In the preview case, FirstSpirit determines the current view of a page in the storefront and displays it in ContentCreator using the Omnichannel Manager. To integrate the editorial content into the shop, Spryker imports it from the Online CaaS and persists it in its internal data system.

As both the preview and the import process are protected by authentication, a technical user must be specified in the project component of the FirstSpirit Connect module. This corresponds to a customer, who in turn is assigned to a Zed user. The assignment can be done in the menu Users Control → User via the button Assign Customers.

The integration of the contents created or maintained in FirstSpirit into the Shop takes place through Spryker. Therefore, Spryker imports the data from the Online CaaS and persists them in its data system. The transfer of the information must take place with each FirstSpirit deployment, which for this reason each time triggers a Spryker sided import command.

The command instructs the importer to import the block data stored in the Online CaaS. To do this, it uses the FirstSpirit Data Import Block CaaS Path stored in the configuration file config_default-[environment].php. Using this path, the importer accesses the CaaS aggregation that is created by the FirstSpirit deployment.

The import commands must be registered in Spryker in the getConsoleCommands. This requires the following extension to the ConsoleDependencyProvider.php file in the src/Pyz/Zed/Console directory:

Erweiterung der getConsoleCommands. 

use ESpirit\Zed\FirstSpiritDataImport\Communication\Console\FsDataImportConsole;
use ESpirit\Zed\FirstSpiritDataImport\Communication\Console\FsStoreDataImportConsole;

[...]

$commands = [
   // Default commands
   [...]

   new DataImportConsole(DataImportConsole::DEFAULT_NAME . ':' . DataImportConfig::IMPORT_TYPE_CMS_BLOCK_STORE),
   new DataImportConsole(DataImportConsole::DEFAULT_NAME . ':' . DataImportConfig::IMPORT_TYPE_CMS_BLOCK_CATEGORY_POSITION),
   new DataImportConsole(DataImportConsole::DEFAULT_NAME . ':' . DataImportConfig::IMPORT_TYPE_DISCOUNT),

   [...]

   // FirstSpirit Data importers
   new FsDataImportConsole(FsDataImportConsole::DEFAULT_NAME),
   new FsStoreDataImportConsole(FsStoreDataImportConsole::DEFAULT_NAME),
];

To import blocks for categories, the contents of the the DataImportBusinessFactory.php file in the src/Pyz/Zed/DataImport/Business directory have to be adjusted:

Extension of the DataImportBusinessFactory. 

[...]
use Pyz\Zed\DataImport\Business\Model\CmsBlock\CmsBlockWriterStep;
use Pyz\Zed\DataImport\Business\Model\CmsBlockCategoryPosition\CmsBlockCategoryPositionWriterStep;
use Pyz\Zed\DataImport\Business\Model\CmsBlockStore\CmsBlockStoreWriterStep;
[...]

   public function getDataImporterByType(DataImportConfigurationActionTransfer $dataImportConfigurationActionTransfer): ?DataImporterInterface
   {
      switch ($dataImportConfigurationActionTransfer->getDataEntity()) {
         [...]
         case DataImportConfig::IMPORT_TYPE_CMS_BLOCK_STORE:
               return $this->createCmsBlockStoreImporter($dataImportConfigurationActionTransfer);
         case DataImportConfig::IMPORT_TYPE_CMS_BLOCK_CATEGORY_POSITION:
               return $this->createCmsBlockCategoryPositionImporter($dataImportConfigurationActionTransfer);
         case DataImportConfig::IMPORT_TYPE_DISCOUNT_AMOUNT:
               return $this->createDiscountAmountImporter($dataImportConfigurationActionTransfer);
         [...]
      }
   }


   [...]

   /**
    * @param \Generated\Shared\Transfer\DataImportConfigurationActionTransfer $dataImportConfigurationActionTransfer
    *
    * @return \Spryker\Zed\DataImport\Business\Model\DataImporterInterface|\Spryker\Zed\DataImport\Business\Model\DataSet\DataSetStepBrokerAwareInterface
    */
   protected function createCmsBlockCategoryPositionImporter(DataImportConfigurationActionTransfer $dataImportConfigurationActionTransfer)
      {
      $dataImporter = $this->getCsvDataImporterFromConfig(
      $this->getConfig()->buildImporterConfigurationByDataImportConfigAction($dataImportConfigurationActionTransfer)
      );

      $dataSetStepBroker = $this->createTransactionAwareDataSetStepBroker(CmsBlockCategoryPositionWriterStep::BULK_SIZE);
      $dataSetStepBroker->addStep(new CmsBlockCategoryPositionWriterStep());
      $dataImporter->addDataSetStepBroker($dataSetStepBroker);

      return $dataImporter;
   }

   [...]

During deployment, the content maintained in FirstSpirit is retrieved from the Online CaaS using the importer. It transfers the data to Spryker and persists them in the backend in its data system. The display of the data in the live state additionally requires its transmission to Yves. The transmission of the data requires the registration of an event subscriber, several queues and a message processor.

The registration of the EventSubscriber is done with the following code to be added to the EventDependencyProvider in the directory Pyz/Zed/Event.

EventDependencyProvider. 

use ESpirit\Zed\FirstSpiritCmsDataStorage\Communication\Plugin\Event\Subscriber\FirstSpiritCmsDataStorageEventSubscriber;

[...]

class EventDependencyProvider extends SprykerEventDependencyProvider
{
   [...]

   public function getEventSubscriberCollection()
   {
      $eventSubscriberCollection = parent::getEventSubscriberCollection();

      /**
      * Storage Events
      */
      [...]
      $eventSubscriberCollection->add(new FirstSpiritCmsDataStorageEventSubscriber());

      /**
      * Search Events
      */
      [...]

      return $eventSubscriberCollection;
   }
}

Registration of the queues requires the following adaption of the RabbitMqConfig file in the src/Pyz/Client/RabbitMq directory:

RabbitMqConfig. 

<?php
namespace Pyz\Client\RabbitMq;

use ESpirit\Shared\FirstSpiritCmsDataStorage\FirstSpiritCmsDataStorageConfig;
[...]

class RabbitMqConfig extends SprykerRabbitMqConfig
{
   [...]

   protected function getPublishQueueConfiguration(): array
   {
      return [
         PublisherConfig::PUBLISH_QUEUE => [
            [...]
         ],
         [...]
         FirstSpiritCmsDataStorageConfig::PUBLISH_CMS_PAGE_DATA_CONNECTOR,
         FirstSpiritCmsDataStorageConfig::PUBLISH_CMS_BLOCK_DATA_CONNECTOR
      ];
   }

   protected function getSynchronizationQueueConfiguration(): array
   {
      return [
         [...]
         FirstSpiritCmsDataStorageConfig::CMS_PAGE_DATA_CONNECTOR_SYNC_STORAGE_QUEUE,
         FirstSpiritCmsDataStorageConfig::CMS_BLOCK_DATA_CONNECTOR_SYNC_STORAGE_QUEUE
      ];
   }

   [...]
}

The trigger plugin needs to be added to the EventBehaviorDependencyProvider file in the src/Pyz/Zed/EventBehavior directory.

EventBehaviorDependencyProvider. 

<?php

namespace Pyz\Zed\EventBehavior;

use ESpirit\Zed\FirstSpiritCmsDataStorage\Communication\Plugin\Event\FirstSpiritCmsBlockDataEventResourceQueryContainerPlugin;
use ESpirit\Zed\FirstSpiritCmsDataStorage\Communication\Plugin\Event\FirstSpiritCmsDataEventResourceQueryContainerPlugin;
[...]

class EventBehaviorDependencyProvider extends SprykerEventBehaviorDependencyProvider
{
   protected function getEventTriggerResourcePlugins()
   {
      return [
         [...]
         new FirstSpiritCmsDataEventResourceQueryContainerPlugin(),
         new FirstSpiritCmsBlockDataEventResourceQueryContainerPlugin(),
      ];
   }
}

In order to enable trigger events from the GLUE application, the dispatcher plugin needs to be added to the EventDispatcherDependencyProvider in the src/Pyz/Zed/EventDispatcher directory.

EventDispatcherDependencyProvider. 

[...]

protected function getBackendGatewayEventDispatcherPlugins(): array
{
   return [
      [...]
      new EventBehaviorEventDispatcherPlugin(),
   ];
}

The sync plugin needs to be added to the SynchronizationDependencyProvider file in the src/Pyz/Zed/Synchronization directory.

SynchronizationDependencyProvider. 

<?php

namespace Pyz\Zed\Synchronization;

use ESpirit\Zed\FirstSpiritCmsDataStorage\Communication\Plugin\Synchronization\FirstSpiritCmsBlockDataSynchronizationDataBulkPlugin;
use ESpirit\Zed\FirstSpiritCmsDataStorage\Communication\Plugin\Synchronization\FirstSpiritCmsDataSynchronizationDataBulkPlugin;
[...]

class SynchronizationDependencyProvider extends SprykerSynchronizationDependencyProvider
{
   protected function getSynchronizationDataPlugins(): array
   {
      return [
         [...]
         new FirstSpiritCmsDataSynchronizationDataBulkPlugin(),
         new FirstSpiritCmsBlockDataSynchronizationDataBulkPlugin(),
      ];
   }

   [...]
}

The registration of the event subscriber necessary for the queues requires an adjustment of the QueueDependencyProvider in the directory Pyz/Zed/Queue:

QueueDependencyProvider. 

<?php
namespace Pyz\Zed\Queue;

use ESpirit\Shared\FirstSpiritCmsDataStorage\FirstSpiritCmsDataStorageConfig;

[...]

class QueueDependencyProvider extends SprykerDependencyProvider
{
   protected function getProcessorMessagePlugins(Container $container)
   {
      return [
         [...]
         FirstSpiritCmsDataStorageConfig::PUBLISH_CMS_PAGE_DATA_CONNECTOR => new EventQueueMessageProcessorPlugin(),
         FirstSpiritCmsDataStorageConfig::PUBLISH_CMS_BLOCK_DATA_CONNECTOR => new EventQueueMessageProcessorPlugin(),
         FirstSpiritCmsDataStorageConfig::CMS_PAGE_DATA_CONNECTOR_SYNC_STORAGE_QUEUE => new SynchronizationStorageQueueMessageProcessorPlugin(),
         FirstSpiritCmsDataStorageConfig::CMS_BLOCK_DATA_CONNECTOR_SYNC_STORAGE_QUEUE => new SynchronizationStorageQueueMessageProcessorPlugin(),
      ];
   }
}

A project-specific configuration is necessary for the use of the FirstSpirit Connect module. This is done via the project component, which is already added to the supplied reference project.

To configure the project component, open the ServerManager and select Project properties → Project components.

Figure 4. Server properties - Project components

The main panel displays a list of all existing project components. Select FirstSpirit Connect for FirstSpirit Commerce OS Project Configuration and open the corresponding configuration dialog via Configure.

The dialog is divided into the tabs General, Preview, Publication, and YouTube:

General

Within the tab General, the Storefront Base URL and the Glue-API Base URL have to be specified. They have to be assigned to the FirstSpirit server to connect to Spryker and retrieve data.

It is also possible to specify user-defined values for the connection timeout and the socket timeout. If no values are specified, the default values of 60 seconds for the socket timeout and 10 seconds for the connection timeout are used for communication with the glue API.

Figure 5. Project component - General

Preview

Within the Preview tab, the login path is required first. The corresponding field contains the default value /firstspirit_login_check, which can be adjusted if necessary.

Furthermore, the login data of a technical user must be entered in this tab. This must correspond to the Customer defined during the steps to be performed on the Spryker side. In Spryker, it is used to query the storefront, which is included in the ContentCreator using the Omnichannel Manager.

Figure 6. Project component - Preview

Publication

The Publication tab contains a list of all groups and full deployment schedules available in the project. It allows the selected deployment schedule to be provided in the Actions menu in the ContentCreators for the groups selected in the tab. The Actions menu contains the Publication menu item for executing the schedule. For groups that are not allowed to execute the schedule, the entry is visible but disabled.

Within the supplied reference project, the ChiefEditors can be enabled to execute the full deployment in this way, for example.

Furthermore, the release and the delete workflow use the selected schedule if the publication of the entire project should be triggered additionally to the release or deletion of a page.

Figure 7. Project component - Publication

YouTube

The reference project provided contains a Shoppable video paragraph. It allows to display and reference products at defined times in a YouTube video. The usage of the paragraph requires a Google API Key, which has to be entered here.

In addition, one or more Channel Ids can be specified, separated by commas. As soon as the field contains an Id, the video selection will show a dropdown. This allows to reference a YouTube video from a specific channel.

Figure 8. Projekt-Komponente - YouTube

To prepare the ContentCreator, a web component is needed, which is already added to the reference project. By default it is installed globally in the ServerManager in the area Server Properties → Web applications. In this case, all installation or configuration steps required for the web component have already been performed by the e-Spirit AG.

Alternatively, you may install the web component in the Project properties. Only in this case it still needs to be installed on an active web server. Therefore, open the ServerManager and select Project properties → Web components.

Within the main panel there are several tabs, each with a list of existing web components. This list contains the FirstSpirit Connect for Spryker Commerce OS Web App for the Preview and ContentCreator. The ContentCreator tab also contains the FirstSpirit ThirdPartyPreview WebApp and optionally the BasicWorkflows_ContentCreator_Library (see figure Web components in the project properties). The web component of the BasicWorkflows is only required when using the workflows.

In both tabs, select a web server via the selection box and start the installation with the Install button. After the successful installation, a dialog opens, in which the activation of the web server is to be confirmed.

For detailed information about adding web components, see the FirstSpirit Documentation for Administrators.