1. Introduction

The CaaS Connect module connects the FirstSpirit editorial environment to the CaaS platform, which is our content delivery layer. Editorial content created in FirstSpirit is automatically synchronized to the CaaS platform, where it is exposed as standardized JSON documents through a REST API and a GraphQL API. Front-end applications consume this content directly from the CaaS platform.

Templating in FirstSpirit is no longer required and is shifted to the front end or to front-end services (see Crownpeak PWA Template for a reference implementation of a Progressive Web App). FirstSpirit developers can therefore focus on modeling domain-oriented objects and designing the corresponding input components.

The connection to the CaaS platform is largely invisible to the editorial team. As soon as a change is made in FirstSpirit, synchronization is triggered in the background and the CaaS platform immediately reflects the change. Editors can inspect the current state of the data directly via the CaaS platform; technical intervention is only needed in the event of a problem.

1.1. Scope of this document

This document is intended for FirstSpirit developers and project administrators who work with projects that use the CaaS Connect module. It covers the activation and project-specific configuration of the module, the data format of CaaS documents, schedules for data reconciliation, media file storage, the status report, and the GraphQL API.

Installation and server-side configuration of the module are described in the administrator documentation.

2. Getting started

2.1. Activation of the module

Once the installation of the CaaS Connect module and the basic configuration of the CaaS Connect Service have been completed (automatically in SaaS environment, on-prem by the FirstSpirit Server Administrator), the module needs to be activated. This is accomplished by adding the project component CaaS Connect project app to each project in which the content should be transferred to the CaaS platform.

Details can be found in the FirstSpirit documentation about project components.

After activating the module for a project, the synchronization of its content with the CaaS platform is set up. Also, the necessary collections and some API keys in the CaaS platform are created automatically. Finally, the schedules for manual synchronization of the project content are created and configured (see chapter Sync schedules).

2.2. Endpoints and API keys

The project component contains a configuration dialog that displays useful information like all CaaS endpoints and project specific API Keys. It also offers various configuration options which are described in the configurations chapter.

project app endpoints
Figure 1. Configuration dialog: "Endpoints"

All collections created by the CaaS Connect module for the project are listed in the "Endpoints" section of the configuration dialog.

project app apikeys
Figure 2. Configuration dialog: "API Keys"

The displayed project-specific API keys are automatically generated by the CaaS Connect module. For preview and release content of the project, one API key with read only permission and one API key with read and write permission are provided. Additionally, one GraphQL API key is provided for each preview and release. These keys exclusively allow executing the respective GraphQL app.

3. Module concepts

3.1. Supported FirstSpirit elements

The module creates documents in the CaaS platform for the following FirstSpirit elements:

  • Page references

  • Media

  • Global content pages

  • Project settings page

  • Datasets

Each element will be represented as multiple documents. For both the preview and release state, a document is created for each language of the FirstSpirit project that is marked with Generate language in the project’s language configuration. This also applies to media elements that are language independent. Each of these documents can be identified and referenced with a unique URL.

3.2. Data synchronization

Content changes are automatically synchronized near real-time with the CaaS platform in the background by relying on FirstSpirit events. This means that the data in the CaaS platform is always up to date and reflects the current state of the project in FirstSpirit. There are only a few scenarios where it may be necessary to manually trigger a reconciliation between FirstSpirit and the CaaS platform:

  • Initial population of CaaS with project data when connecting a project for the first time

  • Correcting inconsistencies between FirstSpirit content and the CaaS platform

  • Propagating configuration changes that affect generated content but do not automatically trigger resynchronization, for example a changed URL factory or updated CaaS tag configuration

  • Repairing individual elements when no FirstSpirit events trigger an update, for example when third-party data injected into the JSON changes, or when a media-store folder move did not produce per-media events

The first three scenarios are handled by the schedules provided by CaaS Connect. Details on the schedules and their configuration can be found in the chapter Sync schedules. The fourth requires an executable that synchronizes individually selected elements to CaaS (see Manual element sync via executable).

3.3. Preview and release state

An essential distinction between preview and release data states is made by both FirstSpirit and the CaaS Connect module. The CaaS platform also manages both states of data, which are distinguishable by different CaaS URLs (see URL schema for CaaS documents). 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.

Project without "use release"

If the release function has been disabled in the FirstSpirit project (See FirstSpirit Documentation about project properties), only preview data states will be transferred to the CaaS. To update data in the release state, a manual data reconciliation needs to be executed using the CaaS Connect schedules.

3.4. URL schema for CaaS documents

