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
  • Proxy setup
  • SSL hostname verifier
  • 2-way SSL
  • Headers forwarding
  • Cookies forwarding
  • Stale checking
  • Socket timeout
  • Request chunking
  • Expired and idle connections
  • See also
  1. Configuration
  2. Properties
  3. General

HTTP client

Proxy setup

To configure an HTTP proxy to be used for all the HTTP connections established by Orbeon Forms, add the following two properties:

<property
    as="xs:string"
    name="oxf.http.proxy.host"
    value="localhost"/>

<property
    as="xs:integer"
    name="oxf.http.proxy.port"
    value="8090"/>

<property
    as="xs:boolean"
    name="oxf.http.proxy.use-ssl"
    value="false"/>

<property
    as="xs:string"
    name="oxf.http.proxy.exclude"
    value=""/>

<property
    as="xs:string"
    name="oxf.http.proxy.username"
    value=""/>

<property
    as="xs:string"
    name="oxf.http.proxy.password"
    value=""/>

<property
    as="xs:string"
    name="oxf.http.proxy.ntlm.host"
    value=""/>

<property
    as="xs:string"
    name="oxf.http.proxy.ntlm.domain"
    value=""/>

By default, the host and port properties are commented and Orbeon Forms doesn't use a proxy. Some of the use cases where you will want to define a proxy include:

  • Your network setup requires you to go through a proxy.

To connect to the proxy over HTTPS, instead of HTTP which is the default, set the oxf.http.proxy.use-ssl property to true.

[SINCE Orbeon Forms 4.6]

You can exclude host names from the proxy using the oxf.http.proxy.exclude property, which contains a space-delimited list of hostnames.

SSL hostname verifier

When using HTTPS, you can specify how the hostname of the server is checked against the hostname in its certificate. You do so with the following property:

<property
    as="xs:string"
    name="oxf.http.ssl.hostname-verifier"
    value="strict"/>

The possible values are:

Typically, you'll leave this property to its default value (strict). However, you might need to set it to allow-all to be able to connect to a server with a self-signed certificate if the cn in the certificate doesn't match the hostname you're using to connect to that server.

2-way SSL

When using HTTPS, you might want Orbeon Forms to authenticate itself by presenting a client certificate. For this, you need the client to have a key and certificate in a keystore, and point Orbeon Forms to that keystore using the propertied below.

<property
    as="xs:anyURI"
    name="oxf.http.ssl.keystore.uri"
    value="oxf:/config/my.keystore"/>

<property
    as="xs:string"
    name="oxf.http.ssl.keystore.password"
    value="changeit"/>
  • oxf.http.ssl.keystore.uri

    • Specifies the URI of the keystore file.

    • The URI can use the file: or [SINCE Orbeon Forms 2021.1] oxf: protocol.

    • Relationship to the truststore:

      • [UNTIL Orbeon Forms 2020.1] If you specify a keystore, it is also used as a truststore. This is the case even if connecting to server whose key is signed by a recognized certificate authority (CA), which means that you need to add the certificate of the CA who signed the key of the server you want to connect to the keystore.

      • If this property is blank, the default JSSE algorithm to find a truststore applies.

  • oxf.http.ssl.keystore.password

    • Specifies the password needed to access the keystore file.

You might also want to:

  • For Orbeon Forms to accept incoming connections using the same certificate, set up your servlet container, on Tomcat in the server.xml on the <Connector> used for HTTPS, to point to same keystore.

  • [SINCE Orbeon Forms 2021.1] Set the oxf.http.ssl.keystore.* system property to point to a truststore that contains the certificate of the certificate authority who signed the certificate of the server you want to connect to.

Headers forwarding

When Orbeon Forms performs XForms submissions, or retrieves documents in XPL over HTTP, it has the ability to forward incoming HTTP headers. For example, if you want to forward the Authorization header to your services:

<property
    as="xs:string"
    name="oxf.http.forward-headers"
    value="Authorization"/>

WARNING: For security reasons, you should be careful with header forwarding, as this might cause non trusted services to receive client headers.

Cookies forwarding

Similar to general headers forwarding, cookies can be forwarded. By default, the property is as follows:

<property
    as="xs:string"
    name="oxf.http.forward-cookies"
    value=""/>

If you need to forward, say, JSESSIONID and JSESSIONIDSSO to services, set this in your properties-local.xml:

<property
    as="xs:string"
    name="oxf.http.forward-cookies"
    value="JSESSIONID JSESSIONIDSSO"/>

