Orbeon Forms
  • Getting started
  • Installation
    • Logging
    • Configuration banner
    • Docker
    • Azure
    • Tomcat
    • WildFly
    • WebSphere
    • WebLogic
    • GlassFish
    • Caches
    • Replication
    • Upgrading
  • Configuration
    • Properties
      • General
        • HTTP client
      • Form Runner
        • Detail page
          • Attachments
          • Email properties
          • PDF
          • Table of contents
        • Persistence
        • Summary page
      • Form Builder
      • XForms
    • Advanced
      • Workflows
      • Session management
      • State handling
      • Client-side error handling
      • Clustering and High Availability
      • Configuring a Form Runner eXist database
      • Creating a production WAR
      • Environments
      • JavaScript and CSS assets
      • Limiter filter
      • Run modes
      • Security
        • Content-Security-Policy header
      • SAP Hybris Module
      • XForms logging
    • Troubleshooting
      • Troubleshooting with the orbeon.log
      • Memory and threads
      • Relational database logging
      • Misc
  • Form Builder
    • Form settings
      • Time window
    • Form editor
      • Form area
      • Toolbox
      • Buttons bar
      • Control settings
      • Dependent fields and sections
      • Validation
      • Choices editor
      • Publishing
      • Cut, copy and paste
      • Section and grid settings
      • Section settings
      • Grid settings
      • Quick control search
      • Repeat settings
      • Repeated grids
      • Undo and redo
      • Keyboard shortcuts
    • Formulas
      • Examples of formulas
      • Formulas inspector
      • Formulas console
    • Summary page
    • Form localization
    • Advanced
      • Edit source
      • Services and actions
        • HTTP services
        • Database services
        • Simple Actions
        • Action Syntax
        • Action Syntax examples
        • Synchronizing repeated content
      • Testing a form in web mode
      • Testing PDF production
      • Testing offline functionality
      • Email Settings dialog
      • Field-level encryption
      • Messages
      • Section templates
      • Template syntax
      • XML Schemas support
      • Extensibility
        • Extension API
        • Integration
        • Toolbox component metadata
  • Form Runner
    • Overview
      • Terminology
    • Pages
      • Landing page
      • Published Forms page
      • Forms Admin page
      • Summary page
    • Components
      • Alert dialog
      • Attachment
      • Autocomplete
      • Captcha
      • Character counter
      • Checkbox input
      • Currency
      • Date
      • Dropdown date
      • Static and dynamic dropdown
      • Error summary
      • Grid
      • Handwritten signature
      • Hidden field
      • Image
      • Image annotation
      • Image attachment
      • Number
      • Open selection
      • Repeater
      • Formatted Text / Rich Text Editor
      • Section
      • Single-selection tree
      • Source code editor
      • Time
      • US phone
      • US state
      • Video
      • Video attachment
      • Wizard
      • XForms inspector
      • Yes/No answer
    • Features
      • Automatic calculations dependencies
      • Datasets
      • Excel and XML import
      • Excel and XML export
      • Summary page Excel Export
      • Form definitions and form data Zip Export
      • Purging historical data
      • Lease
      • Localization
      • Supported languages
      • Mobile support
      • Multitenancy
      • Form Runner navigation bar
      • PDF production
        • Automatic PDF
        • Automatic PDF header and footer configuration
        • PDF templates
      • Responsive design
      • Revision history
      • S3 storage
      • Simple data migration
      • TIFF production
      • Versioning
      • Wizard view
      • Workflow stage
    • Persistence
      • Using a relational database
      • Relational database schema
      • Purging old data using SQL
      • Auditing
      • Autosave
      • Database support
      • Flat view
    • Linking and embedding
      • Linking
      • Java Embedding API
      • JavaScript Embedding API
      • Liferay full portlet
      • Liferay proxy portlet
      • Securing Form Runner access
      • Form Runner offline embedding API
      • Angular component
      • React component
    • Access control and permissions
      • Users
      • Login & Logout
      • Deployed forms
      • Form fields
      • Editing forms
      • Owner and group member
      • Organizations
      • Scenarios
      • Token-based permissions
    • Styling
      • CSS
      • Grids CSS
      • Automatic PDF styling and CSS
    • APIs
      • Authentication of server-side service APIs
      • Persistence API
        • CRUD API
        • Search API
        • List form data attachments API
        • Form Metadata API
        • Lease API
        • Reindexing API
        • Caching
        • Versioning
        • Revision History API
        • Zip Export API
        • Custom persistence providers
      • Other APIs
        • Connection context API
        • Duplicate form data API
        • File scan API
        • Form Runner JavaScript API
        • Generate XML Schema API
        • PDF API
        • Publish form definition API
        • Run form in the background API
      • Data formats
        • Form data
        • Date and time
        • Form definition
    • Architecture and integration
      • Architecture
      • Access form data
      • Integration
    • Advanced
      • Buttons and processes
        • Simple process syntax
        • Core actions
        • Form Runner actions
          • Save action
          • Send action
          • Email action
        • XForms actions
        • Predefined buttons, processes and dialogs
        • Summary page buttons and processes
      • Custom dialogs/model logic
      • Services
      • Singleton form
      • Monitoring HTTP requests
  • XForms
    • Core
      • Attribute Value Templates (AVTs)
      • Binds
      • Validation
      • Variables
      • Keyboard focus
      • XForms JavaScript API
      • Error handling
        • Detailed behavior
      • Model-Bind variables
      • XForms 2.0 support
    • Events
      • Standard support
      • UI refresh events
      • Keyboard events
      • Extension events
      • Extension context information
      • Other event extensions
    • Actions
      • Repeat, insert and delete
      • Scripting actions
      • Extensions
    • Controls
      • Label, hint, help
      • Input
      • Output
      • Text area
      • Button
      • Upload
      • Dialog
    • Submission
      • Standard support
      • JSON support
      • Asynchronous submissions
      • Caching extension
      • Other submission extensions
    • XPath
      • Type annotations
      • Expression analysis
      • Tips
      • Compatibility
      • Standard functions
      • Maps and arrays Functions
      • Extension functions
        • Core functions
        • Utility functions
        • Model functions
        • Controls functions
        • XML functions
        • JSON functions
        • HTTP functions
        • Form Runner functions
        • Other functions
        • Deprecated functions
    • XBL components
      • FAQ
      • Guide
        • XBL Tutorial
        • Bindings
        • XForms models
        • Including content
        • Event handling
        • Conventions
        • Map XBL example
        • Learning from existing components
      • Advanced topics
        • XBL Modes
        • JavaScript companion classes
        • XBL library
        • Extensions
        • Attachment controls
    • XForms tutorial
      • Introduction
      • Installation
      • The Hello application
      • The Bookcast application
        • The basic app
        • Database access
        • Polishing the app
        • Adding a feed
    • Using XForms from Java apps
  • XML Platform
    • Page Flow Controller
      • Basics
      • XML submission
      • Navigating between pages
      • Paths and matchers
      • Other configuration elements
      • Typical combinations of page model and page view
      • Examples
      • Authorizing pages and services
    • Processors
      • URL generator
      • Request generator
      • PDF to image converter
    • Resources
      • Resource managers
      • Setting up an external resources directory
    • Other
      • Binary and text documents
  • FAQ
    • Licensing
    • PE and Dev Support
    • Form Builder and Form Runner
    • Resources and support
    • Other technical questions
  • Contributors
    • Automated tests
    • Building Orbeon Forms
    • Localizing Orbeon Forms
    • Validation functions
    • Contributor License Agreement
  • Release notes
    • Orbeon Forms 2022.1.9
    • Orbeon Forms 2024.1.1
    • Orbeon Forms 2023.1.7
    • Orbeon Forms 2024.1
    • Orbeon Forms 2023.1.6
    • Orbeon Forms 2023.1.5
    • Orbeon Forms 2021.1.11
    • Orbeon Forms 2022.1.8
    • Orbeon Forms 2023.1.4
    • Orbeon Forms 2023.1.3
    • Orbeon Forms 2023.1.2
    • Orbeon Forms 2022.1.7
    • Orbeon Forms 2023.1.1
    • Orbeon Forms 2023.1
    • Orbeon Forms 2022.1.6
    • Orbeon Forms 2021.1.10
    • Orbeon Forms 2022.1.5
    • Orbeon Forms 2021.1.9
    • Orbeon Forms 2022.1.4
    • Orbeon Forms 2022.1.3
    • Orbeon Forms 2021.1.8
    • Orbeon Forms 2022.1.2
    • Orbeon Forms 2022.1.1
    • Orbeon Forms 2022.1
    • Orbeon Forms 2021.1.7
    • Orbeon Forms 2021.1.6
    • Orbeon Forms 2021.1.5
    • Orbeon Forms 2021.1.4
    • Orbeon Forms 2021.1.3
    • Orbeon Forms 2021.1.2
    • Orbeon Forms 2021.1.1
    • Orbeon Forms 2021.1
    • Orbeon Forms 2020.1.6
    • Orbeon Forms 2019.2.4
    • Orbeon Forms 2019.1.2
    • Orbeon Forms 2018.2.5
    • Orbeon Forms 2018.1.4
    • Orbeon Forms 2020.1.5
    • Orbeon Forms 2020.1.4
    • Orbeon Forms 2020.1.3
    • Orbeon Forms 2020.1.2
    • Orbeon Forms 2019.2.3
    • Orbeon Forms 2020.1.1
    • Orbeon Forms 2020.1
    • Orbeon Forms 2019.2.2
    • Orbeon Forms 2019.2.1
    • Orbeon Forms 2019.1.1
    • Orbeon Forms 2019.2
    • Orbeon Forms 2019.1
    • Orbeon Forms 2018.2.4
  • Release history
  • Use cases
  • Product roadmap
  • Index of features
