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.250812, 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.
3.1.1. Configuration dialog
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.
|
Please note that when the CaaS module 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. |
|
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. |
|
If password encryption is set active in the FirstSpirit server, the values for |
3.1.2. 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 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.
3.2.1. Configuration dialog
The configuration dialog of the project component displays useful information like the CaaS base URLs and offers project specific configurations options.
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.
- Generation of URLs/routes
-
The default URL Factory, which is used to generate media binary URLs, as well as dataset and pageRef routes, is
Advanced URLs. It can be overridden on a project-specific basis. 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)andInfix URLs (SEO).
|
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 when the |
- 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 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. |
3.2.2. Schedules
Additionally, multiple schedules are created after adding the project component to a project. The schedules synchronize the preview or release content between FirstSpirit and the CaaS platform. In case of pre-existing project content these schedules can be used to populate the CaaS as well.
More information is available in the chapter Manual data reconciliation of the module documentation.
|
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. |
3.3. WebApp Component
The WebApp component CaaS Connect Web App provides a status report for CaaS documents in the ContentCreator. This dialog allows project administrators to check the synchronization status of the currently displayed page reference between FirstSpirit and CaaS.
3.3.1. Installation
To use this UI extension in the ContentCreator, 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.
After successful installation, the status report dialog is available in the ContentCreator via the “Actions” menu.
3.3.2. Status Report for CaaS Documents
The status report is used to check whether a FirstSpirit element exists in the CaaS and whether the contents match. It helps project administrators identify discrepancies by displaying the current status for each language and version combination. Additionally, further information, such as the associated revisions and links to the CaaS document, is provided.
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.
|
Synchronizations triggered via the dialog count toward the CaaS Connect fair use limit, just like jobs. |
- 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.
- 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.
4. Configuration via the file system
Besides the manual configuration via the FirstSpirit user 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. |
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"
}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) URL Factory that is used to generate SEO routes in media documents
"seoRouteFactory": "Advanced URLs"
}
},
// (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 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. |
|
It is necessary to restart the service after making changes to the configuration. Only then will they be active. |
|
If password encryption is set active in the FirstSpirit server, |
|
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.
6. Legal information
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.
7. 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.
8. 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.