1. Introduction

The CaaS module is the component that runs on the FirstSpirit Server. It enables the compilation and dispatch of information to the CaaS platform. The information concerns all new, changed or deleted editorial content of the used FirstSpirit project.

In addition to processing the release state, there is also the possibility to implement a preview of the unreleased contents. This can be realized with the help of a so-called Preview CaaS.

2. Technical requirements

To use the CaaS module, an installed and configured CaaS platform must be available. A valid CaaS license is also required to use the CaaS module.

A missing or invalid CaaS license will abort any CaaS generation with an error message.

Manipulations to the license make it invalid. If changes are necessary, please contact Technical Support.

For system requirements please consult the technical data sheet of the CaaS module.

3. Installation and configuration

In order to combine the data of a FirstSpirit project in such a way that it can be processed by the CaaS platform, various FirstSpirit components must be installed and configured. The necessary steps are explained in the following subchapters.

3.1. Installation of the module

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

modules
Figure 1. modules

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

If the use of CaaS is not licensed, an error message will appear when installing the CaaS module. However, it only points out the invalid license without preventing or aborting the installation.

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.

After each installation or update of a module a restart of the FirstSpirit Server is necessary.

3.1.1. Configuration of the CaaS service

To transfer data to the CaaS platform, a connection between the platform and the FirstSpirit Server is required. For this purpose, a default configuration must be specified in the service of the module. If another CaaS instance is to be filled in deviation from this default configuration, it can be defined in the generation schedule.

For the default configuration, open the ServerManager and select the menu:Server Properties [Modules] area. Then expand the folder Content as a Service and select the service contained in this folder (see figure CaaS Service).

c service
Figure 2. CaaS Service

The dialog that is opened via the Configure button has four fields that are to be filled in as described below.

service
Figure 3. CaaS Service - Configuration
REST API URL

In this field, enter the URL where the REST Interface of the CaaS platform can be reached. During installation and configuration of the CaaS platform this is determined by the network configuration used.

API Key

At this point an API Key is required that has write permission for all CaaS projects. Alternatively the Master API Key can be used. See the CaaS platform documentation for more information about the creation of API Keys.

Proxy-URI (optional)

In case the REST Interface can only be reached via a proxy server, its URI must be specified here. Otherwise this field can be left empty.

Parallelism of media generation

The numeric value in this field indicates the maximum number of media processed simultaneously. This setting is valid server-wide. It is therefore not evaluated per schedule, which means that all schedules on a server share this restriction at the same time. By default, a value of 8 is already defined at this point, which is sufficient for most situations and therefore does not require adjustment.

Nevertheless, an adjustment can be helpful in the following scenarios, for example:

  • high FirstSpirit-side memory consumption
    With FirstSpirit-side processing, each medium requires at least the amount of memory it consumes on the hard disk. Therefore, a generation operation that contains a lot of large media can be a limiting factor for the media to be processed simultaneously. In case of memory problems, reducing the value may result in less memory consumption. The minimum value is 1.

  • lower FirstSpirit-side memory consumption
    If FirstSpirit projects predominantly carry small media, the parallelism can be increased to increase the throughput of media.

3.2. Configuration of the settings page

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.

3.3. Project component

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.

tpp p list
Figure 4. 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.

3.3.1. Project

When transferring media to CaaS, additional metadata is also transferred and stored in CaaS by default. A list of these metadata fields can be found in the chapter Additional metadata.

Thus, there are always two URLs for each referenced medium. While the ID of the medium is used to query the metadata, the content of the metadata contains the URL of the binary data of the medium. This aspect must be taken into account when generating URLs for referenced media.

For this reason, the tab Project in the configuration dialog of Project component provides two configuration options for media generation:

Media URLs point to content (binary)

This option causes the generated URL for a referenced medium to point to the binary data of the medium.

Media URLs point to metadata (JSON)

Selecting this option activates the generation of media URLs that point to the corresponding metadata. This option assumes that the referenced media are also stored in CaaS.

In addition to the configuration of the media URLs, the evaluation of the FirstSpirit metadata can be configured at project level. It is possible to evaluate the metadata template and thus transfer an adapted format of the metadata to CaaS.

Metadata template is evaluated

The FirstSpirit metadata template is rendered and transferred to CaaS. The transfer of the template form values is thus the responsibility of the template developer.

