1. Introduction

Content as a Service provides the editorial data of FirstSpirit via a uniform JSON-based data format that can be consumed by any endpoint. The data is updated transparently when it is changed or released in the FirstSpirit editorial system. With a cloud installation of the Content as a Service platform the data can be efficiently accessed worldwide. In FirstSpirit, only the form configurations and the data maintained by the editorial system are accessed. Templating in FirstSpirit is completely eliminated and is shifted to the front end or front end services (for more information, see FSXA documentation).

The FirstSpirit developer can thus concentrate completely on modeling the domain-oriented objects and creating the corresponding input components. The following section describes the conventions for data format and URLs, as well as the optimal delivery of content for different consumers.

In the remainder of this document the abbreviation CaaS will be used instead of Content as a Service.

2. Introduction FirstSpirit module

The CaaS Connect module is the link between FirstSpirit editorial environment and the CaaS platform that acts as the content delivery. This connection is largely invisible to the editorial team and only requires attention in the event of a technical problem. The editors can always view the current state of data directly via the CaaS platform. As soon as a change has been made in FirstSpirit, the synchronization is triggered in the background, and the database immediately reflects the change.

There are traditional and fragment projects in FirstSpirit. Technical pages - and thus also the elements that are transferred to the CaaS platform - correspond to the page references in traditional projects and to the fragments in fragment projects. For the sake of simplicity we speak of pages in both cases. The CaaS Connect module automatically distinguishes between traditional and fragment projects.

2.1. CaaS URLs

The smallest addressable element in a CaaS project is a page. The module creates a document in the CaaS platform for each page and language for both the preview and release state. In addition to pages, media are also synchronized. Pictures are multiplied with all project languages and resolutions, while other media are transferred for all languages. Each of these elements can be identified and referenced with a unique URL.

2.1.1. URL schema

The CaaS URL for an element consists of four parts: tenant id, project identifier, collection identifier, and document identifier. The tenant id is the maintained name or abbreviation of the tenant. The project identifier is the GID of the FirstSpirit project. The collection identifier allows you to differentiate between release and preview state. For page documents and metadata documents of media it is either 'release.content' or 'preview.content'. The document identifier consists of the FirstSpirit GID of the page as well as language and resolution. Together with the base URL of the CaaS endpoint, this results in the fully qualified URL of an item.

The URL scheme for binary data of media differs slightly from the listed URL scheme and is therefore described separately in chapter Media URLs.

CaaS URLs for project settings do not use their FirstSpirit GID as document identifier but instead use the identifier projectsettings.

Example:

The tenant id is defaultTenant.

The FirstSpirit project GID is e54cb80e-1f9c-4e8d-84b8-022f473202eb.

The fully qualified CaaS URL of a sample page with the GID f3628468-ee53-453f-a26f-a12edcd1f1f0 in preview and for the English language looks like this

CaaS endpoint: http://localhost:8080

CaaS URL: defaultTenant/e54cb80e-1f9c-4e8d-84b8-022f473202eb.preview.files/f6910b22-6ae8-4ce1-af45-c7b364b3117a.en_GB

For easier access the collection URLs of the project are shown in the configuration dialog of the project component.

2.1.2. Media URLs

For each medium, two types of documents are generated, which can be queried in the CaaS platform: Metadata and binary data.

Metadata document
For a given medium, exactly one metadata document is created for each project language (regardless of whether the medium is language-dependent or not). The metadata document will always be stored in the CaaS platform with a generated CaaS URL. It contains the FirstSpirit metadata of the medium, as well as a list of resolutions and associated resolution-specific URLs. The URL for the binary data of a specific medium for a specific language - and possibly a specific resolution - must be taken from this metadata document.

In case the CaaS platform is used to provide the media binary data, the same URL schema of pages or metadata documents is used. The only difference is the collection identifier where either 'release.files' or 'preview.files' is used for the release or preview state.

