Linking
Rationale
When you create a form with Form Builder, you pick an application name and form name for that form. For instance, for a marriage registration, you might choose clerk
as the application name, and marriage-registration
as the form name.
When you publish the form, assuming you have Orbeon Forms deployed on a server on http://www.city.gov/forms
, citizen will be able to fill out a new marriage registration by going to http://www.city.gov/forms/fr/clerk/marriage-registration/new
.
In a typical deployment, users will access this page from another part of your website or web application that contains a link to form served by Orbeon Forms. For instance, a city government might have on its website a page listing forms citizen can fill out, which links to the marriage registration form on http://www.city.gov/forms/fr/clerk/marriage-registration/new
.
Technology agnosticity
Linking doesn't make any assumption on the technology used by the website or application you're linking from. Your site could use Drupal, WordPress, be served by IIS, using .NET, or any other technology. For instance, the diagram below is for a situation where your website is served by Microsoft IIS, implemented in .NET, and links to forms served by Orbeon Forms.
Paths
The /fr/clerk/marriage-registration/new
in our example is what is referred to below as a path, and for a given form, multiple such paths exist. Knowing what those paths are is particularly important as this allows you to link from your website or web application to forms your created with Form Builder. All the paths are relative to the deployment context, i.e. where you've deployed Orbeon Forms, which in our example was https://www.city.gov/forms
.
Description | Path | Availability |
---|---|---|
Summary page for a given form definition |
| |
New empty form data |
| |
Edit existing form data |
| |
Read-only HTML view |
| |
Read-only PDF view |
| |
Read-only TIFF view |
| 2016.1 |
Excel export with data |
| 2023.1 |
Excel export without data |
| 2023.1 |
XML export with data |
| 2023.1 |
XML export without data |
| 2023.1 |
PDF export with data |
| 2023.1 |
TIFF export with data |
| 2023.1 |
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
By default, the latest published and available form definition version is used. You can request a specific form definition version using the form-version
parameter. For example:
/fr/acme/order/new?form-version=2
/fr/acme/order/edit/fc4c32532e8d35a2d0b84e2cf076bb070e9c1e8e?form-version=3
URL parameters
Summary page
[SINCE Orbeon Forms 2018.2]
You can pass the form-version
URL parameter:
Where:
$app
is the form definition's application name$form
is the form definition's form name$version
is the form definition version number
The page will return a "Not Found" error if the specified version is not found.
By default, the latest available version is selected.
New empty form data
When using versioning, you can pass the form-version
URL parameter:
Where:
$app
is the form definition's application name$form
is the form definition's form name$version
is the form definition version number
By default, the latest available form definition version is used.
Modes that load data
This applies to edit
, view
, pdf
, and tiff
modes.
draft
true
: loads the data for a draftfalse
(default): loads the data for a final document
PDF, TIFF, and other export views
fr-language
With automatic PDF and exports, selects the language to use when producing the PDF.
With PDF templates, choose the template with the specified language if available.
[SINCE Orbeon Forms 2018.1]
fr-use-pdf-template
Whether to use the PDF template or not. Defaults to
true
if there is one or more PDF templates.
fr-pdf-template-name
Selects a PDF template by name.
fr-pdf-template-lang
Select a PDF template by language.
Excel, XML, PDF, and TIFF exports
For exports that use the /export/
path:
export-initialize-form
true
: initializes and runs the form before exportingfalse
(default): does not initialize and run the form before exporting
language
language preference, for example
en
orfr
Excel export in excel-with-named-ranges
format
excel-with-named-ranges
formatThe following parameters control the number of repetitions created in the Excel file for repeated grids and repeated sections:
repeats-at-least
if this is present, the number of repeats is at least the value of this parameter
if the data (or form definition template) contains more repetitions, then all repetitions are included
repeats-exactly
this is ignored if
repeats-at-least
is presentif this is present, the number of repeats is exactly the value of this parameter
if the data (or form definition template) contains more repetitions, then only the repetitions up to the value specified are included
HTTP status codes
Pages and other client requests
Requesting an Orbeon Forms page is done through an HTTP or HTTPS request. This means that Orbeon Forms will respond with one of the standard HTTP status codes.
The following types of HTTP requests can be made:
GET
for an HTML page or page fragmentGET
for a resource such as an image, CSS file, or JavaScript filePOST
XHR (Ajax) to the server to update server state and obtain new client statePOST
to upload attachments to the serverPOST
to navigate to another Orbeon Forms pageOPTIONS
when the browser asks for some CORS information when using the JavaScript embedding API
Where do I see status codes?
If you use Orbeon Forms in standalone mode, or using JavaScript embedding, Orbeon Forms status codes can be visible on the client (that is, the web browser) when loading pages and can be examined in your web browser's developer tools.
Resources, XHR (Ajax), uploads, navigation, and
OPTIONS
requests status codes can be seen in the developer tools as well.Status codes are also often logged by web servers or application servers.
Finally, some error codes are explicitly logged by Orbeon Forms and you can find them in the Orbeon Forms logs.
The following table lists the most common status codes you might encounter when linking to Orbeon Forms pages.
Status code | Description |
---|---|
200 | The request was successful. |
302 | The requested resource has moved to a different URL and the server is telling the browser where to navigate. This is rarely used for pages, but can be used for baseline embedding resources. |
304 | The requested resource has not changed since the last time it was requested. This can be returned for resources. |
400 | The request was invalid. This is rarely returned by Orbeon Forms for pages. Most likely, this is due to an internal error. |
403 | The user is not authorized to access the requested page. Or, with Orbeon Forms version prior to 2022.1.5, this can also be returned if the application server session has expired. |
404 | The requested page was not found. This is typically the case when you request a page that doesn't exist, for example if you use an incorrect path or refer to a non-existing form. |
413 | The request was too large. This can happen when the user uploads a file that is too large. |
440 | From Orbeon Forms 2022.1.5 and newer. The application server session has expired. This can happen after periods of inactivity from the user's part. |
500 | An error occurred on the server. Check the Orbeon log files for details of the error. |
503 | Service unavailable. This is only returned by Orbeon Forms for an XHR request that is a retry, if the original request is still running. The operation will likely be retried. |
Service requests
Service requests are requests for Orbeon Forms server-side service APIs, typically:
called internally by Orbeon Forms
called by some external application
When called internally, the status codes will not always be returned as is to the client. Instead, individual pages and services handle them as needed. They may opt the to return the same or another appropriate status code to the ultimate caller.
You may or may not have external application service calls, depending on how you are integrating Orbeon Forms in your organization.
Service requests also use HTTP or HTTPS, and Orbeon Forms responds with one of the standard HTTP status codes.
However, more status codes can be returned for service requests than for pages. The following table lists the most common status codes you might encounter when calling Orbeon Forms services.
Status code | Description |
---|---|
200 | The request was successful. |
201 | The request was successful and a new resource was created. |
204 | The request was successful and no content is returned. |
206 | The request was successful and partial content is returned. This is used for byte ranges when reading from video attachments. |
400 | The request was invalid. This means the path, parameters, headers, and/or request body are invalid. |
401 | The user is not allowed to perform the specified operation. |
403 | The user is not authorized to access the requested page. Or, with Orbeon Forms version prior to 2022.1.5, this can also be returned if the application server session has expired. |
404 | The requested page was not found. This is typically the case when you request a page that doesn't exist, for example if you use an incorrect path or refer to a non-existing form. |
405 | The HTTP method is not allowed. |
409 | There is a conflict with the current state of the resource. This is only used when checking form definition versions. |
410 | The resource is gone. This is only used when reading from the database and we know that the resource has been deleted. |
423 | The resource is locked. This is only used by the Lease feature. |
440 | From Orbeon Forms 2022.1.5 and newer. The application server session has expired. This can happen after periods of inactivity from the user's part. |
500 | An error occurred on the server. Check the Orbeon log files for details of the error. |
See also
Last updated