Send action
The
send
action is one of the most important actions that Orbeon Forms can perform with form data: it sends data to an HTTP (or HTTPS) service. The following sections detail the possible configuration parameters of this action.[SINCE Orbeon Forms 4.4 except
property
]The following example uses three parameters in the
send
action for the form my-app/my-form
:<property as="xs:string" name="oxf.fr.detail.process.send.my-app.my-form" >
send(
uri = "http://example.org/accept-form",
method = "PUT",
content = "metadata"
)
</property>
The following parameters can be used:
property
: specifies an optional property prefixuri
: URL to which to send the datamethod
:GET
,POST
(default), orPUT
nonrelevant
- [SINCE Orbeon Forms 2017.1]
- values
keep
: all values are serialized,remove
: non-relevant values are not serialisedempty
: non-relevant nodes are serialized as empty values
- default:
remove
prune
- [DEPRECATED SINCE Orbeon Forms 2017.1]
- use
nonrelevant
instead - whether to prune non-relevant nodes (
true
by default)
annotate
: space-separated list of levels to annotate elements (the empty string by default)replace
:all
to load the resulting response in the browser, ornone
(default)[SINCE Orbeon Forms 4.5]Ifreplace
is set toall
and the service issues a redirection via an HTTP status code, the redirection is propagated to the client. This also works with portlets.SECURITY NOTE: Ifreplace
is set toall
, the content of resources or redirection URLs accessible by the Orbeon Forms server are forwarded to the web browser. Care must be taken to forward only resources that users of the application are allowed to see.content
:xml
to send the XML data (default)
data-format-version
[SINCE Orbeon Forms 4.8]:edge
: send the data in the latest internal format2019.1.0
: send the data in the Orbeon Forms 2019.1-compatible format [SINCE Orbeon Forms 2019.1]4.8.0
: send the data in the Orbeon Forms 4.8-compatible format4.0.0
: send the data in the Orbeon Forms 4.0-compatible format (the default)
parameters
: name of parameters sent to the service end point, in addition to the form content- space-separated list of standard parameters to automatically add to the URL (see below)
- default:
app form form-version document valid language process data-format-version
form-version
added to defaults in Orbeon Forms 4.7process
added to defaults in Orbeon Forms 4.7
serialization
:[SINCE Orbeon Forms 4.7]- determine the serialization of the XML data
- values
application/xml
: XML serializationnone
: no serialization
- default
application/xml
whenmethod
is set topost
orput
none
otherwise
prune-metadata
:[SINCE Orbeon Forms 2016.1]- this is applied when
content
is set toxml
only true
to remove all occurrences offr:
-prefixed elements and attributesfalse
to leave such occurrences- default
false
whendata-format-version
is set toedge
true
otherwise
content-type
:[SINCE Orbeon Forms 2016.2]- specify the
Content-Type
header to set whenmethod
is set topost
orput
- it is usually not necessary to specify
content-type
explicitly - default
application/xml
whencontent
is set toxml
,metadata
,pdf-url
ortiff-url
application/pdf
whencontent
is set topdf
image/tiff
whencontent
is set totiff
show-progress
:[SINCE Orbeon Forms 2017.1]- if
replace
is set toall
, whether to continue showing the loading the indicator while the browser navigates away from the current page - typically, you'll only want to set this parameter to
false
if you know that URL the browser navigates to won't replace the current page, say because the page will be opened in another window, or be downloaded by the browser - default:
true
target
:[SINCE Orbeon Forms 2017.1]- if
replace
is set toall
, specifies the name of the window where to display the result from thesend()
, with same semantic as the HTMLtarget
attribute on<a>
- typically, if setting a
target
, you'll also want to add areplace = "false"
attribute, so the loading indicator on the current page doesn't stay after the content in the target page has been loaded - default: none
headers
:[SINCE Orbeon Forms 2019.2]- specifies one or more custom HTTP headers to add to the HTTP request
- a single header has the usual HTTP format:headers = "Foo: value of foo"
- multiple headers can be separated with a newline escape sequence, as in:headers = "Foo: value of foo\nBar: value of bar"
- a value template may be used, with the caveat about character encodings below:headers = "Foo: {//my-control}"
- NOTE: HTTP headers typically do not support all Unicode characters as header values.
The following example refers in the
send
action to the properties with the common prefix oxf.fr.detail.process.send.my-app.my-form
. It configures the URL, the method, and the type of content using three additional sub-properties.<property as="xs:string" name="oxf.fr.detail.process.send.my-app.my-form" >
send("oxf.fr.detail.process.send.my-app.my-form")
</property>
<property
as="xs:string"
name="oxf.fr.detail.process.send.my-app.my-form.uri"
value="http://example.org/accept-form"
/>
<property
as="xs:string"
name="oxf.fr.detail.process.send.my-app.my-form.method"
value="PUT"
/>
<property
as="xs:string"
name="oxf.fr.detail.process.send.my-app.my-form.content"
value="metadata"
/>
The following properties can be used to configure a
send
action with properties:[SINCE Orbeon Forms 4.4]
The following properties are XPath Value Templates evaluating in the context of the root element of the form data instance:
uri
method
headers
prune
annotate
content
parameters
replace
[SINCE Orbeon Forms 4.7]
Example
<property as="xs:string" name="oxf.fr.detail.send.success.uri.my-app.my-form">
/fr/service/custom/orbeon/echo?action=submit&foo={
encode-for-uri(xxf:instance("fr-form-instance")//foo)
}&bar={
encode-for-uri(xxf:instance("fr-form-instance")//bar)
}
</property>
Note the use of the
encode-for-uri()
function which escapes the value to place after the =
sign.Parameters have a higher precedence. In this example, the
uri
parameter is used, even if a oxf.fr.detail.send.success.uri
property is present:send(property = "oxf.fr.detail.send.success", uri = "http://acme.org/orbeon")
The full URL is composed of:
- the URL specified by the
uri
property - the following URL parameters (when present in
parameters
)app
: the current form's app nameform
: the current form's form nameform-version
: the form definition version in use [SINCE Orbeon Forms 4.5]document
: the current document idvalid
: whether the data sent satisfies validation ruleslanguage
: the language of the form at the time it was submitted [SINCE Orbeon Forms 4.5]noscript
: whether the noscript mode was in use [SINCE Orbeon Forms 4.6]- NOTE: Starting with Orbeon Forms 2018.1, this always returns
false
.
process
: unique process id for the currently running process [SINCE Orbeon Forms 4.7]workflow-stage
: the current workflow stage associated with the data, as returned by thefr:workflow-stage-value()
function [SINCE Orbeon Forms 2021.1]
Example:
http://example.org/service?
document=7520171020e65a1585e72574ae1fbe138c415bee&
process=139ceb515f918d6d17030b81255d8a3dfa0501cc&
valid=true&
app=acme&
form=invoice&
form-version=1&
language=en
[SINCE Orbeon Forms 2018.2]
If a parameter name is already present on the URL, the parameter initially on the URL takes precedence.
[SINCE Orbeon Forms 2018.1]
When using PDF templates and
content = "pdf"
or content = "tiff"
, you can control the PDF processing with the following:use-pdf-template
- default:
true
- If at least one PDF template is available, the default is to use one of the PDF templates. But if
use-pdf-template = "false"
, then use of any PDF template is disabled and the automatic PDF is produced.
pdf-template-name
- If
pdf-template-name
specifies a name, such as withpdf-template-name = "archive"
, the list of available PDF templates is reduced to those having an exactly matching name. If no matching name is found, an error is raised.
pdf-template-lang
- If
pdf-template-lang
specifies a language, such as withpdf-template-lang = "fr"
, the list of available PDF templates as reduced bypdf-template-name
is used to find a PDF template with a matching language. If no matching language is found, an error is raised. - If
pdf-template-lang
is empty or missing:- The PDF template with the current form language is used, if there is a match.
- If there is no match, the first available PDF template is used.
[SINCE Orbeon Forms 2016.2]
When
content = "pdf"
is specified, the PDF binary is sent with a Content-Type
set to application/pdf
.[SINCE Orbeon Forms 2016.2]
When
content = "tiff"
is specified, the TIFF binary is sent with a Content-Type
set to image/tiff
.When
content = "pdf-url"
is specified, the XML document sent has the following format:<?xml version="1.0" encoding="UTF-8"?>
<url>/xforms-server/dynamic/567f14ee46c6b21640c1a5a7374d5ad8</url>
The PDF can be retrieved by accessing that path with the proper session cookie.
A use case for this is to submit the URL to a local confirmation page. The page can then link to the URL provided, and the user can download the PDF.
NOTE: When the PDF must be sent to a remote service, send the PDF binary directly with
content = "pdf"
.[SINCE Orbeon Forms 2016.1]
When
content = "tiff-url"
is specified, the XML document sent has the following format:<?xml version="1.0" encoding="UTF-8"?>
<url>/xforms-server/dynamic/567f14ee46c6b21640c1a5a7374d5ad8</url>
The TIFF can be retrieved by accessing that path with the proper session cookie.
A use case for this is to submit the URL to a local confirmation page. The page can then link to the URL provided, and the user can download the TIFF file.
NOTE: When the TIFF must be sent to a remote service, send the TIFF binary directly with
content = "tiff"
.[SINCE Orbeon Forms 4.7]
When
content = "metadata"
is specified, the XML document sent contains metadata per control. This page shows examples based on the Orbeon Forms sample forms.NOTE: The
<value>
element is present only since Orbeon Forms 4.7.1.The metadata is linked to the data with the
for
attribute:- The value of the
for
attribute can contain multiple ids separated by a space. This associates the given piece of metadata with multiple values in the form data. This typically happens where there are repeated fields in the form, so that there is no duplication of identical metadata. - Ids in the
for
attribute match the ids you get on the data when askingsend()
to annotate the data with ids using theedge
format, that is with asend(annotate = "id", data-format-version = "edge")
.
Here is an example of
send
process which sends XML data to a service, followed by sending metadata:<property as="xs:string" name="oxf.fr.detail.process.send.my-app.my-form">
require-uploads
then validate-all
then send(
uri = "http://localhost:8080/orbeon/xforms-sandbox/service/echo-xml",
replace = "none",
method = "post",
content = "xml",
annotate = "id"
)
then send(
uri = "http://localhost:8080/orbeon/xforms-sandbox/service/echo-xml",
replace = "none",
method = "post",
content = "metadata"
)
</property>
[SINCE Orbeon Forms 2022.1]
You can send multiple items in a single
send
request. In this case, the items are sent using a multipart request (with a Content-Type: multipart/related
header). This allows the recipient of the request to access all the items without performing multiple requests.In order to generate a multipart request, you pass the
content
parameter one or more of the following tokens:xml
: form data in XML formatattachments
: all attachments associated with the form data (but not those associated with the form definition)xml-form-structure-and-data
: XML form structure and data export (not yet documented)
For example, to send form data with its attachments:
<property as="xs:string" name="oxf.fr.detail.process.send.my-app.my-form" >
send(
uri = "http://example.org/accept-form",
method = "POST",
content = "xml attachments"
)
</property>
To send form data, attachments, and the PDF file:
<property as="xs:string" name="oxf.fr.detail.process.send.my-app.my-form" >
send(
uri = "http://example.org/accept-form",
method = "POST",
content = "xml attachments pdf"
)
</property>
The recipient will need the ability to decode a multipart request. This is usually done with a utility library. For example Apache Commons FileUpload.
When sending XML data and attachments in the same request, paths to attachments in the XML data are replaced with
cid:
URIs. Each attachment part is given a Content-ID
header with the corresponding id.The
Content-Type
header sent by Orbeon Forms looks like this (the boundary parameter will change for each request):Content-Type: multipart/related; boundary=CHZ6Pogx-A1VVuDgU22pcJASumg8S0CrOZhooqlw
The content body looks like this:
--CHZ6Pogx-A1VVuDgU22pcJASumg8S0CrOZhooqlw
Content-Disposition: form-data
Content-Type: application/xml; charset=UTF-8
Content-Transfer-Encoding: binary
<?xml version="1.0" encoding="UTF-8"?>
<form xmlns:fr="http://orbeon.org/oxf/xml/form-runner" fr:data-format-version="4.0.0">
<my-main-section>
<first-name>Bob</first-name>
<pet-picture filename="cat.jpg" mediatype="image/jpeg" size="56803">cid:94b0e57e87fa8f42cb494fdc2808f58c5b31be41</pet-picture>
</my-main-section>
</form>
--CHZ6Pogx-A1VVuDgU22pcJASumg8S0CrOZhooqlw
Content-ID: <94b0e57e87fa8f42cb494fdc2808f58c5b31be41>
Content-Disposition: attachment; filename*=UTF-8''cat.jpg
Content-Type: image/jpeg
Content-Transfer-Encoding: binary
...binary image content here...
--CHZ6Pogx-A1VVuDgU22pcJASumg8S0CrOZhooqlw
Content-ID: <7a361b305064d3a95511da35a8c53edbabe3af8b>
Content-Disposition: attachment; filename*=UTF-8''My%20demo%20multipart%20form%20-%20ce85cc4b7be9975d.pdf
Content-Type: application/pdf
Content-Transfer-Encoding: binary
...binary PDF content here...
--CHZ6Pogx-A1VVuDgU22pcJASumg8S0CrOZhooqlw--
annotate
can contain the following tokens:error
,warning
,info
: XML elements are annotated with information associated with the given level or levels.id
: XML elements are annotated with a unique id. [SINCE Orbeon Forms 4.7]
If the property is missing or empty, no annotation takes place. For example:
<property
as="xs:string"
name="oxf.fr.detail.send.success.annotate.my-app.my-form"
value="warning info"/>
<form xmlns:xxf="http://orbeon.org/oxf/xml/xforms">
<my-section>
<number xxf:info="Nice, greater than 1000!">2001</number>
<text xxf:warning="Should be shorter than 10 characters">This is a bit too long!</text>
</my-section>
</form>
The
send
action operates on the server, so you won't see the data submitted in your browser's dev tools, in particular.There are a few ways to debug those requests:
- 1.Setup the service you are calling to log requests, if it can do that.
- 2.Use the built-in
echo
service, and modify yoursend
process to look like this:<property as="xs:string" name="oxf.fr.detail.process.send.my-app.my-form">send(uri = "/fr/service/custom/orbeon/echo",method="POST",content="xml",replace="all")</property>This will send the payload to your browser window. - 3.Enable XForms logging and the
submission-details
token. The payloads will be logged to orbeon.log. This will log all Orbeon Forms submissions, however. - 4.Enable logging of http wire in
log4j.xml
with:<category name="org.apache.http.wire"><priority value="debug"/></category>The information will be logged to orbeon.log. This will log all HTTP requests, however, and can be very verbose. - 5.
The easiest ways are probably options 1 and 2 above.
Last modified 7mo ago