FirstSpirit Object Service - Administration and Configuration

Once the module has been successfully installed, the folder UX-Bridge is added to the list of modules installed on the FirstSpirit Server in the server properties. After selecting this folder, click Configure and check the All permissions box in the dialog which appears. After confirming with OK, the UX-Bridge folder is identified by a padlock icon.

Then expand the folder and select the UXBService service before clicking Configure once more. Go to the Options tab in the dialog which appears and enable the sending of status and project information messages there (see figure Configuring the UXBService).

Information on these messages is available in the Documentation for Developers.

Figure 3. Configuring the UXBService

Messages for the Portal Plugin are sent as standard to:

activemq:topic:PORTAL-EVENTS

This end point is defined in the applicationContext.xml of the FOS:

<endpoint id="PORTAL-EVENTS" uri="acticemq:topic:PORTAL-EVENTS"> </endpoint>

A new end point can be configured by changing this entry.

The applicationContext.xml is found within the WEB-INF folder in the fos-service-<version number>.war file.

The FOS requires the following settings:

If the settings have not yet been defined or are incomplete, they are queried when the FirstSpirit Object Service Admin Interface is called.

The settings are stored in a Java properties file. They must be specified the first time the FOS is used because they depend on the local incidents of the user system. An absolute path ending in <file name>.properties is expected to generate the file.

The FOS is the link between FirstSpirit and the portal server. It determines all changes to the data inventory based on the messages transferred to it and forwards this information to the Portal Plugin. The FOS stores this data inventory in a folder which must be shared with it via an absolute path. The messages are called via a connection which the FOS establishes to the UX-Bus. To do this, it requires the host and port of the UX-Bus.

The REST interface of the FOS expects an http header named apikey each time it is called. Its value must be a UUID, which is known to the FOS as an API Key. Otherwise a request will end with the state 401 Unauthorized. The various keys are used to define access permissions for projects via the REST interface. To store the API Keys, the FOS uses a bin file, which it creates when the first API Key is generated and which must be shared with it via an absolute path.

Once the settings file has been generated, the web application must be introduced to it. There are three methods of achieving this:

The web.xml can be expanded by adding a context parameter or an environment entry:

<context-param>
	<param-name>FOS_SETTINGS_FILE</param-name>
	<param-value>PATH OF THE SETTINGS FILE</param-value>
</context-param>

or:

<env-entry>
	<env-entry-name>FOS_SETTINGS_FILE</env-entry-name>
	<env-entry-type>java.lang.String</env-entry-type>
	<env-entry-value>PATH OF THE SETTINGS FILE</env-entry-value>
</env-entry>

These can also be added to the context.xml. The steps required are explained in the following link:

http://tomcat.apache.org/tomcat-7.0-doc/config/context.html#Context_Parameters

When delivered, the logging feature of the web application is set to INFO. If further details are required, in file log4j.properties (found in the web application folder under WEB-INF → classes), the line log4j.rootLogger=INFO, file must be changed to the expression log4j.rootLogger=DEBUG, file.

Information on runtimes is backed up alongside general logging data. This information is stored as standard in a separate file named metrics.log in the logging directory of the web application server. Furthermore, the information is also made available via jmx.

Changes to the runtime measurement can be made in file applicationContext.xml (found in the web application folder under WEB-INF). To modify the frequency of the measurements, for example, the value period must be altered in the following section.

<metrics:reporter type="slf4j" metric-registry="metrics" period="1m" logger="com.espirit.moddev.fos.logger.metrics/>

1m,, indicating one measurement per minute, is the default setting here.

If more information is required on runtime measurements, you can find it at the following links:

https://github.com/ryantenney/metrics-spring

https://dropwizard.github.io/metrics/3.1.0/manual/core/

Multiple instances of FOS can be operated in parallel on a web application server without problems. To do this, simply copy the application initially integrated onto the server (see chapter FirstSpirit Object Service (FOS)) as many times as the number of instances you wish to run.

Each of the instances which then exist requires its own context.xml, which should be stored at a global location on the web application server and have the same name as the associated FOS instance. For a Tomcat server, the storage location of the context.xml files would correspond to a path like the following one, for example:

<Tomcat-directory>/conf/Catalina/<HOST>/<FOS-INSTANCE>.xml

The files are used to specify the path of the settings file for the FirstSpirit Object Service Admin Interface and therefore require the following content:

<?xml version="1.0" encoding="UTF-8"?>
<Context>
	<Parameter name="FOS_SETTINGS_FILE"
	value="PFAD ZUR EINSTELLUNGSDATEI" override="true" />
</Context>

An initialization first has to be performed within the schedule. This requires a MessageGenerator, which generates the messages transferred from the FirstSpirit Server to the UX-Bus.

The script call below is used to add the standard MessageGenerator made available by the FOS module in the schedule's first action:

Initialize FOSGeneration. 

#! executable-class
com.espirit.moddev.fos.util.FosScheduleInitializer

If a user-defined MessageGenerator is to be used, it can be added as the MessageGenerator parameter in the script properties.

For more information on the MessageGenerator, refer to the UX-Bridge Developer Documentation.

As the second action in the schedule, add another script, which contains the following call:

Activate Generation. 

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

This call activates the generation to be performed in the next step; without this activation, no generation can take place. Therefore, the call is absolutely essential for a successful generation operation.

The generation activated in the previous action is performed by the Generate action.

Specify a name of your choice in the generation's Properties and select the Clear generation directory beforehand option (see figure Generation - Properties). The Generate only if necessary option must not be activated, however.

Figure 9. Generation - Properties

On the Extended tab, the presentation channel created previously must be selected for one of the languages of the project (see figure Generation - Extended).

Figure 10. Generation - Extended

The Result Handler action is an error detection function. It enables errors to be identified while delivering the generated messages and event messages.

Create another script for this and add the following script call to it:

Result Handler. 

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

Then open the Properties of the script and create the following parameters via Add (see figure Script properties):

Figure 11. Script properties

So, the maintenance mode is only exited in the event of an error if precisely these conditions are met: a full generation operation has been performed, the disableMaintenanceWithErrors parameter has the value true, and the number of errors and warnings which have occurred does not exceed the threshold defined via the errorThreshold parameter.

The optional Configure UXB Message Header action allows any extra root attributes to be added to the messages sent from FirstSpirit to the UX-Bus.

To generate the root attributes, a script with the following content must be added as the generation schedules first action:

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 generates a HashMap in which the required attributes can be defined in the form of key/value pairs. These are applied both in communication between the FirstSpirit Server and the UX-Bus and in the event messages sent by the FOS.

Information on how to define root attributes is also available in the UX-Bridge Developer Documentation.

Only if the Portal Plugin is also to be informed of potential changes to content must the following script be added to the schedule as the first action. Otherwise, it can be ignored.

Activate HTML Generation. 

import de.espirit.firstspirit.access.schedule.DeploymentUtil;

deltaGeneration = DeploymentUtil.createDeltaGeneration(context);
deltaGeneration.levelRule(0, 0).levelRule(1,1).levelRule(2,2);
changeSet = deltaGeneration.calculateChangeSet();
changeSet.configureGenerateTask();

The script determines the changes which have been made to the content and activates the HTML generation to be performed in the next step. Without this activation, the generation cannot be carried out successfully. Therefore, it is absolutely essential (based on the prerequisite already stated).

The generation to be performed with this action is only required if the Portal Plugin is also to be informed of potential changes to content. It must first be activated and it is essential that it follows the previous Activate HTML Generation action.

On the Extended tab, the HTML channel must be selected for all project languages (see figure Advanced Generate HTML settings).

Figure 13. Advanced Generate HTML settings

Specify a name of your choice in the generation's Properties and select the Clear generation directory beforehand option (see figure Generate HTML properties).

Figure 14. Generate HTML properties

The DeltaEventCollector action must follow Generate HTML, as it records the content generated by that previous action. This is done by means of the following script call:

DeltaEventCollector. 

#! executable-class
com.espirit.moddev.fos.util.FosDeltaEventCollector

The EventCollector is only required if the Portal Plugin is also to be informed of potential changes to content. Otherwise, this action can be omitted.

