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.
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
- 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
Users are configured at Tomcat level. To add an user:
- Provide Vault credential
- Create Vault credential under ops/secrets/nasqueron/orbeon/users/
- Add that credential in pillar/credentials/vault.sls
- Deploy new Vault policy
sudo salt-call --local state.sls_id salt-node-dwellers roles/vault/policies
- Declare the user in Tomcat configuration
- Edit pillar/paas/docker/dwellers/orbeon.sls
- Deploy it with
salt dwellers state.sls_id /srv/orbeon/nasqueron_forms/conf/tomcat-users.xml roles/paas-docker/containers/orbeon, where
nasqueron_formsis the name of our forms.nasqueron.orf instance
- Restart container:
docker restart nasqueron_forms
Nasqueron Forms instance uses the database
forms on db-A cluster, through the user
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;
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.
- 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 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 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.
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
- PDF doesn't have style when generated through nginx. As a work around, you can create SSH tunnel with
ssh -L 16080:dwellers:16080and browse http://localhost:16080 if you need a PDF.
- No flat view for multi-files attachment: https://github.com/orbeon/orbeon-forms/issues/1069