{
    "_id": "f6910b22-6ae8-4ce1-af45-c7b364b3117a.en_GB",
    "fsType": "Media",
    "name": "audio_video_connector",
    "displayName": "Connecting cable for audio and video",
    "identifier": "f6910b22-6ae8-4ce1-af45-c7b364b3117a",
    "uid": "audio_video_connector",
    "uidType": "MEDIASTORE_LEAF",
    "fileName": "audio-video-connector",
    "languageDependent": false,
    "mediaType": "PICTURE",
    "description": "Within this demo project \"Mithras Energy\"...",
    "resolutionsMetaData": {
        "110x73": {
            "fileSize": 3885,
            "extension": "jpg",
            "mimeType": "image/jpeg",
            "width": 110,
            "height": 73,
            "url": "http://localhost:8080/defaultTenant/e54cb80e-1f9c-4e8d-84b8-022f473202eb.preview.files/f6910b22-6ae8-4ce1-af45-c7b364b3117a.110x73/binary"
        },
        "ORIGINAL": {
            "fileSize": 69597,
            "extension": "jpg",
            "mimeType": "image/jpeg",
            "width": 693,
            "height": 462,
            "url": "http://localhost:8080/defaultTenant/e54cb80e-1f9c-4e8d-84b8-022f473202eb.preview.files/f6910b22-6ae8-4ce1-af45-c7b364b3117a.ORIGINAL/binary"
        }
    },
    "metaFormData": {},
    "locale": {
        "identifier": "EN",
        "country": "GB",
        "language": "en"
    },
    "_etag": {
        "$oid": "5f23f63dc9977b5e90c25dc2"
    }
}

The administrator can customize the media deployment configuration so that binary data from media URLs cannot be retrieved using CaaS URLs. Therefore it’s very important that binary data URLs for media are always queried via the metadata document and are never generated by string concatenation.

2.2. Data format

Unlike traditional FirstSpirit projects and earlier module versions, CaaS version 3 or later does not support either output channels or FirstSpirit templating. Instead, a JSON document is generated for each page of the project, based on the toJson standard of FirstSpirit. An adaptation of the format is not possible. This restriction allows to deliver a complete, standardized data format via CaaS platform, so that all consuming endpoints can work with the same data format. Since the standard data format is very comprehensive, the platform offers filtering and aggregation capabilities to reduce data volumes for mobile end points, for example. For more information about CaaS platform, see platform documentation.

Since the CaaS URLs derive the document identifier from a unique FirstSpirit ID (among other things), it is necessary to use a filter when querying a document using its name. To query a CaaS page (a FirstSpirit page reference) with the name services a GET request is executed with the following URL:

For more information on queries for the CaaS platform, see platform documentation.

2.2.1. CaaS JSON format

The standard JSON format of FirstSpirit serves as the basis for the CaaS JSON format and is extended by the CaaS Connect module both with CaaS specific JSON format configuration, as well as with some attributes that simplify its usage. The CaaS specific format configurations include reducing the output of datasets to references, the indirect referencing of records of a content projection, and enabling the output of the FirstSpirit metadata.

Dataset URLs: FirstSpirit does not address individual datasets and instead works with content projections or selects and embeds datasets in pages. In CaaS projects, individual datasets are identified by a unique URL and can be queried with it. Therefore, pages do not embed datasets, but contain references to the stored datasets in the CaaS platform.

JSON snippet example
{
   "fsType" : "FS_DATASET",
   "name" : "st_button_link",
   "value" : {
      "fsType" : "DatasetReference",
      "target" : {
         "entityType" : "product",
         "fsType" : "Dataset",
         "identifier" : "fae0687b-c365-4851-919e-566f4d587201",
         "schema" : "products"
      }
   }
}

Dataset routes: The route attribute contains the relative route of a dataset. This route is only calculated if a preview page has been selected for the underlying table template. The preview page should contain a content-projection for the rendered table, and the setting "number of entries per page" should be set to "1" (see Content Projection). This is the only way different datasets will have different routes.

JSON snippet example
{
    "route" : "/Company/Locations/Locations.html"
}

Fragment metadata: The attribute fragmentMetaData contains the attributes id (fragment ID) and type (fragment type).

JSON snippet example
{
    "fragmentMetaData": {
        "id": "378d5ec9_58f1_4dec_83bc_724dc93de5c2",
        "type": "news"
    }
}

Locale: The locale attribute contains the attributes identifier (abbreviation of the language), country (associated country) and language (associated language).

