CaaS Module

The module must be added to the FirstSpirit Server using the supplied caas-2.26.0.fsm file. To do this, open the ServerManager and select the Server properties  modules area.

The main panel shows a list of all modules installed on the FirstSpirit Server. After clicking on Install, select the caas-2.26.0.fsm file and confirm the selection with Open.

After the successful installation, the folder Content as a Service was added to the list of folders, which must be given All Rights using the Configure button (see figure modules).

The module also requires a configuration, which is explained in the following subchapter.

The CaaS generations require that a template for the project settings is maintained and released in the FirstSpirit project. Otherwise the generation job will abort early and report errors via the job logs.

Further information can be found in the Online Documentation for FirstSpirit in the area Documentation for editors inside the document FirstSpirit SiteArchitect under Global settings  Project Settings.

The settings defined in CaaS Service are valid server-wide. The Project component offers the possibility to partially overwrite these settings at the project level and should therefore be added to the project.

To do this, open the ServerManager and select the area Project properties  Project components.

In the main panel you can see a list of all existing Project components. After clicking Add, select the CaaSProjectConfiguration and confirm your selection with OK. The Project component is added to the list in the main panel and must then be configured (see figure Project components). To do this, select the entry in the list and open the corresponding configuration dialog via Configure.

The dialog is divided into three tabs, which are explained in the following subchapters.

In addition to the already existing template sets of a project, a new template set for the definition of the contents to be transmitted to CaaS is required, which must be created manually.

To do this, open the Server and Project Configuration and select the item Project properties  Template sets. By clicking on Add a dialog is displayed, which is to be filled as follows

Then confirm the dialog with OK to finish adding the template set.

The list of existing template sets is then extended by the new template set. This has been automatically activated and is thus directly available in the project.

Information about templating are described in section Transmission of documents.

The initial filling of CaaS as well as the later notification of changes in the FirstSpirit project is done by messages that the CaaS module sends to the CaaS platform. To create these messages, a schedule is required that contains at least the actions described in the following subchapters (see also figure full generation).

Open the ServerManager for the required schedule and select the Project properties  Schedule management area.

Add a new default schedule or edit an existing one.

A second schedule is required to create the messages, which only informs CaaS about the changes made since the last delta generation of this schedule. It must supplement the actions of full generation described in the previous chapter with the action CaaS DeltaGeneration (see also figure delta generation). This is explained in the following subchapter.

Because the CaaS platform allows only a limited choice of characters for naming, the project, collection, and document names from FirstSpirit are normalized in use. These normalized names only contain alphanumeric characters, as well as underscores and hyphens. The only additional restriction is that the project name must not begin with an underscore. Any other characters, such as spaces and special characters, are removed.

By default, FirstSpirit content is not transferred to CaaS. Therefore, the contents to be transferred must first be defined project-specifically. This definition is made in the template set created during the installation. In this template set, the contents are to be specified in the form of a JSON object.

Even though the JSON can be generated manually in the template, we strongly recommend using the json function provided by FirstSpirit. This has the following main advantages:

This reduces the configuration of the output channel to the following content:

More information is available in the Online Documentation for FirstSpirit under the item Enhanced JSON support  Single expression page rendering.

If you deviate from this recommendation, please always make sure first that valid JSON is generated via the templating valid JSON, as this is the main source of errors.

As mentioned in the previous chapter, media can also be transferred to CaaS. When using the json function provided by FirstSpirit, all referenced media will be processed automatically.

To allow language-dependent processing of the transferred data, all media are given a suffix corresponding to the language before being saved in CaaS. For language-independent media, the master language of the FirstSpirit project is the default suffix.

In contrast to all other transferred information, the persistence of the media in CaaS is not done in collections, but in a so-called bucket called assets.files.

The information defined within the FirstSpirit project are transferred to CaaS via Deployment. By default, they also contain the following FirstSpirit data:

For media, additional information is also transferred, if available:

By default, all information sent by the CaaS module is persisted in CaaS in a collection named content. It is automatically created on the first transmission and includes all content that is not media.

In addition to the default collection, additional collections can be defined to sort the contents in CaaS. This is especially useful if a large amount of different information is transmitted to CaaS.

Optionally, contents from one FirstSpirit project can also be transferred to several CaaS projects. This allows even finer sorting of complex data and enables advanced application scenarios, such as manual versioning.

