Omnichannel Manager

e-Spirit AG

2020-04-01
Table of Contents

1. Introduction

One of the use cases for FirstSpirit CaaS is the provision of content for websites that obtain their content from several different sources. Among the examples of these websites are Single Page Applications: websites that only consist of one page (an HTML document) and reload their content dynamically. Pages of this kind are often based on a tile or card design, which means that items of content on different subjects are shown next to one another or below one another in specific content areas (slots) on a website. These slots may contain teasers, product images, or videos (potentially leading to detail pages), to name a few examples. However, content may also be distributed across multiple pages; this is a more conventional approach.

Omnichannel Manager (TPP) enables content of this kind to be displayed and used in FirstSpirit despite it originating from external applications (apps) rather than being generated directly from FirstSpirit. In this case, the content from the external app is displayed in FirstSpirit ContentCreator. Content that is maintained in FirstSpirit (editorial content) can also be displayed and edited there.

In contrast to conventional FirstSpirit projects, individual items of FirstSpirit content can (depending on the project design) be edited and released independently of each other (by different editors), even if they are displayed on a (HTML) page. This means that multiple editors can then edit the central homepage of an online shop in parallel, for example, and publish individual elements independently of one another.

Advantages:

  • Displaying and editing of content from several different sources (including FirstSpirit CaaS)
  • Dynamic partial reloading of areas in which content has changed instead of page reloading, enabling improved performance
  • Parallel editing of content areas on a (HTML) page

The function is provided in the form of a FirstSpirit module: fs-tpp-[Version].fsm.

2. Architecture

The TPP function is provided in the form of a module. Configurations also need to be made in the FirstSpirit ServerManager, the FirstSpirit project, and the external app (see the chapter entitled Module installation ff.).

A typical architecture contains the following components:

  • FirstSpirit Server with FirstSpirit project (TPP)
  • FirstSpirit CaaS
  • External app
Architecture
Figure 1. Architecture


Data is exchanged between the components in JSON format. This is a format that most external apps are able to process.

External app FirstSpirit project
The TPP function is used to display the content of the required external app in FirstSpirit ContentCreator (in an iFrame). postMessage enables cross-domain communication to take place.
FirstSpirit project FirstSpirit CaaS
The content is exchanged between the FirstSpirit project and FirstSpirit CaaS in the form of JSON objects. For this purpose, the content must be defined in a corresponding (CaaS) presentation channel. The JSON attribute previewId is used to identify FirstSpirit elements. This attribute is expected as a parameter in most API functions. Once the FirstSpirit content has been edited, the changes are automatically transferred from FirstSpirit to CaaS.
FirstSpirit CaaS external app

The external app is then able to access the JSON data that was previously transferred from the FirstSpirit project to FirstSpirit CaaS. It does so using an HTTP GET request.

This is an example of how a workflow might take place within the app:

  1. REST calls to CaaS request content in JSON format.
  2. The content is converted into HTML elements.
  3. The previewId attribute from the JSON is transferred to the data-preview-id HTML attribute.
  4. The HTML elements are inserted in the locations provided for them on the page being displayed.
  5. The front-end lib (snap.js) decorates the element for mouse-over with the edit opeartions.
  6. If the editor then clicks on the Edit icon, the TPP API opens the editing dialog.
  7. If the editor confirms the changes, the event is fired with the updated JSON as the payload. Steps 2 to 5 must be run with this data again in order to update the content being displayed.

3. Technical requirements

3.1. FirstSpirit Server

The Omnichannel Manager function requires FirstSpirit Server version 5.2R16 or higher and Java 8.

3.2. External app