JSON snippet example
{
    "locale": {
        "identifier": "EN",
        "country": "GB",
        "language": "en"
    }
}

Media URL attributes in media metadata: The media metadata provided by FirstSpirit (see Media URLs) usually only includes the URL to a medium that was generated by a URL factory.

Content2Section: The JSON data of content projections or its sections contain references to its records when using the standard JSON configuration of FirstSpirit. However, the CaaS Connect module uses a specific configuration for the JSON format so that the records are not referenced directly, but indirectly via a query object. For this purpose, the query object contains identifiable attributes of the content projection.

JSON snippet example
{
   "displayName" : "blog",
   "entityType" : "blog",
   "filterParams" : {},
   "fsType" : "Content2Section",
   "maxPageCount" : 0,
   "name" : "blog",
   "ordering" : [
      {
         "ascending" : false,
         "attribute" : "fs_id"
      }
   ],
   "query" : null,
   "recordCountPerPage" : 1,
   "schema" : "global",
   "template" : {
      "displayName" : "Blog entry",
      "fsType" : "TableTemplate",
      "identifier" : "e657e0f0-0fd3-456f-b5ab-560a879ca748",
      "name" : "Blog entry",
      "uid" : "global.blog",
      "uidType" : "TEMPLATESTORE_SCHEMA"
   }
}

2.3. Preview and release state

An essential distinction between release and preview data states is made by both FirstSpirit and the CaaS Connect module. The platform manages both states of data, which are distinguishable by different CaaS URLs (see URL schema). A synchronization of both data states is always based on certain actions that the editors perform in FirstSpirit. Release actions are the only actions that update the release state, all other changes only affect the preview state.

2.4. Manual data reconciliation

For certain scenarios, it may be necessary to perform a full reconciliation between FirstSpirit and CaaS:

  • Populating the CaaS with existing project data to start a project.

  • Reconciling data in the event of an error to manually restore data consistency between systems.

This manual full reconciliation of the data is enabled via schedules, which are automatically created with the installation of the CaaS Connect module. After module installation, the project contains two schedules Caas Connect Release Generation and Caas Connect Preview Generation, which can perform a full synchronization for the release or preview state. These schedules are automatically updated when the CaaS Connect module is updated.

schedules
Figure 1. configuration dialog of the project component of the CaaS module

Changes to the configuration of these schedules are not persistent, as the schedules are reset to their original state by the automatic update. If the configuration of these schedules needs to be changed, these changes have to be applied to a copy of the respective schedule.

2.4.1. Overwrite the complete data set

If changes in the FirstSpirit project are expected to be visible in the CaaS data but instead are not reflected in the CaaS, the schedules can be used to overwrite the full data set of the CaaS. For this purpose it is necessary to create a copy of the respective schedule and to adjust its configuration so that the replicationMode parameter of the script task contains the value FULL (in contrast to the default DELTA). Running this task will then overwrite the complete data set in CaaS.

full replication

2.4.2. Hidden sections

In FirstSpirit it is possible to hide sections. The data of these sections is treated differently depending on the preview or release state.

Sections hidden in FirstSpirit are always part of the preview data, but never included in the release data. The preview data also contains an additional JSON attribute named displayed per section. This indicates whether the section is displayed or hidden and thus whether it is transferred to the CaaS as part of the release data.

Accordingly, the following possibilities for sections arise:

Visibility Part of preview state Value of displayed in preview state Part of release state

Displayed

Yes

true

Yes

Hidden

Yes

false

No

Please note that the displayed attribute is only present in the preview state. In the release state, only visible sections are present and therefore this attribute is not used there.

2.5. Push notifications (change streams)

It is often convenient to be notified about changes in the CaaS platform. For this purpose the CaaS platform offers change streams. This feature allows a websocket connection to be established to the CaaS platform, through which events about the various changes are published.

By default, a crud change stream is provided for each collection created by CaaS Connect. It publishes all insert, replace, update and delete events. It is accessible at <collectionUrl>/_streams/crud. The exact definition of the change streams can be accessed at any time in the collection metadata.

More information on using change streams is available in the CaaS platform documentation.

The CaaS 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.

4. Help

The Technical Support of the e-Spirit AG 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.

5. 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.