Metadata template is not evaluated

The FirstSpirit metadata template is not evaluated, but the contents of the input fields are transferred to CaaS as JSON structure. (default behavior)

The options shown in this tab interact with the configurable options of the tabs Job Configuration and Preview Configuration.

tpp g conf
Figure 5. Project component - Project

3.3.2. Release state

Projects are always individual and have specific requirements. One of these requirements may be to store media not in CaaS, but in a third party system.

For this reason, the tab Release state in the Project component configuration dialog provides two configuration options for processing media:

Generate media in CaaS

This option corresponds to the use of the standard CaaS generation, where the referenced media are transmitted to and persisted by CaaS.

Use FirstSpirit default generation

Selecting this option causes the FirstSpirit default mechanism to be used and the media to be stored in the file system. This can be useful for subsequent processing of the media, such as transfer to a CDN.

If the option FirstSpirit Use default generation is activated, the option Media URLs point to content (binary) must be selected in the tab Project. If the option Media URLs point to metadata (JSON) is selected there instead, the selection will change automatically.

If, in combination with a possibly assigned CDN prefix, the folder names in the generation directory are not generated as desired, you can set the parameter caasEnsureMediaPathStartsWithSlash to the value true in the properties of the action Initialize CaaSGeneration of the generation schedule.

For backwards compatibility, this option must be explicitly enabled.

The following fields are only available if the option Use default generation is selected.

CDN prefix for media

If you want media to be served from a CDN instead of CaaS, you can specify a prefix in this field. This can be the same as specifying a host name and, if necessary, a context path. It is prefixed to all URLs generated during generation by the URL Factory used.

The transfer of the media to the CDN can be solved with the help of the usual FirstSpirit mechanisms and is not part of this documentation.

URL Factory for media use

The CaaS module has its own URL Factory for the generation of media and their URLs. At this point, the URL factory to be used when using the FirstSpirit default generation must be specified. There is a selection of URL factories available on the FirstSpirit server. If no selection is made, Advanced URLs will be used by default during CaaS generation.

For technical reasons, only a limited selection of the path generation methods installed on the server is available in this field: These must implement the Java interface UrlFactory. For the implementations provided by FirstSpirit this applies to the Advanced URLs (AdvancedUrlFactory), as well as the CaaS URL Creator (CaaSUrlFactory).

tpp p conf
Figure 6. Project component - release status

3.3.3. Preview state

When processing unreleased content, it is important to note that mixing the release status with unreleased content must be avoided. This is solved with a Preview CaaS. At this point it is assumed that a Preview CaaS already exists in the CaaS platform and its URL is known.

In order to be able to automatically generate unreleased content when changes are made to a FirstSpirit project without executing a job, the FirstSpirit Eventing API is used.

Using CaaS in conjunction with the FirstSpirit Omnichannel Manager requires the installation and configuration of the Omnichannel Manager module. The necessary steps are described in the documentation for the FirstSpirit Omnichannel Manager.

The configuration for using the Preview CaaS is done in the tab Preview state of the configuration dialog of the Project component:

REST API URL

To use Preview CaaS, its URL must be specified. The URL depends on the chosen implementation of the Preview CaaS in the CaaS platform.

If the field remains empty, the preview functionality is disabled for the respective FirstSpirit project.

API Key

At this point, a API Key is required that has write permission for the project in use.

Proxy URI

In case the REST Interface can only be reached via a proxy server, its URI must be specified here. Otherwise this field can be left empty.

Template set

At this point, the template set must be selected, in which the CaaS contents to be generated are defined.

Language

Select all languages for which contents are to be transferred to the Preview CaaS.

Template evaluation context

The standard FirstSpirit functionality allows template developers to display certain editorial content in the FirstSpirit preview or ContentCreator only. With the generation of the unreleased content, this content can also be transferred to the Preview CaaS. The context selection determines whether all preview contents or contents intended exclusively for the ContentCreator are transferred. The option Preview corresponds to the case #global.isPreview = true and #global.is("WEBEDIT") = false, while the option ContentCreator covers both #global.is("WEBEDIT") = true and #global.isPreview = true. The default setting, Default does not capture any of the above parameters and returns false for both #global.isPreview and #global.is("WEBEDIT").

Media usage

