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. Using the CaaS Connect module reduces the configuration and administration effort in the FirstSpirit project for the delivery layer considerably.

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

1.1. Technical requirements

Besides the FirstSpirit version 5.2.220807, the module requires access to the CaaS platform. An API key with appropriate permissions must be configured, and the accessibility of the platform endpoint over the network must be ensured. For more information on installing and using the CaaS platform, refer to the appropriate documentation.

2. 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, the project data is not automatically synchronized after the module is installed. In order for the module to work as expected, the service component must be configured.

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

3. Components

In the following chapters all components of the module and their administration are described.

3.1. Service

The service component CaaS Connect Service is the link between the projects on the FirstSpirit server and the CaaS platform. In order for project content to be transferred to the platform, the service must be started. If the service is stopped, no synchronization takes place. A valid configuration is required to operate the service. 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 different configuration points are explained in more detail in the chapter Configuration via the file system. The minimal configuration includes a reachable CaaS platform and an API key that has read and write access to all CaaS projects. More information about API keys and permissions can be found in the CaaS platform documentation.

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

Please note that when the CaaS endpoint 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.

The tenant ID may consist of a maximum of 63 characters and is not case-sensitive.

A detailed explanation of the resulting URL scheme can be found in the CaaS Connect documentation.

3.1.1. Media hosting

Media binary data can be stored either in the CaaS platform or in an S3-compatible service. Uploading binary data to the CaaS platform is the default configuration. If binary data is to be delivered via a S3 service, the configuration of the service component CaaS Connect Service must be adjusted accordingly.

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. If needed, a full synchronization can be performed to avoid having to make project changes. The two schedules that were automatically created can be used to trigger a full synchronization for this purpose.

Hosting via S3: Both Amazon S3 and S3-compatible services can be used for delivery. The specification of an S3 endpoint is optional. If no end point is specified, it is assumed that Amazon S3 is being accessed. In this case, a client region must be specified so that the Amazon end point can be determined. It is composed as follows: s3.$clientRegion.amazonaws.com. The access credentials for the S3 service are also optional. 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.

If an S3-compatible service is used without using a CloudFront domain, the links of the binary data of media files will use the virtual hosted-style format. For more information about the format and its limitations see Virtual hosting of buckets and Amazon S3 Path Deprecation Plan.

3.2. Project component

When adding the project component CaaS Connect project app to a project, it activates the CaaS Connect module for that project. The configuration dialog of the project component displays useful information like the CaaS base URLs and offers project specific configurations options.

project app config
Figure 2. Configuration dialog of the project component of CaaS Connect

The configuration of the URL factory that is used for generating URLs to media binary data and Dataset routes can be overwritten on a per-project basis.

After changing the URL factory configuration it is necessary to overwrite all CaaS content to apply these changes. For more information on how to overwrite the CaaS content using the schedules see Overwrite the complete data set.

The configured URL Factory is used to generate media binary URLs only if the hosting of media binary data is disabled through the NoBinaryUpload option within the module configuration.

The displayed project-specific API keys are automatically generated by the CaaS Connect module. For preview and release of the project, one API key with read only permission and one API key with read and write permission are provided.

3.3. Schedules

Additionally, two schedules are created after adding the project component to a project. The schedules CaaS Connect Preview Generation and CaaS Connect Release Generation synchronize the preview or release content between FirstSpirit and CaaS.

In case of pre-existing project content these schedules can be used to populate the CaaS as well.

4. Configuration via the file system

