Orbeon Forms
Search…
Persistence API

Children pages

Introduction

Orbeon Forms form definitions and form data are stored via an an abstraction called the persistence API. This allows storing form definitions and form data for all or specific forms in different places. For example, you could store your form definitions into Oracle, and your form data into your own, custom database.

Built-in support

Out of the box, Orbeon Forms provides an implementation of the persistence API for a number of databases, and other implementations are provided by third parties. See Database Support for details.

Configuration

For a description of the terminology and configuration properties, see Form Runner Configuration Properties.

REST-based

The Form Runner/Form Builder persistence API is based on REST. This means that Form Builder and Form Runner use HTTP to communicate with a persistence layer implementation.
Following the REST philosophy, HTTP methods are used to determine what CRUD operation to perform:
    GET: read a resource
    PUT: create or update a resource
    DELETE: delete a resource
For example, to deal with form data:
/fr/service/persistence
Operation
HTTP Method
URL
Create
PUT
/fr/service/persistence/crud/$app/$form/(data|draft)/$doc/data.xml
Read
GET
/fr/service/persistence/crud/$app/$form/(data|draft)/$doc/data.xml
Update
PUT
/fr/service/persistence/crud/$app/$form/(data|draft)/$doc/data.xml
Delete
DELETE
/fr/service/persistence/crud/$app/$form/(data|draft)/$doc/data.xml
Search
POST
/fr/service/persistence/search/$app/$form
Metadata
GET
/fr/service/persistence/form
where:
    $app is the form definition's application name
    $form is the form definition's form name
    $doc is the form definition's document id

Optional features

[SINCE Orbeon Forms 4.4]
    Drafts – If your persistence provider does not support drafts, you can specifically turn off the autosave feature for that persistence layer with the oxf.fr.persistence.*.autosave property. See Autosave and persistence layer configuration for details.
    User/group permissions – Similarly, if your persistence provider does not support user/group permissions, you can specifically turn off the permissions feature for that persistence layer with the oxf.fr.persistence.*.permissions property. See persistence layer configuration for details.

Virtual hierarchy of data

Form Runner/Form Builder access data under a virtual hierarchy of URLs, not unlike directories or folders in a filesystem. However, this hierarchy can be physically located in different places:
    An XML database, like eXist.
    A disk-based filesystem.
    Your own system, which you can implement on top of a database or other type of storage.
Following XML database technology, we use the terms collections and resources instead of directories and files.
The hierarchy looks like this:
    acme/ → app name
      address/ → form name
        form/ → form definition
          form.xhtml → the form definition proper
          e9ed0270896ac9012612c570698c6955d8c0de67.bin → PDF template attached to form definition
          d7419b1467b0c0c4df3ed415aaa788325817d478.bin → image attached to form definition
          873ee4175a820fe3bac2fabb808b1ce9927d7f3a.bin → other file attached to form definition
        data/ → form data
          74cb880847c638577e7afa15911efc99ceaf2dcb → one instance of form data
            data.xml → form data proper
            c738877f52110302e407e9bba87e0ef92531b357.bin → image attached to form data
            a502ea5404ba8afb9e364a3e73dbd477eb6e40b8.bin → other file attached to form data
        4abca3daf30523fd17c3699a6044f2e53b21f933 → another instance of form data
          data.xml
        draft/ → draft form data
          9438f77ff8326c0c206b02f090f818841affd98a → one instance of draft form data
            data.xml
      contract/
        form/
        data/
    foobar/
The hierarchy is organized as follows:
    At the top-level there is one collection per application
    Within an application collection, there is one collection per form definition
    Within a form definition there is one collection called form for the form definitions produced by Form Builder, and one collection called data for form data produced by Form Runner
    Each form collection contains:
      form.xhtml: the main form definition, which is an XHTML+XForms resource
      optional attachments, such as images, PDF files, and other file attachments uploaded by the form author when editing the form definition
    Each data collection contains one collection for each form data id, identified by an automatically-generated UUID
    The draft collection is analogous to the "data" collection, but used by autosave to store form data before users explicitly save it
      implementations of the persistence API are expected to remove the draft (with the corresponding attachments) when the corresponding data is saved
    Each form data collection contains:
      data.xml: the main form data document
      optional attachments, such as images uploaded by the user when editing the form data

Headers

All persistence URLs are called with headers matching configuration properties for the given persistence layer implementation. For example:
    eXist
      property:
      1
      <property
      2
      as="xs:anyURI"
      3
      name="oxf.fr.persistence.exist.exist-uri"
      4
      value="/exist/rest/db/orbeon/fr">
      Copied!
      header:
      1
      Orbeon-Exist-Uri: /exist/rest/db/orbeon/fr
      Copied!
    Oracle
      properties:
      1
      <property
      2
      as="xs:string"
      3
      name="oxf.fr.persistence.oracle.datasource"
      4
      value="oracle">
      5
      <property
      6
      as="xs:boolean
      7
      name=" oxf.fr.persistence.oracle.create-flat-view"
      8
      value="false">
      Copied!
      headers:
      1
      Orbeon-Datasource: oracle
      2
      Orbeon-Create-Flat-View: false
      Copied!
    MySQL
      property:
      1
      <property
      2
      as="xs:string"
      3
      name="oxf.fr.persistence.mysql.datasource"
      4
      value="mysql">
      Copied!
      header:
      1
      Orbeon-Datasource: mysql
      Copied!
    DB2
      property:
      1
      <property
      2
      as="xs:string"
      3
      name="oxf.fr.persistence.db2.datasource"
      4
      value="db2">
      Copied!
      header:
      1
      Orbeon-Datasource: db2
      Copied!
Last modified 2yr ago