The CaaS URL for a document consists of the following elements:

  • Tenant ID is the maintained name or abbreviation of the tenant.
    It is set in the CaaS Connect Service by the server administrator

  • Project identifier is the GID of the FirstSpirit project.

  • Collection identifier contains either the value release.content or preview.content.
    It allows you to differentiate between release and preview state.

  • Document identifier is composed of the FirstSpirit GID of the FirstSpirit element and the Locale (language and country).
    Note: The project settings page use the identifier projectsettings instead of the GID.

Together with the base URL of the CaaS endpoint, this results in the fully qualified URL of a document:

https://CAAS-BASE-URL/<tenant id>/<project identifier>.<collection identifier>/<document identifier>

Example:

The tenant ID is defaultTenant. The FirstSpirit project GID is e54cb80e-1f9c-4e8d-84b8-022f473202eb. For previewing a page with the GID f6910b22-6ae8-4ce1-af45-c7b364b3117a for the English language the URL looks like this:

https://CAAS-BASE-URL/defaultTenant/e54cb80e-1f9c-4e8d-84b8-022f473202eb.preview.content/f6910b22-6ae8-4ce1-af45-c7b364b3117a.en_GB

You can get an overview of all collection URLs for the project in this chapter.

4. Data format of CaaS documents

The CaaS JSON format is generated automatically, FirstSpirit templating is not used in this process. CaaS JSON format is based on FirstSpirit’s toJson standard and is extended by the CaaS Connect module to include both CaaS specific JSON format configuration and some attributes that simplify its usage. This involves features like reducing the output of datasets to references, the indirect referencing of records of a content projection, and enabling the output of the FirstSpirit metadata.

The format cannot be customized. This restriction enables the CaaS platform to deliver a complete, standardized data format, ensuring that all consuming endpoints can work with the same data format.

We strongly advise against creating your own documents, that is documents with a different data format, in the collections created by CaaS Connect to avoid breaking functionality of other features of the CaaS Connect module or cause issues for API users.

Details of the CaaS specific attributes are explained in the following sections.

4.1. 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 of a dataset reference in a page document
{
   "fsType" : "FS_DATASET",
   "name" : "st_button_link",
   "value" : {
      "fsType" : "DatasetReference",
      "target" : {
         "entityType" : "product",
         "fsType" : "Dataset",
         "identifier" : "fae0687b-c365-4851-919e-566f4d587201",
         "schema" : "products"
      },
      "url" : "https://CAAS-BASE-URL/<TENANT-ID>/<PROJECT-UUID>.preview.content/fae0687b-c365-4851-919e-566f4d587201.en_GB"
   }
}

4.2. Dataset routes

The routes attribute is an array that lists all available content projections of a dataset as individual objects. A dataset has multiple routes if it is part of multiple content projections and therefore multiple preview pages are available for that dataset.

The route attribute is deprecated and has been replaced by the new routes array, but is still added for compatibility reasons.

The pageRef attribute is the FirstSpirit-GID of the associated page reference.

JSON snippet example of a route in a Dataset
{
  "routes": [
          {
            "pageRef": "39332e1e-0a42-4fb9-934a-dd3efe58cbc8",
            "route": "/Company/Press/Solar-systems-unveiled-at-Old-Trafford-stadium.html"
          },
          {
            "pageRef": "78dc7762-657b-4524-ab00-debbfd5e6d62",
            "route": "/Company/Solarnews/Solar-systems-unveiled-at-Old-Trafford-stadium.html"
          }
  ]
}

See the chapter Alternative URL generation for more information on how the Dataset route is generated.

4.3. PageRef routes

The route attribute contains the URL of a pageRef rendered with the configured project-specific URL factory.

JSON snippet example of a route in a PageRef
{
  "fsType": "PageRef",
  "name": "news_overview",
  "route": "/Company/Press/Press-Overview.html"
}

See the chapter Alternative URL generation for more information on how the PageRef route is generated.

4.4. Locale

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

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

4.5. Media references

Media references point to the associated document of the medium. The URLs to the medium’s actual binary data can be found in the referenced document.

JSON snippet example of a media reference
{
   "st_header_image": {
        "fsType": "FS_REFERENCE",
        "name": "st_header_image",
        "value": {
            "fsType": "Media",
            "name": "header_home",
            "identifier": "b7fd2e2c-a022-44d6-ae2d-f0b9fd48f9a2",
            "uid": "header_home",
            "uidType": "MEDIASTORE_LEAF",
            "mediaType": "PICTURE",
            "url": "https://CAAS-BASE-URL/defaultTenant/631e4786-0dc3-4db6-bad8-adaad685944a.preview.content/b7fd2e2c-a022-44d6-ae2d-f0b9fd48f9a2.de_DE"
        }
    }
}

4.6. Content projections

When using the standard JSON configuration of FirstSpirit, the JSON data of content projections or its sections contain references to its records. 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 of a content projection
{
   "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"
   }
}

4.7. Broken references