Besides the manual configuration via the FirstSpirit interface, CaaS Connect version 3 or later on 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 configuration, content of the caasConnect.json file
{
  // The CaaS platform endpoint
  "baseUrl":"http://localhost:8080",
  // The API key that is used for data transfer between module and platform
  "apiKey": "ef27ef88-11c1-4ba0-946c-5c82d2880a18",
  // The name or abbreviation of the tenant
  "tenantId": "defaultTenant"
}
Content of the caasConnect.json file
{
  // URL to the API of the CaaS platform
  "baseUrl": "http://localhost:8080",
  // API key for data transfer between module and platform
  "apiKey": "ef27ef88-11c1-4ba0-946c-5c82d2880a18",
  // The name or identifier of the tenant
  "tenantId": "defaultTenant",
  // (Optional) Configuration for uploading and serving media files via an S3 bucket
  // Default configuration: CaaS is used to serve media files
  "mediaConnectorConfig" : {
    "S3": {
      // (Optional) URL to an S3-compatible API endpoint
      // Default configuration: AWS API endpoint (https://s3.{region}.amazonaws.com)
      "endpointUri": "https://s3.eu-central-1.amazonaws.com",
      // (Optional) S3 credentials for uploading media files
      // Default configuration: uses the "Default provider chain" of the AWS Java SDK (see https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/credentials.html#credentials-chain)
      "credentials": {
        "accessKeyId": "mySecretS3KeyId",
        "secretAccessKey": "mySecretS3AccessKey"
      },
      // Name of the S3 bucket
      "bucketName": "examplebucketname",
      "timeoutInSeconds": 10,
      // (Optional) region of the bucket
      // Default configuration: uses the "Default region provider chain" of the AWS SDK (see https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/region-selection.html#automatically-determine-the-aws-region-from-the-environment)
      "clientRegion": "eu-central-1",
      // (Optional) "Cache-Control" metadata attribute added to the S3 object when uploading to the bucket
      // Default configuration: maxAge 300 seconds (5 minutes), maxAgeShared 900 seconds (15 minutes)
      "cacheControl": {
        "maxAge": {
          "seconds": 100
        },
        "maxAgeShared": {
          "seconds": 150
        }
      },
      // (Optional) Configuration to service media files via CloudFront distribution.
      // Default configuration: URL of the S3 bucket in virtual-hosted-style is used to serve media files (e.g. https://examplebucketname.s3.{region}.amazonaws.com/)
      "cloudFront": {
        // (Optional) URL to a CloudFront-compatible API endpoint
        // Default configuration: AWS CloudFront API endpoint (https://cloudfront.amazonaws.com)
        "endpointUri": "https://cloudfront.amazonaws.com",
        // Id of the CloudFront distribution
        "distributionId": "A4L1CDF3GND316",
        // Base url of the CloudFront domain
        "baseUrl": "https://my-cloudfront-domain.com",
        // (Optional) Enables/disables manual invalidation of files in the CloudFront CDN
        // Default configuration: files are not manually invalidated (invalidateFiles = false)
        "invalidateFiles": false
      }
    }
  },
  // (Optional) Endpoint of an HTTP proxy to use for communication with the CaaS platform or other services (S3, CloudFront)
  "proxyAddress": "foo:123"
}

If an error occurs while the service is reading the configuration file, a corresponding error message is displayed in 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 endpoint 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 UI 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.

Adding a project component to a project is also possible via the FirstSpirit API.

ModuleAdminAgent.installProjectApp("CaasConnect", caasConnectProjectAppName, project)

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 displayed in 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 lead to the data change.

5.2. Configuration of the API key

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.

5.3. Push notifications (change streams).

The change stream definitions can be found in the metadata of the collections. They are created at the same time as the collection. If the definitions are missing, they can be restored by triggering a new deployment by executing a schedule.

5.4. Indexes

Indexes that are provided by default for a collection are created at the same time as the collection. This happens when the CaaS Connect Service is started or when a deployment job is executed in the CaaS. If an index cannot be created, a corresponding warning is written to the FirstSpirit log.

If an index with the same content but a different name already exists in a collection, it remains unchanged. The same applies to an index with the same name but different content. In both cases, the new index cannot be created. The request is answered with HTTP status 406 and logged as a warning. Such warnings can either be ignored or the existing index can be deleted. A new attempt to create the index is triggered by starting the service or executing the request.

Information on existing indexes can be found in each collection under _indexes.

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.

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

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