Configuration Properties

Overview

Orbeon Forms is mainly configured via properties. A property is made of:
  • a type, such as xs:boolean
  • a name, such as oxf.resources.versioned
  • a value, such as true
  • optionally, a processor name, such as oxf:request, which refers to an XPL processor name
The basic format looks like this:

<property
  as="xs:boolean"
  name="oxf.resources.versioned"
  value="true"/>

Some properties support wildcards, for example:
oxf.fr.persistence.app.uri.*.*.*

You can also place longer property values inline: [SINCE Orbeon Forms 4.6]

<property as="xs:string" name="oxf.fr.detail.process.save-final.*.*">
    require-uploads
    then validate-all
    then save
    then success-message("save-success")
    recover error-message("database-error")
</property>

Properties fall in two categories:
  • standard: defined by Orbeon Forms
  • custom: defined by programmers
All standard properties have standard values defined in built-in property files, described below, and can be overridden when needed. They are documented in sub-pages.

In general, here is how you deal with properties:
  • look up the documentation for a given property
  • if needed, override it in one of the properties-local*.xml files under your web app's WEB-INF/resources/config
Property files are reloaded every time they are changed (after a short delay), however some properties are taken into account only when the server is first started.

Overriding properties

To override properties, you create one of the following files under your web app's WEB-INF/resources/config:
  • properties-local.xml
    • all run modes
  • properties-local-dev.xml
    • dev run mode only [SINCE 2012-05-03]
    • properties in this file also override properties in properties-local.xml
  • properties-local-prod.xml
    • prod run mode only [SINCE 2012-05-03]
    • properties in this file also override properties in properties-local.xml
Properties defined in these files override properties in the standard property files.

By following this practice, you avoid modifying files that ships with Orbeon Forms, which makes upgrading to newer versions of Orbeon Forms easier.

If you don't already have one of the properties-local*.xml files:
  • copy any or all of the following files, as required:
    • properties-local.xml.template to properties-local.xml
    • properties-local-dev.xml.template to properties-local-dev.xml
    • properties-local-prod.xml.template to properties-local-prod.xml
  • add your own properties to the resulting XML files
 Note that each property file must have a root <properties> element:

<properties xmlns:xs="http://www.w3.org/2001/XMLSchema"
            xmlns:oxf="http://www.orbeon.com/oxf/processors">
    ... properties are defined here ...
</properties>

NOTE: The *.template files are just templates for the actual property files. We don't recommend you modify the template files themselves.

Wildcards in properties

Property names may be defined using wildcards. A property name is assumed to be built as a series of path elements separated by . characters. A path element may contain a * character instead of an actual path element value.

<property as="xs:anyURI" name="oxf.fr.persistence.app.uri.*.*.*" value="/fr/service/exist"/>
<property as="xs:anyURI" name="oxf.fr.persistence.app.uri.*.*.data" value="/fr/service/oracle"/>
<property as="xs:anyURI" name="oxf.fr.persistence.app.uri.orbeon.builder.form" value="/fr/service/resource"/>

In this example:

  • If the property name oxf.fr.persistence.app.uri.orbeon.builder.form is requested, the value /fr/service/resource is returned (exact match).
  • If the property name oxf.fr.persistence.app.uri.orbeon.foobar.data is requested, the value /fr/service/oracle is returned, because the path elements orbeonfoobar match wildcards, and data matches the last path element.
  • If the property name oxf.fr.persistence.app.uri.orbeon.foobar.form is requested, the value /fr/service/exist is returned, because the path elements orbeonfoobar and form all match wildcards.

This allows creating hierarchical properties with generic defaults and more specific values.

In general these are used with Form Runner or Form Builder and in these cases:

  • The first wildcard matches a forms "application name"
  • The second wildcard matches a forms "form name"
There is a precedence order with wildcards:
  1. an exact match is checked first and always wins if found
  2. a wildcard match is done then, starting from the left
So:
  • foo.bar wins over *.**.bar, and foo.*
  • foo.* wins over *.bar

Built-in property files

The default values for those properties are provided in the following files, which are stored in orbeon-resources-private.jar:
  • config/properties-dev.xml
    • [SINCE 2012-05-03]
    • root of dev mode properties
  • config/properties-prod.xml
    • [SINCE 2012-05-03
    • root of prod mode properties [SINCE 2012-05-03]
  • config/properties-base.xml
    • base Orbeon Forms properties
  • config/properties-xforms.xml
    • XForms engine properties
  • config/properties-form-runner.xml
    • Form Runner properties
  • config/properties-form-builder.xml
    • Form Builder properties
In general, you shouldn't modify these files.

Properties types

Properties have a documented type, which must be one of the following:
  • xs:string
  • xs:boolean
  • xs:integer
  • xs:anyURI
  • xs:QName
  • xs:date
  • xs:dateTime
  • xs:NMTOKENS

Defining your own properties

In addition to the standard properties, you can define your own properties. You can then access them from:
  • XPath expressions in XForms with xxf:property().
  • XPath expressions in XPL with p:property(), where the prefix p is mapped to the namespace http://www.orbeon.com/oxf/pipeline.
  • XPath expressions in XSLT with pipeline:property(), where the prefix pipeline is mapped to namespace java:org.orbeon.oxf.processor.pipeline.PipelineFunctionLibrary.
In all cases, for security reasons, those functions won't return the value of properties that contain the string "password" in the name of the property.

Properties subsystem initialization

The properties sub-system is initialized after the Resource Manager (the properties being read like any other Orbeon Forms resources). By default, the following top-level URL is loaded:
  • web app in prod mode: oxf:/config/properties-prod.xml [SINCE 2012-05-03]
  • web app in dev mode: oxf:/config/properties-dev.xml [SINCE 2012-05-03]
  • web app (prior to 2012-05-03): oxf:/config/properties.xml
  • command-line: oxf:/properties.xml
Property files support inclusions via XInclude. This is the mechanism used by Orbeon Forms to load all the secondary property files.