1. Introduction

This document is intended for FirstSpirit server administrators who install, configure, and operate the CaaS Connect module on a FirstSpirit server. It covers the technical requirements, the installation and server-side configuration of the module, and the troubleshooting of operational issues. Editorial usage and project-level configuration are covered in the module documentation.

The topics described in this document are generally only relevant for on-premises installations.

1.1. Technical requirements

The module requires FirstSpirit version 5.2.250812 or later and access to the following external systems:

  • CaaS platform (mandatory) — the target system for synchronized content. The FirstSpirit server must be able to reach the platform endpoint over the network, and a Master API key with read and write access must be available. For installation and operation of the CaaS platform, refer to the CaaS platform Operations Guide.

  • S3-compatible object storage, optionally fronted by a CloudFront distribution (optional) — an alternative hosting backend for media files. See Media hosting for details.

2. Module setup

The following sections describe the steps a FirstSpirit server administrator needs to perform in order to set up the module, including installation and basic minimal configuration.

2.1. Installation of the module

The module has no dependencies on other modules and can therefore be installed very easily on the FirstSpirit server. Since projects must be explicitly marked as CaaS projects (see Module documentation), the project data is not automatically synchronized after the module is installed.

After installation or update of the module, restarting the FirstSpirit server is required.

2.2. Configuration of the service

The service component CaaS Connect Service is the link between the projects on the FirstSpirit server and the CaaS platform. While the service is running, editorial changes are automatically synced to CaaS for every configured project. The service requires a valid configuration whose settings apply to all CaaS projects. Settings may be overwritten on a project-specific basis. This is explained in the project configuration chapter in the module’s documentation.

Please note that when the CaaS Connect Service is started, it checks if a connection to the CaaS platform can be established. If this connection check fails an error message will be appended to the FirstSpirit server log. If the service is stopped, no synchronization takes place.

The configuration dialog of the service component CaaS Connect Service shows which fields are optional or mandatory. If a field is empty or the entry is invalid, the field is highlighted with a red border.

The minimal configuration includes:

  • the URL of a reachable CaaS platform.

  • an API key that has read and write access to all CaaS projects (Master API key).
    More information about API keys and permissions can be found in the CaaS platform documentation.

  • the Tenant ID.
    The value may consist of a maximum of 63 characters and is not case-sensitive.

The various configuration settings are explained in more detail in the chapter Configuration via the file system.
To learn more about the options for hosting of media, see the chapter Media hosting.

service config empty
Figure 1. Configuration dialog of the CaaS Connect Service

If password encryption is set active in the FirstSpirit server, the values for API Key and Secret access key (S3) get automatically encrypted whenever the configuration is saved via the dialog and upon service start. The values in the dialog are then presented in ciphertext.

2.3. Installation of the WebApp Component

The WebApp component CaaS Connect Web App is a component of the module and provides some optional features in the ContentCreator.

If you wish to use these features, the WebApp component must be installed via ServerManager in the ContentCreator web application. Details on the installation can be found in the FirstSpirit documentation at Web Applications or Web Components.

The following features are provided by the CaaS Connect Web App:

  • Status report for CaaS documents
    This dialog allows project administrators to check the synchronization status of the currently displayed page reference between FirstSpirit and CaaS.
    After successful installation, the status report dialog is available in the ContentCreator via the "Actions" menu.
    For more information about the content of the status report and how to interpret it, see the CaaS Connect documentation.

  • CaaS Connect Preview Rendering Plugin
    This plugin can be used in the Omnichannel Manager as described in the respective OCM documentation. It renders the CaaS document JSON on-the-fly in FirstSpirit and returns it in response to specific OCM methods.

3. Configuration via the file system

Besides the manual configuration via the FirstSpirit user interface, CaaS Connect can also be configured via the file system. To achieve this, all that is necessary is to create a JSON configuration file. The service CaaS Connect Service automatically loads the file caasConnect.json at startup, which must be located in the FirstSpirit server in ./conf/modules/CaasConnect.CaasConnectService/caasConnect.json.

