The Forms Service is responsible for generating the forms displayed on your site and in iCM. It provides a standard, centralised, cross-platform tool that handles form rendering, form submission, action processing, control flow, storage of uploaded files via the File Store worker, and persistent form sessions. Form sessions are stored persistently on the database along with all other data relating to the form render.
Worker Configuration
The following configuration options can be passed to the Forms Service worker via the API Server configuration file, overriding the defaults.
Expired form sessions are deleted upon an attempt to load them, or each time the expiry task runs.
| Property | Type | Description |
|---|---|---|
| sessionTimeout | Object | How long a standard form session will last since it was last updated until it times out Default: {"T": "time","V": "01:00:00"} |
| icmSessionTimeout | Object | How long an internal iCM form session (eg your article extra tab) will last since it was last updated until it times out Default: {"T": "time","V": "12:00:00"} |
| longLivedSessionTimeout | Integer | How long a long-lived form session will last since it was last updated until it times out. Long-lived form sessions are used by the "Save" button in the forms designer. 672 hours is 28 days Default: 672 |
| sessionIdWrapperQueryParams | Array | Specifies the name of a query parameter that allows the session id information to be extracted from various parts of a URL from a third party like a payment service |
| genericErrorMessage | String | A generic message. You'll see this if for some reason a form session has been deleted. Default: "<div class=\"alert alert--error\"><p>Oops! Something went wrong with your form. Help us improve your experience by letting us know about the issue.</p></div>" |
| doubleSubmitWarningMessage | String | Message displayed to the user if they attempt to double submitting a form. For example: 1) Render form 2) Submit page 1. 3) Hit the browser's back button 4) Submit page 1 again. This message is not output if the message is set (overridden) to null or an empty string. Default: "<div class=\"alert alert--error\"><p>A double form page submission has been detected. The form has been returned to the state it was in after the last valid submission.</p></div>" |
| noCommandsWarningMessage | String | The message displayed to the user when returning an empty list of commands, e.g. after the user hits their browser's back button to a previous form page. Default:"<div class=\"alert alert--error\"><p>Refreshing the page or using the browser's back button is not supported. Please use the navigation buttons provided. The form has been returned to the state it was in after the last valid submission.</p></div>" |
| hbMaintenanceModeHeaderTemplate | String | Handlebars header template, evaluated and output to the user when getCommands, /processformsubmission, or /redirect are called while the "siteforms" area is in maintenance mode. Default: |
| hbMaintenanceModeBodyTemplate | String | Handlebars body template, evaluated and output to the user when getCommands, /processformsubmission, or /redirect are called while the 'siteforms' area is in maintenance mode. Default:"{{maintenanceDetails.offlineComment}} {{#gt maintenanceDetails.schedules.size 0}} <p>Site forms are scheduled to come back online at {{formatDate maintenanceDetails.schedules.0.getParsedScheduleDate.getTime \"%H:%M\"}} on {{formatDate maintenanceDetails.schedules.0.getParsedScheduleDate.getTime \"%d/%m/%Y\"}}</p> {{/gt}}" |
| hbFutureMaintenanceModeHeaderTemplate | String | Handlebars header template, evaluated and output to the user when getCommands, /processformsubmission, or /redirect are called when the "siteforms" area is scheduled to go into maintenance mode. Default: |
| hbFutureMaintenanceModeBodyTemplate | String | Handlebars body template, evaluated and output to the user when getCommands, /processformsubmission, or /redirect are called when the "siteforms" area is scheduled to go into maintenance mode. Default:"{{#gt maintenanceDetails.schedules.size 0}} {{#isnt maintenanceDetails.schedules.0.online true}}<p>Site forms are scheduled to go offline at {{formatDate maintenanceDetails.schedules.0.getParsedScheduleDate.getTime \"%H:%M\"}} on {{formatDate maintenanceDetails.schedules.0.getParsedScheduleDate.getTime \"%d/%m/%Y\"}}</p>{{/isnt}}{{/gt}}" |
| resumeSessionHTML | String | The message displayed when recovering a session on the "resume session" page. Default:"<p>Please click here to resume your session.</p><div class=\"icmform\"><div class=\"icmbutton-surround\"><div class=\"icmbutton\"><input type=\"submit\" class=\"icminput icminput--button\" value=\"Resume Session\"></div></div></div>" |
HTTP Methods
These methods are called via standard HTTP POST and GET.
JSON RPC Methods
The worker supports nine JSON-RPC methods which cover all aspects of form handling.
Commands
The getCommands method returns commands for the caller to process based upon the current form state.
Sessions
Form and page sessions are stored in the iCM database and expired by the expiry task.
Example Usage
Example form rendering and processing.
Share this page
