Configure the Stages Server

CMS Configuration

Stages can interact with configuration management systems (CMS) to work with remotely stored files. The configuration for these systems is done in two simple steps:

  1. Add the XML snippet explained in this section to your Stages configuration for each configuration management system you want to work with
  2. Adjust this snippet for the specific configuration management system according to the explanations below

Currently, following content management systems are available and can be configured as described in the linked sections:

Common Configuration

To enable Stages to communicate with an external CMS, you have to add an XML snippet to the central configuration file, which is located at <STAGESHOME>/conf/config.xml.

A generic XML snippet for all CMS configurations looks like the following:

<?xml version="1.0" encoding="UTF-8" ?>
<stages-config>
    ...
    <cms>
        <cms-type name="[name]">
            <!-- Global Properties -->
            <cms-property name="[key]" value="[value]" />
            <cms-host ident="[ident]" name="[http://hostname.com]" displayName="[displayName]">
                <!-- Host Properties -->
                <cms-property name="[key]" value="[value]" />
            </cms-host>
        </cms-type>
    </cms>
    ...
</stages-config>

<stages-config>

The root XML element of the stages configuration file. The configuration for the content management systems has to be inserted inside this element. The CMS configuration is a child element of the <stages-config> element.

<cms>

This element holds all configuration data for the content management systems.

<cms-type name=“” >

The <cms-type> element represents the configuration for a single content management system you want to support in your Stages application.

  • name: The attribute “name” of each <cms-type> is crucial for the system to work. Every CMS implementation has its own and unique “name”.

<cms-property name=“” value=“” > (Global Properties)

Right inside the <cms-type> element you can define multiple <cms-property> elements, which affect the entire CMS type. These properties are called global properties.

  • name: The attribute “name” identifies the property by its key.
  • value: The “value” attribute defines the value for that property.

<cms-host ident=“” name=“” displayName=“” >

A <cms-type> element can have several <cms-host> elements.

  • ident: The “ident” of a <cms-host> is a simple string but has to be unique for the Stages server.
  • name: The “name” attribute identifies the server by the URL of the content management system. Please note that this URL must contain the protocol, the server's host name (not its IP address), optionally a port number, and NO path elements (e.g. https://myhost:10443).
  • displayName: The display name of the host will be shown in the host dropdown selection field in the Stages application.

<cms-property name=“” value=“” > (Host Properties)

Inside a <cms-host> element you can define <cms-property> elements, which affect only the specific host. These properties are called host properties.

  • name: The attribute “name” identifies the property by its key.
  • value: The “value” attribute defines the value for that property.

Subversion

Example Configuration

<cms-type name="subversion">
    <cms-host ident="subversion.example.ident" name="https://subversion.example.net:1234" displayName="Subversion Example Server">
        <cms-property name="user" value="subversion_username" />
        <cms-property name="password" value="subversion_password" />
    </cms-host>
</cms-type>

Host Properties

user

  • Default Value: N/A
  • Description: You may enter the Subversion username for the Stages system account here instead of the corresponding field Username in the CMS profile. If both values exist, the username from the CMS profile is preferred.

password

  • Default Value: N/A
  • Description: You may enter the Subversion password for the Stages system account here instead of the corresponding field Password in the CMS profile. If both values exist, the password from the CMS profile is preferred.

domain

  • Default Value: N/A
  • Description: You may enter the Subversion default domain for the Stages system account, and all user accounts. (Only necessary for NTLM authentication)

http.authentication.hostname (required for NTLM authentication)

  • Default Value: N/A
  • Description: The host name of the server that runs Stages and is allowed to authenticate via NTLM against the Subversion server

http.connection.timeout

  • Default Value: 300000
  • Description: The timeout in milliseconds until a HTTP connection has to be established and the maximum period of inactivity (in milliseconds) between two consecutive data packets before the socket is closed.

http.max.connections

  • Default Value: 100
  • Description: The maximum number of simultaneously used HTTP connections between Stages and the Subversion Server.

http.ssl.allow.all

  • Default Value: false
  • Description: When set to true, disables any verification checks for certificates in case of SSL-secured HTTPS connections. It is recommended to only use this in test environments where no valid certificates exist (e.g. self-signed certificates).

Sharepoint

Example Configuration

<cms-type name="sharepoint">
    <!-- Global Properties -->
    <cms-property name="stages.server.url" value="https://stages.mycompany:8080" />
    <cms-property name="http.authentication.hostname" value="nonempty" />
    <cms-property name="http.max.connections" value="100" />
    <cms-property name="http.connection.timeout" value="10000" />
    <cms-property name="http.socket.timeout" value="90000" />
    <cms-property name="http.connection.pool.max.idle" value="60000" />
    <cms-property name="http.ssl.allow.all" value="true" />
 
    <cms-host ident="sharepoint.example.ident" name="https://sharepoint.example.net:1234" displayName="Sharepoint Example Server">
        <!-- Host Properties -->
        <cms-property name="state.attribute.name" value="_Status" />
        <cms-property name="version.date.format" value="dd.MM.yyyy HH:mm" />
        <cms-property name="document.content.type.name" value="Document" />
        <cms-property name="link.content.type.name" value="Link to a document" />
        <cms-property name="user" value="sharepoint_username" />
        <cms-property name="password" value="sharepoint_username" />
    </cms-host>
