UX-Bridge - Developer Documentation

The first step in development within the context of UX-Bridge is to install the components.

To do this, first install the provided module in the server settings of FirstSpirit server. Doing this will start the UX-Bridge service, and the UX-Bridge components will be available in the projects of the server.

In addition to the FirstSpirit module, installation of the UX-Bus is also required. For local development, the installation in standalone operation is recommended.

For further details refer the UX-Bridge Installation Manual.

The architecture of UX-Bridge permits the development of solutions based on UX-Bridge to be divided into two roles:

If the roles are performed by different people, then a common data exchange format should be defined during the conceptual design process. In this case the intended data format is the one that is generated by the templates and is sent as a message to the adapter via the UX-Bus.

The data exchange format thus forms the interface between the components and thus also between the two roles. From the point of view of the template developer, this is the end product of their work. For the (web) application developer, this represents the input for the adapter. Here, only an outer container is prescribed by UX-Bridge. The remainder can be freely defined (see Section Creating and filling a presentation channel).

A carefully selected data exchange format can significantly reduce the implementation effort.

The following questions can help during the selection:

To use UX-Bridge, a new template set (UXB) must first be created under project settings → Template sets. As a presentation channel, XML is to be configured as the Unicode to XML conversion rule and xml is to be configured as the target file extension.

Figure 1. create new Template Set

The Unicode to XML conversion rule serves to transform special characters and control characters into corresponding XML entities, which otherwise would be interpreted in XML as a part of the markup language or would appear as invalid characters.

In order to send messages to the UX-Bus, the corresponding template that is to generate the messages contains fields that have been defined in the data exchange format and which are to be output in XML format.

Figure 2. presentation channel in SiteArchitect

Only the following structure is predefined:

<uxb_entity uuid = String destinations = String  language = String command = String objectType = String>
 <uxb_content>
   […] defined data exchange format […]
 </uxb_content>
</uxb_entity>

The language, command and objectType attributes are optional, but have proven helpful with the adapters implemented by e-Spirit.

In order to convert the data from FirstSpirit into messages that can be further processed by UX-Bus, it is mandatory for a schedule to be created or an existing schedule extended so that it generates XML. This is then forwarded to the UXB-Service, which generates a message from it and sends this to the UX-Bus. The schedule can be started later via a Workflow. This section will now describe two schedules that will probably be needed in every project that uses UX-Bridge.

Partial generation

In order to publish new content quickly on the website, it is useful to create a schedule or to expand on one in such a manner that it carries out the steps described in the following while only generating and publishing the new content.

A typical generation schedule which uses UX-Bridge is divided into multiple actions as described in the following:

Figure 3. schedule entry planning

First, all of the complete static pages that are needed for display on the website (e.g. news overview pages) should be generated in a generation action. This generation action takes place in the deployment schedules commonly used to date and does not have to be adapted.

In the next step, the content generated in the previous step should then be transferred to the web server as usual (in the example, via rsync). In this step, too, no adaptations are usually necessary.

Next, in order to use UX-Bridge, a new, additional action needs to be added which activates the generation process for UX-Bridge by calling a script:

UX-Bridge Generate. 

#! executable-class
com.espirit.moddev.uxbridge.inline.UxbInlineUtil

In the subsequent generation action, the exact page should then be generated (e.g., the news detail page) that generates the XML to be forwarded to the UXB-Service. It is important to ensure that the UXB template set has been enabled in the advanced properties.

Figure 4. activating the presentation channel

Delta generation in FirstSpirit 5 now adapts this generation action automatically so that it no longer generates all pages, but rather just the page desired. In addition, for example, a workflow script that initiates the generation process can transfer the generated page to the schedule.

The last action, UX-Bridge Statistics Report, is optional and enables the cycle times to be measured for the messages in the UX-Bus until deployment on the website.

INFO  22.08.2012 09:59:54.631 (de.espirit.firstspirit.server.scheduler.ScheduleManagerImpl): starting task 'UX-Bridge Statistics Report' - schedule entry 'UX-Bridge-Test (News)' (id=5142)
INFO  22.08.2012 10:00:04.645 (com.espirit.moddev.uxbridge.service.UxbServiceImpl): Time for #uxb/pressreleasesdetails/UXB/EN/256 (postgres): 242ms
INFO  22.08.2012 10:00:04.645 (com.espirit.moddev.uxbridge.service.UxbServiceImpl): Time for #uxb/pressreleasesdetails/UXB/DE/256 (postgres): 224ms
INFO  22.08.2012 10:00:04.645 (com.espirit.moddev.uxbridge.service.UxbServiceImpl): 2/2 deployed successfully (overall: 233ms, postgres: 233ms).
INFO  22.08.2012 10:00:04.646 (de.espirit.firstspirit.server.scheduler.ScheduleManagerImpl): finished task 'UX-Bridge Statistics Report' - schedule entry 'UX-Bridge-Test (News)' (id=5142)

The following script call is necessary for this:

UX-Bridge Statistics Report. 

#! executable-class
com.espirit.moddev.uxbridge.inline.UxbResultHandler

The service waits the maximum amount of time defined in the UX-Bridge service configuration until the adapters' responses are evaluated. If there is no response within this time frame, then the message is classified as having a delivery error. Since response times can vary depending on message and system, this value can be configured.

