Form Metadata API
Last updated
Last updated
HTTP GET
(v1) or POST
(v2) to the following path:
This API is used to obtain the list of published forms as well as associated metadata, including published versions, form titles, and permissions.
In particular, this API is used internally by:
the
the
the
the , to obtain a given form's permissions and versions
The Form Metadata API v2 tries to behave as much as possible like the first version of the API. The main difference is that it uses POST
instead of GET
. This allows for more complex requests to be passed to the API (filtering, sorting, paging).
All requests to the API must include an XML content body, with a Content-Type: application/xml
header.
You get the list of all the published forms with a POST
on:
with the following payload, which is the simplest request that can be sent:
The following optional attributes can be added to the search
element:
all-forms
false
ignore-admin-permissions
false
xml:lang
None
Default language for language-specific filtering/sorting directives (e.g. en
, fr
, etc.)
To filter the results, you can add a filter
element to your request:
metadata
Yes
The metadata to filter by
match
Yes
The match type
xml:lang
No
Language for language-specific metadata, overrides any request-wide value specified on the search
element
url
No
URL of the remote server or local server if no URL specified
combinator
No
Combinator to use in case of multiple local and/or remote values
One or multiple filters can be specified. If no filter is present, all results are returned.
The following metadata are supported:
application-name
String
No
Application name
form-name
String
No
Form name
form-version
Number
No
Form version
created
Date/time
No
Creation date/time
last-modified
Date/time
No
Last modification date/time
last-modified-by
String
No
Username of the user who last modified the form definition
title
String
Yes
Form title
available
Boolean
No
Whether the form definition is available
operations
List of strings
No
Space-separated list of operations allowed on the form (admin
, create
, read
, update
, delete
and/or list
)
exact
String, boolean
Exact match
substring
String
Substring match
gte
Date/time, number
Greater than or equal
gt
Date/time, number
Greater than
lte
Date/time, number
Lower than or equal
lt
Date/time, number
Lower than
token
List of strings
All listed values must be found in the metadata (in any order)
For an exact
match on form-version
, the special value latest
can be used to retrieve the latest version of each form.
The following combinators are supported:
min
Date/time
Least recent date/time
max
Date/time
Most recent date/time
or
Boolean, list of strings
Booleans: OR
operator
Lists of strings: union of values
and
Boolean, list of strings
Booleans: AND
operator
Lists of strings: intersection of values
Date/time values are expected to be given in ISO format.
To sort the results, you can add a sort
element to your request:
metadata
Yes
The metadata to sort by (see above)
direction
Yes
The sort direction, either asc
(ascending) or desc
(descending)
xml:lang
No
Language for language-specific metadata, overrides any request-wide value specified on the search
element
url
No
Same semantics as on filter
element (see above)
combinator
No
Same semantics as on filter
element (see above)
If no sort
element is specified, the results are sorted by last modification date/time, in descending order, using the most recent last modification date/time between the local server and any remote server (i.e. using the max
combinator).
Limitations:
At the moment, only a single sort
element is supported.
To page the results, you can use the following XML element:
page-number
is the 1-based page number and page-size
is the maximum number of results to return per page.
Paging the results is optional. By default, all results are returned.
The Form Metadata API v2 supports querying one or multiple remote servers. To do so, you can add remote-server
elements to your request:
When remote-server
elements are present, the API queries the remote servers in addition to the local providers. The results are then aggregated.
Retrieving the latest versions of any form with the application name acme
, sorted by form name, and paginated:
Retrieving any form that is available, either locally or remotely, sorted by the French title of the form on the local server:
Retrieving forms that have the admin
operation on the remote server:
Response documents in v2 follow the same format as in v1:
The main difference with v1 is that metadata for remote servers can be included in the response as well, if credentials for remote servers are included in the request. In that case, metadata specific to remote servers will be included in remote-server
elements. Each remote server is identified by its URL.
Example:
The following elements are never included in the remote server metadata, as they are used to identify (and hence group) the form definitions: application-name
, form-name
, and form-version
.
You get the list of all the published forms with a GET
on:
Then it might call the eXist implementation with another GET
on:
Finally, it aggregates the results returned by each implementation.
[SINCE Orbeon Forms 4.3]
Optionally, an app name or both an app name and form name can be specified on the URL. In that case, the API only returns information about published forms in that specific app, or that specific app and form is returned.
When an app specified, the URL looks like:
/fr/service/persistence/form/$app
When both an app and form name are specified, the URL looks like:
/fr/service/persistence/form/$app/$form
[SINCE Orbeon Forms 2016.2]
Optionally, you can pass the URL parameter all-versions
:
when set to true
All form definition versions are returned.
when omitted or set to false
Only the form definition with the highest published version number is returned.
[SINCE Orbeon Forms 2019.1, 2018.2.1, 2018.1.4, 2017.2.3]
Optionally, you can pass the URL parameter all-forms
:
when set to true
all forms are returned without checking for permissions or other criteria
when omitted or set to false
(which was the behavior before all-forms
was supported)
Only forms to which the user has "access" are returned.
If the user has access as per form-builder-permissions.xml
, then all form definitions are returned.
[SINCE Orbeon Forms 2022.1], this logic is ignored if ignore-admin-permissions
is set to true
.
Otherwise:
library
form definitions are excluded
forms which have permissions defined and for which the user has no permissions at all are excluded
unavailable form definitions are excluded
[SINCE Orbeon Forms 2021.1]
Optionally, you can pass the URL parameter modified-since
:
this must be an ISO date/time
when passed, only form definitions which have been modified since the given date/time are returned
For example:
[SINCE Orbeon Forms 2022.1]
Optionally, you can pass the URL parameter ignore-admin-permissions
:
when set to true
when omitted or set to false
(the default)
The behavior is the same as before this parameter was supported.
Each <form>
element contains:
<application-name>
<form-name>
All the elements inside the form metadata instance of the corresponding form definition
This can be retrieved with the following XPath expression:
/xh:html/xh:head/xf:model/xf:instance[@id = 'fr-form-metadata']/metadata/*
[SINCE Orbeon Forms 2016.1]
The <description>
and <migration>
elements are excluded.
<last-modified-time>
[SINCE Orbeon Forms 4.4]
[UNTIL Orbeon Forms 4.10.x]
last modification date/time for the app/form combination
[SINCE Orbeon Forms 2016.1]
last modification date/time for the app/form/version combination
<form-version>
[SINCE Orbeon Forms 2016.1]
contains the version number of the given <form>
<available>
set to false
when the form definition is marked as not available
<permissions>
contains the form definition permissions as contained in the form definition's metadata
this is required for permissions checking to work
The document returned by this API looks like this:
The document returned by this API looks like this, here for the acme/order
form:
Note that the versions do not have to be in order and some versions can be missing.
Here note that version 5 is marked as not available with:
The following match types are supported and follow the same semantics as in the :
For more information about remote server configuration, see .
This, in turn, calls the corresponding API for each persistence API implementation defined in the properties as , since different forms can be published on different persistence implementations. For example, this might call MySQL implementation doing a GET
on:
Even if the user has access to the form as per form-builder-permissions.xml
, the forms are filtered as .
If the all-forms
parameter is set to true
, then this parameter is ignored, and all forms are returned without checking for permissions or other criteria as .
NOTE: This is only returned when using a relational database, as the implementation of the persistence API for eXist .