Since FirstSpirit 2026.5, when a referenced content element cannot be fully resolved during rendering — for example because it has not yet been released — FirstSpirit outputs it as a partial object marked with brokenReference: true instead of omitting it from the output entirely. CaaS Connect adds a url attribute to these partial objects, allowing consuming applications to identify the corresponding CaaS document and fetch it once the referenced content becomes available.

Page references and media references carry brokenReference: true directly on the reference object:

JSON snippet example of a broken page reference
{
   "fsType" : "PageRef",
   "brokenReference" : true,
   "identifier" : "b0ac2697-79b8-4c9e-a35c-fc7c4ba6212b",
   "url" : "https://CAAS-BASE-URL/<TENANT-ID>/<PROJECT-UUID>.preview.content/b0ac2697-79b8-4c9e-a35c-fc7c4ba6212b.en_GB"
}

Note: in cases where a referenced content element is completely missing (for example because it has been deleted), the identifier is null and the url attribute cannot be set by CaaS Connect.

Dataset references carry brokenReference: true on the inner target object; url is added to the enclosing value object:

JSON snippet example of a broken dataset reference in a page document
{
   "fsType" : "FS_DATASET",
   "name" : "st_button_link",
   "value" : {
      "fsType" : "DatasetReference",
      "target" : {
         "fsType" : "Dataset",
         "identifier" : "fae0687b-c365-4851-919e-566f4d587201",
         "schema" : "products",
         "brokenReference" : true
      },
      "url" : "https://CAAS-BASE-URL/<TENANT-ID>/<PROJECT-UUID>.preview.content/fae0687b-c365-4851-919e-566f4d587201.en_GB"
   }
}

4.8. Project master language

The project settings document has the attribute projectConfiguration with the sub-attribute masterLocale in which the project’s master language is contained.

JSON snippet example of the project master language
{
  ..,
  "projectConfiguration": {
    "masterLocale": "en_GB"
  }
}

Changing the project master language does not automatically update the document in the CaaS platform. To update the document, the project schedules Total Sync for performing data synchronization can be used (see chapter Total Sync).

5. Configuration options

CaaS Connect offers important project specific configuration options that are described in the following sections.

5.1. Alternative URL generation

For generating Media Binary URLs and the routes for Dataset and PageRef documents, a URL Factory is used. The default URL Factory is Advanced URLs.

The CaaS Connect project app allows the configuration of an alternative URL factory.
Please note that for Media Binary URLs, the configured URL Factory will only be used when media is stored in S3 (which is default in the Crownpeak SaaS offering).

project app config urlfactory blurred
Figure 3. Configuration dialog of CaaS Connect project component: URL factory configuration

We recommend using a URL Factory that uses the FirstSpirit Registry as persistence. Of the standard FirstSpirit URL factories, the following use the FirstSpirit Registry: Advanced URLs, Default URLs (SEO), Multiview URLs (SEO) and Infix URLs (SEO).

After changing the URL factory configuration it is necessary to overwrite all CaaS content to apply these changes. For this we recommend using the Total Sync schedules for performing data synchronization (see chapter Data synchronization).

5.2. Remote datasets

CaaS Connect offers the option to use references for datasets instead of embedding the dataset data in the page documents. This can be configured in the CaaS Connect project app.

project app config datasets blurred
Figure 4. Configuration dialog of CaaS Connect project component: Remote datasets

Using references for remote data sets in the project avoids the load of distributing datasets to the target projects, making changes visible more quickly. In this case, URLs that refer to remote datasets are directed directly to the source project. We recommend using this configuration.

The generated collection API keys that you can see in the project app UI are project-specific. If you use remote dataset references, they will not be able to access the datasets that are within a separate project. You will need to manually create an additional API key with the appropriate permissions for the referenced projects. Alternatively, the generated GraphQL API keys can be used to query the GraphQL apps successfully, as they are not restricted to specific collections.

5.3. Transmitted resolutions

It is possible to control the number of resolutions that are subsequently transferred to CaaS platform during a generation. This can be achieved by assigning tags with the label CaaS to the desired resolutions in the FirstSpirit project. More information about tagging resolutions can be found in the FirstSpirit documentation for administrators.

If no CaaS tag is configured in ServerManager for the given project, corresponding binary data will be transferred by default for all resolutions present in the project.

We strongly recommend limiting the number of resolutions to only those that are needed, as this can significantly reduce the runtime of the event processing and the sync jobs.

When images are transferred to the CaaS, FirstSpirit calculates all resolutions and stores them in a cache. As long as this cache is not yet filled, the runtime of the event processing and the sync jobs, especially during their initial execution, is extremely delayed. This situation can be counteracted by setting the CaaS tag described here.

Also, when exporting projects, the option "Export automatically calculated image resolutions" should remain activated so that the resolution cache is already filled after the import.
add resolution tag
Figure 5. Adding a new tag

