Toggle menu

Sessions

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.

Form Session DB Tables
 

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:

NameTypeDescription
IDUUIDThe FormSessionID
PageSessionIDUUIDPageSessionID the FormSession is within
NonceUUIDThe current nonce value used to ensure forms cannot be double submitted. May be null
FormIDLongID of the form this session has been created against
SessionTypeVARCHAREither 'standard' or 'longlived'
CreatedTimestampWhen the FormSession was created
UpdatedTimestampWhen the FormSession was last updated
RowVersionLongUsed internally for caching purposes
UserIDLongID of the site user using the form. May be null.As supplied in the last getCommands call via userDetails
UserNameVARCHARUsername of the site user using the form. May be null. As supplied in the last getCommands call via userDetails
PageURLVARCHARAs supplied in the last getCommands call
HandlerURLVARCHARAs supplied in the last getCommands call
ErrorPageURLVARCHARAs supplied in the last getCommands call
RedirectPageURLVARCHARAs supplied in the last getCommands call
ContextVarsVARCHARCurrent context variable state. JSON
FormPropertiesVARCHARCurrent form property state. JSON
FormSessionVARCHARCurrent form session state - previous page values, etc. JSON
ValidationResultsVARCHARValidation errors if encountered in the previous form submission. Nullable. JSON
PersistentCommandsVARCHARCommands 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 sessionTimeout worker.conf property. The default timeout is 60 minutes.

Longlived sessions are expired by the session expiry task when they haven't been updated for the time period specified by the longLivedSessionTimeout worker configuration property. The default timeout is 28 days. Standard sessions generally created by the "save button" field type which can be added to forms in the forms designer.

Last modified on March 06, 2020

Share this page

Facebook icon Twitter icon email icon

Print

print icon