The definition of additional collections and CaaS projects is done via a plug-in, which is provided via the menu bar as well as via the context menu in the Site Store of the FirstSpirit project.

The plug-in opens a dialog in which a CaaS project and a collection can be specified for the selected page reference or the referenced structure folder. The initial value of the CaaS project is derived from the name of the FirstSpirit project, the initial value of the collection corresponds to the default content collection (see figure Change the collection name for a structure folder). For page references, it is also possible to customize the document name (see figure Change the collection and document name for a page reference). This name is used to store the JSON objects generated on the basis of the page reference in CaaS. Without an adjustment, the document name corresponds to the reference name of the page reference.

If a CaaS project or new collection is defined on a structure folder, the change applies to all items subordinate to it. However, following the usual FirstSpirit behavior, specifying a collection for a child always takes precedence over specifying a collection for a parent. This means that the customization made for a structure folder is only applied to a child item if no change has been made to the child item itself.

Example

In the example shown in the following figure, a separate collection folder was specified for the structure folder. This adjustment affects the page 1 contained in it and the subfolder with the page 2 contained in it. Since a change was also made for page A and the page collection was selected, the parent definition has no effect on it.

During generation, the JSON objects based on page A are then stored in the page collection. However, the JSON objects generated by page 1 or page 2 are stored in the folder collection.

If the change to the collection or the document name for a force element is to be reversed, this can also be done using the plug-in provided. Note that the associated JSON objects are then processed according to the default configuration and saved in CaaS.

Changing the project name creates a new project in CaaS, which contains all current information. The initial project with the obsolete data is not automatically removed, but remains and must be deleted manually e.g. via the CaaS Admin Interface.

The persistence of all information transmitted by FirstSpirit takes place in CaaS in so-called collections. These can be freely defined within the SiteArchitect. Changing a collection for contents already persisted in the CaaS creates a consistent dataset only in the case of a full generation. The FirstSpirit contents are stored in the new collection and simultaneously removed from the initial collection. Since the initially selected collection potentially has other contents, it is retained. If it is no longer needed, it can be deleted via the CaaS Admin Interface, for example.

The Delta Generation only recognizes the change to a collection if additional changes have also been made to the corresponding contents. In this case the new collection is created including the changed contents. At the same time, however, the initial collection remains with the now obsolete information and an inconsistent dataset is created.

Without further changes to the contents, delta generation cannot determine the change to a collection. The new collection is therefore not created and the initial collection remains in existence, including its contents.

Like the assigned collection (see section Changing an Assigned Collection), the assigned CaaS project can also be freely defined. This results in behavior similar to changing collections with regard to cleanup and delete operations. If, for example, the CaaS project is changed for all items to be generated, no more cleanup is performed on the previously configured project and the old data is retained. For delta generation, additional changes must also be made to the corresponding contents. If an item is deleted on the FirstSpirit side, it is only deleted from the CaaS if it was previously transferred with the currently configured CaaS project.

Deleting a FirstSpirit item removes all associated information from the CaaS with the next generation. Even in this case, the associated collection is retained, even if the generation removes the last document from it. If the collection is no longer needed, it can be deleted using the CaaS Admin Interface.

Deleting a project or collection in the CaaS Admin Interface removes all information contained in the project or collection from the CaaS. Restoring the deleted data is not possible via the interface, but only via full generation. The delta generation only transfers the data since the last change. In this case, this creates an incomplete dataset in CaaS and inevitably leads to inconsistencies.

If the used FirstSpirit project creates static web pages in addition to the CaaS contents, there may be links between them. Since the CaaS content is generated with the CaaS URL Creator, but static content is generated with a different URL Creator, the links cannot be resolved correctly. Including your own project as a remote project circumvents this by specifying a URL Creator.

The linking of contents from the remote project is done via remote references. These behave for the editor in the same way as normal references within the project used. Only the use case differs.

If a malfunction occurs while using the CaaS module, it may be due to various causes. The basic analysis steps for determining the causes of faults are explained below.

For the FirstSpirit-sided backup, different procedures are available from which the preferred one can be selected individually. A detailed description of the corresponding procedure is contained in the FirstSpirit Documentation for Administrators.

If a newer version of the CaaS module is available, an update must be performed.

Just like the installation, the update of the CaaS module is done in the ServerManager in the Server Properties  Modules section. For this purpose the new version of the CaaS module must be selected via the Install button and installed on the FirstSpirit Server. A previous deinstallation of the module is not necessary.