In the following example, only three resolutions are transmitted to the CaaS.

resolution list
Figure 6. Listing of the project resolutions

Please note that previously transferred binary data is not removed from CaaS by subsequent changes to the resolution tag.

Additionally, a change in the CaaS tags will not automatically update the CaaS data, a synchronization has to be started manually using the Total Sync schedules (see chapter Total Sync).

6. Data reconciliation

Full reconciliation of data can be triggered via the schedules automatically created during installation of the CaaS Connect project app (see Activation of the module). For targeted element repair, an executable is available (see Manual element sync via executable).

6.1. Sync schedules

Both schedules also remove obsolete documents from the CaaS platform after a successful run. If the schedule’s pipeline ends with errors, the cleanup step is skipped to avoid deleting documents that may simply have failed to update.

schedules sync
Figure 7. Sync schedules of the CaaS module

Changes to the configuration of these schedules are not persistent, as the schedules are reset to their original state when the project component is installed or updated. If the configuration of these schedules needs to be changed, these changes have to be applied to a copy of the respective schedule.

Depending on the size of the projects and the resulting amount of data, the schedule runtime duration may be very long. This applies in particular to the Total Sync jobs. In addition to the pure number of elements in the FirstSpirit project, factors include the number of languages and especially the number of image resolutions.

The runtime for the calculation and transfer of resolutions can be significantly reduced by configuring CaaS tags, see chapter Transmitted resolutions.

6.1.1. Smart Sync

The schedules

  • CaaS Connect - Smart Sync (fast, sends changed data) - PREVIEW and

  • CaaS Connect - Smart Sync (fast, sends changed data) - RELEASE

perform an intelligent full reconciliation of the preview and release data of FirstSpirit and the CaaS platform. This only includes creating or updating outdated documents. The revision information of related FirstSpirit elements is used to identify outdated documents.

In some cases not all documents are updated, even though there were relevant changes in FirstSpirit. To force an update of these documents, the CaaS Connect - Total Sync …​ schedules need to be used.

6.1.2. Total Sync

The schedules

  • CaaS Connect - Total Sync (slow, sends all data) - PREVIEW and

  • CaaS Connect - Total Sync (slow, sends all data) - RELEASE

perform a full reconciliation of the preview and release data of FirstSpirit and the CaaS platform. This includes creating and updating documents of all FirstSpirit elements (as opposed to the Smart Sync schedules), independent of their FirstSpirit revision info.

6.2. Manual element sync via executable

This executable pushes a caller-defined list of FirstSpirit elements to CaaS in a single call. It covers cases in which FirstSpirit continues to treat modified documents as up-to-date, so that a Smart Sync cannot help, but a Total Sync is too coarse.

Executable class:

#Executable class
com.espirit.caasconnect.executable.CaasConnectGidSyncExecutable

Parameters:

Key Required Description

elements

yes

Element GIDs to sync. Either a List<String> or a comma-separated String.

useRelease

no

true to push the release state, false (default) for preview. A single call targets one state.

languages

no

Language abbreviations (List<String>) to restrict the push to. Omitted = all generated languages.

resolutions

no

Picture resolution UIDs (List<String>) to restrict the push to. Omitted = all CaaS-tagged resolutions (or all resolutions if no tag is configured).

Result: a JSON string with this shape:

{
    "success": true,
    "documentsSent": 12,
    "binariesSent": 4,
    "failures": [
        { "gid": "<element identifier>", "reason": "<description>" }
    ],
    "error": "<top-level rejection reason, only present when the call was rejected up front>"
}

7. Media file storage

In the Crownpeak SaaS environment, the binary data of media files is stored in an S3 bucket and can be accessed via a Content Delivery Network (CloudFront distribution service). For on-premise installations also other hosting options are supported, more information can be found in the Administrator documentation.

For language-independent media, exactly one binary file is transferred. For language-dependent media, one binary file is transferred for each language of the FirstSpirit project that is marked with Generate language. Additionally, for images the binary data of each resolution is transferred if no CaaS-Tag has been set.

7.1. Accessing binary data

A media document contains URL attributes, which point to the respective binary data. Where this URL is located inside the media document depends on the media type.

Example of media document:
The following code snippet shows an example of the content of a media document of type PICTURE, including the URLs that point to the binary data for each resolution of the image. If the CaaS-Tag is set in the resolutions settings, only these tagged resolutions will be listed in the resolutionsMetaData object.