The Calculate Changes action determines the changes made within the FirstSpirit project being used since the last generation. It also configures the next generation action such that only a minimum number of messages is sent to the FOS in order to refresh it. If no changes have been identified, the schedule is canceled at this point.

Therefore, it is absolutely essential that the action is performed after the initialization and before the generation.

The changes made are determined and the necessary information is transferred to the generation action via the following lines, which must be inserted in a script:

Calculate Changes. 

import com.espirit.moddev.fos.generation.*;

deltaGeneration = DeploymentUtil.createFosDeltaGeneration(context);
FosDeltaGeneration.ChangeSet changeSet = deltaGeneration.calculateChangeSet();
generateTaskConfigurator = GenerateTaskConfigurator.getInstance(context, changeSet);

generateTaskConfigurator.configureGenerateTask(true);

The boolean value transferred to the configureGenerateTask call controls whether, once changes have been made to templates, a generation of the pages based on those templates is to be triggered. If this is not required, the value must be changed from true to false.

The Remove Deleted Nodes action informs the FirstSpirit Object Service of the elements deleted in FirstSpirit. This is done by means of the following script call:

Remove Deleted Nodes. 

import com.espirit.moddev.fos.generation.DeploymentUtil;

DeploymentUtil.removeDeletedNodes(context);

The DeltaEventGenerator action is only required if the Portal Plugin is also to be informed of potential changes to content. Otherwise, this action can be omitted.

The EventGenerator sends messages relating to changes to content to the FOS. To do this, it uses the information determined by the EventCollector. This is done by means of the following script call:

Event Generator. 

#! executable-class

com.espirit.moddev.fos.util.FosDeltaEventGenerator

The generation of messages by the EventGenerator must be positioned between the FOS generation and before the ResultHandler, so the FOS is able to process the information without errors.

The Finalize DeltaGeneration action completes the delta generation:

Finalize DelteGeneration. 

#! executable-class

com.espirit.moddev.fos.util.FosDeltaFinalizer

The Maintenance Mode slider is used to manually activate or deactivate a project's maintenance mode and therefore has the states ON and OFF. The maintenance mode is deactivated as standard and the slider is set to the OFF state.

Figure 18. Maintenance Mode

If a project is in the maintenance mode, the FOS does not send any event messages and all requests from the Portal Plugin to the REST interface of the FOS are answered with a Retry later message for this project. So no data for this project is supplied from the FOS to the Portal Plugin during this time. The project data saved inside the persistence layer of the FOS cannot be accessed again until the maintenance mode has been deactivated.

The maintenance mode can also be changed automatically by means of a generation operation. A distinction must be made between a partial and a full generation here.

Manually deactivating the maintenance mode if it has been automatically activated by FirstSpirit will generate a warning with a confirmation prompt (see figure Warning). This prompt gives the administrator the option to either actually deactivate the maintenance mode or cancel the process.

Figure 19. Warning

When the maintenance mode is deactivated, the FOS starts sending event messages again for the remainder of that generation operation. The REST interface is also available for requests from the Portal Plugin once more. Therefore, the information transferred to the Portal Plugin may be incomplete or in a version still being modified by the ongoing generation. This can lead to inconsistencies.

For more information on the maintenance mode, refer to the Documentation for Developers.

Clicking the Settings button opens a dialog where project-specific settings can be made.

MediaEvent mode

All changes made to FirstSpirit elements are always recorded in the event messages sent to the Portal Plugin. However, modifying the inheritable attributes of a structure, content or media folder not only has an effect on the folder itself, but also on all the elements it contains.

This aspect is already covered for structure and content folders by the general structure of the event messages. Media folders, by contrast, represent a special case and need to be dealt with separately. This is defined via the MediaEvent mode slider (see figure Inheritance mode activated).

Figure 20. Inheritance mode activated

More information on inheritance is available in the Documentation for Developers.

Clicking the Clear Cache button deletes all project-related data contained in the FOS. The project and all settings are retained.

