Persistence configuration properties

Levels of configuration

Storage for the persistence hierarchy can be configured at multiple levels:

  • Globally
  • For each application
    • The application is referred to with an app name.
  • For each form definition within an application
    • The form definition is referred to with a form name.
  • For each resource type (form definition vs. form data)
    • The resource type is referred to with an identifier:
      • form: form definition as XHTML, with optional associated resources (images, PDF template, and other attachments)
      • data: form data as XML, with optional associated attachments

This allow you for example to store certain form definition on disk, while storing the associated data, as filled-out by users, in one or more databases.

Persistence layer configuration

Orbeon Forms 4.0 introduces a level of indirection in the persistence layer configuration: you map the parameters app, form, and form definition or data to a provider, and then map that provider to its REST persistence API. This is configured via properties starting with oxf.fr.persistence.provider.

By default, eXist is configured for all apps and forms, including form definitions and form data. This is done by associating the exist provider:

<property
    as="xs:string"
    name="oxf.fr.persistence.provider.*.*.*"
    value="exist"/>

In each such provider mapping, there are 3 configurable pieces of information. They represent, in this order:

  1. A string to specify the Form Runner application name, like orbeon or acme.
  2. A Form Runner form name, like registration or address.
  3. Whether the configuration regards form data (data), or the form configuration files (form).

Each of those can be a wildcard (*). Wildcards allow you to setup Orbeon Forms to use different persistence providers for different app, form, and resource type combinations.

The properties are interpreted hierarchically and you may specify the configuration more or less specifically:

Property Explanation
oxf.fr.persistence.provider.*.*.* form definitions and form data for all applications
oxf.fr.persistence.provider.*.*.data form data for all applications
oxf.fr.persistence.provider.*.*.form form definitions for all applications
oxf.fr.persistence.provider.orbeon.*.form form definitions for all forms in application "orbeon"
oxf.fr.persistence.provider.orbeon.*.data form data for all forms in application "orbeon"
oxf.fr.persistence.provider.orbeon.contact.* form definitions and data for "orbeon/contact"
oxf.fr.persistence.provider.orbeon.contact.form form definitions for "orbeon/contact"
oxf.fr.persistence.provider.orbeon.contact.data form data for "orbeon/contact"

NOTE: This means that you can't name a persistence provider provider.

For example some built-in demo forms as well as Form Builder load their form definitions directly from the Orbeon Forms web application. This is done by using more specific properties (without wildcards):

<property
    as="xs:string"
    name="oxf.fr.persistence.provider.orbeon.builder.form"
    value="resource"/>
<property
    as="xs:string"
    name="oxf.fr.persistence.provider.orbeon.dmv-14.form"
    value="resource"/>

One thing you might notice is that, as far as configuring persistence, you treat Form Builder itself just like another form, with app name orbeon and form name builder.

If you want to change the default provider to Oracle, and since a provider named oracle is predefined, the following configuration will do just that:

<property
    as="xs:string"
    name="oxf.fr.persistence.provider.*.*.*"
    value="oracle"/>

Because wildcards are used, this property does not override the configuration for the built-in demo forms as well as Form Builder! This is desirable, because the Form Builder implementation itself is not usually something you want to store somewhere else.

In the case of Oracle, the wildcards also allow you to setup Orbeon Forms to use different schemas for different app, form, and resource type combinations. For instance you could store everything related to an hr app in one Oracle database schema and everything related to another finance app in another Oracle database schema. For more on this, see how to setup the persistence layer for multiple schemas.

Each provider supports standard properties, as follows:

Property Explanation
oxf.fr.persistence.[provider].uri specifies the location, via HTTP, of the provider implementation.
oxf.fr.persistence.[provider].active specifies whether the provider is active
oxf.fr.persistence.[provider].autosave specifies whether autosave is supported.
oxf.fr.persistence.[provider].permissions specifies whether user/group permissions are supported
oxf.fr.persistence.[provider].versioning specifies whether versioning is supported

uri property

The uri property specifies the location, via HTTP, of the provider implementation.

<property
    as="xs:anyURI"
    name="oxf.fr.persistence.[provider].uri"
    value="[URI to reach the provider]"/>