Example: JSON of a picture media document in the preview state
{
    "_id": "3b3fe5b6-9ec1-4e45-84c8-bc6a39d0aa61.en_US",
    "fsType": "Media",
    "name": "thisisatest",
    "displayName": "thisisatest",
    "identifier": "3b3fe5b6-9ec1-4e45-84c8-bc6a39d0aa61",
    "uid": "thisisatest",
    "uidType": "MEDIASTORE_LEAF",
    "fileName": "thisisatest",
    "languageDependent": false,
    "mediaType": "PICTURE",
    "description": null,
    "resolutionsMetaData": {
        "ORIGINAL": {
            "fileSize": 16358,
            "extension": "png",
            "mimeType": "image/png",
            "width": 578,
            "height": 340,
            "url": "https://my-cloudfront-domain.tld/631e4786-0dc3-4db6-bad8-adaad685944a/preview/FirstSpirit/Bilder/thisisatest.png"
        },
        "Teaser": {
            "fileSize": 1192,
            "extension": "png",
            "mimeType": "image/png",
            "width": 111,
            "height": 65,
            "url": "https://my-cloudfront-domain.tld/631e4786-0dc3-4db6-bad8-adaad685944a/preview/FirstSpirit/Bilder/thisisatest_Teaser.png"
        }
    },
    "metaFormData": {},
    "changeInfo": {
        "date": "2021-05-10T10:41Z",
        "revision": 21077
    },
    "locale": {
        "identifier": "EN",
        "country": "US",
        "language": "en"
    },
    "_etag": {
        "$oid": "60990def3542845893b034da"
    }
}

7.2. CloudFront Caching

When changing the binary data of media, its files are not immediately invalidated in the cache of the CloudFront distribution. Instead, an automatic update takes place after a maximum of 15 minutes, provided that the CloudFront distribution is configured to take into account the Cache-Control header from an origin’s HTTP responses. In the Crownpeak Cloud this is active by default.

For more information regarding the Cache-Control header, see the information about caching in the Administrator documentation.

8. Visibility of 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.

9. 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. The change stream notifies all connected clients for all Change Events of the types insert, replace, update and delete. 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.

10. Indexes

To query documents from CaaS platform by an attribute that is not the document identifier, filters can be used that specify criteria for the documents to be returned.

Example:
To retrieve a CaaS document (a FirstSpirit page reference) with the name services a GET request is executed with the following URL:
https://CAAS-BASE-URL/defaultTenant/e54cb80e-1f9c-4e8d-84b8-022f473202eb.preview.content?filter={"name": "services"}

10.1. Automatically created indexes

The performance of such filter queries can be greatly improved by using indexes. Therefore, various indexes on frequently used document attributes are automatically set up on some collections created by CaaS Connect.

The following indexes are set up in the collections preview.content and release.content for each project:

  • idx_identifier_lang_country with the attribute combination identifier, locale.language and locale.country

  • idx_entity_lang_country with the attribute combination entityType, locale.language and locale.country

  • idx_fstype_lang_country with attribute combination fsType, locale.language and locale.country

  • idx_route with the document attribute route

  • idx_routes_route with the document attribute routes.route

  • idx_changeinfo_lastsynced with the document attribute changeInfo.lastSynced

  • idx_fstype_template_uid with the attribute combination fsType and template.uid

  • idx_fstype_page_template_uid with the attribute combination fsType and page.template.uid

  • idx_fstype_media_type with the attribute combination fsType and mediaType

Details on all existing indexes can be retrieved under
https://CAAS-BASE-URL/<tenant id>/<project gid>.<preview|release>.content/_indexes/.

The order of the index fields is relevant. Please use the database documentation to ensure that your filter queries are designed in such a way that the indexes are used.

More information on indexes is available in the CaaS platform documentation.

10.2. Custom indexes

You can create your own indexes using the REST API of CaaS platform. The following information is required for this:

  • an authorized API key

  • a collection URL

  • an index name

  • an index body

To simplify the creation of an index, CaaS Connect also offers the executable CaasConnectCreateIndexExecutable. This only requires the specification of the index name and its body; the remaining parameters are determined from the calling context.

An example use for the executable are FirstSpirit generations. It can be used within generations in script actions.

#Executable class
com.espirit.caasconnect.executable.CaasConnectCreateIndexExecutable

Example parameter configuration of a script action in an FirstSpirit generation

name value

indexName

idx_page_lang

indexBody

{ "keys": { "page.uid": 1, "locale.language": 1 } }

If you pass the parameters from the table above in the properties of a generation, the following index is created when the generation is executed:

{
    "v": 2,
    "key": {
        "page.uid": 1,
        "locale.language": 1
    },
    "_id": "idx_page_lang"
}

More information on creating indexes can be found in the Documentation of RESTHeart.

If the index creation takes longer due to very large amounts of data in CaaS, an error is logged. It is possible that the index creation is still successful after more than an hour.

11. Status Report for CaaS Documents