The following examples show the format of the configuration file that is required and supported.

Never use the values of the sample configurations on your test or production systems as is, but replace them with values specific to your project.
Minimal sample configuration
{
  "baseUrl": "http://localhost:8080", (1)
  "apiKey": "ef27ef88-11c1-4ba0-946c-5c82d2880a18", (2)
  "tenantId": "defaultTenant" (3)
}
1 The CaaS platform endpoint
2 The API key used for data transfer between module and platform
3 The name or abbreviation of the tenant
Full sample configuration
{
  "baseUrl": "http://localhost:8080", (1)
  "apiKey": "ef27ef88-11c1-4ba0-946c-5c82d2880a18", (2)
  "tenantId": "defaultTenant", (3)
  "mediaConnectorConfig" : { (4)
    "S3": {
      "endpointUri": "https://s3.eu-central-1.amazonaws.com", (5)
      "credentials": { (6)
        "accessKeyId": "mySecretS3KeyId",
        "secretAccessKey": "mySecretS3AccessKey"
      },
      "bucketName": "examplebucketname", (7)
      "timeoutInSeconds": 10,
      "clientRegion": "eu-central-1",  (8)
      "cacheControl": { (9)
        "maxAge": {
          "seconds": 100
        },
        "maxAgeShared": {
          "seconds": 150
        }
      },
      "cloudFront": { (10)
        "endpointUri": "https://cloudfront.amazonaws.com", (11)
        "distributionId": "A4L1CDF3GND316", (12)
        "baseUrl": "https://my-cloudfront-domain.com", (13)
        "invalidateFiles": false (14)
      },
      "seoRouteFactory": "Advanced URLs" (15)
    }
  },
  "proxyAddress": "foo:123" (16)
}
1 The CaaS platform endpoint
2 API key for data transfer between module and platform
3 The name or identifier of the tenant
4 (Optional) Configuration for uploading and serving media files via an S3 bucket
Default: CaaS platform is used to serve media files
5 (Optional) URL to an S3-compatible API endpoint
Default: AWS API endpoint (https://s3.<region>.amazonaws.com)
6 (Optional) S3 credentials for uploading media files
Default: uses the "Default provider chain" of the AWS Java SDK (see AWS documentation)
7 Name of the S3 bucket
8 (Optional) Region of the bucket
Default: uses the "Default region provider chain" of the AWS SDK (see AWS documentation)
9 (Optional) Cache-Control metadata added to the S3 object on upload
Default: maxAge 300 seconds (5 minutes), maxAgeShared 900 seconds (15 minutes)
10 (Optional) Configuration to service media files via CloudFront distribution
Default: URL of the S3 bucket in virtual-hosted-style is used to serve media files (e.g. https://examplebucketname.s3.<region>.amazonaws.com/)
11 (Optional) URL to a CloudFront-compatible API endpoint
Default: AWS CloudFront API endpoint (https://cloudfront.amazonaws.com)
12 ID of the CloudFront distribution
13 Base URL of the CloudFront domain
14 (Optional) Enables/disables manual invalidation of files in the CloudFront CDN
Default: false, files are not manually invalidated
15 (Optional) URL Factory used to generate SEO routes in media documents We recommend to set "Advanced URLs" as default This factory will also be used for binary data URLs of media files unless a custom URL factory is defined in the project-specific configuration (see project configuration chapter)
16 (Optional) Endpoint of an HTTP proxy for communication with the CaaS platform or other services (S3, CloudFront)

It is necessary to restart the service after making changes to the configuration file. Only then will they be active.

If an error occurs while the service is reading the configuration file, a corresponding error message is written to the FirstSpirit log. Since the service cannot start without a valid configuration file, the functionality of the module is severely limited in this case.

Please note that when the CaaS module service is started, it checks if a connection to the CaaS platform can be established. An unsuccessful connection attempt on the part of the module will then result in an error message in the FirstSpirit server log.

Some configuration values are subject to further restrictions besides optionality, for example, a bucket name cannot contain uppercase letters. Invalid values are displayed directly in the user interface and cannot be saved. If such an invalid configuration is stored as a file, a corresponding error message will appear in the FirstSpirit log and the service will not start.

If password encryption is set active in the FirstSpirit server, apiKey and mediaConnectorConfig.S3.credentials.secretAccessKey are automatically encrypted. See FirstSpirit documentation for Administrators for more details. Please note that the module uses an internally defined key for encryption and does not use any of the values given in password.encryption.key.*.

4. Media hosting

Binary data of media elements are either stored in the CaaS platform itself or in an S3-compatible service. For performance reasons, we strongly recommend using an S3-compatible service for hosting media files.

Uploading binary data to the CaaS platform is the module’s default configuration. If binary data is to be delivered via an S3 service, the Media hosting configuration of the service component must be adjusted accordingly. It may be necessary to configure the service via the configuration file to provide all necessary information.

Depending on the chosen hosting option, the URLs that point to the binary data differ, as described in the Appendix. The number of media files that are transferred to the target system is identical for all hosting options.

If the media hosting option is changed, previous binary data URLs become invalid. As soon as a medium is changed or released again, both binary data and URLs are updated. Instead of making changes to all media files to trigger their synchronization, we recommend executing the Total Sync schedule.

4.1. Storage in CaaS

In this mode, the binary data of media is stored in CaaS file buckets and can be accessed via the CaaS REST API. As this is the default configuration, no further adjustments are necessary to use this media hosting option. For more information about the resulting URLs, see the Appendix.

4.2. Storage in S3

In this mode, the media binary data is uploaded to an S3 bucket. Both Amazon S3 and S3-compatible services can be used for delivery.

This option requires an S3 bucket to be set up. Also, the configuration of the service must be adjusted accordingly which has to be done via file system.

If there is no specification in the configuration, environment variables and system properties are evaluated. Further information about such a configuration can be found in the official Amazon S3 documentation.
An example of an S3 object path is found in the Appendix.

When using S3 storage, the files can be retrieved either through a CloudFront distribution or directly through the associated S3 REST API endpoint.
The following chapters describe these two options.

4.2.1. Access via CloudFront Distribution

You can set up a CloudFront distribution to serve the media files from the S3 bucket. The URL to binary file is then composed of the domain of the CloudFront distribution and the path of the S3 object (see Appendix for an example).

CloudFront Caching

The module always sends the Cache-Control header when uploading released media files to the S3 bucket, see the S3 object metadata section for more details. You can configure your CloudFront distribution to take into account this header from an origin’s HTTP responses. The full configuration example shows how to adjust the Cache-Control header to control the desired caching behavior of media files in the CloudFront CDN.

4.2.2. Access via S3 REST API

When no CDN is used, media files are directly accessed via the S3 REST API. The URL to a media file is then composed of the S3 REST API (virtual hosted endpoint of the bucket) and the path of the S3 object (see Appendix for an example).

For more information about the format and its limitations see Virtual hosting of buckets and Amazon S3 Path Deprecation Plan.

4.2.3. S3 object metadata

During the upload of media files to the S3 bucket, various metadata attributes are set for the S3 object:

  • Content-Type
    This attribute is used as the Content-Type response header for requests to the S3 object. It contains the MIME type of the media file (e.g. image/png).

  • Cache-Control
    This attribute is used as the Cache-Control response header for requests to the S3 object.

    • For the release state it contains the value public, max-age=300, s-maxage=900 by default.
      Information about configuration options can be found in chapter Configuration via the file system.

    • For the preview state it contains the value private, no-cache.

5. Error handling

Invalid configuration or network problems may cause errors on the CaaS Connect module side. All errors are logged in the FirstSpirit log.

5.1. Network error or overload

The module depends on the full availability of the CaaS platform. If the platform is not available or cannot process incoming requests fast enough, the module tries to repeat the requests. If this does not succeed either, an error is written to the FirstSpirit log and possible changes to the data are not synchronized with the CaaS platform. The editor is not notified of the error, so monitoring the server log by the administration is essential. If an error occurs it can be corrected either by executing the schedules or by repeating the action that led to the data change.

5.2. API key permissions not sufficient

The API key configured in the service component is used to synchronize all projects on the server with the CaaS platform. The API key therefore requires write and read permissions for all CaaS projects on the FirstSpirit server. For more information on configuring API keys, refer to the CaaS platform documentation.

6. Appendix

6.1. Binary data URLs for media files

Depending on the media hosting configuration, the URLs that point to the binary data of media files differ.

The following table gives an overview of the different URL formats.

Media hosting configuration URL format for binary data of media files

CaaS

https://CAAS-BASE-URL/<tenant id>/<project GID>.<release|preview>.files/<media GID>.<language>_<country>_<resolution>/binary

S3 with CloudFront distribution

https://<cloudfront base url>/<s3 object path>

S3 REST API

https://<s3 rest api url>/<s3 object path>
CaaS

The URL to the binary data consists of the following elements:

  • the base URL of the CaaS endpoint

  • the CaaS database corresponding to the Tenant ID.

  • the CaaS file bucket <project GID>.release.files or <project GID>.preview.files depending on whether a medium is in release or preview state.

  • the FirstSpirit GID of the medium, as well as language and/or resolution (if the medium depends on language and/or resolution).

  • the suffix /binary

In the JSON of a media file, the URL to the binary data points to the CaaS REST API:

Example: JSON of a media document pointing to the CaaS REST API
{
    "_id": "3b3fe5b6-9ec1-4e45-84c8-bc6a39d0aa61.en_US",
    "fsType": "Media",
    "name": "thisisatest",
    ...
    "resolutionsMetaData": {
        "ORIGINAL": {
            ...
            "url": "https://CAAS-BASE-URL/defaultTenant/e54cb80e-1f9c-4e8d-84b8-022f473202eb.preview.files/f6910b22-6ae8-4ce1-af45-c7b364b3117a.ORIGINAL/binary"
        }
    },
    ...
}
S3 object path

The S3 object path is composed of:

  • the configured path prefix (default prefix is /)

  • the GID of the project and the path segment /preview or /release depending on whether the medium is in release or preview state.

  • the rest of the path and the filename, which are derived from the URL factory defined in the service configuration (see seoRouteFactory in the full configuration example) or if present from the project-specific configuration.

Example of an S3 object path:
/631e4786-0dc3-4db6-bad8-adaad685944a/preview/FirstSpirit/images/thisisatest.png

CloudFront

The binary file is accessible through a CloudFront distribution that is configured to use the S3 bucket.
In the JSON of a media file, the URL points to the CloudFront domain my-cloudfront-domain.tld:

Example: JSON of a media document pointing to the CloudFront distribution domain
{
    "_id": "3b3fe5b6-9ec1-4e45-84c8-bc6a39d0aa61.en_US",
    "fsType": "Media",
    "name": "thisisatest",
    ...
    "resolutionsMetaData": {
        "ORIGINAL": {
            ...
            "url": "https://my-cloudfront-domain.tld/631e4786-0dc3-4db6-bad8-adaad685944a/preview/FirstSpirit/images/thisisatest.png"
        }
    },
    ...
}
S3 REST API

URL to a media file is composed of the S3 REST API and the path of the S3 object.
For example, the URL points to the original resolution of an image in the S3 bucket my-bucket located in the region eu-central-1:

Example: JSON of a media document pointing to the S3 REST API
{
    "_id": "3b3fe5b6-9ec1-4e45-84c8-bc6a39d0aa61.en_US",
    "fsType": "Media",
    "name": "thisisatest",
    ...
    "resolutionsMetaData": {
        "ORIGINAL": {
            ...
            "url": "https://my-bucket.s3.eu-central-1.amazonaws.com/631e4786-0dc3-4db6-bad8-adaad685944a/preview/FirstSpirit/images/thisisatest.png"
        }
    },
    ...
}

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.

Details of any third-party software products not produced by Crownpeak Technology GmbH that are used, their own licenses and any update information can be found in the META-INF/licenses.csv file supplied with the module.

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

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