Linking
Last updated
Last updated
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.
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.
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.
Summary page for a given form definition
/fr/$app/$form/summary
New empty form data
/fr/$app/$form/new
Edit existing form data
/fr/$app/$form/edit/$document
Read-only HTML view
/fr/$app/$form/view/$document
Read-only PDF view
/fr/$app/$form/pdf/$document
Read-only TIFF view
/fr/$app/$form/tiff/$document
2016.1
Excel export with data
/fr/$app/$form/export/$document?export-format=excel-with-named-ranges
2023.1
Excel export without data
/fr/$app/$form/export?export-format=excel-with-named-ranges
2023.1
XML export with data
/fr/$app/$form/export/$document?export-format=xml-form-structure-and-data
2023.1
XML export without data
/fr/$app/$form/export?export-format=xml-form-structure-and-data
2023.1
PDF export with data
/fr/$app/$form/export/$document?export-format=pdf
2023.1
TIFF export with data
/fr/$app/$form/export/$document?export-format=tiff
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
[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.
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.
This applies to edit, view, pdf, and tiff modes.
draft
true: loads the data for a draft
false (default): loads the data for a final document
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.
For exports that use the /export/ path:
export-initialize-form
true: initializes and runs the form before exporting
false (default): does not initialize and run the form before exporting
language
language preference, for example en or fr
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 present
if 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
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 fragment
GET for a resource such as an image, CSS file, or JavaScript file
POST XHR (Ajax) to the server to update server state and obtain new client state
POST to upload attachments to the server
POST to navigate to another Orbeon Forms page
OPTIONS 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.
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 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.
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.