If the CaaS Connect Web App WebComponent is installed, a status report dialog is available for project administrators in the ContentCreator via the "Actions" menu.

It is used to check whether a FirstSpirit element is available in the CaaS and whether the contents match. It helps project administrators identify discrepancies by displaying the current status for each language and data state combination. Additionally, further information, such as the associated revisions and links to the CaaS document, is provided.

The following FirstSpirit elements are currently supported:

  • page references

  • datasets

  • media

The dialog can be accessed for page references via the "Actions" menu. For datasets, it can be opened via the context menu of a selected item within the data sources section. Similarly, the dialog can be opened via the context menu of a selected media item in the media management section. The corresponding entry in the context menu is indicated by the icon saas sync.

caas document status
Figure 8. CaaS document status report in the ContentCreator

Please note that a discrepancy between documents does not necessarily indicate an error in the synchronization process:

  • The cause may be missing prerequisites on the FirstSpirit side, such as approvals that have not yet been granted or missing references.

  • In addition, transferring a recently edited page to CaaS may take some time, so an item may still be displayed as not "IN_SYNC" while it is still in the synchronization process.

These causes should be checked before assuming a technical error.

If an element is missing in CaaS or the content differs, it can be resynchronized from the dialog. If an undesirable status persists afterward, the status report can be downloaded as a JSON file and forwarded to technical support for analysis.

Detail pages (dataset and page reference)

On a detail page (a content projection that displays exactly one dataset), both the page reference and the associated dataset are synchronized to CaaS as independent documents, and either one can diverge without the other. When the status report is opened on such a page, the dataset’s synchronization status is shown first. A button in the dialog header switches between the dataset view and the page reference view.

This applies to detail pages only. On overview pages, where the number of associated datasets is unbounded, only the status of the page reference is shown.

Status Overview

The synchronization status is displayed for each language and stage (Preview/Release):

Status Icon Meaning

In Sync

✓

The content of the element and the CaaS document match.

Out of Sync

✗

The contents of the element and the CaaS document differ. This status occurs, for example, when the event-driven processing of a change to the element has not yet been completed, or when content maintained outside the CMS that is referenced in FirstSpirit changes.

Missing in CaaS

✗

The document was not found in CaaS. Therefore, the synchronization status cannot be determined. This happens, for example, when a FirstSpirit project has been imported but the CaaS has not yet been initially populated.

Content unavailable

✗

Rendering of the element failed, e.g., due to a deleted page template. Further information can be accessed via the "Details" button. The cause must be resolved on the FirstSpirit side before synchronization in the CaaS is possible.

Never Released

ℹ

The element has never been released, so the document cannot exist in the CaaS release stage.
Filters and Sorting

The status display can be sorted by language, preview/release stage, and filtered by synchronized or divergent documents.

Links

For each document, a link to the corresponding CaaS document can be copied to the clipboard.

Synchronizing documents

Individual documents can be resynchronized to CaaS directly from the dialog. You can choose between the preview and release stage. However, it is not possible to select individual languages.

The synchronization initiated in this way occurs in parallel with synchronization processes already in progress that were started via eventing or a job.

Pipeline Status

The dialog header displays the current processing status of the synchronization. The display updates automatically every two seconds and shows whether documents are currently being processed by the module. The pipeline status does not indicate how many documents are currently waiting to be processed.

State Meaning

Idle (green)

No events are currently being processed.

Active (blue)

Documents are currently being processed. In addition to the count, the timestamp of the oldest document not yet processed is displayed.

Lagging (orange)

A document is delayed by more than 30 seconds. This may indicate a slightly elevated load or a complex element.

Critical (red)

A document is delayed by more than 2 minutes. This indicates high load in the synchronization process.
Download status report

The complete status report, including the synchronization log, can be downloaded as a JSON file. If you contact our technical support regarding any discrepancies, please attach this file for reference.

12. FirstSpirit GraphQL API

The CaaS Connect module supports generating and provisioning the FirstSpirit GraphQL API since version 3.25.10. As of version 3.59.2 this feature is stable and generally available.

The FirstSpirit GraphQL API enables querying FirstSpirit content with GraphQL including filtering, sorting and pagination. The capabilities for querying content are therefore virtually identical to the collection endpoints of the REST API.

12.1. API deployment/provisioning

Unlike the REST API of the CaaS platform, which is provisioned independently of the CaaS Connect module, the FirstSpirit GraphQL API is provisioned dynamically by CaaS Connect. To do that, the CaaS Connect module uses the Management API for GraphQL applications of the CaaS platform.

Initial (automatic) provisioning

The FirstSpirit GraphQL APIs are deployed for the first time during the service start and after installation/update of the project component, only if the FirstSpirit GraphQL APIs do not yet exist.

Manual provisioning