active property

[SINCE Orbeon Forms 4.4]

The active property specifies whether the provider is active.

This is used as follows (confirmed for Orbeon Forms 4.4 to 4.10):

  • If active, the Form Runner Home Page queries the persistence implementation to obtain the list of published forms and enable administrative operations.
  • See issue #2327.
<property
    as="xs:boolean"
    name="oxf.fr.persistence.[provider].active"
    value="[true|false]"/>

autosave property

[SINCE Orbeon Forms 4.4]

The autosave property specifies whether autosave is supported.

This is used as follows (confirmed for Orbeon Forms 4.4 to 4.10):

  • If true, Form Runner enables autosave if the other conditions are met. Otherwise, Form Runner will not attempt to enable autosave.
<property
    as="xs:boolean"
    name="oxf.fr.persistence.[provider].autosave"
    value="[true|false]"/>

permissions property

[SINCE Orbeon Forms 4.4]

The permissions property specifies whether user/group permissions are supported.

If true, Form Runner assumes that permissions are supported by the provider implementation.

This is used as follows (confirmed for Orbeon Forms 4.4 to 4.10):

  • The Summary Page sends a 403 if the user doesn't have access based on role, and the persistence provider is known not to support permissions.
<property
    as="xs:boolean"
    name="oxf.fr.persistence.[provider].permissions"
    value="[true|false]"/>

versioning property

[SINCE Orbeon Forms 4.5]

The versioning property specifies whether versioning is supported.

If true, Form Runner assumes that versioning is supported by the provider implementation.

This is used as follows (confirmed for Orbeon Forms 4.5 to 4.10):

  • At form publishing time, Form Builder proposes the option to overwrite the existing published form definition, or to create a new version.
<property
    as="xs:boolean"
    name="oxf.fr.persistence.[provider].versioning"
    value="[true|false]"/>

Multiple databases of the same type

Say you have two MySQL databases (or a single MySQL database with different schemas and users configured) and you would like to configure Orbeon Forms to store form definitions and form data to one or the other of the databases. Assume the following JDBC datasources:

  • mysql_foo
  • mysql_bar

You associate each datasource with a Form Runner persistence provider with the following properties:

<property as="xs:anyURI"  name="oxf.fr.persistence.mysql_foo.uri"         value="/fr/service/mysql"/>
<property as="xs:string"  name="oxf.fr.persistence.mysql_foo.datasource"  value="mysql_foo"/>
<property as="xs:boolean" name="oxf.fr.persistence.mysql_foo.autosave"    value="true"/>
<property as="xs:boolean" name="oxf.fr.persistence.mysql_foo.permissions" value="true"/>
<property as="xs:boolean" name="oxf.fr.persistence.mysql_foo.versioning"  value="true"/>
<property as="xs:boolean" name="oxf.fr.persistence.mysql_foo.active"      value="true"/>

<property as="xs:anyURI"  name="oxf.fr.persistence.mysql_bar.uri"         value="/fr/service/mysql"/>
<property as="xs:string"  name="oxf.fr.persistence.mysql_bar.datasource"  value="mysql_bar"/>
<property as="xs:boolean" name="oxf.fr.persistence.mysql_bar.autosave"    value="true"/>
<property as="xs:boolean" name="oxf.fr.persistence.mysql_bar.permissions" value="true"/>
<property as="xs:boolean" name="oxf.fr.persistence.mysql_bar.versioning"  value="true"/>
<property as="xs:boolean" name="oxf.fr.persistence.mysql_bar.active"      value="true"/>

Then if you would like:

  • form definitions and form data for the Form Runner app foo to go to mysql_foo
  • form definitions and form data for the Form Runner app bar to go to mysql_bar

Add:

<property as="xs:string"  name="oxf.fr.persistence.provider.foo.*.*"      value="mysql_foo"/>
<property as="xs:string"  name="oxf.fr.persistence.provider.bar.*.*"      value="mysql_bar"/>

Configuration properties for specific persistence providers

Each provider may have specific configuration properties. For the latest settings, see properties-form-runner.xml.

See also

results matching ""

    No results matching ""