In conjunction with the Preview CaaS, it may be useful under certain conditions to obtain media from the FirstSpirit Server rather than from CaaS when displaying the preview. Two options are available for the corresponding configuration:

Generate media in CaaS

This option corresponds to the default behavior, where the referenced media are retrieved from CaaS.

Use media from FirstSpirit preview

Selecting this option causes the FirstSpirit defaults to be used to display media in the preview and retrieve them directly from the FirstSpirit Server. In this case the media will not be stored in CaaS and the generated media URLs will point to the FirstSpirit internal preview.

If the option Use media from FirstSpirit preview is activated, the option Media URLs point to content (binary) must be selected in the tab Project. If the option Media URLs point to metadata (JSON) is selected there instead, the selection will change automatically.

Variables

No page variables are evaluated within the preview. Here you can set variables that are available in the page context at the time of generation.

tpp b conf
Figure 7. Project component - Preview

3.4. Conversion rule

The definition of the data to be transmitted at CaaS is done in the template set that still has to be created. The data is JSON objects in which character strings are identified by double quotation marks. If double quotation marks were also included in the output, this would result in invalid JSON objects. For this reason, a conversion rule must be created to avoid potential errors.

It is recommended that you create a new conversion rule instead of editing an existing one. To do this, create a text file in your file system and add the following content to it:

conversion rule
0x22="\""

Then open the server and project configuration and select the item Server properties  Conversion rules. In the main panel you will see a list of existing conversion rules. After clicking Add, select the previously created text file from your file system and confirm the selection with Open. The list in the main panel will then be extended by the new rule to be assigned to the template set to be created.

Further information can be found in the FirstSpirit Documentation for Administrators.

3.5. Template set

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

templateset
Figure 8. create template set

In the selection box of the same name, the previously created conversion Rule must be selected.

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.

3.6. Generation schedule (full generation)

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.

fullgeneration
Figure 9. full generation

To avoid data loss in CaaS in case of an error, the checkbox Execute even in case of error must be deactivated for all actions of the schedule except the Finalize CaaS Generation.

Page references with an empty template set cause the generation to be aborted. For this reason, care must be taken within the project to generate only the necessary page references during generation, or to skip the corresponding pages during CaaS generation.

3.6.1. Initialize CaaSGeneration

Within the schedule, an initialization must first take place. This ensures the transmission of the messages generated by FirstSpirit to CaaS.

initialize CaaS Generation
#! executable-class
com.espirit.caas.generation.CaaSScheduleInitializer

Furthermore, the call activates the generation to be carried out in the next step, which cannot be carried out without this activation. The action is therefore obligatory for successful generation.

If it is necessary to fill a specific CaaS instance with data, after the script has been created, its properties can optionally be adjusted, and the following parameters can be created via Add:

  • caasUrl

  • caasApiKey

  • caasProxyUri

  • caasMaxTransferTimeoutInMs

  • caasMaxTransferRetries

timeout
Figure 10. parameters

If the REST Interface of the specific CaaS instance is accessible via a proxy server, its URI can be specified additionally.

If the parameters are missing at this point, the generation uses the default configuration defined in the Service. If they are specified, they overwrite the default configuration.

The parameters are not mutually dependent and can therefore also be defined individually.

The parameters caasMaxTransferTimeoutInMs and caasMaxTransferRetries influence the behavior of the module with regard to the transfer of data to the CaaS platform. They are not globally adjustable and are only needed in case of problems. In this case an error message during the FirstSpirit deployment indicates that the values need to be increased. A single transfer always aborts when the value of the parameter caasMaxTransferTimeoutInMs is exceeded. If a problem occurs during the transfer, it will be repeated as often as the value of the parameter caasMaxTransferRetries allows.

3.6.2. CaaS Generate

The generation activated in the previous action is executed by the generation action to be added.

Any name (here: CaaS Generate) must be specified in the Properties of the generation. Make sure that the option Generate only if necessary is deactivated and the option Generate release version is activated (see figure properties). Furthermore, the CaaS URL Creator must be selected for Path Generation.

caasgenerate
Figure 11. properties

Using a custom URL Creator in a CaaS scenario is not possible because URLs must be created in a fixed, CaaS-compatible schema. Selecting your own URL Creator in the Properties of the generation is therefore not allowed. If the user nevertheless makes a selection, it has no effect.

