Operations grimoire/Orbeon

Orbeon Forms allows to build and manage dynamic web forms, following the XForms XML specification. We use Orbeon Forms CE, released under open source LGPL license.

For Nasqueron, Orbeon Forms is deployed on the Docker PaaS and can be accessed at https://forms.nasqueron.org/

It allows forms administrators to create and read forms, and users to read fill forms. Those forms can be for a website or for a survey.

As of May 2023, the deployment is currently in testing mode on the "Dwellers" server. If the service has been moved to a different server, the references to "dwellers" in the procedures below should be replaced with the correct server name, for example "docker-002".

In the "Concepts" section, provide brief descriptions of Form Runner and Form Builder, explaining their respective functionalities.

Concepts

Orbeon Forms is divided in several applications:

• Form Runner allows to fill a form and read form replies. For that, it reads a form in the XForms and connects to a database source.
• Form Builder is an editor to visually design forms.

Once published, forms can be used different ways:

• Through Form Runner. You direct the user to https://forms.nasqueron.org/orbeon/fr/<your app name>/<your form name>/new. It fills the form there, and afterwards is redirected to the configured URL.
• As a storage back-end. You can also interact through Persistence API with the storage back-end.

Publish a form

The Form Builder is an editor to create a new form. You can also publish forms so they're accessible to the runner.

An access to the form builder is required. Browse:

• https://forms.nasqueron.org/orbeon/fr/orbeon/builder/new to create a new form
• https://forms.nasqueron.org/orbeon/fr/orbeon/builder/summary to view and edit current forms

Each form is identified by:

• application name -> use an unique name for your application, with nasqueron- prefix, for example join.nasqueron.org uses nasqueron-join
• form name -> use a short descriptive name for your form goal

Forms should also be published to the forms Git repository, so they're under version control, and can also be recreated if something goes wrong with the service database.

The repository is organized in subfolders, one per application. Each subfolder matches application name, without the nasqueron- prefix, for example join.nasqueron.org uses join/.

Authentication

Users are configured at Tomcat level. To add an user:

• Provide Vault credential
  1. Create Vault credential under ops/secrets/nasqueron/orbeon/users/
  2. Add that credential in pillar/credentials/vault.sls
  3. Deploy new Vault policy sudo salt-call --local state.sls_id salt-node-dwellers roles/vault/policies
• Declare the user in Tomcat configuration
  1. Edit pillar/paas/docker/dwellers/orbeon.sls
  2. Deploy it with salt dwellers state.sls_id /srv/orbeon/nasqueron_forms/conf/tomcat-users.xml roles/paas-docker/containers/orbeon, where nasqueron_forms is the name of our forms.nasqueron.orf instance
  3. Restart container: docker restart nasqueron_forms

Database

Nasqueron Forms instance uses the database forms on db-A cluster, through the user orbeon.

DDL can be found on repository in form-runner/jvm/src/main/resources/apps/fr/persistence/relational/ddl. This documentation page indicates what to use.

Permissions also need to be set:

   $ sudo -u postgres psql forms
   GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO orbeon;
   GRANT USAGE ON SEQUENCE public.orbeon_form_data_id_seq TO orbeon;
   GRANT USAGE ON SEQUENCE public.orbeon_seq_val_seq TO orbeon;

Shorter URLs

We proxy /<application name> to avoid the /orbeon/fr/ in the URL and offer a more semantic URL.

To add an application there, the pillar must be updated, adding your new application under the container arguments `apps`, then the nginx vhost updated. For Dwellers, it's rOPS: pillar/paas/docker/dwellers/orbeon.sls then salt dwellers state.sls_id /etc/nginx/vhosts/orbeon/nasqueron_forms.conf roles/paas-docker/nginx/config.

Troubleshoot

Logs

• Tomcat logs: /usr/local/tomcat/logs
• Application log: /usr/local/logs/orbeon.log
• Log4j configuration: /usr/local/tomcat/webapps/orbeon/WEB-INF/resources/config/log4j2.xml

Authentication

Authentication is known to be rather buggy:

• if you login at form runner level (e.g. /fr/admin), you can be unlogged at builder level
• if you login from login form, you'll get a 403
• if you login from builder, it can't tell you something is wrong

Configuration known issues:

• If you got a 408 you accessed yourself /fr/login, but web.xml needs to be configured with a <login-config> block using the FORM auth method (that's the default Orbeon web.xml)
• To enable login/logout menu, you need to add <property as="xs:boolean" name="oxf.fr.authentication.user-menu.enable" value="true" /> to properties-local.xml

Forms

• Forms must explicitly use the save action when you sent or submit them. Symptom if not is a warning do you want to leave this site, and the fact the form is correctly sent by mail but not saved in the database.

Database

If the database doesn't work, check the container logs.

For example, during setup, we've got a org.postgresql.util.PSQLException with:

       Caused by: org.postgresql.util.PSQLException: FATAL: no pg_hba.conf entry for host "172.27.27.4", user "orbeon", database "forms", no encryption

For PostgreSQL, it requires:

• plain authentication in pg_hba.conf
• XML support

Features

Known issues:

• PDF doesn't have style when generated through nginx. As a work around, you can create SSH tunnel with ssh -L 16080:dwellers:16080 and browse http://localhost:16080 if you need a PDF.
• No flat view for multi-files attachment: https://github.com/orbeon/orbeon-forms/issues/1069

Timeout when pressing send

When pressing send it follows the workflow configured for the form. For example:

               require-valid
               then save
               then email
               then navigate("https://agora.nasqueron.org/Agora:Request/Successful")
               recover navigate("https://agora.nasqueron.org/Agora:Request/Failure")' />

If it wait during long dozen of seconds, then go to failure page, it could be a difficulty to reach SMTP server, for example because the orbeon_smtp exim container is down.

Useful links

• Official documentation
• Google Groups