Toggle menu

getCommands

The getCommands method is the main point of interaction with the Forms Service. It creates PageSessions, FormSessions, and returns Commands for the caller to process based upon the current form state. Commands should be processed in the order they are returned.

Example commands are RENDER commands that contain content to be output to the page and FINISH commands which indicate that processing is finished for a given form.

If the "siteforms" iCM maintenance area is offline, this method will return a single RENDER command containing a user friendly message informing the user that site form rendering and submission is currently disabled. This message is output by the hbMaintenanceModeHeaderTemplate and hbMaintenanceModeBodyTemplate handlebar templates in the worker configuration.

Action Results

The getCommands method returns the results of any actions executed by the Forms Service during the previous submission. These results are keyed by the page name and page instance that the action was located on. After submitting a form the action results for the previous page will be available. 

See below for an example actionResults structure where PAGE1, containing a DATABASE save action, has been submitted. Note that the previousPageName and previousPageInstance properties may be used as keys to find actions for the last submitted page. Also note that the details of the saved object have been returned and are accessible. In this case the current form data was saved as objectId=317, with a type of "FORM_SIMPLEMULTIPAGEFORM" and a label of "8920db97-0900-4535-a73c-8e0396c4af8f".

{
    "actionResults": {
        "currentPageName": "PAGE2",
        "currentPageInstance": "0",
        "previousPageName": "PAGE1",
        "previousPageInstance": "0",
        "results": {
            "PAGE2": {
                "0": {
                    "DATABASE": [{
                        "page": "PAGE2",
                        "instance": "0",
                        "type": "DATABASE",
                        "fieldName": "DBSAVE",
                        "properties": {
                            "objectLabel": "8920db97-0900-4535-a73c-8e0396c4af8f",
                            "objectId": "317",
                            "objectType": "FORM_SIMPLEMULTIPAGEFORM"
                        }
                    }]
                }
            }
        }
    }
}

Parameters

NameTypeDescription
formIdLongID of the form to render. Either formId or formName and formType must be supplied
-or-
formNameStringLabel of the form to render. Required if formType is set
formTypeStringType of the form to render. Required if formName is set. Either FORMDEFINITIONEX for a public form, or CSFORMDEFINITIONEX for a private form
 
pageSessionIdUUID, requiredpageSessionId for this page render, generated by generatePageSessionId. Groups forms rendered on the same page together
pageURLString, requiredThe pageURL, containing the articleID and so on. After a form submission the browser will be redirected back to this URL. pageSessionId and formSessionId are automatically appended to it as query parameters
handlerURLString, requiredPublically accessible URL to the /processformsubmission submission endpoint, used as the form action URL. The pageSessionId, formSessionId, and nonce are automatically added to this as query parameters
errorPageURLString, requiredUpon a total failure the user's browser will be redirected to this URL
apiServerHostURLString, requiredPublically accessible URL for the API Server, e.g. http://mysite/apiserver
formsServiceURLString, requiredPoints to the root of the publically accessible URL for the Forms Service. For example: http://mysite/apiserver/formsservice
objectIdLong, optionalID of the iCM object to load and display in the form, ie displaying previously submitted data in a form. Provide on initial render only
-or-  
objectLabelString, optionalLabel of the iCM object to load. Supplied with objectType. Provide on initial render only
objectTypeString, optionalType of the iCM object to load. Supplied with objectLabel. Provide on initial render only
-or-  
formDataiCM Object data, optionalRather than specifying an object ID or label/type you may give it the complete object data, identical to that which would come back by doing a CSObject.get(objectID)
-or-
rawFormDataForm data, as submitted by the browser, optionalIn certain special cases it may be necessary to provide form data in the same format the values were submitted to the browser. This is the case for the workflow worker as the process state is stored as variables in the workflow itself (prefixed by form_), not in an iCM object. To populate data on a form the workflow worker simply exposes a method that returns the form_ prefixed process variables in the standard form submission name/value format, and the template specifies this as the rawFormData. Generally however this should not be used
 
userDetailsMap, optionalIf set, values extracted are: {"userId": 1, "username": "FRED"}. Made available to skeletons via Context["_FORMSERVICE_"]. The username must be uppercase.
forceFormRenderBoolean, optionalDefault: false. If true the Forms Service will be forced to return a RENDER command containing the main content of the form for sessions of type "longlived" (ie forms saved via the save button field type), regardless of whether a RENDER command already exists in the session as previously generated by a form submission

It must not be set to true in the general case of rendering a form. In the case of a link generated by the Save Button field type a URL parameter will be passed through on the URL with the name &fsfrr=true. If this URL parameter is detected on the URL by the site the value should be passed through to the Forms Service getCommands call via the forceFormRender parameter
renderModeString (enum), optionalOne of: normal, readonly, readonlynoctrl. Defaults to normal
sessionTypeString (enum), optionalOne of: standard, icm, longlived. Defaults to standard
userContextVarsMap, optionalOverride/introduce user context variables that may be read by skeletons, eg {"SITEUSERALIASES": ["ALIAS" ] }
formPropertiesMap, optionalOverride form properties, eg EXTPATH/EXTSUPPORT.
Last modified on September 15, 2023

Share this page

Facebook icon Twitter icon email icon

Print

print icon