When a username for HTTP Basic authentication is specified, cookies are not forwarded. The first cookie in the list, typically JSESSIONID, is interpreted by Orbeon Forms to be the session cookie. If the value of the session cookie doesn't match the current session, say because the provided JSESSIONID has expired or is invalid, then the value of the cookie from the incoming request isn't forwarded. Instead, in that case, the new value of the session cookie is:

  • [UP TO Orbeon Forms 2016.3] The session id.

  • [SINCE Orbeon Forms 2017.1] The concatenation of the following 3 values:

    1. The value of the oxf.http.forward-cookies.session.prefix property

    2. The session id

    3. The value of the oxf.http.forward-cookies.session.suffix property

By default, the value of the prefix and suffix properties is empty, as shown below, which works well with application servers like Tomcat that set the JSESSIONID directly to the session id.

<property 
    as="xs:string"
    name="oxf.http.forward-cookies.session.prefix"         
    value=""/>
<property
    as="xs:string"
    name="oxf.http.forward-cookies.session.suffix"
    value=""/>

On the other hand, some application servers, add a prefix and suffix to the session id. For instance, WebSphere uses the cache id as prefix, and the colon character (:) followed by the clone id as suffix. So, on WebSphere, assuming that in your situation the cache id is always 0000, and the clone id (found in WebSphere's plugin-cfg.xml) is 123, you will want to set those properties as shown below. Note how the value of the clone id follows the colon character in the value of the suffix property.

<property 
    as="xs:string"
    name="oxf.http.forward-cookies.session.prefix"         
    value="0000"/>
<property
    as="xs:string"
    name="oxf.http.forward-cookies.session.suffix"
    value=":123"/>

WARNING: For security reasons, you should be careful with cookies forwarding, as this might cause non trusted services to receive client cookies.

Stale checking

Defines whether stale connection check is to be used. Disabling stale connection check may result in slight performance improvement at the risk of getting an I/O error when executing a request over a connection that has been closed at the server side.

By default, Orbeon checks for stale HTTP connections. You can disabling stale connection checking by setting the following property to false (it is true by default):

<property
    as="xs:boolean"
    name="oxf.http.stale-checking-enabled"
    value="false"/>

Socket timeout

Sets the default socket timeout (SO_TIMEOUT) in milliseconds which is the timeout for waiting for data. A timeout value of zero is interpreted as an infinite timeout.

By default, Orbeon doesn't set a timeout with HttpClient. Setting a timeout can be potentially dangerous as it can lead to service calls that take longer to run than the timeout you specified to fail in a way that can be unpredictable, as it is possible for your services to sometimes return before the timeout and sometimes after. If, nevertheless, you need to set a timeout, you can do so by adding the following property, e.g. here setting a timeout at 1 minute:

<property
    as="xs:integer"
    name="oxf.http.so-timeout"
    value="60000"/>

NOTE: These two headers are computed values and it is only possible to override them with constant values by using the properties above. In general we don't recommend overriding these headers by using the properties above.

Request chunking

<property
    as="xs:boolean"
    name="oxf.http.chunk-requests"
    value="false"/>

Expired and idle connections

[SINCE Orbeon Forms 2019.1]

Since the HTTP client uses connection pooling, some connections can be come stale, which can cause errors at inopportune times. Enabling expired and idle connections checking can help reduce this issue.

The oxf.http.expired-connections-polling-delay property sets the expired connection checking polling delay. The default is 5,000 milliseconds (5 seconds).

<property 
    as="xs:integer" 
    name="oxf.http.expired-connections-polling-delay"      
    value="5000"/>

The oxf.http.idle-connections-delay property sets the idle connection time to live. The default is 30,000 milliseconds (30 seconds).

<property 
    as="xs:integer" 
    name="oxf.http.idle-connections-delay"
    value="30000"/> 

If oxf.http.expired-connections-polling-delay is commented out or not present, neither checks are performed.

If oxf.http.idle-connections-delay is commented out or not present, but oxf.http.expired-connections-polling-delay is present, then only the check for expired connections takes place.

Keeping expired and idle connections checking enabled can improve the reliability of connections to remote servers.

See also

PreviousGeneralNextForm Runner

Last updated 6 months ago

You would like see what goes through HTTP by using a tool that acts as an HTTP proxy, such as .

strict — (the default) See .

browser-compatible — See .

allow-all — See .

[SINCE Orbeon Forms 2021.1] Whether this property is specified or not, the server certificate is verified using the default truststore, which you override by setting the javax.net.ssl.trustStore property (more on this in the ).

For more, see .

This property is tied to the :

This property is tied to the :

Charles
StrictHostnameVerifier
BrowserCompatHostnameVerifier
AllowAllHostnameVerifier
JSSE Reference Guide
HttpClient stale checking
HttpClient SO timeout
General configuration properties
HTTP headers forwarding