Orbeon Search

Comments? Feedback?

This wiki does not yet support public comments (a limitation of Google Sites), so we encourage you to post your comments either:

On Twitter by responding to @orbeon.

On our community mailing list: subscribe sending an email to ops-users-subscribe@ow2.org (content of subject/body doesn't matter), you'll get a response with the email to use to send your message to the community mailing list.

Recent site activity

Form Runner Liferay Proxy Portlet Guide

Contents

  1. 1 Status
  2. 2 Introduction
  3. 3 Architecture
  4. 4 Installation
    1. 4.1 Deploy Orbeon Forms
    2. 4.2 Configure Form Runner
    3. 4.3 Deploy the proxy portlet
    4. 4.4 Configure the proxy portlet
  5. 5 Securing Form Runner with an IP filter
    1. 5.1 Rationale
    2. 5.2 Example configuration
      1. 5.2.1 Put urlrewrite-3.2.0.jar in the Orbeon Forms WEB-INF/lib folder
      2. 5.2.2 Configure the filter in Orbeon Forms WEB-INF/web.xml
      3. 5.2.3 Put the urlrewrite.xml configuration in the Orbeon WEB-INF folder
      4. 5.2.4 Test the setup
  6. 6 Scenarios
    1. 6.1 Scenario: create and save form data
    2. 6.2 Scenario: list, edit, create and save form data
    3. 6.3 Scenario: list and review form data
  7. 7 Limitations
    1. 7.1 Orbeon Forms URL rewriting configuration is global
    2. 7.2 Form Runner configuration properties are global
  8. 8 Related resources

Status

This feature is available since January 2011.

Introduction

Form Runner can be deployed directly within portals like Liferay. However in some cases, it is desirable to deploy Form Runner separately. The Form Runner proxy portlet provides allows this type of deployment, with the following benefits:

  • portlet-specific code and deployment is simpler
  • security is easier to manage as Form Runner can be placed behind a firewall
  • Form Runner can be maintained and upgraded separately from the portal
  • portal security can be used to protect access to the portlet
This guide describes how to install, administer and use the Form Runner proxy portlet.

NOTE: This feature has only been tested with Liferay 6. It is likely to also work with other JSR-286 compliant portals but note that this hasn't been tried by Orbeon as of 2011-01.

Architecture

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.

Installation

Deploy Orbeon Forms

Install and deploy Orbeon Forms as usual. You can deploy it:
  • within the same container as Liferay
  • in a separate servlet container
Note the URL at which Form runner is deployed. The default is:

http://localhost:8080/orbeon/

NOTE: An instance of Form Runner configured as server for the proxy portlet cannot, as of 2011-01-07, be used as a regular instance of Form Runner due to the URL rewriting configuration. See the Limitations section below for more details.

Configure Form Runner

For builds since 2012-05-14, no particular configuration is needed.

NOTE: For builds prior to 2012-05-14, you need the following configuration in your properties-local.xml:

<properties xmlns:xs="http://www.w3.org/2001/XMLSchema"
            xmlns:oxf="http://www.orbeon.com/oxf/processors">

    <property as="xs:boolean" name="oxf.url-rewriting.wsrp.encode-resources" value="true"/>

    <!-- ... Other properties will go here ... -->

</properties>



NOTE: Prior to 2011-10-18 builds, the following property was also needed:

    <property as="xs:string"  name="oxf.url-rewriting.strategy.servlet"      value="wsrp"/>

Deploy the proxy portlet

1. Deploy orbeon-PE-proxy-portlet.war into Liferay
2. Add an instance of The Orbeon Forms → Form Runner portlet to a page:


3. The portlet will load with its default configuration. If Orbeon Forms is deployed at the default address, the Bookshelf should show:


Configure the proxy portlet

1. Open the portlet preferences page:


2. Configure the preferences


The preferences are as follows:
  • 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: bookshelf
  • Form Runner action
    • Initial Form Runner action (page) to show
    • Possible values
      • new: show the "new" page for the given app/form
      • summary: show the "summary" page for the given app/form
  • Read-Only access
    • Whether the user is able to edit forms
    • Possible values: true or false
    • NOTE: To ensure read-only access, it is also important to configure a oxf.fr.detail.buttons.view.*.* property without the workflow-edit button.
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 the portlet.xml file:

<portlet-app>

    <!-- Orbeon Forms proxy portlet (to access a remote Form Runner instance) -->
    <portlet>
        <portlet-name>orbeon-forms-proxy-portlet</portlet-name>
        <portlet-class>org.orbeon.oxf.portlet.OrbeonProxyPortlet</portlet-class>
        <supports>
            <mime-type>text/html</mime-type>
            <portlet-mode>view</portlet-mode>
            <portlet-mode>edit</portlet-mode>
        </supports>

        <!-- Initialization parameters -->
        <init-param>
            <name>form-runner-url</name>
            <value>http://localhost:8080/orbeon/</value>
        </init-param>
        <init-param>
            <name>app-name</name>
            <value>orbeon</value>
        </init-param>
        <init-param>
            <name>form-name</name>
            <value>bookshelf</value>
        </init-param>
        <init-param>
            <name>action</name>
            <value>new</value>
        </init-param>
        <init-param>
            <name>read-only</name>
            <value>false</value>
        </init-param>

        <portlet-info>
            <title>Form Runner</title>
        </portlet-info>
    </portlet>

</portlet-app>

Securing Form Runner with an IP filter

Rationale

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.

Example configuration

There are many IP filter options out there. One option is to use the very flexible UrlRewriteFilter. You can configure it this way:

Put urlrewrite-3.2.0.jar in the Orbeon Forms WEB-INF/lib folder

Configure the filter in Orbeon Forms WEB-INF/web.xml

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

Put the urlrewrite.xml configuration in the Orbeon WEB-INF folder

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 type="temporary-redirect" last="true">/unauthorized</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 <filter> 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.

Test the setup

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.

Scenarios

Scenario: create and save form data

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"/>

Scenario: list, edit, create and save form data

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.

Scenario: list and review form data

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"/>

Limitations

Orbeon Forms URL rewriting configuration is global

NOTE: This is no longer a limitation starting 2011-10-18 builds.

The Form Runner server's URL rewriting configuration is global. This configuration makes Orbeon Forms in effect inaccessible directly from a web browser.

This means that:

  • Form Builder must be deployed as its own WAR. So you deploy:
    • one Orbeon Forms instance specifically as Form Runner server
    • one Orbeon Forms instance as Form Builder server (or as a general-purpose Orbeon Forms installation)
  • Your Form Runner database (eXist, Oracle, etc., or your own persistence layer implementation) must be shared between the two installations.

Form Runner configuration properties are global

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" scenario
  • orbeon/contact form in "list and review form data" scenario
This is because both scenarios need a different configuration for the summary page buttons.

Related resources