Liferay proxy portlet
This is an Orbeon Forms PE feature.
These issues apply to Orbeon Forms 2017.1 to 2019.1.
- The Form Runner language selector doesn't work
- Workaround: Select the "Send Liferay language" option. When this option is sent, the Form Runner language selector doesn't show. Orbeon Forms uses instead the current Liferay user's language preference.
- The Liferay navigation menu doesn't navigate to Form Runner
- Workarounds:
- 1.Don't use the Liferay navigation menu to reach the Form Runner proxy portlet.
- 2.
NOTE: We plan to lift these limitations in a future release of Orbeon Forms.
Form Runner can be deployed directly into Liferay. However in some cases, it is desirable to deploy Form Runner separately. The Form Runner proxy portlet provides this type of deployment, with the following benefits:
- You configure a specific form to show in the portlet via portlet preferences.
- Form Runner can be maintained and upgraded separately from the portal.
- The Form Runner application itself does not have to be exposed to the outside world.
If you only need Form Runner and are happy with deploying only one form per portlet, and if you want a simple configuration UI to set this up, then the proxy portlet is for you. Otherwise, you will have to look into the full portlet.
This guide describes how to install, administer and use the Form Runner proxy portlet.

Controls form through the Liferay proxy portlet
The solution is comprised of:
- The proxy portlet: a Liferay portlet (JSR-286 portlet) available as a portlet application to deploy into Liferay
- The Form Runner server: an Orbeon Forms instance deployed as a web application into a servlet container
The proxy portlet communicates with the Form Runner server using HTTP.
The Form Runner server can be entirely hidden behind a firewall as it doesn't need direct access from the user's web browser.
- within the same container as Liferay
- in a separate servlet container
Note the URL at which Form runner is deployed. The default is assumed to be:
http://localhost:8080/orbeon/
For Orbeon Forms 4.0 and newer, no particular configuration is needed.
- 1.Deploy
proxy-portlet.war
(formerlyorbeon-PE-proxy-portlet.war
) into Liferay - 2.Add an instance of Orbeon Forms → Form Runner to a page:
- 3.The portlet will load with its default configuration. If Orbeon Forms is deployed at the default address, a form shows.If Orbeon Forms is not deployed at the default address, the proxy portlet will initially show an error. You can ignore this error and proceed to the proxy portlet configuration below.
- 1.Open the portlet preferences page
- 2.Configure the preferencesThe preferences are as follows:
- Form Runner Page
- Initial Form Runner action (page) to show
- Possible values
- New Page: show the "new" page for the given app/form
- Summary Page: show the "summary" page for the given app/form
- Home Page: Form Runner Home page showing the form list [SINCE Orbeon Forms 4.4]
- Form Runner URL
- URL, including servlet context, where the Form Runner instance is deployed
- Example:
http://localhost:8080/orbeon/
- Form Runner app name
- Initial Form Runner application name to show
- Example:
orbeon
- Form Runner form name
- Initial Form Runner form name to show
- Example:
controls
- Readonly access
- Whether the user is able to edit forms
- NOTE: To ensure read-only access, it is also important to configure a
oxf.fr.detail.buttons.view.*.*
property without theworkflow-edit
button.
- Send Liferay language [SINCE Orbeon Forms 4.4]
- Whether Form Runner should use the Liferay user's language
- This also hides the Form Runner language selector
- Send Liferay user [SINCE Orbeon Forms 4.4]
- Whether the Liferay user information is sent to Form Runner
- This sends the following headers to Form Runner
Orbeon-Liferay-User-Id
Orbeon-Liferay-User-Screen-Name
Orbeon-Liferay-User-Full-Name
Orbeon-Liferay-User-First-Name
[SINCE Orbeon Forms 2018.1]Orbeon-Liferay-User-Middle-Name
[SINCE Orbeon Forms 2018.1]Orbeon-Liferay-User-Last-Name
[SINCE Orbeon Forms 2018.1]Orbeon-Liferay-User-Email
Orbeon-Liferay-User-Group-Id
Orbeon-Liferay-User-Group-Name
Orbeon-Liferay-User-Roles
When read-only access is enabled, if the Form Runner summary page is enabled and accessed, selecting a form takes the user to the Review page instead of the Edit page for a given form.Press the "Save" or "Cancel" button to save/cancel and return to the portlet.The default values of the preferences are provided via initialization parameters in theportlet.xml
file. The latest version of this file is [available here][8].
[SINCE Orbeon Forms 4.1]
Specific client URL parameters and client request headers can be forwarded to Form Runner with the following portlet init parameters:
<init-param>
<name>forward-parameters</name>
<value>param1 param2</value>
</init-param>
<init-param>
<name>forward-headers</name>
<value>My-Header-1 My-Header-2</value>
</init-param>
The value of the parameters is a space-separated list of parameter names or header names.
This makes these headers and URL parameters available to Form Runner, for example with the
xxf:get-request-header()
and xxf:get-request-parameter()
functions.[SINCE Orbeon Forms 4.2]
Headers forwarded now follow the capitalization specified in the
forward-headers
property. For example, if the incoming header has name mY-hEaDeR-1,
and the property specifies My-Header-1
, the header will be forwarded under the name My-Header-1
.[SINCE Orbeon Forms 4.10]
You can forward portlet request properties as headers to Form Runner.
<init-param>
<name>forward-properties</name>
<value>My-Property-1 My-Property-2</value>
</init-param>
This is useful for example to set custom security headers in the proxy portlet:
- use the
forward-properties
parameter to specify that the proxy portlet must send the names and values of these properties as headers to Form Runner
[SINCE Orbeon Forms 2018.1]
Portal URL parameters specified with the
keep-parameters
portlet init parameter are read from the portal URL and re-appended to action, render and resource URLs produced by the proxy portlet:<init-param>
<name>keep-parameters</name>
<value>param1 param2</value>
</init-param>
[SINCE Orbeon Forms 4.4]
When "Send Liferay user" is enabled, you can configure Form Runner to use the HTTP headers sent by the proxy portlet to handle forms access control. For this, you must use the "Header-driven method". Set the following property:
<property
as="xs:string"
name="oxf.fr.authentication.method"
value="header"/>
In addition to this, depending on the version of Orbeon Forms you're using, set the properties listed in the following sections.
<property
as="xs:string"
name="oxf.fr.authentication.header.credentials"
value="Orbeon-Liferay-User-Credentials"/>
In Liferay, you can configure whether users authenticate using their email, user id, or screen name. The Orbeon Forms proxy portlet takes the username to be the user's email, user id, or screen name, depending on that configuration.
<property
as="xs:string"
name="oxf.fr.authentication.header.username"
value="Orbeon-Liferay-User-Screen-Name"/>
<property
as="xs:string"
name="oxf.fr.authentication.header.group"
value="Orbeon-Liferay-User-Group-Name"/>
<property
as="xs:string"
name="oxf.fr.authentication.header.roles"
value="Orbeon-Liferay-User-Roles"/>
For the
oxf.fr.authentication.header.username
header, you can choose any of the Liferay headers associated with the user, but typically this will be:Orbeon-Liferay-User-Id
Orbeon-Liferay-User-Screen-Name
- or possibly
Orbeon-Liferay-User-Email
<property
as="xs:string"
name="oxf.http.forward-headers"
value="Orbeon-Liferay-User-Screen-Name Orbeon-Liferay-User-Group-Name Orbeon-Liferay-User-Roles"/>
<property
as="xs:string"
name="oxf.xforms.forward-submission-headers"
value="Orbeon-Liferay-User-Screen-Name Orbeon-Liferay-User-Group-Name Orbeon-Liferay-User-Roles"/>
[SINCE Orbeon Forms 4.7]
You can enable form selection via URL parameters by setting the
enable-url-parameters
portlet parameter in portlet.xml
to true
:<init-param>
<name>enable-url-parameters</name>
<value>true</value>
</init-param>
When this is enabled, the following portal URL parameters are propagated to Orbeon Forms to allow form selection:
orbeon-app
: the Form Runner app nameorbeon-form
: the Form Runner form nameorbeon-document
: the Form Runner document (foredit
andview
pages)orbeon-page
: the Form Runner page (new
,edit
, orview
)
[SINCE Orbeon Forms 2019.2]
Short namespaces are no longer supported and therefore entirely disabled.
[SINCE Orbeon Forms 2017.2.3 and 2018.1]
Short namespaces are disabled by default in
portlet.xml
:<init-param>
<name>use-short-namespaces</name>
<value>false</value>
</init-param>
[SINCE Orbeon Forms 2016.2]
You can disable the use of short namespaces by setting the
use-short-namespaces
portlet parameter in portlet.xml
to false
:<init-param>
<name>use-short-namespaces</name>
<value>false</value>
</init-param>
By default (and this was the case in previous Orbeon Forms versions as well), short namespaces are enabled to reduce the size of the resulting HTML page and browser DOM.
However, in some cases of load balancing, this can be an issue. In such cases, you can disable short namespaces with this option. See issue #2764 for details.
[SINCE Orbeon Forms 4.7]
NOTE: Be aware that
web.xml
uses <param-name>
and <param-value>
, but portlet.xml
uses <name>
and <value>
.The proxy portlet can be secured with Liferay. On the other hand, the Form Runner server runs as a servlet and whether it runs within the same container as Liferay or on a different machine, direct accesses from end clients must be prevented.
One first step to achieve this is to place the Form Runner server behind a firewall, where it can be accessed from the portal but not from end clients.
Additional security steps can be desirable depending on your environment. One such step is to use an IP filter in order to:
- Allow accesses from the proxy portlet and from Form Runner itself.
- Disallow accesses from any other sources.
The following describes such a configuration.
There are many IP filter options out there. One option is to use the very flexible [UrlRewriteFilter][9]. You can configure it this way:
<filter>
<filter-name>UrlRewriteFilter</filter-name>
<filter-class>org.tuckey.web.filters.urlrewrite.UrlRewriteFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>UrlRewriteFilter</filter-name>
<url-pattern>/*</url-pattern>
<dispatcher>REQUEST</dispatcher>
<dispatcher>FORWARD</dispatcher>
</filter-mapping>
This is a generic configuration which enables the filter for any incoming path.
Here is an example configuration:
<?xml version="1.0" encoding="utf-8"?>
<urlrewrite>
<rule>
<condition type="remote-addr" operator="notequal">0:0:0:0:0:0:0:1%0</condition>
<condition type="remote-addr" operator="notequal">127.0.0.1</condition>
<set type="status">403</set>
<to>null</to>
</rule>
</urlrewrite>
This configuration encodes the following rule: "for any incoming path, if the remote IP is different from
0:0:0:0:0:0:0:1%0
(IPv6) and different from 127.0.0.1
(IPv4), then set the status to 403 and redirect to the path /unauthorized".You should modify the IP address(es) to fit your network configuration, as the originating address might not be
127.0.0.1
, as well as modify the redirection path.Enabling UrlRewriteFilter's logging is helpful to see what's happening during development. To do this, modify the `` config to:
<filter>
<filter-name>UrlRewriteFilter</filter-name>
<filter-class>org.tuckey.web.filters.urlrewrite.UrlRewriteFilter</filter-class>
<init-param>
<param-name>confReloadCheckInterval</param-name>
<param-value>0</param-value>
</init-param>
<init-param>
<param-name>logLevel</param-name>
<param-value>DEBUG</param-value>
</init-param>
</filter>
NOTE: You could also setup filtering on the type "remote-host" and check on the value "localhost" instead of filtering on IP addresses, however often reverse DNS lookups are not enabled in servlet containers for performance reasons, which means you need to filter by IP address instead.
Make sure accesses from the proxy portlet work as before, and test that accesses from machines other than the portal and/or directly from the client browser get rejected.
In this scenario, the user of the portlet is only allowed to capture and save form data.
Portlet preferences:
- Form Runner action:
new
- Read-Only access:
false
Configuration properties in
properties-local.xml
(here for the orbeon/contact form):<property
as="xs:string"
name="oxf.fr.detail.buttons.orbeon.contact"
value="clear submit"/>
<property
as="xs:string"
name="oxf.fr.detail.submit.buttons.orbeon.contact"
value="clear"/>
In this scenario, the user of the portlet can, in addition to capture and save, also list and edit submitted form data.
Portlet preferences:
- Form Runner action:
summary
- Read-Only access:
false
Configuration properties in
properties-local.xml
(here for the orbeon/contact form):<property
as="xs:string"
name="oxf.fr.summary.buttons.orbeon.contact"
value="new edit delete"/>
<property
as="xs:string"
name="oxf.fr.detail.buttons.orbeon.contact"
value="close clear submit"/>
<property
as="xs:string"
name="oxf.fr.detail.submit.buttons.orbeon.contact"
value="clear"/>
NOTE: Remove the
delete
token if the Delete button is not needed.In this scenario, the user of the portlet is only allowed to capture and save form data.
Portlet preferences:
- Form Runner action:
summary
- Read-Only access:
true
Configuration properties in
properties-local.xml
(here for the orbeon/contact form):<property
as="xs:string"
name="oxf.fr.summary.buttons.orbeon.contact"
value="print pdf"/>
<property
as="xs:string"
name="oxf.fr.detail.buttons.view.orbeon.contact"
value="close"/>
The Form Runner configuration properties are global, i.e. a given Form Runner server cannot have configuration properties per portlet (although it can have them per app/form name). This means for example that for a given app/form/action, it is not possible to have a different set of buttons.
Concretely, this means that you cannot have the following portlet instances at the same time:
orbeon/contact
form in "list, edit, create and save form data" scenarioorbeon/contact
form in "list and review form data" scenario
This is because both scenarios need a different configuration for the summary page buttons.
Last modified 3yr ago