Please note that every generation action invoked between UX-Bridge Activate Generation and UX-Bridge Statistics Report will perform a UX-Bridge generation. To add a further file system generation without calling the `UX-Bridge Statistics Report´ script beforehand, it will be necessary to add a preceding script to deactivate the UX-Bridge generation:

UX-Bridge Deactivate Generation. 

#! executable-class
com.espirit.moddev.uxbridge.inline.UxbDeactivate

Complete alignment process

It makes sense to create an additional schedule which carries out a complete alignment process in order to maintain the most current state of the data inventory in the content repository. For this purpose, the data deleted in FirstSpirit must also be deleted in the external repository.

The following procedure is recommended:

cleanup-Skript. 

import com.espirit.moddev.uxbridge.api.v1.service.UxbService;
uxbService = context.getConnection().getService(UxbService.class);
uxbService.removeUxbEntriesByTime(context.getStartTime().getTime(), "news", "postgres,mongodb");

Historic Data

To generate historic data using UX-Bridge a new script action is to be added before the action UX-Bridge - Activate Generation.

Script. 

import java.util.Date;
Date d = new Date(114, 5, 24);
context.setStartTime(d);

The date that is set will be used in the following action (UX-Bridge - Activate Generation).

Recognizing the schedule start/end in the adapter

To make sure the adapter is able to respond at the start and/or end of a schedule in certain circumstances, the UX-Bridge can send a separate message automatically at both the start and end of generation (see UX-Bridge Installation Manual).

The format of the start message is as follows:

<uxb_entity projectName="PROJEKT_NAME" status="start" schedulerId="AUFTRAGS_ID" createTime="ZEITPUNKT_DER_NACHRICHT" projectId="PROJEKT_ID" startTime="STARTZEITPUNKT_DES_AUFTRAGS" />

During full generation, the command="startMaintenanceMode" attribute is also added.

The format of the end message is as follows:

<uxb_entity projectName="PROJEKT_NAME" status="end" schedulerId="AUFTRAGS_ID" createTime="ZEITPUNKT_DER_NACHRICHT" projectId="PROJEKT_ID" startTime="STARTZEITPUNKT_DES_AUFTRAGS" />

During full generation, the command="stopMaintenanceMode" attribute is also added.

If the maximal number of allowed errors or timeouts are exceeded in the adapter during a full generation, the command attribute has the value keepMaintenanceModeUp.

Adding root attributes

The root node of every message sent through the UX-Bridge comes with a set of predefined root attributes like the project name or the id of the schedule entry. They can be extended by further custom attributes by adding the following script Configure UXB Message Header to the beginning of the schedule:

Script - Configure UXB Message Header. 

import java.util.HashMap;
attributeMap = new HashMap();
attributeMap.put("customAttribute1", "customAttributeValue1");
attributeMap.put("customAttribute2", "customAttributeValue2");
context.setProperty("uxbMessageRootAttributes", attributeMap);

The script creates a HashMap containing each custom attribute as a key/value-pair. The HashMap will then be added to the schedule context, so that the UXBService can include the additional attributes during generation of the messages.

Pages can be skipped when generating messages by setting the uxbSkipMessage page variable.

uxbSkipMessage. 

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

The use of "stopGenerate" (see Online Documentation for FirstSpirit → Template development → Template syntax → System objects → #global → Preview-specific → Cancel a preview/generation) is not supported and in this case will result in invalid XML, resulting in error messages in the log.

The UX-Bridge can send a message with expanded project information at the start of generation (see UX-Bridge Installation Manual). This information currently includes the defined project languages and resolutions.

Example. 

<uxb_entity projectName="UXB" objectType="projectInfo" schedulerId="92460" createTime="1371037891875" projectId="88785"  startTime="1375346932923">
 <project key="UXB">
  <id>88785</id>
  <name>UXB</name>
  <languages>
   <language key="DE">
    <name>Deutsch</name>
    <abbreviation>DE</abbreviation>
    <isMasterLanguage>true</isMasterLanguage>
   </language>
  </languages>
  <resolutions>
   <resolution key="ORIGINAL">
    <name>Originalauflösung</name>
    <uid>ORIGINAL</uid>
    <height>0</height>
    <width>0</width>
    <isOriginal>true</isOriginal>
   </resolution>
  </resolutions>
 </project>
</uxb_entity>

The publication of content via UX-Bridge can be started directly via scripts and schedules or indirectly via workflows.

Release workflow

In order to publish content, an existing workflow simply has to be expanded by adding a workflow script that starts a schedule which, alongside generation and deployment, also generates XML messages and forwards them to the UXB-Service (see Partial generation).

Delete workflow

In order to delete content, an existing delete workflow has to be expanded by adding a workflow script that generates an XML message, which is forwarded to the UXB-Service.

Invoking the UXB-Service is written in the script as follows, where msg (string) corresponds to the XML message:

UXB-Service. 

UxbService uxbService = context.getConnection().getService(UxbService.class);
uxbService.removeUxbEntry(msg);

The XML message follows the example below:

<uxb_entity uuid=STRING language=STRING destinations=STRING objectType=STRING command=STRING />

FirstSpirit expects a response from the adapter in the form of an XML document after a message has been written to a repository. The response is expected in the case of both successful and failed processing. The XML document is structured as follows:

<uxb_entity command=STRING createTime= STRING destinations=STRING finishTime=STRING language=STRING path=STRING schedulerId=STRING startTime=STRING status=STRING uuid=STRING ><uxb_error>STRING </uxb_error></uxb_entity>