The rendering of a form is inherently stateful. Multipage forms need to store the values of fields submitted on previous pages, context variables must persist between pages and so on. This state is stored in a FormSession, and stored in a database table called WkFormsServiceSessions.
Page Sessions
On the initial rendering of a page a pageSessionId must be generated and provided with every subsequent call to getCommands for each form on the page. PageSessions are simply a way of logically grouping the forms (and their FormSessions) rendered on the same page together.
This grouping is important when rendering multiple forms on the same page. If multiple forms on the same page weren't grouped together by a PageSession then upon the user submitting one of the forms, the other forms on the page wouldn't have any RENDER commands to process after coming back from the submission. If a form in a PageSession is submitted by the user then RENDER commands are also generated for all other forms in the PageSession on that page.
PageSessions are created implicitly when getCommands is called with a PageSessionId that doesn't exist in the database. In pseudo-code:
if pageSessionExists(pageSessionId)
pageSession = loadPageSession(pageSessionId)
else
pageSession = createPageSession(pageSessionId)
Only one instance of a form may be present in a single PageSession - two instances of the same form cannot be rendered on the same page.
Form Sessions
FormSessions are created implicitly and linked to the PageSession when getCommands is called with a formId that doesn't already have a FormSession linked to the PageSession. In pseudocode:
if formSessionExistsForFormId(pageSessionId, formId)
formSession = loadFormSession(pageSessionId, formId)
else
formSession = createFormSession(pageSessionId, formId)
Stored within a FormSession:
| Name | Type | Description |
|---|---|---|
| ID | UUID | The FormSessionID |
| PageSessionID | UUID | PageSessionID the FormSession is within |
| Nonce | UUID | The current nonce value used to ensure forms cannot be double submitted. May be null |
| FormID | Long | ID of the form this session has been created against |
| SessionType | VARCHAR | Either 'standard' or 'longlived' |
| Created | Timestamp | When the FormSession was created |
| Updated | Timestamp | When the FormSession was last updated |
| RowVersion | Long | Used internally for caching purposes |
| UserID | Long | ID of the site user using the form. May be null.As supplied in the last getCommands call via userDetails |
| UserName | VARCHAR | Username of the site user using the form. May be null. As supplied in the last getCommands call via userDetails |
| PageURL | VARCHAR | As supplied in the last getCommands call |
| HandlerURL | VARCHAR | As supplied in the last getCommands call |
| ErrorPageURL | VARCHAR | As supplied in the last getCommands call |
| RedirectPageURL | VARCHAR | As supplied in the last getCommands call |
| ContextVars | VARCHAR | Current context variable state. JSON |
| FormProperties | VARCHAR | Current form property state. JSON |
| FormSession | VARCHAR | Current form session state - previous page values, etc. JSON |
| ValidationResults | VARCHAR | Validation errors if encountered in the previous form submission. Nullable. JSON |
| PersistentCommands | VARCHAR | Commands to be returned in the next call to getCommands, generally generated in the submission process. JSON |
Expiry
Expiry is performed by a session expiry task that runs every five minutes.
Page Sessions
A page session is expired when there are no longer any form sessions referencing it.
Form Sessions
There are two types of form session, each with their own expiry time: standard and longlived.
Standard sessions are expired by the session expiry task when they haven't been updated for the time period specified by the
Longlived sessions are expired by the session expiry task when they haven't been updated for the time period specified by the
Share this page