Powered by GitBook
On this page
  • Rationale
  • Technology agnosticity
  • Paths
  • URL parameters
  • Summary page
  • New empty form data
  • Modes that load data
  • PDF, TIFF, and other export views
  • Excel, XML, PDF, and TIFF exports
  • Excel export in excel-with-named-ranges format
  • HTTP status codes
  • Pages and other client requests
  • Service requests
  • See also
  1. Form Runner
  2. Linking and embedding

Linking

PreviousLinking and embeddingNextJava Embedding API

Last updated 10 months ago

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

/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

URL parameters

Summary page

[SINCE Orbeon Forms 2018.2]

You can pass the form-version URL parameter:

/fr/$app/$form/summary?form-version=$version

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:

/fr/$app/$form/new?form-version=$version

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 draft

    • false (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 exporting

    • false (default): does not initialize and run the form before exporting

  • language

    • language preference, for example en or fr

Excel export in excel-with-named-ranges format

The 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

HTTP status codes

Pages and other client requests

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

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

  • 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.

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

Requesting an Orbeon Forms page is done through an HTTP or HTTPS request. This means that Orbeon Forms will respond with one of the .

OPTIONS when the browser asks for some when using the JavaScript embedding API

Service requests are requests for Orbeon Forms server-side , typically:

Service requests also use HTTP or HTTPS, and Orbeon Forms responds with one of the .

standard HTTP status codes
CORS information
service APIs
standard HTTP status codes
Multitenancy
Sending PDF and TIFF content: Controlling the format
PDF templates