Documentation “Content Experience Tools”

The CXT platform is the basis for clients who are already using the CXT technology to incorporate MicroApps. It currently covers three primary main functions:

an authorization server that is compatible with the “OAuth2” log, which secures access to other REST interfaces
the MicroApp Registry, in which MicroApps can register for the use from clients
a rudimentary REST-API for basic functions of FirstSpirit

Prerequisites

A SOCKET connection to the FirstSpirit Server is required.
The platform web app must be accessible via the same external host as the CXT clients (e.g., the FragmentCreator Web App, “same-origin”).

The use of this module is necessary only if the FragmentCreator module is used in a version 3.x.

Module file

platform-[version].fsm

Installing the module

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

Adapting the URL

The “CXT-Platform | Configuration Service” provides a configuration interface that can be opened by clicking on “Configure” or by double-clicking on the service. The URL to the MicroApp must be configured. In this case, the URL is the one through which the CXT MicroApp API can be integrated into a website.

This is the value of the cxt.platform.external-url parameter configured for the CXT Platform (see Configation):

https://external/cxt-platform/microapps/api.js

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

Creating a global web application

The web application must subsequently be defined and configured as a separate, global web application using FirstSpirit ServerManager in the “Web applications” area (button “Add” at “Configure global web apps”, see also Web applications (→Documentation for Administrators), paragraph “Installing global web applications”).

The value for Web Context must be

/cxt-platform

e.g.:

Adding a web component

Select a suitable web server for this global web application and then add and deploy the “CXT Platform” web component (“Install” / “Update” button):

Status page for error analysis

An incorrect configuration is a common source of errors. It can result in the software not functioning as expected or not functioning at all.

Under

/status

(appended to the URL of the platform), a status page can be reached which helps when detecting configuration problems, for example:

http://myServer:8080/cxt-platform/status

Along with providing information about the server, the page also runs a test on the configuration and lists the most recent HTTP requests and log messages, as well as all currently registered MicroApps along with their accessibility, name, and URL.

In order to receive log messages, the logging.file.name parameter must be specified with the desired log file (e.g., /tmp/platform.log), for example:

logging.file.name=/home/tomcat/logs/platform.log

The status page can only be accessed by administrators.

Note: To test accessibility, the status page sends an empty context to each MicroApp for checking. This can result in warning messages such as the following in the log:

de.espirit.cxt.microapps.stereotype.UnsupportedContextException: Context is not supported

Management page for MicroApps

The management page can only be accessed by server or project administrators.

Under

/management

(appended to the URL of the platform), a management page can be reached that can be used to configure the availability of the MicroApps, for example:

http://myServer:8080/cxt-platform/management

To reach the management page without having to know the URL, a start button can be configured on the FirstSpirit start page.

For this, the “ApplicationPlugin: MicroApp Management” has to be added to the web application “Start page”.

The web component must also be deployed there (“Install” /“ Update” button).

The ApplicationPlugin for “MicroApp Management” then has to be added in the “Home page” area (“FirstSpirit ServerManager / Server / Properties / Home page”):

Once the plugin has been selected, the icon for launching “MicroApp Management” is available on the start page.

In addition, MicroApps can also define actions that are available to users. These actions can also be configured on the management page.

To save the configuration settings, the parameter cxt.platform.management.persistence.persistenceFile must be specified with the desired path to the persistence file (see Configuration).

Configuration

per web.xml

The web application is configured via the corresponding web.xml or a Properties file.
The default placeholder values do not work in all setups and must be checked and adapted to the respective setup.

Especially in the case of changes of the default value of the URL for the “FirstSpirit Start page” web app fs5root via the WEBAPP_ROOT_URL) parameter, the automatic substitution for the ${FIRST_SPIRIT_URL} placeholder does not work (e. g. cxt.dataservice.url). In this case, the desired value must be entered manually.
(For more information on the WEBAPP_ROOT_URL parameter, see Web Applications (→Documentation for Administrators).)

Example: FirstSpirit Server, default configuration for cxt.dataservice.url in the web.xml:

<context-param>
   <param-name>cxt.dataservice.url</param-name>
   <param-value>${FIRST_SPIRIT_URL}/cxt</param-value>
</context-param>

Module rolled out on the Tomcat web server (automatic substitution):

<context-param>
   <param-name>cxt.dataservice.url</param-name>
   <param-value>http://demo.e-spirit.de:2001/cxt</param-value>
</context-param>

With change to the value WEBAPP_ROOT_URL=/fs5root:

<context-param>
   <param-name>cxt.dataservice.url</param-name>
   <param-value>http://demo.e-spirit.de:2001/fs5root/cxt</param-value>
</context-param>

Comments

Comments in the web.xml start with

<!--

This character string can also be used to comment out parameters.

Communication

cxt.platform.firstspirit.hostname: Host name or IP address of the FirstSpirit server.

cxt.platform.firstspirit.port: Port of the FirstSpirit server.

cxt.platform.firstspirit.connection-mode: Connection mode for the communication with the FirstSpirit server.

HTTP: normal Internet connection
SOCKET: direct connection mode (default setting; Single-Sign-On in SOCKET mode only)

cxt.dataservice.url: Address at which the DAP Bridge can be accessed, e.g.

cxt.dataservice.url=http://localhost:8080/cxt/

cxt.platform.internal-url: The URL at which the CXT platform is internally accessible, e.g.

cxt.platform.internal-url=http://localhost:8888/cxt-platform/

