FirstSpirit Object Service - Documentation for Developers

Project-specific attributes are added or changed using the insert method of an attributeHandler. This method expects a hashMap as a transfer parameter.

The map must be filled in advance with the project-specific attributes and the associated values in the form of key/value pairs. There is no restriction to a certain number of attributes here.

The insert method of the attributeHandler sends the hashMap to the FOS, in whose internal persistence layer the transferred values are saved. The individual attributes are then available to the Portal Plugin, which can query them via the REST interface.

Adding and changing project-specific attributes. 

import com.espirit.moddev.fos.AttributeHandler;
import java.util.HashMap;

// create attributeHandler
attributeHandler = new AttributeHandler(context);

// create map with attributes/values to add
attributeMap = new HashMap();
attributeMap.put(eSpiritDefaultPluginMyKey,myValue);
attributeMap.put(eSpiritDefaultPluginMySecondKey,mySecondValue);

// insert map
attributeHandler.insert(attributeMap);

Project-specific attributes are removed using the delete method of an attributeHandler. This method expects a hashSet as a transfer parameter.

The attributes to be removed simply have to be added to the set; the values belonging to the attributes are not important here. They are removed at the same time the attributes are deleted, so they do not have to be specified explicitly.

The delete method of the attributeHandler transfers the hashSet to the FOS, which removes the corresponding attributes from its internal persistence layer.

Deleting attributes. 

import com.espirit.moddev.fos.AttributeHandler;
import java.util.HashSet;
// create attributeHandler
attributeHandler = new AttributeHandler(context);
// create set with attributes to delete
attributeSet = new HashSet();
attributeSet.add(eSpiritDefaulPluginMyKey);
// delete set
attributeHandler.delete(attributeSet);

Each attribute consists of a key/value pair and a tag, which surrounds the pair. The surrounding tag comprises the type and the reference name (UID) of the required element to which the new attribute is to be added. The key can be selected as desired - with one exception - and encloses the data to be transferred, which is the value that corresponds to the selected key.

So an individual attribute has the following structure:

<OBJEKTTYP uid=UID_OBJEKT>
 <KEY>VALUE</KEY>
</OBJEKTTYP>

The individual attributes, as many of which as desired can be specified within the presentation channel, must be combined into a list using a surrounding <attributes/> tag.

Input:

<attributes>
 <PageFolder uid="$CMS_VALUE(#global.node.uid)$">
  <portlettype>$CMS_VALUE(pt_portlettype)$</portlettype >
 </PageFolder>
 <Page uid="$CMS_VALUE(#global.page.uid)$">
  <pageportletname>$CMS_VALUE(pt_portletname)$</pageportletname>
 </Page>
</attributes>

Output:

<attributes>
 <PageFolder uid="umsetzungmitfirstspirit">
  <portlettype>WIDGET</portlettype>
 </PageFolder>
 <Page uid="firstspirit">
  <pageportletname>Blog</pageportletname>
 </Page>
</attributes>

It is important to note that attributes can only be added for the elements which have been generated in each case. This means they must be contained in the message addressed to the FOS.

This message always consists of the following for a generated element:

An attempt to add an attribute to an element which does not exist will result in a warning in the generation schedule.

The tag <medialist/> enables a list of media to be transferred in addition to the attribute list. The individual entries in this list contain four items of information, which belong together in two pairs:

The first pair relates to the medium and contains its type and reference name.

The second pair refers to the element which uses the medium. The origin and originType values specify the reference name and the type of this element. It could be, for example, a folder or a section within a page.

