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.

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 data fragments 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 fragment example
{
   "fsType" : "FS_DATASET",
   "name" : "st_button_link",
   "value" : {
      "fsType" : "DatasetReference",
      "target" : {
         "entityType" : "product",
         "fsType" : "Dataset",
         "identifier" : "fae0687b-c365-4851-919e-566f4d587201",
         "schema" : "products"
      }
   }
}

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

JSON fragment 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 fragment 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 fragment 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.

In addition to the automatic synchronization after editorial actions, it is possible to execute a manual full synchronization of the data state via schedules. After the installation of the CaaS Connect module, 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.

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.