cxt.platform.external-url: The URL, at which the CXT platform is accessible in a browser (incorporation of the Javascript API, query of MicroApp buttons, etc.), e.g.

cxt.platform.external-url=https://external/cxt-platform/

Cross-Origin Resource Sharing (CORS)

The CXT platform's integration interface provides individual functions from the CXT world in the form of MicroApps and via CXT REST calls that can then be used in other environments. This includes, for example, classic CRUD access to fragments and variants, even from (corporate) web apps that do not run on the FirstSpirit web server (“cross-origin resource sharing (CORS)”).

If the calling location (e.g., custom web app) and the CXT platform are not on the same web server (“same-origin”), but on different servers (“cross-origin”), access is normally prevented by the browser of the external web app (using the Same-Origin Policy (SOP)). This restriction can be lifted for certain URLs.

cxt.platform.cors-allowed-origins: This parameter is used to define a global CORS configuration for CXT MicroApps and for CXT REST calls. The following values are possible:

Empty (no access allowed)
* (all access allowed)
Comma-separated list of URLs (access allowed for individual origins)

Authentication (OAuth and Eureka)

FirstSpirit CXT uses the open security protocol OAuth for authorization and authentication purposes.
This protocol is based on the exchange of tokens: The access token issued by the OAuth server following successful authentication enables access to content in CXT. The refresh token can request a new access token from the OAuth server once the first one has expired without the authentication process having to be repeated. The refresh token cannot be extended or used again once the session is complete.

cxt.platform.eureka.password: Services register on the integrated Eureka server. This requires a password. Assign a fixed password and use the same password for the configuration of the client (e.g. FragmentCreator).

cxt.platform.oauth.client-secret: Clients that use OAuth tokens require a shared secret key (“Shared Secret”) for access to the authorization server. Assign a fixed password and use the same password for the configuration of the client (e. g. FragmentCreator).

cxt.platform.oauth.jwt-signing-key: OAuth tokens are signed with this code and remain valid until they expire according to the configured timeout below. The default value RANDOM_VALUE ensures a secure character string that changes at each start.

The tokens have a time limit that is specified by FirstSpirit as standard. The following parameters can be used to adjust the validity of the tokens to the specific requirements of the respective project:

cxt.platform.oauth.access-token-validity-seconds: Defines the validity period of the OAuth-Access-Token (in seconds).
Default value: 3600 (1 hour)

cxt.platform.oauth.refresh-token-validity-secondsDefines the validity period of an OAuth-Refresh-Token (in seconds). The value should be set higher than the value of the cxt.platform.oauth.access-token-validity-seconds parameter.
Default value: 43200 (12 hours)

Content security policy header (CSP)

cxt.platform.microapps.csp-origins: This parameter can be used to customize the Content-Security-Policy (CSP, see also https://content-security-policy.com/) HTTP header field. This is required if, for example, access to MicroApps from other domains is to be permitted.
If the parameter is configured incorrectly or not configured, an error message is shown in the browser console, e.g.,

Refused to display 'http://myhost:8050/fragments/microapps/firstspirit-fragments-edit-by-reference' in a frame because an ancestor violates the following Content Security Policy directive: "frame-ancestors 'self'".

and the corresponding MicroApp will not open.

This parameter can be used to define the origins from which access is to be possible. The fully qualified domain name is expected.
* can be used as a wildcard, e.g., to permit all URLs or certain subdomains of a domain.

Multiple entries can be specified separately using a space.

If the parameter is not specified, the default value 'self' is used. This means that only access from the same server is permitted (the same host and port).

Example:

cxt.platform.microapps.csp-origins='self' *.e-spirit.de:8050

permits access from the domain from which the header is sent and from subdomains of e-spirit.de:8050.

Log outputs

Optional parameters can be configured for advanced log outputs.
See also Spring Boot Documentation (HowTo Logging).

logging.level: Spring Boot logs messages logs messages based on the content of the class path. By default, messages with the level WARN and higher are logged. For debug purposes, the level can be temporarily set to a lower level, however, using the prefix logging.level in the web.xml. This means, for example, that log outputs for CXT classes can be set to the DEBUG log level by specifying the de.espirit.cxt package, for example

<context-param>
    <param-name>logging.level.de.espirit.cxt</param-name>
    <param-value>DEBUG</param-value>
</context-param>

logging.file.name: This parameter can be used to write log outputs (for output to the console) to a file in addition, for example

<context-param>
    <param-name>logging.file.name</param-name>
    <param-value>/var/log/tomcat/cxt.log</param-value>
</context-param>

Management of MicroApps

cxt.platform.management.persistence.persistenceFile: This optional parameter can be used to define the file path to the persistence file. This file stores the availability configuration of MicroApps that are registered with the CXT platform.

per Properties file

Alternatively, a Properties file can be used for the configuration of the Platform module (cxt-platform.properties). The configuration stored there overwrites all other properties (including the configuration via the web.xml file). In the event of an automatic FirstSpirit update, the settings saved in the Properties file remain unchanged and will not be overwritten or reset.

First, a “config” directory must be created in the class path and then a

/config/cxt-platform.properties

File must be created. When using a Tomcat, e.g., in the directory

${TOMCAT_HOME}/lib

The desired parameters can be configured in this file, e.g.,

cxt.dataservice.url=http://localhost:8080/cxt/

Deployment

Finally, roll out the web application configured as described above for the CXT platform on the selected web server by pressing the “Install” button.

Print version | Page start