To manually deploy the APIs (e.g., after making changes to the project model), the related schedule entries Deploy FirstSpirit GraphQL API or the executable CaasConnectGraphqlSyncExecutable can be used.

schedules graphql
Figure 9. GraphQL schedules of the CaaS module

If non-backward-compatible changes have been made to the project’s data model, the schedules and the executable still provision and update the FirstSpirit GraphQL APIs. This can negatively impact consumers of the APIs because it can break queries due to breaking changes in the schema.

Manual provisioning is recommended if changes have been made to the FirstSpirit templates or a GCAPage template is used for the first time. Regular execution is not necessary.

12.2. URL endpoints

The CaaS Connect module provides a separate GraphQL API for the preview and release content. The URL endpoints of the API consist of the following elements:

  • Base URL of the CaaS platform + /graphql path

  • Tenant ID

  • Project GID plus suffix for preview -preview-documents or release -release-documents

This results in the URL endpoint:
https://CAAS-BASE-URL/graphql/<tenant id>___<project gid>-preview-documents|release-documents

Example:
A tenant with the ID my-caas-dev can query the FirstSpirit GraphQL API for the preview content of the project with the GID 631e4786-0dc3-4db6-bad8-adaad685944a by using the following URL:

https://CAAS-BASE-URL/graphql/my-caas-dev___631e4786-0dc3-4db6-bad8-adaad685944a-preview-documents

More information on querying data via the GraphQL API can be found in the chapter GraphQL API of the CaaS platform documentation.

The configuration dialog of the project component shows an overview of all FirstSpirit GraphQL API URLs of the project.

The tutorial Quickstart tutorial: FirstSpirit GraphQL API serves as a quick introduction for using the FirstSpirit GraphQL API.

12.3. Schema

The FirstSpirit GraphQL API schema is generated dynamically based on the data model of the project and is very similar to the data format of the JSON documents (see chapter Data format of CaaS documents).

12.3.1. Query fields (entry points)

The generated schema contains at least one query field for querying multiple documents (collection field) of the following content types:

  • PageRef

  • Dataset

  • Media

  • ProjectProperties

  • GCAPages

The query fields are generated automatically based on the project’s templates. Data does not need to exist for these templates in advance. However, GCAPages are handled differently: queries are only generated for templates that are already in use.

Each query field also allows filtering, sorting, and paging the results using the arguments filter, sort, skip and limit.

Only JSON documents (using GraphQL variables) are accepted for the filter and sort arguments.

The format of the value corresponds to that of the filter or sort query parameter of the CaaS platform REST API (see chapter Use of filters of the CaaS platform documentation).

12.3.2. Type name disambiguation

GraphQL type names are derived from template UIDs. If a project contains two templates whose UIDs differ only in case (e.g. myTemplate and MyTemplate), both would normally collapse to the same GraphQL type name. CaaS Connect resolves this conflict by appending a stable numeric suffix to the affected type names: the template with the lowest FirstSpirit ID keeps its name unchanged; each additional colliding template receives a suffix _1, _2, and so on (e.g. MyTemplate_1). The suffix assignment is stable against move and rename operations because it is based on the FirstSpirit ID rather than the tree position of the templates.

Deleting a template that is part of a UID collision group changes the suffix assignments of the remaining templates (e.g. MyTemplate_1 may become MyTemplate once the competing template is removed). This is a breaking change to the GraphQL schema and results in incompatibility with existing client applications that query the affected types — those applications must be updated and redeployed.

12.3.3. Automatic resolution of references

There is a significant difference to the format of JSON documents for all form fields that contain references to other documents. Specifically, this affects the following form field types:

  • FS_REFERENCE (only PageRef and Media references)

  • FS_DATASET

  • FS_INDEX (only DatasetDataAccessPlugin)

The following fields of these types do not contain the raw data of the reference, but instead contain the data of the referenced documents (by resolving the references).

  • value for FS_REFERENCE

  • value.target for FS_DATASET

  • value[].value for FS_INDEX (only with DatasetDataAccessPlugin)

For FS_INDEX fields using a DAP other than the DatasetDataAccessPlugin, the index records are represented as generic JSON (BsonDocument scalar) without automatic reference resolution.

13. Troubleshooting

There are some known issues and limitations of the CaaS Connect module that you may encounter when working with the module.

13.1. Errors during full sync schedule when transmitting documents for project settings page

The error ReferenceNotFoundException: No template defined for project properties can occur during a full sync schedule run when there is no project settings template defined in the project configuration.

This issue was fixed with FirstSpirit version 2023-04 and can be resolved either by updating the FirstSpirit server or by setting a project settings template in the project configuration.

13.2. Missing GID with external databases

