POST
to the following path:POST
to provide an XML document containing the search criteria as well as information about the response to provide.Content-Type: application/xml
header.query
element is the most complex element. It is used for full-text and structured search. Full-text search and structured search are exclusive: either Form Runner performs one, or the other.<query>
element is used for free text search: its attributes, if any, are ignored, and its text content, if present, is taken to be the text of the search. The result details to return is still determined by the subsequent <query>
elements with summary-field set to true
. See below for more information about the response format. The exact semantic of the full-text search is implementation-dependent.<query>
element used for full-text search is no longer necessarily the first element. Instead, it is the first element that doesn't specify a path
attribute. Similarly, <query>
elements used for structured search are those with a path
attribute. This means that it is no longer required to have an empty <query>
element at the beginning.fr-summary
or fr-search
. These are used to build the request.<query>
element is added to the request, with the following attributes and text value:path
attributematch
attributesubstring
, exact
, token
(see Match types below)control
attributeinput
, textarea
, select
, etc.), used if match
is absentmatch
attribute is absent, the control
attribute is used to determine the match type:input
or textarea
: imply match="substring"
select
: implies match="token"
match="exact"
name
label
type
search-field
summary-field
match
attribute can have the following values:substring
: a substring match is requested (default)exact
: an exact match is requestedtoken
: a token match is requested (for multiple selection controls)substring
is not specified at the moment (the search implementation may use a "starts-with", a "contains" logic, or something else).path
attribute can be looked at as a search key. Say your documents looks like this:personal-info/first-name
matches XML elements following the XPath notation, relative to the root element of the document.fr-summary
or fr-search
classes.[1]
suffixes.[1]
after element names, to guarantee the query only returns one node.app
and form
elements:sort-key
element:<query>
element, by specifying return-all-indexed-fields="true"
on the root element of the query:page-size
and page-number
elements control paging.page-size
attribute: how many results to return at the mostpage-number
attribute: page number to result, starting with 1<lang>
element, and the implementations of the API that ship with Orbeon Forms don't use it even if provided. Instead, when the persistence knows about multiple values corresponding to different languages for a "field", it returns all the values. In turn, the summary page displays all the values. This is inline with what is done for fields inside repeated grids or repeated sections, which can have multiple values.lang
element contains the current language used by the user in the summary page. If the form contains language-dependent fields, this information can be used to refine the search. Only Form Builder makes use of this capability.$fb-lang
, which allows the persistence implementation to discriminate on the language:<lang>
element.<lang>
element (therefore ignoring the language-sensitive search)<drafts>
element is used to tell the implementation of the persistence API which documents to return with respect to drafts:exclude
: don't include drafts. This value isn't used by Form Runner, but could be used in the future, and [SINCE 2016.2] is supported by the persistence for relational databases.only
: only return drafts.include
: return both drafts and non-drafts. This is the default if the <drafts>
element is missing.exclude
is not used in 4.6.2, but it could be used in the future.<drafts>
is only
, then the <drafts>
element can optionally have one of the following attributes:for-document-id="$document-id"
instructs the persistence to only return drafts for the given document id, of which there can be 0 or 1. This is used by Form Runner's /edit
page to check if a draft exists for a given document that is being opened, so it can, when appropriate, ask users if they prefer to open the draft or non-draft document.for-never-saved-document="true"
instructs the persistence to only return drafts for documents that were never saved. This is used by Form Runner's:/new
page to check if existing drafts already exist, in which case it might ask users if they prefer to start a new document or edit one of those drafts./summary
page if that page gets drafts-for-never-saved-document=true
in the URL.edit
mode. Only zero or one document can be returned:new
mode, zero or more documents can be returned:<operations>
element is used to tell the implementation of the persistence API which documents to return with respect to operations the user can perform.<operations any-of="update delete"/>
, where the value of the any-of
attribute is a space-separated list of one or more operations. In this example, the search API will only return documents the user can either update or delete, but not documents the user can only read.Orbeon-Form-Definition-Version
request header tells which version of the form definition is requested. Possible values are:all
: [SINCE Orbeon Forms 2020.1 and 2019.2.3] to do a search across all versions of the form definition, which used to be what was done until Orbeon Forms 2018.1; while this can lead to unexpected results (see below), callers of the API who relied on this behavior might find this backward compatible mode useful; if you are interested in this in the context of the summary page, see the oxf.fr.summary.show-version-selector.*.*
property.search-total
attribute: number of documents matched by the current search.total
attribute: total number of documents in the database for this app/form.page-size
attribute: echos of the query's attribute.page-number
attribute: echos of the query's attribute.query
attribute: echos of the full-text query text.<document>
element is returned with the following attributes:created
last-modified
name
draft
true
or false
, depending on whether the form data is a draft (autosaved) or notoperations
read
, write
, update
, and delete
, whichever operations the user is allowed to perform; also see Supporting permissions in your persistence API implementation​created-by
created-by-groupname
last-modified-by
workflow-stage
<detail>
element in the order determined by the <query>
elements with a summary-field set to true
in the request. The text value of the <detail>
element is the value of the field in the document found.path
attribute that identifies the field.return-all-indexed-fields="true"
is specified in the search query, all indexed fields are returned as separate <detail>
elements, and not only the fields specified in the search query with <query>
, if any.