Using FirstSpirit CaaS

The FirstSpirit CaaS Connect module is used for communication with FirstSpirit CaaS (also: “CaaS v3” / CaaS module from version 3). It represents the link between FirstSpirit and the delivering CaaS platform and supports the transfer of fragments out-of-the-box.
See the following documentation:

• general product documentation
• CaaS Connect
• CaaS Platform (only relevant for on-premises customers)

If, on the other hand, the previous version of FirstSpirit CaaS is used (“CaaS v2” / CaaS module in a version 2.x), the “CaaS Integration” module described on this page must be used in order to be able to publish the content of a fragment project via FirstSpirit CaaS.

CaaS v2 is obsolete and should only be used in migration contexts. The “CaaS Integration” module is not required for using FirstSpirit CXT with FirstSpirit CaaS v3.

Module "CaaS Integration"

Operating principle

Content from the fragment project is automatically

• exported into a CaaS instance (Preview) whenever a change is made.
• exported into another CaaS instance (Live) whenever a release occurs.

Alongside this event-based transfer of content, it is also possible to publish all of the content of a fragment project directly via FirstSpirit CaaS (see Execute deployment via schedule entry).

Module file

caas-integration-[version].fsm

Installing the module

The module is installed using the FirstSpirit ServerManager, in the “Server properties / Modules” dialog using the “Install” button:

(For more information about installing modules, see also Modules (→Documentation for Administrators).)

Starting "CXT CaaS Integration Service"

The “CaaS Integration” module contains the “CXT CaaS Integration Service”. Following installation, a dialog where the Autostart option for the service can be configured is displayed. If the dialog is confirmed by clicking on “Yes”, the service is started automatically every time the server is restarted.

The service can also be started at a later point in time via the “Start service” and “Activate Autostart” buttons.

Configuration

CaaS Integration is configured at the project level. If a fragment project is to make its content available via FirstSpirit CaaS v2, the project component “CXT CaaS Integration Configuration” must be configured for each fragment project.

First, the project component “CXT CaaS Integration Configuration” must be added to the project in the ServerManager via “Project properties / Project components”.

For common information about how to configure project components please see Project components (→Documentation for Administrators).

The project component “CXT CaaS Integration Configuration” provides a configuration interface.
It is opened in the ServerManager via “Project properties / Project components / Configure” or double click on the Project component:

Tab:

LIVE: The content from the fragment project is exported into the CaaS instance configured here whenever a release occurs.

PREVIEW: The content from the fragment project is exported into the CaaS instance configured here whenever a change is made.

Parameters:

URL: URL for the CaaS instance.

PROXY_URI: Specifies a proxy address used to establish the CaaS connection. If the field remains empty or if spaces are entered, no proxy is used.

COLLECTION_NAME: Specification of a name for the collection to which the contents are to be transferred.
If you leave this field empty, the reference name of the respective page template is used (fragment type, see Defining fragment types).

API_KEY: Specification of a CaaS API key (see documentation about the CaaS Platform or common cloud information).

The configured API_Key must enable write (and read) access.

URL_CREATOR: Selection of the desired URL Creator.
When using the FirstSpirit CaaS v2 module, the “CaaS URL Creator” supplied with the module can usually be selected. This generates URLs that meet the special requirements for CaaS URLs. As an alternative, you can also implement your own URL Creator and select it here. See also Generation (→FirstSpirit Online Documentation).
If no selection is made, the URL Creator “Preview URLs” will be used for all instances.

Execute deployment via schedule entry

In addition to the event-based transfer of content from a fragment project (in case of a change event or a release event), it is also possible to publish the entire content of a fragment project using a schedule entry script.

Two executables are available for this (for deployment on the Live CaaS server and the Preview CaaS server):

• cxt-caas-integration-full-live-deployment-executable
  (provides all released content)
• cxt-caas-integration-full-preview-deployment-executable
  (provides all changed content)

The deployment into the two CaaS instances is executed using separate schedule entries.

To do this, a new default schedule entry is created in the schedule management menu via “Add / Default schedule”. A new action is then created within the schedule entry in the “Action” tab: “Add / Execute script / Apply”.

The corresponding executable is added to this script.

For providing the project contents on the Preview CaaS server:

#!executable-class
cxt-caas-integration-full-preview-deployment-executable

or for providing the project contents on the Live CaaS server:

#!executable-class
cxt-caas-integration-full-live-deployment-executable

When the schedule entry is executed, the project contents from the fragment project are made available for publishing on the configured CaaS server.

Output via JSON

JSON (JavaScript Object Notation) is used to exchange fragments between FirstSpirit CXT and FirstSpirit CaaS. The template set of the project must be adapted accordingly. See also Single expression page rendering (→FirstSpirit Online Documentation) and Support for JSON (→Documentation for Administrators).

Example of fragment/variant output via JSON:

{
  "fragmentUUid": "$CMS_VALUE(#global.page.parent.uid.replaceAll("_","-"))$",
  "documentUUid": "$CMS_VALUE(#global.page.uid.replaceAll("_","-"))$",
  "variation": $CMS_VALUE(#global.page.meta("variations").toJSON())$,
  "title": $CMS_VALUE(#global.page.meta("title").toJSON())$,
  "text": $CMS_VALUE(text.toHtml().toJSON())$,
  "url": "$CMS_VALUE(url)$"
}