It is possible to use external databases in FirstSpirit projects. These databases may be included in a read-only manner. However, using a database in such a way results in FirstSpirit not being able to generate GIDs for the elements. Without a GID, CaaS Connect cannot synchronize these elements with CaaS platform. This may also result in errors during synchronization schedules.

Therefore, using CaaS Connect with external read-only databases is not supported.

13.3. Push notifications (change streams) not working

Every collection that is created by the CaaS Connect module should have a change stream definition for push notifications. If the definitions are missing, they can be restored by executing a schedule.

14. Quickstart tutorial: FirstSpirit GraphQL API

This guide describes how to query FirstSpirit content using the FirstSpirit GraphQL API.

It covers defining a GraphQL query and expanding it step by step to demonstrate the most important features of FirstSpirit GraphQL API.

To complete this guide you need…​

  • access to a FirstSpirit project where the CaaS Connect module is activated,

  • existing content that has already been synchronized with the CaaS platform

  • and a tool or IDE that supports GraphQL.

Guide

  1. Provisioning the FirstSpirit GraphQL API
    First, the latest version of FirstSpirit GraphQL API must be provisioned. To do this, the Deploy FirstSpirit GraphQL API schedules can be executed for the preview and release state.

  2. URL of the API endpoint and API key
    For the next steps you need both the URL of an API endpoint and an API key with read permissions. These can be copied from the project component.

  3. Query basic attributes of a PageRef

    The following GraphQL query needs to be sent to the URL from the previous step of an API endpoint of the FirstSpirit GraphQL API using a tool or IDE that supports GraphQL.

    To authenticate the request, the API key from the previous step must be specified in the Authorization header using the Bearer authentication scheme.

    The following query fetches basic attributes of the PageRef content.

    GraphQL query
    {
  pageRefs {
    displayName
    locale {
      identifier
    }
  }
}
    JSON response body
    {
  "data": {
    "pageRefs": [
      {
        "displayName": "Produkt Landingpage",
        "locale": {
          "identifier": "DE"
        }
      },
      {
        "displayName": "Product Landingpage",
        "locale": {
          "identifier": "EN"
        }
      }
    ]
  }
}

  4. Query authored content
    In addition to the basic attributes of various content, authored content can also be queried.

    The following query fetches the headline of all PageRef documents of type LandingPage as an example.

    GraphQL query
    {
  pageRefs {
    displayName
    locale {
      identifier
    }
    page {
      ... on LandingPage {
        formData {
          pt_headline {
            value
          }
        }
      }
    }
  }
}
    JSON response body
    {
  "data": {
    "pageRefs": [
      {
        "displayName": "Produkt Landingpage",
        "locale": {
          "identifier": "DE"
        },
        "page": {
          "formData": {
            "pt_headline": {
              "value": "Testsieger 2013"
            }
          }
        }
      },
      {
        "displayName": "Product Landingpage",
        "locale": {
          "identifier": "EN"
        },
        "page": {
          "formData": {
            "pt_headline": {
              "value": "Test winner 2013"
            }
          }
        }
      }
    ]
  }
}

  5. Filter content
    All query fields also support passing an arbitrary filter via the filter argument.

    In the following query example, the results are filtered so that only English content is returned.

    GraphQL query
    query ($filter: BsonDocument) {
  pageRefs(filter: $filter) {
    displayName
    locale {
      identifier
    }
    page {
      ... on LandingPage {
        formData {
          pt_headline {
            value
          }
        }
      }
    }
  }
}
    GraphQL query variables
    {
  "filter": {
    "locale.identifier": "EN"
  }
}
    JSON response body
    {
  "data": {
    "pageRefs": [
      {
        "displayName": "Product Landingpage",
        "locale": {
          "identifier": "EN"
        },
        "page": {
          "formData": {
            "pt_headline": {
              "value": "Test winner 2013"
            }
          }
        }
      }
    ]
  }
}

  6. Sort and paginate content
    Finally, the results are sorted and paginated using the arguments sort, skip and limit.

    The results are sorted in ascending order using the attribute page.formData.pt_headline.value.

    GraphQL query
    query ($filter: BsonDocument, $sort: BsonDocument) {
  pageRefs(filter: $filter, sort: $sort, skip: 5, limit: 5) {
    displayName
    locale {
      identifier
    }
    page {
      ... on Product_specialPage {
        formData {
          pt_headline {
            value
          }
        }
      }
    }
  }
}
    GraphQL query variables
    {
  "filter": {
    "locale.identifier": "EN"
  },
  "sort": {
    "page.formData.pt_headline.value": 1
  }
}

More information on the format of the filter and sort arguments can be found in the chapter FirstSpirit GraphQL API → Schema.

The CaaS is a product of Crownpeak Technology GmbH, Dortmund, Germany.

Only a license agreed upon with Crownpeak Technology GmbH is valid with respect to the user for using the module.

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

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