The external app must meet the following requirements in order for it to be used successfully with Omnichannel Manager:

  • It must be possible to run the app in an iFrame (see MDN/X frame options).
  • Protocols for ContentCreator and the external app:
    If the ContentCreator protocol and the external app protocol are not the same (http://, https://), the JavaScript console will issue a warning message. This can be ignored. To suppress the warning message, the external app should be operated under the same protocol as ContentCreator. Alternatively, it is possible to use absolute links that begin with // instead of http[s]://.

3.3. FirstSpirit CaaS

In the Omnichannel Manager context, FirstSpirit CaaS has the task of providing unreleased content for the external app. This requires a project component from the CaaS module to be added to the project being used; the component must then be configured. It is also necessary to create another CaaS instance on a second host. The steps required to do this are described in the documentation for Content as a Service.

4. Module installation

The module needs to be added to the FirstSpirit Server using the fs-ttp-[version].fsm file supplied. To do this, open the ServerManager and select Server propertiesModules.

Modules
Figure 2. Modules


The main panel contains a list of all the modules installed on the FirstSpirit Server. After clicking Install, select the fs-ttp-[version].fsm file and click Open to confirm your selection.

After successful installation, a FirstSpirit ThirdPartyPreview folder is added to the list.

It contains the following components:

  • FirstSpirit ThirdPartyPreview WebApp
  • TppApi
  • TppClientResourcePlugin
TPP module components
Figure 3. TPP module components


The FirstSpirit ThirdPartyPreview WebApp component must be activated as a web application for ContentCreator, either for all FirstSpirit Server projects (Server propertiesWeb applications):

Server properties
Figure 4. Server properties


or for individual projects (Project propertiesWeb components):

Project properties
Figure 5. Project properties


For more information on installing modules and configuring web applications or web components, see the FirstSpirit Documentation for Administrators; Modules, Web applications, and Web components pages.

5. Configuration on the FirstSpirit side

5.1. Configuring the preview URL

The external web application URL to be used for the preview in FirstSpirit is entered in the External Preview URL text field in the FirstSpirit ServerManagerProject propertiesContentCreator area:

Configuring the preview URL
Figure 6. Configuring the preview URL


The preview application can then be used in ContentCreator. If the linked application has been suitably prepared, the editor can then edit the content displayed in the preview area with the functions of ContentCreator, and can create and delete content (for information on restrictions, see the chapter entitled Editing interface (ContentCreator)).

The URL specified at this point must also contain the protocol of the external web application.

If the text field is empty (specify URL: http://), the internal ContentCreator preview function is used.

More information is available in the FirstSpirit Documentation for Administrators.

5.2. Template code

The previewId() function is used to identify a FirstSpirit element in a certain project language. It is used for communication between the Single Page Application and FirstSpirit ContentCreator.

Example. 

$CMS_VALUE(previewId())$

The function can be given the optional element parameter. This parameter can be used to transfer a FirstSpirit object (of type IDProvider); for example, a global page from the Global content area (GCA) (#global.gca("…​")), or the current page (#global.page).

Example. 

$CMS_VALUE(previewId(element:#global.page))$

See also the editorId() function in the FirstSpirit Online Documentation.

The function must be inserted in the required presentation channel of the relevant template. In the app, this ID can then be accessed via API (see the chapter entitled Configuring the application).

Example for JSON. 

{
   "previewId": "$CMS_VALUE(previewId())$",
   "highlight": $CMS_VALUE(pt_highlight)$,
   "headline": "$CMS_VALUE(pt_headline)$,
   "Text": "$CMS_VALUE(pt_text.toString.toJSON)$"
}

The previewId() function only provides information up to section level. Card objects returned by FS_CATALOG, for example, do not contain any corresponding information.

5.3. Workflows

In principle, workflows can be used in TPP mode. For example, a release workflow can be used to release new content and changes to existing content so that these are taken into account the next time publication takes place. For information on developing and configuring workflows in FirstSpirit, see FirstSpirit Online Documentation.

Deleting content in TPP requires a suitable delete workflow to be present in the project. This may take the form of the Delete workflow developed by e-Spirit (found in BasicWorkflows, basicworkflows.fsm, available from FirstSpirit Technical Support).

To enable this workflow to be used when the delete icon is pressed in ContentCreator , it must be selected in Workflow for deleting elements in the project properties (FirstSpirit ServerManagerProject propertiesOptions). For more information, see the FirstSpirit Documentation for Administrators.

It is also possible to use customer-specific workflows.

In FirstSpirit, workflows can only relate to Site Store or Page Store pages. See also the FirstSpirit Documentation for Administrators.

5.4. Customer-specific actions/scripts/plug-ins

There is a wide range of external applications that can be used with FirstSpirit TPP, as well as an extensive variety of processed data and options for editing this data.

Some actions (e.g., insert and edit new page, upload and manage media) are supported by TPP as standard. Other actions that are provided by an external application and are to be reproduced in FirstSpirit can be implemented using project-specific scripts and plug-ins.

To help the editor or other users with their work, it is usually possible to transfer the wording used by the external application as well. For example, a creation script may be worded as follows, depending on the framework/context:

  • Insert new pages
  • Create content
  • Generate campaign

For information on developing scripts and plug-ins, see the FirstSpirit Online Documentation, Scripting and Plug-in development chapters.

5.5. Media

Media represent a special case when it comes to requirements for data from FirstSpirit CaaS: To receive a medium from CaaS in the form of binary data, the URL returned by CaaS must have the expression /binary appended to it. In the HTML template that renders the associated preview in FirstSpirit, this URL is then inserted into the img tag as an src attribute. For example:

<img src='http://Servername:Port/Projectname/assets.files/ImageId/binary'>

However, this only works if a CaaS proxy is being used. The proxy must be configured so that it forwards requests to CaaS and appends the API key to the request header. The header must appear as follows in this case:

Authorization:apikey="{apikey}"

A basic example implementation in node.js can be found at GitHub.

For more information on using media with CaaS, please refer to the CaaS documentation.

6. Configuring the application

Content from customer-specific apps can be displayed in FirstSpirit ContentCreator as standard using the Omnichannel Manager function. This is carried out by following the steps in the chapters entitled Module installation and Configuration on the FirstSpirit side. To ensure the app is able to address the ContentCreator functions so that content can also be edited, some adjustments need to be made to the app code. A special API is required for this (see below). This API enables editors to edit the content made available in the app:

  • Creation of content
  • Modification of content
  • Deletion of content
  • Start and advance workflows

In the context of the application, the API provides the functions via editing icons. To display the area to which the functions apply, a frame is drawn around the corresponding HTML element (when mousing over). The functions can be expanded easily to meet project-specific requirements.

Example editing icons
Figure 7. Example editing icons


Further functions are provided in the menus in ContentCreator.

6.1. API

In order for it to be possible to use the TPP API in a customer-specific app, a JavaScript file must be embedded in the front-end code. This file is included with the module supplied (zip format). It can also be embedded via NPM: https://www.npmjs.com/package/fs-tpp-api

Documentation for the API including a description of the embedding process and example codes is available at https://docs.e-spirit.com/tpp/snap or https://docs.e-spirit.com/tpp/fs-tpp-api .

The demo application(snap-shop) included in the scope of supply shows examples of how to use the API based on the most common use cases.

7. Editing interface (ContentCreator)

FirstSpirit ContentCreator is used to edit content. Documentation for editors can be found in the FirstSpirit Handbook for Editors (ContentCreator) at https://docs.e-spirit.com/odfs/documentation/editors. It can also be accessed directly in the ContentCreator via the (?) button.

7.1. Restrictions

FirstSpirit is only able to check and control content from external sources to a limited extent. These technical circumstances mean that some of the ContentCreator functions are not available as standard when Omnichannel Manager is being used. These include, for example, dragging and dropping files from the desktop to the application.

Menu buttons and icons whose functions are not available in TPP mode are hidden. Any missing functions can be provided using customer-specific implementations (see also the chapter entitled Customer-specific actions/scripts/plug-ins). For information on the options that are available and for concrete examples, see the FirstSpirit Online Documentation

8. Release notes

Every time a new version of TPP is deployed, it is accompanied by version information detailing the changes that have been made.

9. Glossary

TermDefinition

EAP

Early Access Program

Software version with unreleased changes (features and bug fixes). EAP versions meet the same stability criteria as released versions. However, in a very small number of cases, further changes may be made to as yet unreleased functions prior to version release.

SPA

Single Page Application

A defining feature of an SPA is that it is able to run without page reloads, something that is possible through the use of JavaScript.

NPM

Node Package Manager

A package manager for the Node.js JavaScript runtime environment via which the front-end API for Omnichannel Manager is also made available.

10. Legal notices

The Omnichannel Manager module is a product of e-Spirit AG, Dortmund, Germany.

Only a license agreed upon with e-Spirit AG is valid with respect to the user for using the module.

Details regarding any third-party software products in use but not created by e-Spirit AG, as well as the third-party licenses and, if applicable, update information can be found in the file THIRD-PARTY.txt included with the module.

11. Disclaimer

This document is provided for information purposes only. e-Spirit may change the contents hereof without notice. This document is not warranted to be error-free, nor subject to any other warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or fitness for a particular purpose. e-Spirit specifically disclaims any liability with respect to this document and no contractual obligations are formed either directly or indirectly by this document. The technologies, functionality, services, and processes described herein are subject to change without notice.