Persistence API
Children pages
Introduction
Orbeon Forms form definitions and form data are stored via 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 resourcePUT
: create or update a resourceDELETE
: delete a resource
For example, to deal with form data:
/fr/service/persistence
where:
$app
is the form definition's application name$form
is the form definition's form name$document
is the form data'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 nameaddress/
→ form nameform/
→ form definitionform.xhtml
→ the form definition propere9ed0270896ac9012612c570698c6955d8c0de67.bin
→ PDF template attached to form definitiond7419b1467b0c0c4df3ed415aaa788325817d478.bin
→ image attached to form definition873ee4175a820fe3bac2fabb808b1ce9927d7f3a.bin
→ other file attached to form definition
data/
→ form data74cb880847c638577e7afa15911efc99ceaf2dcb
→ one instance of form datadata.xml
→ form data properc738877f52110302e407e9bba87e0ef92531b357.bin
→ image attached to form dataa502ea5404ba8afb9e364a3e73dbd477eb6e40b8.bin
→ other file attached to form data
4abca3daf30523fd17c3699a6044f2e53b21f933
→ another instance of form datadata.xml
draft/
→ draft form data9438f77ff8326c0c206b02f090f818841affd98a
→ one instance of draft form datadata.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 calleddata
for form data produced by Form RunnerEach
form
collection contains:form.xhtml
: the main form definition, which is an XHTML+XForms resourceoptional 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 UUIDThe
draft
collection is analogous to the "data" collection, but used by autosave to store form data before users explicitly save itimplementations 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 documentoptional 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:
header:
Oracle
properties:
headers:
MySQL
property:
header:
DB2
property:
header:
Last updated