</cms-type>

Global Properties

These configuration properties affect the behavior of every integrated SharePoint server. The configuration of them needs to be done in the <cms-type> section of config.xml.

stages.server.url (required)

  • Default Value: N/A
  • Description: The URL under which Stages is accessible.

http.authentication.hostname (required for NTLM authentication)

  • Default Value: N/A
  • Description: The host name of the server that runs Stages and is allowed to authenticate via NTLM against the SharePoint server.

upload.service

  • Default Value: Copy service
  • Description: Either CopyService or RPC. Defines the interface that is used for uploads to SharePoint. CopyService is the default setting, the only drawback is that it might create an additional version for the initial checkin depending of the SharePoint setting Checkout required

initial.checkin.fix

  • Default Value: true
  • Description: If CopyService is used for uploads, causes Stages to repeat the initial checkin in case the comment or version are not created correctly in SharePoint.

http.ssl.allow.all

  • Default Value: false
  • Description: When set to true, disables any verification checks for certificates in case of SSL-secured HTTPS connections. It is recommended to only use this in test environments where no valid certificates exist (e.g. self-signed certificates).

http.max.connections

  • Default Value: 100
  • Description: The maximum number of simultaneous HTTP connections between Stages and SharePoint.

http.connection.timeout

  • Default Value: 10000
  • Description: The timeout in milliseconds until a connection to the server has to be established.

http.socket.timeout

  • Default Value: 90000
  • Description: The maximum time of inactivity (in milliseconds) until a server connection is considered dead and will be closed forcefully. This value should be higher than http.connection.pool.max.idle.

http.connection.pool.max.idle

  • Default Value: 60000
  • Description: The maximum period of inactivity (in milliseconds) until a server connection will be closed automatically. For technical reasons the sum of http.connection.pool.max.idle and http.connection.resource.check.interval has to be lower than the keep-alive timeout of SharePoint's IIS site (default: 120s).

http.connection.context.timeout

  • Default Value: 60000
  • Description: The maximum period of inactivity (in milliseconds) before an authentication context is considered obsolete and will be removed by the resource monitor.

http.connection.resource.check.interval

  • Default Value: 10000
  • Description: The interval (in milliseconds) between two consecutive resource monitor runs which check for idle or expired connections and obsolete authentication contexts.

Host Properties

version.date.format

  • Default Value: N/A
  • Description: The localized date format that SharePoint is using.

raw.version.date.format (required)

  • Default Value: yyyy-MM-dd'T'HH:mm:ss'Z'
  • Description: The date format that SharePoint is using internally.

document.content.type.name (required if Sharepoint Content Types are enabled)

  • Default Value: Document
  • Description: The configurable name of the content type “Document”. The default value corresponds with the default name in english versions of SharePoint.

link.content.type.name (required if Sharepoint Content Types enabled)

  • Default Value: Link to a document
  • Description: The configurable name of the content type “Link to a document”. The default value corresponds with the default name in english versions of SharePoint.

user

  • Default Value: N/A
  • Description: You may enter the SharePoint username for the Stages system account here instead of the corresponding field Username in the CMS profile. If both values exist, the username from the CMS profile is preferred.

password

  • Default Value: N/A
  • Description: You may enter the SharePoint password for the Stages system account here instead of the corresponding field Password in the CMS profile. If both values exist, the password from the CMS profile is preferred.

domain

  • Default Value: N/A
  • Description: You may enter the SharePoint default domain for the Stages system account here instead of the corresponding field Default domain in the CMS profile. If both values exist, the default domain from the CMS profile is preferred.

state.attribute.name (required)

  • Default Value: N/A
  • Description: The optional SharePoint column to write the Stages state to.

label.attribute.name

  • Default Value: N/A
  • Description: The optional SharePoint column to read Stages labels from.

label.attribute.delimiter

  • Default Value: N/A
  • Description: A delimiting character or string that separates single labels.

element.url.attribute.name

  • Default Value: N/A
  • Description: The optional SharePoint column where external links to Stages may be stored as a back-reference

major.versions

  • Default Value: true
  • Description: This optional property can be used to specify whether major versions (e.g 2.0) or minor versions (e.g. 0.2) are to be created on checkin. By default major versions are created (major.versions=true). Set major.versions=false if minor versions shall be created instead. A more fine-grained configuration which version type is created on which state change can be defined for document lifecycles in the metamodel.