Depending on whether the order generates the release or preview state, the URL generation is automatically adjusted internally. Thus the FirstSpirit preview URLs are generated in a preview state schedule when the media are controlled via FirstSpirit (see figure Project component - release status). For a schedule with generation of the release state, however, the configured URL factory is still used.

In the register Extended the previously created template set must be selected for all languages of the project (see figure extended).

caasext
Figure 12. extended

Since a generation of the CaaS module itself already works in parallel, the use of several parallel generation actions in one schedule is not supported. The option for parallel execution of several generation actions must therefore not be activated. The number of parallel connections can be defined during the module configuration and, if necessary, can be overwritten per schedule .

Use of the CaaS module requires a valid license. A missing or invalid CaaS license interrupts the data transfer between it and the CaaS platform.

3.6.3. CleanUp

To ensure that the data is always up-to-date, the information deleted in the FirstSpirit project must also be removed in CaaS. The following script call ensures this:

cleanup
#! executable-class
com.espirit.caas.generation.CaaSCleanupExecutable

If different generations - even within a FirstSpirit project - use the same project, no cleanup process may take place here, otherwise one of the generations will clean up the data of the other schedule.

The action only deletes obsolete information within CaaS. However, the potentially empty collections in which the transferred data is stored are always retained (see also chapter Transmission of documents).

This script action may only be used in conjunction with full generation. If it is used in partial or delta generation, data will be lost CaaS-sided.

3.6.4. Finalize CaaS Generation

The action Finalize CaaS Generation is used to detect errors during the delivery of the generated messages.

To do this, create another script and add the following code to it:

finalize CaaS Generation
#! executable-class
com.espirit.caas.generation.CaaSScheduleFinalizer

In contrast to the other actions of the schedule, the Finalize CaaS Generation must be executed even in case of an error. Otherwise, a failed job may result in a subsequent deployment being impossible to execute. In this case a restart of the FirstSpirit Server is required.

3.7. Generation schedule (delta generation)

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.

deltageneration
Figure 13. delta generation

When duplicating the full generation, the action CleanUp must be removed. In connection with delta generation it leads to data loss on the CaaS side and may therefore only be used in full generation.

In the properties of the CaaS Generate action, the option Generate only if necessary must be disabled and any existing startup nodes must be removed.

To avoid data loss in CaaS in case of an error, the checkbox Execute even in case of error must be deactivated for all actions of the job except the Finalize CaaS Generation.

If no changes were made to the project between the current and the last delta generation, the job simply runs through. In this case no pages are generated and therefore no information is transmitted to CaaS.

3.7.1. CaaS Delta Generation

The CaaS DeltaGeneration action determines the changes made since the last generation within the FirstSpirit project used. It also configures the subsequent generation action. In this way, the update of the data stored in CaaS is realized via a minimum amount of data transfers to the REST Interface.

It is therefore absolutely necessary that the action is executed after the initialization and before the generation.

A script action with the following content is used to determine the changes made and to transfer the necessary information to the generation action:

CaaS Delta Generation
#! executable-class
com.espirit.caas.generation.CaaSDeltaGenerationExecutable

Handling of data sources

In the context of delta generations, newly created or changed datasets lead to a processing of all page references that have included the corresponding data source. As a consequence, all datasets are retransferred to CaaS.

For all content projections that generate exactly one dataset per page, this behavior can be optimized so that only the changed data is transferred to CaaS.

To do so, please set the parameter caasOptimizeSingleDatasetDeployment in the properties of the action CaaS DeltaGeneration to the value true. For backwards compatibility reasons, this option must be explicitly enabled.

4. Definition of the contents

The CaaS module provides the possibility to transfer editorial content to CaaS. These must be defined in the template set previously created. The selection of the information to be transferred is always individual and must therefore be based on existing project-specific requirements.

4.1. Normalization of the FirstSpirit project, collection and document names

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 restriction is that the name must not begin with an underscore. Any other characters, such as spaces and special characters, are removed.

Since the project name within the CaaS serves as an identifier, its uniqueness must be maintained even after normalization. This aspect must therefore be taken into account when assigning project names.

4.2. Transmission of documents

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.

The filling of the template set is arbitrary and could look like the following for products from the demo project Mithras Energy:

table template - Products
{
   "name": "$CMS_VALUE(cs_name.convert2)$",
   "description": "$CMS_VALUE(cs_description)$",
   "picture": "$CMS_REF(cs_picture,abs:2)$",
   "properties": [
      $CMS_FOR(for_property,cs_properties)$
         $CMS_VALUE(for_property)$$CMS_IF(!#for.isLast)$,$CMS_END_IF$
      $CMS_END_FOR$
   ]
}

When referencing media using CMS_REF, it is necessary to use the 'abs:1' or 'abs:2' parameter. This parameter is used to generate absolute URLs. Otherwise, the generated URLs cannot be used to query the media from the CaaS. Further information can be found in the Online Documentation for FirstSpirit under Template development  Template syntax  Instructions  CMS_REF.

In the next example, for each product, the name, description, product image and product properties are transferred to CaaS. The product properties are taken from a separate table. The information is therefore not directly available, but is stored in the respective product as an array of JSON objects. The template set of the corresponding table template must also be filled accordingly.

table template - Product properties
{
   "property" : "$CMS_VALUE(cs_property)$",
   "value" : "$CMS_VALUE(cs_value)$"
}

A preceding underscore as well as the prefix fs_ are reserved as namespace, since they identify internal attributes. The use of the prefix or a preceding underscore is therefore not permitted for the identifiers of the fields. The same applies to the attribute name filename. Otherwise, data will be lost in CaaS.

During generation, a call is generated for each page reference. For this reason, all information to be transferred must be available in the template set of the corresponding page reference to be taken into account during generation. In the case of the example described, only the output of the content area that references the products is required in the template set of the page reference.

page template - standard
$CMS_VALUE(#global.page.body("Content center"))$

When nesting JSON objects across different templates, it is imperative to ensure that validity is maintained. If the JSON is invalid, generation terminates and no information is transferred to CaaS.

No message to CaaS is generated for page references to external addresses, so there is no entry for them in CaaS. Corresponding statements in the template set are not evaluated.

Page references with an empty template set cause the generation to be aborted. For this reason, you must make sure within the project that you only create the necessary page references during generation. Such a restriction can be achieved by partial generation, for example.

Alternatively, it is possible to prevent the activation of a generation in a template. To do this, the page variable caasSkipMessage must be set within the template set:

caasSkipMessage
$CMS_SET(#global.pageContext["caasSkipMessage"], true)$

In this case no content is transferred to CaaS and any existing content is deleted as part of the CleanUp.

Further information can be found in the Online Documentation for FirstSpirit under Template development  Template syntax  System objects  #global  preview-specific  Cancel a generation.

4.3. Transmission of media

As mentioned in the previous chapter, media can also be transferred to CaaS. For this purpose, they must be defined either directly or by specifying the corresponding input component in the template set.

A preceding underscore is reserved for the reference names of media as namespace, since it identifies internal resources. During generation, such a reference name of a medium prevents the medium from being transferred to the CaaS and generates a corresponding error message in the generation log.

referencing of images in the template set
{
   "logo" : "$CMS_REF(media:"fs_logo",resolution:"Teaser",abs:2)$",
   "picture" : "$CMS_REF(pt_picture,abs:2)$"
}

If the medium is an image, the resolution in which it is transferred to CaaS can be determined. In addition, the use of the parameter abs:1 or abs:2 is required for all media. This parameter is used to generate absolute URLs. Otherwise, the generated URLs cannot be used to query the media from CaaS.

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.

4.4. Additional metadata

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

  • Id (fs_id)

  • Language (fs_language)

  • Timestamp (fs_date)

  • Execution of the schedule (fs_scheduler_date)

  • Reference name (fs_reference_name)

  • Revision Id (fs_revision_id)

  • FirstSpirit UID Type (fs_uid_type)

  • Project Id (fs_project_id)

  • Object type (fs_object_type)

  • FirstSpirit metadata (fs_metadata)

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

  • File extension (fs_extension)

  • Resolution - width (fs_resolution_width)

  • Resolution - Height (fs_resolution_height)

  • Checksum (fs_crc)

  • Description (fs_description)

  • Mimetype (fs_mimetype)

  • File size (fs_size)

  • File encoding (fs_encoding)

4.5. Adjustment of project/collection in CaaS

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.

plugin
Figure 14. menu bar and context menu

These settings can only be made by a project administrator.

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.

When transferring to CaaS, the document name is supplemented by a language suffix, which allows a language-dependent storage of the contents.

edit pagereffolder
Figure 15. Change the collection name for a structure folder
edit pageref
Figure 16. Change the collection and document name for a 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.

A preceding underscore is reserved as namespace for collection or document names, since it identifies internal resources. During generation, such a name prevents the document from being transferred to CaaS and generates a corresponding error message.

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.

example
Figure 17. Example

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.

URL settings made in the Global Settings are not taken into account when generating JSON objects and therefore have no influence on URL generation.

5. Change and delete contents

The contents of a FirstSpirit project can be changed or deleted at any time during the normal editing process. In order to ensure that the release state is always up-to-date, changes must be incorporated into CaaS. Just like the initial filling of CaaS, an update is done by generation.

5.1. Renaming a FirstSpirit project

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.

5.2. Change of an assigned collection

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.

5.3. Change to an assigned CaaS project

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.

5.4. Deleting a FirstSpirit item

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.

5.5. Deleting a Project or Collection from 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.

A collection is potentially filled from different sources. For this reason, a generation can never delete it. Deleting both a collection and a project is basically only possible manually via the CaaS Admin Interface.

6. Best Practices

In this chapter solutions for questions that may arise when using the CaaS are shown.

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.

remote project
Figure 18. configuration dialog of a remote project

Remote access requires a license-dependent additional module. For further information please refer to the FirstSpirit CorporateMedia documentation.

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.

remote reference
<FS_REFERENCE name="remote" useLanguages="no">
    <LANGINFO>
      <LANGINFO long="*" label="Remote-Project"/>
      <LANGINFO lang="en" label="Remote project"/>
    </LONGINFOS>
    <PROJECTS>
      <REMOTE name="myself"/>
    </PROJECTS>
</FS_REFERENCE>

A prefix for absolute paths can be specified during generation. This is not possible for a remote project and must therefore be taken into account if necessary.

7. Maintenance

The transfer of FirstSpirit data to CaaS can only work if the individual components work properly. If faults occur or an update is necessary, both the FirstSpirit Server and all CaaS components must therefore always be considered. The following subchapters describe the necessary steps of an error analysis in case of a malfunction as well as the execution of a backup or update.

7.1. Error analysis

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.

Analysis of the logs

In case of a problem, the log files are a good starting point for analysis. They offer the possibility to trace all processes on the system. In this way, possible errors and warnings become apparent.

The schedule and server logs of the FirstSpirit Server can be viewed both in the Schedule overview and in the Server monitoring.

FirstSpirit-License

Transferring data to the CaaS requires a valid license. If no transfer takes place, an invalid license may be the cause.

Template error

The FirstSpirit contents are transferred to the CaaS as JSON objects. They are defined in the template set. Errors in the definition can lead to invalid JSON, which prevents the data from being transferred to CaaS. Errors of this type are expressed as generation errors in the schedule and are visible in the schedule logs.

Configuration of the schedule

If the CaaS does not receive any data, check that the deployment schedule has been completely created and configured according to the description. If, for example, the action Initialize CaaS Generation is missing, the job will still run without errors. In this case, however, only a deployment to the Staging directory of the FirstSpirit Server takes place and no data is sent to CaaS.

Specific CaaS instance

A specific CaaS instance can be defined instead of the CaaS platform specified during the configuration of the module. If this does not receive any data from the FirstSpirit Server, the configurations in the Initialize CaaS Generation action of the generation job must be checked. If the configurations of the specific instance are missing in this action, the generation uses the default configuration defined in Service.

7.2. Backup

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.

Depending on the backup, it is recommended to save settings and configuration changes separately.

7.3. Update

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.

After each installation or update of a module a restart of the FirstSpirit Server is necessary.

The CaaS module is a product of e-Spirit AG, Dortmund, Germany.

Only the licence agreed with e-Spirit AG applies to the user for the use of the module.

Details of any third-party software products used that are not produced by e-Spirit AG, their own licences and, if applicable, update information, can be found in the file 'THIRD-PARTY.txt', which is supplied with the module.

9. Help

The Technical Support of the e-Spirit AG provides expert technical support to customers and partners covering any topic related to the FirstSpiritâ„¢ product. You can get and find more help concerning relevant topics in our community.

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