Clicking the Delete Cache button removes the corresponding entry from the list of projects. Furthermore, all data relating to that project is deleted from the FirstSpirit Object Service Admin Interface and cannot be recovered. The project can then only be transferred to the persistence layer of the FOS again by means of a full generation operation.

It makes sense to use this functionality if the corresponding project will no longer be used in future and will no longer exist on the FirstSpirit Server either. This applies to test projects, for example.

If there is a large number of API Keys and projects, it may be that not all API Keys or projects are of interest and simply make the overview unnecessarily complex. Therefore, two input components named Filter Projects and Show empty API-Keys can be found above the list and serve to filter the overview of API Keys.

If a project is selected in Filter Projects, API Keys with permissions for this project are displayed in the overview. Otherwise, the corresponding API Keys are hidden.

All projects are selected in Filter Projects as standard, so the overview contains all API Keys which have permissions for at least one project. At the same time, this means that API Keys with permissions for no project are not displayed as standard. This is why the Show empty API-Keys button is provided, so exactly these keys can be shown and hidden.

A special dialog is provided for creating a new API Key (see figure Dialog for creating a new API Key), which is opened by clicking the + Add API-Key button.

Figure 22. Dialog for creating a new API Key

In the upper part of the form, a description of the new API Key must be entered in the Description field in order to give it a functional reference.

Initial project permissions for the new API Key are granted in the lower part of the form. An overview of all the projects in the portal service can be found here in table format. If a check box in the left-hand column of this list is selected, the API Key receives read permissions for the corresponding project. The key receives administrative permissions when the slider in the right-hand column is also set to ON.

Clicking Save stores the data on the form and generates a new API Key. Clicking Cancel, by contrast, discards all the entries.

Since a newly created API Key is sorted into the overview automatically, once it has been successfully generated, another dialog opens, which tells the user the name of the new key (see figure Confirmation dialog once an API Key has been created).

Figure 23. Confirmation dialog once an API Key has been created

The description of an API Key can be edited in the overview. All that has to be done is click on the description in order to edit it in the input component which appears (see figure Editing the description of an API Key).

Figure 24. Editing the description of an API Key

Once the description has been revised, it can be accepted by clicking on the button with a check mark on a blue background. Since the description is a mandatory field, however, the save operation will be rejected as long as the text field is empty. To reject the changes, simply click the second button.

Adding another project

If an API Key is to obtain permissions for another project, said project can be selected in a corresponding dialog (see figure Adding another project). This dialog is opened by clicking the + Add Project button under the project list of the corresponding API Key.

Figure 25. Adding another project

The dialog contains two input components: First there is a selection list containing all the projects for which the API Key has no permissions. The API Key receives permissions for the project selected in this list. The dialog also contains a slider, which can be used to set administrative permissions for the selected project. If this slider is set to ON, the API Key has administrative permissions, otherwise it only has read permissions.

As soon as a project has been selected in the selection list, the process can be continued by clicking Add and the permissions of the API Key are supplemented as per the selection in the dialog. Clicking Cancel closes the dialog and no changes are made to the API Key.

Setting or removing administrative permissions for a project

Once permissions for a project have been added to an API Key, administrative permissions can be set or removed for this project at any time subsequently. It is enough to simply toggle the slider in the ADMIN RIGHTS column for the project concerned in the overview of all the API Keys. If the slider is set to ON, administrative permissions are set, otherwise they are not.

Removing all permissions for a project

A button labeled with an X can be found to the left of every project in the project list of every API Key. A click on this button removes all permissions for the project from the respective API Key. However, this must first be confirmed in the dialog which appears automatically after clicking the button (see figure Removing all permissions for a project).

Figure 26. Removing all permissions for a project

Clicking OK removes the permissions from the API Key. They have to be set again manually in order to restore them. Clicking Cancel closes the dialog and the API Key retains its permissions.

An API Key can be deleted irrevocably by clicking the button with the gray X to its left. However, first a dialog appears in which the user is requested to confirm the API Key should be deleted (see figure Deleting an API Key).

Figure 27. Deleting an API Key

The deletion process is confirmed by clicking the OK button. The API Key is then permanently lost and removed from the overview. Clicking Cancel aborts the process instead and the API Key is not deleted.