1. Introduction

One use case for the FirstSpirit CaaS is to provide content for web pages that draw their content from several different sources. This can be single-page applications, for example: Web pages that consist of only one page (an HTML document) and dynamically reload their content. These pages are often based on a tile or card design, i.e. content on different topics is displayed in specific content areas (slots) next to or below each other on a web page. These can be, for example, teasers, product images or videos that may lead to detail pages. However, the content can just as well be distributed classically on several web pages.

In order to be able to display and use such content, which is not generated directly from FirstSpirit but comes from external applications ("apps"), in FirstSpirit, the Omnichannel Manager (TPP) can be used. In this case, the contents of the external app will be displayed in FirstSpirit ContentCreator. Content that is maintained in FirstSpirit (editorial content) can also be displayed and edited there.

Unlike classic FirstSpirit projects, individual FirstSpirit content can also be edited and released independently (by different editors) (depending on the project design), although they are displayed on one (HTML) page. This means several editors can then, for example, edit the central homepage of an online store in parallel and publish individual elements independently of each other.

Advantages:

  • Display and editing of content from multiple, different sources (including the FirstSpirit CaaS)

  • Dynamic, partial reloading of areas where content has changed instead of page reload for better performance

  • Parallel editing of content areas of a (HTML) page

The functionality is provided by FirstSpirit module: fs-tpp-[version].fsm.

2. Architecture

The TPP functionality is provided by a module. In addition, configurations are required in the FirstSpirit ServerManager as well as in the FirstSpirit project and in the external app (see chapter Module Installation.).

A typical architecture includes the following components:

  • FirstSpirit server with FirstSpirit project (TPP)

  • FirstSpirit CaaS

  • external app

image9
Figure 1. Architecture

The exchange of data between components is done in JSON format. This format can be processed by most external apps.

External App ↔ FirstSpirit project

Using the TPP functionality, the content of the desired external app is displayed in the FirstSpirit ContentCreator (in an iFrame). The cross-domain communication is implemented using postMessage.

FirstSpirit project ↔ FirstSpirit CaaS

The content is exchanged between the FirstSpirit project and the FirstSpirit CaaS in the form of JSON objects. To do this, the content must be defined in a corresponding (CaaS) output channel. The JSON attribute previewId is used to identify FirstSpirit elements in this process. This attribute is expected as a parameter in most API functions. After editing the FirstSpirit contents, these changes are automatically transferred from FirstSpirit to the CaaS.

FirstSpirit CaaS ↔ External App

The JSON data previously transferred from the FirstSpirit project to the FirstSpirit CaaS can in turn be accessed by the external app, via HTTP GET request.

An exemplary flow within the app can then look like the following, for example:

  1. Content in JSON format is requested via REST calls to the CaaS.

  2. The content is converted into HTML elements.

  3. The attribute _id for top-level objects (page references, data sets, media) or identifier for inner objects (e.g. the page and the paragraphs of page references) from the JSON is converted to the data-preview-id HTML attribute.

  4. The HTML elements are inserted into the rendered page at the designated places.

  5. The front-end library (snap.js) decorates the element on mouse-over with the edit operations.

  6. If the editor now clicks on the Edit icon, the TPP API opens the edit dialog.

  7. If the editor confirms his changes, an event is fired with the updated JSON as payload. With this data, steps 2 through 5 must be gone through again to update the rendered content.

3. Technical Requirements

3.1. FirstSpirit server

The use of the functionality Omnichannel Manager requires a FirstSpirit server with a version from 5.2R16 and Java 8.

