Orientation to the CMS Lite Forms platform
Last updated on August 2, 2022Orbeon is a robust and well-documented application. Here is basic introduction to using Orbeon in CMS Lite.
Training
Training on Orbeon is usually provided to onboarding ministry staff shortly before their service begins. New staff are contacted when their request for access is received to determine their training needs.
Training on CMS Lite is required if form builders don’t already have it. (Many forms people also manage related content.) This training will cover useful subjects such as:
- How to create and publish various page types
- How to create useful metadata
- How to access analytics and history
CMS Lite training and access is available for an additional cost and can be arranged through the Learning Centre.
The basic model
Most government forms are available in PDF. This format is not mobile-friendly and usually not accessible either. One of the reasons for choosing Orbeon was its advanced PDF handling capabilities.
The basic model for creating forms in Orbeon is:
- Start with your existing paper or PDF form
- Design a new, modern experience for citizens
- Receive data by email through your PDF form
This approach has a few key advantages:
- It requires almost no change to existing workflows, processes, and records management
- It’s the fastest and cheapest path to modernizing services for citizens
- Forms are ready for integration when you are
Essentially, it adds a new and improved channel for citizens.
Components
The CMS Lite Forms Service is largely composed of three chief components:
- Orbeon Form Builder
- Orbeon Form Runner
- CMS Lite
Orbeon Form Builder is the tool you use to create and manage your forms. It consists of the Form Summary page, where you can see all the forms you have access to, and the Form Editor, where you build or edit a specific form.
Orbeon Form Runner is the tool that GDX uses to manage the platform and [custom form configurations]. You don’t have access to this tool, but if you’re working on more advanced forms or are a systems integrator, there’s some useful information in the manual.
CMS Lite is the tool you use to create the page that will host the form on the government website. You can add things like alert messages and information boxes. You’ll also add your metadata for your form here.
Controls
The objects you place on a form are called controls. They include sections, fields, grids, images, and buttons. There is a wide assortment of controls available. Technical details can be found in Orbeon’s documentation.
Control settings
Each control you add to a form has a collection of settings that apply to it. You can use these settings to control things like validation or help. The exact options available to you will depend on the type of control it is.
Custom controls
Orbeon is an American-based product that lacked certain Canadian controls which we’ve created for your convenience. They are marked with “CA”.
- CA Phone Number replaces the American phone number and uses the national and international phone number format for Canada
- CA Postal Code validates an entry against the allowed characters according to Canada Post and formats the entry
- CA Province is a dropdown list of province names such as “British Columbia”
- CA Province Abbreviation is a dropdown list of provincial abbreviations such as “BC”
- CA Soc. Ins. No. accepts any nine numbers and formats it
The phone number, postal code, and social insurance number fields only change the appearance of the data entered, but don’t change the data itself. This is known as ‘masking’. If you want to reuse the data elsewhere on the form, you may need to re-apply the mask.
Also note that neither the postal code nor social insurance number fields validate the accuracy of the information entered. The postal code does not check for a match to the address, and the social insurance number does not check the number entered against an algorithm.
Versioning
Orbeon has a built-in version control, but it’s purpose and function are a little different from other version control tools you may have experience with. For starters, it doesn’t permit you to ‘roll-back’ to a previous version because that could cause problems with data captured in earlier forms.
Where versioning is concerned, things to keep in mind when building and editing forms are:
- Don’t change form names. Form versions are stored based on the application (e.g. gov-hlth) and the form name (e.g. HLTH-8102). A change to either of these results in a new set of versions not connected to previous ones.
- Control your version numbers. When publishing a form, Orbeon offers to save a new version. You should only allow the version number to go up with public releases. The first version released to the public is version 1, the second is version 2, etc., regardless of how many times you had to publish for testing.
- Match your template. If you’re using a PDF template with a form, that template should be reviewed and adjusted if necessary. Even if there are no data changes to make, the version number at the bottom of the form should be updated to reflect which Orbeon form version was used to capture the data.
- Keep backups of your versions. As part of normal records management for forms, you should be keeping records of changes. Before beginning work on a new version for public release, check that a copy of the current version’s form definition XML is in your records. If you decided to restore an earlier version in the future, this backup will allow you to do so easily.
Outputs
The default configuration for a form created in Orbeon is to produce a generic email with the data attached in both plain XML and an autogenerated PDF.
Generic email (default)
When using the email function, a generic email is generated to act as a ‘carrier’ to send the XML and PDF to the program area.
Note that only one email can be set for a form. The citizen and program will receive the same email. This is one reason to avoid sending a copy of the form to the citizen; the other is for privacy reasons.
Custom email (optional)
You have some flexibility in overriding the default email subject and body through the Form Editor.
Note that you can only set up one email for a form. The citizen and program will receive the same email. This is one reason to avoid sending a copy of the form to the citizen; the other is for privacy reasons.
Plain XML (default)
XML files present data using structured containers like the tags you’d see in HTML. XML files are often used to transport data from a source (like Orbeon) to a destination (like an application programming interface or “API”).
If you’re just beginning to use Orbeon and not ready to develop an end-to-end automated workflow, the XML files can be used to quickly bring that data into a database at a future time.
Autogenerated PDF (default)
Orbeon will automatically generate a PDF of the form and collected data. By default, this form will look just like the form presented to the citizen, which may not be ideal for the citizen or the program area that will process the information. Consider using a template instead or designing a ‘print-friendly’ version of the form.
You can have Orbeon place data collected into a PDF that has form fields. You may want to do this to have greater control on the presentation of the output for aesthetic, processing, or records management reasons.
Configurations
Configurations are sets of code that tell Orbeon how to handle a form or group of forms. These configurations need to be developed and deployed by GDX. To request a custom configuration, send a request to the GDX Service Desk.
Things to keep in mind
- Configurations require developer time and testing and may result in a charge
- For some configurations, ministry staff need to be available and ready for testing to avoid delays in releasing
- Configurations are based on the application and form name. Changing that name will cause configurations to stop working for that form
- Configurations are released during the Wednesday afternoon change window. To ensure inclusion, they should be fully tested and approved by the Thursday before
Common configuration requests
- To change the buttons that appear at the bottom of the form
- To change the file name of generated PDFs
- To send the data to an API
- To change the text of the message that appears upon successful completion of a form
- To direct a user to another location after submitting a form
- To run a custom process (a series of events and actions)