$CMS_VALUE(#global.page.name)$#$CMS_VALUE(#global.page.body("Content left").children.first.name)$

$CMS_VALUE(#global.page.name)$#$CMS_VALUE(#global.section.name)$

Both pairs are bundled into a tag and together they represent one entry in the list of media.

Therefore, a media list with just one element has the following structure:

<medialist>
 <Media uid=UID_MEDIUM origin=UID_REFERENZELEMENT originType=TYPE_REFERENZELEMENT/>
</medialist>

The medium is saved in the persistence layer of the FOS with this information and a reference to the specified reference element is generated.

The individual media entries do not contain any attributes, as these are recorded and sent to the FOS via the standard FirstSpirit mechanism (see also chapter Presentation channel).

If other data is to be transferred in addition, it must be recorded in the list of attributes.

A media list with just one entry could look like this.

Input:

<medialist>
 <Media uid="connector_cable" originType="$CMS_VALUE(#global.node.UidType)$" origin="$CMS_VALUE(#global.page.name)$"/>
</medialist>

Output:

<medialist>
 <Media uid="connector_cable" originType="Page" origin="mithras_home"/>
</medialist>

In order to be able to send the information made available via the attribute and media lists in the message created by a generation operation, the two individual lists must be combined into one joint list.

This is done using the surrounding <supplementary/> tag, which links the two lists to one another:

<supplementary>
 <attributes> […] </attributes>
 <medialist> […] </medialist>
</supplementary>

A simple XML message generated as described in the preceding sections could look like this, for example:

<supplementary>
 <attributes>
  <PageFolder uid="umsetzungmitfirstspirit">
   <portlettype>WIDGET</portlettype>
  </PageFolder>
  <Page uid="firstspirit">
   <pageportletname>Blog</pageportletname>
  </Page>
 </attributes>
 <medialist>
  <Media uid="connector_cable" originType="PageRefFolder" origin="firstspirit"/>
 </medialist>
</supplementary>

As mentioned in chapter List of attributes, content projections can be supplemented by additional attributes too. In this case, however, it is necessary to expand the Uid, whereby a distinction must be made between detail and overview pages.

The ID of the relevant dataset must be appended to the Uid of detail pages, separated by a hash symbol (#).

The index of the relevant page (0 ... n) is also appended to the Uid of overview pages, again separated by a hash symbol (#).

<supplementary>
 <attributes>
  // Detailpage
  <PageRefContentProjection uid="$CMS_VALUE(#global.node.uid)$#$CMS_VALUE(#global.dataset.entity.id)$">
   <myAttribute>myValue</myAttribute>
  </PageRefContentProjection>
  // Overviewpage
  <PageRefContentProjection uid="$CMS_VALUE(#global.node.uid)$#$CMS_VALUE(#global.pageParams.index)$">
   <myAttribute>myValue</myAttribute>
  </PageRefContentProjection>
 </attributes>
</supplementary>

Each time a generation operation is run, the Portal Plugin is informed of this via what are known as status messages, which indicate the start and end of the schedule respectively.

Furthermore, the status messages also contain information on the type of generation executed on the FirstSpirit Server. A full generation operation activates the maintenance mode for the corresponding project in the FOS automatically.

The Portal Plugin must be informed of this state, as the FOS stops communication while maintenance mode for this project is active. It also reacts to all requests to the REST interface with a "Retry later" response. So the Portal Plugin receives no information on the corresponding project from the FOS during this time.

The information transferred and the structure of a status message are described in chapter Message structure.

The FOS sends information on changes, that have been made to the data inventory and determined as such, to the Portal Plugin via the UX-Bus. This information is referred to as an event message. Each event message contains a list of individual events.

An event message is only sent by the FOS automatically if it is deemed necessary. Prior to that, data matching must first have been performed in the persistence layer of the FOS, which was in turn triggered by a generation operation on the FirstSpirit Server.

If data matching does not determine that any changes have been made to the data inventory, it is superfluous to send event messages to the Portal Plugin, as it is not necessary to refresh the live state on the portal server. In this case, the Portal Plugin is simply informed of the start and end of the schedule by means of a status message. However, no event messages are sent.

If data matching does record changes that have been made to the data inventory, the FOS transfers every one of these changes to the Portal Plugin in the form of event messages. Changes to inherited attributes, such as metadata, are a special case and are therefore dealt with separately (see chapter Inheritance).

Event messages are sent via push. No previous action is required on the part of the Portal Plugin. Ideally, the information contained in the event messages should be sufficient to refresh the data inventory contained in the portal. Otherwise the Portal Plugin must send a request to the REST interface.

A detailed explanation of the information transferred in event messages and its structure can be found in the sections that follow.

The FOS transfers changes to content to the Portal Plugin via the UX-Bus using ChangedContent messages. These are special event messages, which differ from standard event messages only in terms of their type.

A ChangedContent message is only sent automatically if it is deemed necessary, as is also the case for event messages.

Only if changes have been made to content will the FOS transfer these to the Portal Plugin. Unlike with event messages, information will be sent in precisely one ChangedContent message, in which all changes are combined.

If no changes have been detected, the Portal Plugin is simply informed of the start and end of the schedule by means of a status message.

ChangedContent messages are sent via push. No previous action is required on the part of the Portal Plugin.

To ensure that all information is transferred, the FOS must know all the project information. To this end, the Send project information message checkbox must be enabled, as described in the FirstSpirit Object Service Documentation for Administrators.

A detailed explanation of the information transferred in ChangedContent messages and its structure can be found in the sections that follow.

Generally speaking, a generation operation on the FirstSpirit Server and subsequent data matching in the FOS trigger the sending of event messages. Every change determined by the FOS generates an event message during this process, which is pushed to the Portal Plugin via the UX-Bus.

A full generation operation performed on the FirstSpirit Server, however, triggers an alignment of all data in the persistence layer of the FOS for a project. Such a full alignment would thus cause countless event messages to be sent.

To prevent this, the project is set to a maintenance mode in the FOS automatically while a full alignment is being performed. The Portal Plugin is informed of this procedure by a status message.

During the maintenance mode, the FOS does not deliver any data for the corresponding project to the Portal Plugin. If the Portal Plugin attempts to request data via the REST interface nevertheless, it receives a "Retry later" response.

Once the full alignment is complete, maintenance mode is usually deactivated automatically and the Portal Plugin is again informed of this by a corresponding status message. It then independently requests the project's entire data inventory via the REST interface and exchanges the data in the portal.

In FirstSpirit there is an option to define attributes at folders of the Site, Page, and Media Store and for all lower-level elements to inherit them by using metadata, for example.

If a portal possesses the inheritance function, it is sufficient to only take such a folder into account to a limited extent: Just the change made to the attributes of the parent node is kept in the associated event message and transferred to the Portal Plugin. This then automatically assigns the attributes to the lower-level elements.

If a portal does not possess the inheritance function, it is not sufficient to transfer the information of the parent node, as the change which has been made would then only be assigned to that node. The effect of this change on the attributes of its lower-level elements would therefore be lost, which would result in a loss of information. This is why all lower-level elements are also transferred to the Portal Plugin via event messages in this case. However, these additional messages which are sent only say which elements are affected. They do not contain the modified attributes, as they would otherwise be transferred for both the parent node and all lower-level elements. This would lead to redundancies. In order to prevent this, the modified attributes themselves must be determined for every lower-level element via the REST interface of the FOS.

When modifying a site folder, only that folder and information on the change which has been made are ever recorded in the event message. In this case, this information is sufficient, since every portal is able to map the structure and is thus usually capable of assigning the attributes of a parent node to its lower-level structure elements.

If a page folder is changed, the event message always contains, alongside the corresponding PageFolder event, the events for all the pages contained in the folder and the page references based on them. The Portal Plugin thus receives all the information it needs in every case: If the portal being used cannot handle inheritance, the modified attributes are assigned via a query to the REST interface of the FOS. Otherwise the information on the page folder contained in the event message is sufficient.

Since the effects of changes made to site and page folders are thus already recorded via the general structure of the event messages (see also the table in chapter Message structure), inheritance simply has to be taken into account for the attributes defined at media folders.

The handling of media folders can be explicitly defined manually via a switch in the FirstSpirit Object Service Admin Interface.

Figure 4. MediaEvent mode for media folders

If the MediaEvent mode is set to SINGLE, only the media folder, including information on the modifications which have been made, is recorded in the corresponding event message. The modified attributes are assigned to its lower-level elements via the Portal Plugin.

If the MULTI MediaEvent mode is activated, only the events for all the elements contained in the folder are recorded in the associated event message. This also includes subfolders contained in the folder. The folder itself is not taken into account. For this reason the modified attributes are assigned to the media at this point already and not afterwards via a request to the REST interface of the FOS.

The Portal Plugin receives service messages in the form of JSON documents, which always have the same structure, as follows:

{
 "schedulerID":"ID",
 "projectName" : "PROJECTNAME",
 "createTime" : "A MESSAGE'S CREATE TIME",
 "startTime" : "A SCHEDULE'S START TIME",
 "type" : "A MESSAGE'S TYPE"
 //specific Parameter
 "status" : "A STATUS MESSAGE'S STATUS"
 "fullGeneration": TRUE OR FALSE
 "events" : [ {...} ]
}

Since the FOS may potentially manage several projects and these will all use the same interface, it must always be possible to unambiguously assign the service messages to a FirstSpirit project. Therefore, every JSON document created by the FOS initially contains the project's unique name, the time the message was created, and the start time of the underlying generation schedule:

"projectName" : "PROJECTNAME",
"createTime" : "AN EVENT MESSAGE'S CREATE TIME",
"startTime" : "THE SCHEDULE'S START TIME",

The type specified for the message distinguishes whether it is a status message, an event message or a ChangedContent message. For a status message, the parameter has the value StatusMessage; for an event message, it is EventMessage; and for a ChangedContent message, it is ChangedContentMessage.

"type" : "StatusMessage"
"type" : "EventMessage"
"type" : "ChangedContentMessage"

Chapter Examples uses examples to explain the message types.

Status message

In the case of a status message, the status and fullGeneration parameters are added to the document.

The status parameter can only have the values start and end. These define whether the information relates to the start or the end of a generation operation.

"status" : "start"	// Schedule Start
"status" : "end"	// Schedule End

The fullGeneration parameter identifies the type of generation and can only have the value true or false. In the case of a full generation operation, the parameter has the value true.

"fullGeneration" : true		// Full-Generation
"fullGeneration" : false	// each other Generation

The maintenanceModeStopped parameter provides information about whether or not the maintenance mode has been deactivated again once the full generation is complete and can only have the value true or false. If the maintenance mode has been deactivated, the parameter has the value true. The maintenance mode can be retained if the number of errors allowed in the FOS has been exceeded during the generation.

[...]
"type" : "StatusMessage"
"status" : "start" || "end"			// Start or End of the MaintenanceMode
"fullGeneration" : true
"maintenanceModeStopped" : "true" || "false 	// just when status:end

Event message

In the case of an event message, the rest of the document's structure is formed by an array of associated events:

"events" : [
 { [...] },
 { [...] }
]

These events always represent the change made to one single element. With the exception of media, the element's parent chain is also always taken into account, which is why the events are sometimes mutually dependent.

Within the parent chain there is a special feature in relation to the start pages. If changes have been made to a start page within the parent chain and no event has yet been sent for the same, this start page will be transferred in the current event message (including folder). This guarantees that a start page is always available for every folder, either because the information has already been sent in a previous event message or is being delivered in the current message.

The table below shows the events triggered if a change is made:

If several elements have been changed within the project, a separate event message is created for each element.

The structure of an event is described in the section that follows.

All events always have the following parameters:

These correspond to the type of the event, as well as the reference name and the type of the element represented by the event. The properties of the element which have potentially been changed or deleted and the references of the element which have been added or deleted are also specified.

The values available for the nodeType and type parameters are explained in the corresponding sections.

The id parameter corresponds to a consecutive number assigned to the events within an event message. It serves to uniquely identify an event within an event message.

The origin parameter can only have the values true or false. It indicates whether the specific element represented by the event has changed or just a referenced element. If a section has been changed, for example, a Page event must be generated too. In this case, the Section event receives the value true for the origin parameter. Since the Page event was only generated on the basis of the Section event, but the page has not changed, the origin parameter in the Page event adopts the value false.

Changes to the properties of a FirstSpirit element are transferred in the form of removedProperties or changedProperties:

"events": [
{ "type":"...",
  "id":...,
  "origin":...,
  "refname":"...",
  "nodeType": "...",

  "removedProperties": [
   {"name":"headline", "language":"DE"},
   {"name":"headline", "language":"EN"} ],

  "changedProperties": [
   {"name":"title", "langugae":"DE", "value":"Startseite"},
   {"name":"title", "language":"EN", "value":"Startpage"},
   {"name":"description", "value":"The startpage!"} ]
}]

The Properties are all specified by their respective names. Since the value of a property is only significant in the event of changes, it is not listed for removed properties.

In addition, the language parameter and a language code are added to language-dependent properties to enable the removed or changedProperties to be processed for all languages available in the project.

The references of a FirstSpirit element are recorded by specifying addedReferences or removedReferences:

{ "type":"...",
  "id":...,
  "origin":...,
  "refname":"...",
  "nodeType":"...",

  "addedReferences": [
   { "refType":"REFERENCE'S TYPE",
     "refname":"THE REFERENCED ELEMENT'S REFERENCENAME",
     "type":"THE REFERENCED ELEMENT'S TYPE",
     "direction":"The DIRECTION OF THE REFERENCE"} ],

  "removedReferences": [
   { "refType":" THE REFERENCE'S TYPE ",
     "refname":" THE REFERENCED ELEMENT'S REFERENCENAME",
     "type":"THE REFERENCED ELEMENT'S TYPE",
     "direction":"The DIRECTION OF THE REFERENCE"} ]
}

Each entry contains the type of reference, the reference name, and the type of element referenced. Possible values for the refType are:

The direction of the connection is also specified via the direction attribute. Possible values are INCOMING for incoming connections or OUTGOING for outgoing connections.

Changes to a user's or a group's access permissions are represented by the corresponding User or Group events. These contain the nodeType User or Group and have the following parameters as well as the ones which are always present:

This is information relating to permissions which have either been assigned to or removed from a user or a group.

{ "type" : "MODIFIED",
  "id" : ...,
  "origin" : true,
  "refname" : "USER'S (OR GROUP'S) NAME",
  "nodeType" : "USER OR GROUP",

  "addedPermissions" : [
   { "access" : "ZUGRIFFSRECHT",
     "refname" : "NAME DES KNOTENS",
     "nodeType" : "TYP DES KNOTENS"
   } ],

   "removedPermissions" : [
    { "access" : "ZUGRIFFSRECHT",
      "refname" : "NAME DES KNOTENS",
      "nodeType" : "TYP DES KNOTENS"
    } ],
}

Every entry in the two lists contains the reference name and the node type of the element for which access permissions have been changed. The value of the access parameter indicates exactly which permission has been changed. For example, if the canChange permission has been removed on the page with the reference name homepage, this is depicted as follows in the event message:

"removedPermissions" : [
 { "access" : "canChange",
   "refname" : "homepage",
   "nodeType" : "Page"
 } ]

All values available for the access parameter are explained in chapter Access.

If there are no values for the removedProperties, changedProperties, addedReferences, removedReferences, removedPermissions, or changedPermissions parameters for an event, these parameters are not included in the event.

Each event represents a change to the FirstSpirit project being used. This may be a change to a user group, an individual user or an element from the Page, Site or Media Store.

The following values are therefore available for the nodeType parameter:

Document groups are not included in this list, as they consist of several individual pages, which are combined into one single document. They are treated in the same way as page references and, as such, trigger events with the PageRef node type.

Changes to datasets in the data sources are not taken into account by explicit events either, as they are recorded by means of content projections. These are assigned in the FOS to the associated page and page reference via a separate PageRefContentProjection object. Therefore, they are represented by the corresponding events with the PageRefContentProjection node type.

A FirstSpirit element always has one of four possible states, according to whether the corresponding element has been created, modified, deleted or not edited at all.

Since a non-edited element has no significance when it comes to refreshing the live state, the following values are available for the type parameter of an event (see chapter Event messages):

Since individual events are mutually dependent, an event message may sometimes contain several events with different node types (see chapter NodeType) but the same event type.

Example 1 - Deleting a page

If a page is deleted, for example, this will also require the media used exclusively by that page to be removed too, as well as the sections belonging to it and the page references based on it. Assuming that a page does not exist in total isolation within a project, a corresponding event message would therefore have to contain not only the Page event, but also, potentially, a Media event, Section event, and PageRef event too. In this case, all four events would have the event type DELETE.

Example 2 - Deleting a section

Deleting a section removes just that section itself and the media used exclusively by that section. The associated page and the page reference based on it are retained; they are, however, classed as modified. The corresponding event message would therefore have to contain not only the Section event and Media event with the event type DELETED, but also a Page event and PageRef event with the event type MODIFIED.

The editorial permissions which can be configured in the FirstSpirit JavaClient (see figure Editorial permissions which can be configured in the JavaClient) are irrelevant when it comes to subsequently viewing the deployed live page.

Figure 5. Editorial permissions which can be configured in the JavaClient

However, certain use cases are possible where editors are redirected via a corresponding methodology from the portal into the FirstSpirit environment in order to edit content, for example. It makes good sense for this methodology to only be available to editors logged in to the portal who have the necessary FirstSpirit permissions; otherwise, it should be hidden.

For this reason, changes to editorial permissions are also transferred to the Portal Plugin with the event messages (see chapter Structure of an event). The relevant permission is specified in a User or Group event via the access parameter, which then takes on one of the following values:

Since the permissions are inherited between the user/user group and node, the canNothing "permission" is required. The canNothing permission serves to distinguish whether a permission is inherited from the parent node or does not exist. For example, if a User has the canRead permission for a PageRefFolder, he also has read access to all PageRefs in that folder, provided that no specific access permissions have been set for these PageRefs. If read access (and all other permissions) is rejected for a PageRef, this receives the canNothing permission for this user or user group. Without the canNothing permission this could not be done and inheritance would not be possible. It comes into play if the inheritance hierarchy has been interrupted in FirstSpirit and all permissions have been removed for a user or user group.

For information on the individual editorial permissions, refer to the FirstSpirit Handbook for Editors.

This section provides an example of each of the three message types.

Status message

A status message created by the FOS could look like this, for example:

{ "schedulerId":"139292",
  "projectName":"FOS-Project",
  "createTime":"1369404090435",
  "startTime":"1369404090509",
  "type":"StatusMessage",
  "status":"start",
  "fullGeneration":false
}

The status message can be identified in this example by its type. Its status indicates that it is a start message, which is used to inform the Portal Plugin of the start of a schedule. This schedule is not a full generation operation, as the fullGeneration parameter shows.

Event message

An event message created by the FOS for sending to the Portal Plugin could have the following content, for example:

{ "schedulerID":"3141592", "projectName":"Mithras Energy",
  "createTime":"1369404090435", "startTime":"1369404090509",
  "type":"EventMessage",
  "events":[
   { type:MODIFIED, id:1, origin:true,
     refname:startpageref, nodeType:PageRef
   },
   { type: MODIFIED, id:2, origin:true,
     refname:startpage, nodeType:Page
   },
   { type:CREATED, id:3, origin:true,
     refname:newstartpagetext, nodeType:Section
   },
   { type:DELETED, id:4, origin:true,
     refname:startpagetext, nodeType:Section
   },
   { type:DELETED, id:5, origin:true,
     refname:startpageimage1, nodeType:Media
   },
   { type:DELETED, id:6, origin:true,
     refname:startpageimage2, nodeType:Media
   },
   { type:MODIFIED, id:7, origin:true,
     refname:everybody, nodeType:Group,
     removedPermission:[
      {	refname: startpageref, type:PageRef,
        access:canChange },
      {	refname: startpage, type:Page,
        access:canChange }
] } ] }

In this example, the startpagetext section has been deleted (see id:4). Since there were no further references from other elements to the startpageimage1 and startpageimage2 media used by that section, they have been removed too (see id:5 and id:6). The three events therefore have the event type DELETED.

The newstartpagetext section has been created in place of the deleted section for the same page (see id:3). Therefore, the associated event type is CREATED.

The changes described mean that the startpage belonging to the section and the startpageref based on the page are also classed as modified (see id:1 and id:2). Furthermore, the canChange permission has been removed from the everybody group on the startpage and the startpageref (see id:7). The three events are therefore of the type MODIFIED.

ChangedContent message

A ChangedContent event message created by the FOS for sending to the Portal Plugin could have the following content, for example:

{ "schedulerId":"5887",
  "projectName":"FOS-Project,
  "createTime":"1375169338642",
  "startTime":"1375169338781",
  "type":"ChangedContentMessage",
  "events":[
    { "type":"MODIFIED",
      "id":3,
      "origin":true,
      "refname":"startpageref",
      "nodeType":"PageRef"
    }
  ]
}

In this example, the content of the startpageref section has been changed.

It is not possible to determine the extent to which the page content has been modified. Therefore, in order to transfer the new content, the page must be imported into the portal from the generation directory of the FirstSpirit Server again.

Depending on the portal, it may be necessary to first query additional information about the page from the FOS via the Rest interface for this import.

The messages created during the generation operation performed on the FirstSpirit Server enable data to be transferred to the FOS and saved in its persistence layer.

The messages include the information made available via the extra presentation channel which has been created, as well as standard FirstSpirit data.

Since the data transferred via the presentation channel is project-specific and, as such, always individual, no further details can be given on it.

The languages and resolutions used in the project are recorded for the part of the message created by FirstSpirit as standard; the release states of the Page, Site, and Media Store are also taken into account.

A list of the information contained in this part of the message can be found in chapter Presentation channel.

All information is saved in the persistence layer of the FOS. It can be queried via the REST interface and is thus also available to the Portal Plugin if necessary.

The REST interface has a URL, to which all requests must be directed:
http://<server name>:<port>/<webb app name>/rest/v1

Each request to the REST interface must contain an HTTP header called apikey. This header's value must be a UUID, which is known to the FOS as an API Key.

The API Keys are used to define access permissions for projects via the REST interface. Without this header, a request will be answered with the state 401 Unauthorized. As well as permissions for reading project data, an API Key can also have administrative permissions for a project, which enable it to send requests that modify the project.

More information on managing API Keys is available in the FirstSpirit Object Service Documentation for Administrators.

The FOS client makes it possible to perform queries to the REST interface of the FOS from an application, which is usually the Portal Plugin which is to be implemented. It must be integrated into this application and is therefore provided in the form of a jar file, which is included in the supplied fos-client <version number> distribution.tar.gz along with all the other dependencies.

Two examples of requests to the REST interface of the FOS are depicted here. All requests can be carried out via an http request and by using the Java API. Both versions and the result of the request are provided for each example.

List of all projects managed by the FOS

Since the FOS is not linked to one particular project on the FirstSpirit Server, it will usually manage several projects, which use it as an interface. This example shows how to query an overview of all these projects.

http request

A query via an http request is performed by expanding the URL:

http://<server name>:<port>/<web app name>/rest/v1/projects

Java API

When performing a query via the Java API, an ApiClient with access to the REST interface of the FOS must be built first. It is important here to ensure that an http header is defined called apikey. The client can be used to query the resources of the FOS and to determine the projects it manages.

import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import org.junit.Test;
import com.espirit.moddev.fos.api.project.Project;
import com.espirit.moddev.fos.api.result.ResultListProjects;
public class ClientExample {
 public void createClient() {
  // get a client builder for the REST-Service
  ApiClient.Builder apiClientBuilder = ApiClient.builder("http://<SERVERNAME>:<PORT>/<WEBAPP-NAME>/rest/v1/");

  // set the apikey to be used
  apiClientBuilder.header("apikey", "<APIKEY>");

  // build a Client
  ApiClient client = apiClientBuilder.build();

  // get the ProjectsResources
  ProjectsResources projectResources = client.getResources();

  // get all Projects
  ResultListProjects projects = projectResources.projects();

  // iterate over the Projects
  for (Project project : projects.getItems()) {
   System.out.println(project.getName());
  }
  client.close();
 }
}

Result

In this example, the REST interface returns the two projects FOS and FS Object Service. As can be seen in the additional information, FOS is a single-language project, while the FS Object Service project uses the German and English languages. Furthermore, just one of the two projects is in the maintenance mode, which has been activated automatically in this case.

{ "view":list,"items":[
  { "name":"FOS",
    "attributes":[{}],
    "languages":["DE"],
    "maintenanceMode":false,
    "automaticMaintenanceMode":false
  },
  { "name":"FS Object Service",
    "attributes":[{}],
    "languages":["DE","EN"],
    "maintenanceMode":true,
    "automaticMaintenanceMode":true
  }
] }

When the request was sent, an API Key was transferred, which had an impact on the content of the result. In creating the list of individual projects, the permissions of the API Key were taken into account and a result was generated that corresponds to these permissions. In this example, therefore, it can be assumed that the API Key has read permissions for the projects FOS and FS Object Service. However, it may be the case that other projects exist for which the API Key being used has no permissions and which, therefore, have not been included in the results. In the same way, it is also possible that neither FOS nor FS Object Service would be included in the results if a different API Key were used.

Determining a particular page from a particular project

In contrast to the previous example, it is also possible to determine just one single element via the REST interface of the FOS. This example shows the query which returns the Mithras home page reference from the FS Object Service project.

http request

In this case too, the request to the REST interface of the FOS causes the URL to be expanded. However, the name of the project, the type of the element to be determined, and its reference name are also specified:

http://<server name>:<port>/<web app name>/rest/v1/projects/FS%20Object%20Service/pageref/mithras_home

Java API

When performing a query via the Java API, an ApiClient with access to the REST interface of the FOS must be built first. As for every other request, this primarily means that an API Key is defined in the http header. The ApiClient created enables all project resources to be queried, from which the required page reference can be determined.

import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import org.junit.Test;
import com.espirit.moddev.fos.api.project.Project;
import com.espirit.moddev.fos.api.result.ResultListProjects;

public class ClientExample {
 public void createClient() {
  // get a client builder for the REST-Service
  ApiClient.Builder apiClientBuilder = ApiClient.builder("http://<SERVERNAME>:<PORT>/<WEBAPP-NAME>/rest/v1/");

  // set the apikey to be used
  apiClientBuilder.header("apikey", "<APIKEY>");

  // build a Client
  ApiClient client = apiClientBuilder.build();

  // get the ProjectsResources
  ProjectsResources projectResources = client.getResources();

  try {
   // get the pageref "mithras_home"
   Result result = projectResources.detail("FS Object Service", "pageref", "mithras_home", "list", null, null, null, null);
   System.out.println(result);
  } catch (NotFoundException e)
   e.printStackTrace();
  } catch (ProjectNotFoundException e)
   e.printStackTrace();
  } catch (BadRequestException e) {
   e.printStackTrace();
  } catch (MaintenanceException e) {
   e.printStackTrace();
  }
  client.close();
 }
}

Result

In this example, the REST interface returns the page reference Mithras home as required. The information transferred by FirstSpirit as standard regarding the page is also output.

{ "view": "list",
  "item": {
   "pageRef": {
    "refname": "mithras_home",
    "type": "PageRef",
    "attributes": [
     { "name": "fsId",
       "value": "325146"},
     { "name": "refname",
       "value": "mithras_home"},
     { "name": "type",
       "value": "PageRef"},
     { "name": "modifiedby",
       "value": "Admin"},
     { "name": "releasedate",
       "value": "1370595424313"},
     { "name": "displayName",
       "language": "DE",
       "value": "Mithras Startseite"},
     { "name": "displayName",
       "language": "EN",
       "value": "Mithras Homepage"},
     { "name": "url",
       "language": "DE",
       "value": "http://<LifeserverName>:<Port>/mithras/content/de/startpage/mithras_home.html"},
     { "name": "url",
       "language": "EN",
       "value": "http://<LifeserverName>:<Port>/mithras/content/en/startpage/mithras_home.html"}
    ],
    "groupPermissions": [],
    "userPermissions": [],
    "nodeReferences": {}
   }
 }
}

In this example too, it should be noted that the result depends on the API Key being used. In order to obtain the result shown, the API Key must have read permissions for the project FS Object Service. Otherwise the request would have ended with the http state 401 Unauthorized.

The values of a CMS_INPUT_PERMISSION input component are output in JSON, which is in turn written in a string, e.g.:

{\"activities\":[{\"name\":\"myActivity\",\"allowed\":[\"Management\",\"Marketing\"],\"forbidden\":[\"Customer\"]}]}

This is required to generate a static JSON schema. If the values were supplied not as a string but directly as JSON, a dynamic schema would be generated.

For the INPUT_PERMISSION component, both the activities and groups are "dynamic". They therefore do not depend only on the project, but can also change further within it.

The value can be read first as a string and then called as a jsonFromString easily using a JSON library. Please note that there can be any number of activities and groups.

Please also note that the name of the INPUT_PERMISSION input component also depends on the project. It should therefore be possible to configure which name is given to the input component that has the permissions.

The format in which values of the INPUT_DATE input component are output is not significantly different to the format of other input components (string). However, the format of the date in the output text depends on the configuration of the input component (mode) in FirstSpirit.

If the mode is set to DATE, then only the set date is output: 2014-07-02

If the mode is set to TIME, then the selected time is output: 05:11:51

If the mode is set to DATETIME, then the time and date including the time zone are output. Please note that the time will be the time stamp in the time zone of the server: 2014-07-02T05:11:45+01:00