3.2. External App

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

  • The app must be allowed to run in an iFrame (see MDN/X-Frame-Options).

  • Protocols for the ContentCreator and the external app: +. If the protocols of the ContentCreator and the external app do not match (http:‌//…, https:‌//…), this will result in a warning message on the JavaScript console. This can be ignored. To prevent the warning message, the external app should be run under the same protocol as the ContentCreator. Alternatively, absolute links starting with // can be used instead of http[s]://.

3.3. FirstSpirit CaaS

Within the Omnichannel Manager context, the role of the FirstSpirit CaaS is to provide non-shared content to the external app. To do this, a project component of the CaaS module must be added to the project in use and has to be configured properly. Furthermore, the creation of another CaaS instance on a second host is required. The necessary steps for this are described in the Documentation of Content as a Service description.

4. Module Installation

The module must be added to the FirstSpirit server using the supplied fs-tpp-api-[version].fsm file. To do this, open the ServerManager and select the Server Settings  Module section.

ServerManager_Module_initia.png
Figure 2. Modules

The main panel shows a list of all modules installed on the FirstSpirit server. After clicking Install, select the fs-tpp-api-[version].fsm file and confirm the selection with Open.

After the successful installation, the folder FirstSpirit ThirdPartyPreview has been added to the list.

It contains the following components:

  • FirstSpirit ThirdPartyPreview WebApp

  • TppApi

  • TppClientResourcePlugin

ServerManager_Module.png
Figure 3. components of the TPP module

The component FirstSpirit ThirdPartyPreview WebApp must be enabled as a web application for the ContentCreator, either for all projects of the FirstSpirit server (Server Settings  Web-Applications):

ServerManager_Web-Applikati.png
Figure 4. Server Settings

or for individual projects (Project Settings  Web Components):

ServerManager_project_webApplication.png
Figure 5. Project Settings

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

5. FirstSpirit-side configuration

5.1. Configuration of the Preview URL

The URL of the external web application to be used for previewing in FirstSpirit is entered in the External preview URL text box in the FirstSpirit ServerManager  Project Settings  ContentCreator section:

SM_FAPS_PreviewURL.png
Figure 6. Configuration of preview URL

The preview application can then be used in the ContentCreator. If the linked application is prepared accordingly, the content displayed in the preview area can then be edited by the editor using the functions of the ContentCreator, and the editor can create and delete content (for restrictions, see chapter Editing interface (ContentCreator).).

The URL specified here must also contain the protocol of the external web application.

If the text field is empty (URL assigned: http:‌//…), the ContentCreators internal preview is used.

For more information, see FirstSpirit Documentation for Administrators.

5.2. Template code

To identify a FirstSpirit element in a particular project language, the previewId() function is used, for the reason of communication between the single page application and the FirstSpirit ContentCreator.

Example 
$CMS_VALUE(previewId())$

The function can be given an optional parameter element which should be a FirstSpirit-Objekt (of type IDProvider), e.g. a global page out of the Global Content (GCA) (#global.gca("…​")) or the current page (#global.page).

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

Cf. also the function editorId(), in the FirstSpirit Online Dokumentation.

The function must be inserted into the desired output channel of the template in question. In the app this ID can then be accessed via the API (see chapter Configuration of the Application).

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

The previewId() function returns information only down to the level of paragraphs. For example, Card objects returned by FS_CATALOG will not receive 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 they are included in a next release. For information on developing and configuring workflows in FirstSpirit, see FirstSpirit Online Dokumentation.

To be able to delete content in TPP, a suitable deletion workflow must exist in the project. This can be the Delete workflow developed by Crownpeak (contained in the BasicWorkflows, basicworkflows.fsm, available from FirstSpirit Technical Support).

In order for this to be used when the delete icon is pressed in the ContentCreator deleteicon.png, it must be set in the Project Settings (FirstSpirit ServerManager  Project Settings  options) under workflow for deleting elements. For more information, see also FirstSpirit Documentation for Administrators.

In addition, custom workflows can also be used.

Workflows can refer to only structure management pages or content management pages in FirstSpirit. See also FirstSpirit Documentation for Administrators.

5.4. Custom actions/scripts/plugins.

Even by default, some actions (e.g. create and edit page, upload and manage media) are provided by TPP. Beyond that, specific actions offered by an external application that should be mapped to FirstSpirit can be implemented via project-specific scripts and plugins.

In order to support the editor or other users in their work in the best way possible, the terminology of the external application can usually be adopted for this purpose. For example, depending on the context/framework, a script for creating can then be called:

  • Create pages

  • Create content

  • Generate campaign

For script and plugin development, see FirstSpirit Online Dokumentation, chapters Scripting and Plugin Development.

5.5. Media

Media represent a special case when requesting data from the FirstSpirit CaaS: To get media from the CaaS in the form of binary data, the expression /binary must be appended to the URL returned by the CaaS. In the HTML template that renders the associated preview in FirstSpirit, this URL is then inserted into the img tag as an src attribute, e.g.

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

However, that works only if a CaaS proxy is used. The proxy must be configured to forward the requests to the CaaS and additionally append the API key to the request header. The header must look like this:

Authorization:apikey="{apikey}"

A minimal example implementation in node.js is available on GitHub.

For more information on using media with the CaaS, see the CaaS documentation.

6. Configuration of the Application

By default, content from custom apps can be configured following the steps described in Module Installation and FirstSpirit-side configuration, can already be represented in the FirstSpirit ContentCreator using the Omnichannel Manager functionality. In order for the app to be able to address the functionalities of the ContentCreator so that it can edit the contents, adaptations to the code of the app are required. to the code of the app are required. For this purpose, a special API must be used (see below). This API allows the editor to maintain the content provided in the app:

  • Create content

  • Change content

  • Remove content

  • Start and advance workflows

The API provides the functions via edit icons in the context of the application. To display the area to which the functions refer, a frame is also drawn around the respective HTML element (at mouseOver). The functions can easily be extended project-specific.

editiericons.png
Figure 7. Example for edit icons

Further functions are provided by the menus of the ContentCreator.

6.1. API

To use the TPP API in a custom app, a JavaScript file must be included in the frontend code. This file is a part of the delivered module (zip format). It can also be included via NPM: https://www.npmjs.com/package/fs-tpp-api

A documentation of the API with a description of the integration as well as code examples can be found at https://docs.e-spirit.com/tpp/snap.

The included Demo application (snap-shop) shows an example of how to use the API using the most common use cases.

7. Editing interface (ContentCreator).

The FirstSpirit ContentCreator is used to edit content. Documentation for editors can be found in the FirstSpirit Manual for Editors (ContentCreator) at https://docs.e-spirit.com/odfs/documentation/editors and is directly accessible from the ContentCreator via the (?) button.

7.1. Restrictions

Content from external sources can only be controlled and managed by FirstSpirit to a limited extent. Due to this technical condition, some functions of ContentCreator are not available when used with the Omnichannel Manager by default. This includes amongst others drag-and-drop of files from the desktop into the application.

Menu buttons and icons whose functionality is not available in TPP mode are hidden. Missing functionality can be realized via custom implementation (see also chapter Custom actions/scripts/plugins.). For possibilities and concrete examples see also FirstSpirit Online Dokumentation

8. Release Notes

For each release of a new version of TPP there are release notes with information about the included changes.

9. Glossary

Term Meaning

EAP

Early Access Program

Software version with not yet released changes (features and bug fixes). EAP versions meet the same stability criteria as released versions, but in rare cases there may still be changes to the not yet released functions.

SPA

Single Page Application

A SPA is characterized by the fact that it does not require page reloads, which is realized through the use of JavaScript.

NPM

Node Package Manager

A packet manager for the JavaScript runtime environment Node.js that also provides the frontend API of the Omnichannel Manager.

The Omnichannel Manager module is a product of Crownpeak Technology GmbH, Dortmund, Germany.

For the use of the module only the license agreed with Crownpeak Technology GmbH applies to the user.

Details about possibly foreign software products not produced by Crownpeak Technology GmbH, their own licenses and, if applicable, update information, can be found in the file 'THIRD-PARTY.txt', which is delivered with the module.

11. Help

The Technical Support of the Crownpeak Technology GmbH provides expert technical support covering any topic related to the FirstSpirit™ product. You can get and find more help concerning relevant topics in our community.

12. Disclaimer

This document is provided for information purposes only. Crownpeak Technology GmbH 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. Crownpeak Technology GmbH 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.