Example Usage

To render a form using the Forms Service the following basic steps must be performed.

1. Generate a PageSessionId via generatePageSessionId which will be supplied for all subsequent getCommands calls for the lifetime of forms on a given page
2. For each form on the page, until a FINISH command is received for the form:
   1. Call getCommands, specifying among other parameters the pageSessionId generated in step 1 and the ID of the published form to render
   2. Process any returned commands appropriately. For example process a RENDER command by outputting the headerContent into the page <head/>, and the bodyContent into the page <body/> where you wish the form to be displayed
   3. The user submits the form to the /processsubmission endpoint
      1. The action of which is set to the handlerURL specifying the publically accessible path to the Form Service's /processsubmission endpoint as provided in the getCommands call
      2. If server side form validation is successful actions are processed and control processing is executed

var pageSessionId, getCommandsResult, 
  getCommandsArgs = 
    // Required
    formSessionId:        null
    formId:            12
    apiServerHostURL:    http://host:5706
    formsServiceURL:    http://host:5706/formsservice
    handlerURL:        http://host:5706/formservice/http/processformsubmission
    pageURL:            http://mysite.com/articles/9
    errorPageURL:        http://mysite.com/errorpage
    // etc

if url.containsQueryParam("pageSessionId")
  // Not the first render. Use the existing pageSessionId.
  getCommandsArgs.pageSessionId = url.getQueryParam("pageSessionId")
else
  // First render. Generate a pageSessionId.
  getCommandsArgs.pageSessionId = callGeneratePageSessionId()
  // Supply objectId/objectLabel+objectType/objectData/rawObjectData if required.
  getCommandsArgs.objectId = 14

// Process result
getCommandsResult = callGetCommands(getCommandsArgs)
foreach command in getCommandsResult.commands
  switch (command.commandName):
    case "RENDER":
      // Output command.params.headerContent in the <header/>.
      // Output command.params.bodyContent in the <body/> where you wish the form 
         to be displayed on the page.
    case "EXECUTE_ACTION":
      // Represents an action the Forms Service wasn't able to process. 
      // You may process it yourself.
    case "ERROR":
      // An error internal to the Forms Service occurred upon form submission.
      // Suggest logging the error and showing a user-safe error to the user.
    case "FINISH":
      // Indicates that form has finished - i.e. the last page has been submitted.
      // Nothing more to do. The Form Session has ended.
    default:
      throw new Exception "Unknown command: " + command

Page Render Request/Response Example

The following captures requests to and responses from the Forms Service for a two page form (ID 130) that has a CONFIRMATIONACTION on the second page.

1. Initialise: Generate a PageSessionId via generatePageSessionId() which will be supplied for all subsequent getCommand calls for the lifetime of all forms on a given page
2. First getCommands call to render the form:
   1. Form is rendered and presented to the user
   2. User submits PAGE1 to the /processsubmission HTTP method, redirecting back to the pageURL resulting in the second getCommands call
3. Second getCommands call to render PAGE2 of the form:
   1. Form is rendered and presented to the user
   2. User submits PAGE2 to the /processsubmission HTTP method, executing actions on the last page and redirecting back to the pageURL resulting in the third getCommands call
4. Third getCommands call:
   1. Returns a RENDER command containing the message "<p>Thank You</p>" generated by the CONFIRMATIONACTION on the final page
   2. Returns a FINISH command indicating that the form has been followed to completion. The form session will not exist after a FINISH action is emitted

Example Request [Initialise - generateFormSession call]

{ 
    "id": "635931424210777559",
    "jsonrpc": "2.0",
    "method": "generatePageSessionId",
    "params": null
}

Example Response [Initialise - generateFormSession call]

{ 
    "id": "635931424210777559",
    "jsonrpc": "2.0",
    "result": {   
        "result": {     
            "pageSessionId": "eb9fe3ef-fc20-40e9-aac6-c502e831a467"   
        } 
    }
}

Example Request [Page #1 - Initial Form Render]

{ 
    "id": "635931424210907566",
      "jsonrpc": "2.0",
      "method": "getCommands",
      "params": {
        "formId": 130,
            "formLabel": null,
            "formType": null,
            "pageSessionId": "eb9fe3ef-fc20-40e9-aac6-c502e831a467",
            "handlerURL": "http://devtestw3/apiserver/formsservice/http/processsubmission",
            "apiServerHostURL": "http://devtestw3/apiserver",
            "formsServiceURL": "http://devtestw3/apiserver/formsservice",
            "pageURL": "http://devtestw3/article/151/Multipage-Form-Test",
            "errorPageURL": "http://devtestw3/article/151/Multipage-Form-Test?errorMessage=%24%5b%5berrorMessage%5d%5d",
            "objectId": 0,
            "objectLabel": null,
            "objectType": null,
            "userDetails": {
            "username": "ADMIN",
            "userId": 1   
        },
        "renderMode": "Normal",
        "userContextVars": {},
        "formProperties": {
            "LIBRARYBASEURL": "http://devtestw3/resource/formlib/"
        },
        "rawFormData": null
    }
}

Example Response [Page #1 - Initial Form Render]

{
    "id": "635931424210907566",
    "jsonrpc": "2.0",
    "result": {
        "result": {
            "pageSessionId": "eb9fe3ef-fc20-40e9-aac6-c502e831a467",
            "sessionId": "1b4390f4-da08-44ae-8b75-51a75aab0b33",
            "nonce": "e66084e0-5dfc-44af-a197-74f9988df67e",
            "commands": [{
                "commandName": "RENDER",
                "params": {
                    "currentPageTitle": "",
                    "identifier": null,
                    "mainFormContent": true,
                    "bodyContent": "[...SNIP...]",
                    "headerContent": "[...SNIP...]"
                }
            }],
            "actionResults": {
                "previousPageName": "",
                "results": {},
                "currentPageInstance": "0",
                "previousPageInstance": "",
                "currentPageName": "PAGE1"  
            }
        }
    }
}

Example Request [Page #2 - Render - Post Page #1 Submission]

Page 1 has been submitted by the user to the /processformsubmission HTTP method, which has returned a redirect back to the pageURL specified in the initial getCommands call:

{ 
    "id": "635931426867449512",
      "method": "getCommands",
      "params": {   
        "formId": 130,
            "formLabel": null,
            "formType": null,
            "pageSessionId": "eb9fe3ef-fc20-40e9-aac6-c502e831a467",
            "handlerURL": "http://devtestw3/apiserver/formsservice/http/processsubmission",
            "apiServerHostURL": "http://devtestw3/apiserver",
            "formsServiceURL": "http://devtestw3/apiserver/formsservice",
            "pageURL": "http://devtestw3/article/151/Multipage-Form-Test",
            "errorPageURL": "http://devtestw3/article/151/Multipage-Form-Test?errorMessage=%24%5b%5berrorMessage%5d%5d",
            "objectId": 0,
            "objectLabel": null,
            "objectType": null,
            "userDetails": {     
            "username": "ADMIN",
            "userId": 1   
        },
            "renderMode": "Normal",
            "userContextVars": {},
            "formProperties": {
            "LIBRARYBASEURL": "http://devtestw3/resource/formlib/"
        },
        "rawFormData": null
    }
}

Example Response [Page #2 - Render - Post Page #1 Submission]

{ 
    "id": "635931426867449512",
      "jsonrpc": "2.0",
      "result": {   
        "result": {     
            "sessionId": "1b4390f4-da08-44ae-8b75-51a75aab0b33",
            "nonce": "359c3065-c071-4b26-865c-84a50ee74a7b",
            "commands": [{         
                "commandName": "RENDER",
                "params": {         
                    "currentPageTitle": "",
                    "identifier": null,  
                    "mainFormContent": true,
                    "bodyContent": "[...SNIP...]",
                    "headerContent": "[...SNIP...]"         
                }       
            }],
            "pageSessionId": "eb9fe3ef-fc20-40e9-aac6-c502e831a467",
            "actionResults": {       
                "previousPageName": "PAGE1",
                "results": {},
                "currentPageInstance": "0",
                "previousPageInstance": "0",
                "currentPageName": "PAGE2"     
            }   
        } 
    }
}

Example Request [Post Page #2 Submission]

Page 2 has been submitted by the user to the /processformsubmission HTTP method, which has returned a redirect back to the pageURL specified in the initial getCommands call:

{ 
    "id": "635931427036599187",
    "jsonrpc": "2.0",
    "method": "getCommands",
    "params": {   
        "formId": 130,
        "formLabel": null,
        "formType": null,
        "pageSessionId": "eb9fe3ef-fc20-40e9-aac6-c502e831a467",
        "handlerURL": "http://devtestw3/apiserver/formsservice/http/processsubmission",
        "apiServerHostURL": "http://devtestw3/apiserver",
        "formsServiceURL": "http://devtestw3/apiserver/formsservice",
        "pageURL": "http://devtestw3/article/151/Multipage-Form-Test",
        "errorPageURL": "http://devtestw3/article/151/Multipage-Form-Test?errorMessage=%24%5b%5berrorMessage%5d%5d",
        "objectId": 0,
        "objectLabel": null,
        "objectType": null,
        "userDetails": {
            "username": "ADMIN",
            "userId": 1   
        },
        "renderMode": "Normal",
        "userContextVars": {},
        "formProperties": {     
            "LIBRARYBASEURL": "http://devtestw3/resource/formlib/"   
        },
        "rawFormData": null 
    }
}

Example Response [Post Page #2 Submission]

{
    "id": "635931427036599187",
    "jsonrpc": "2.0",
    "result": {
        "result": {
            "pageSessionId": "eb9fe3ef-fc20-40e9-aac6-c502e831a467",
            "sessionId": "1b4390f4-da08-44ae-8b75-51a75aab0b33",
            "nonce": "5f29e6e7-aefd-45e9-9488-52ffb816fa16",
            "commands": [{
                "commandName": "RENDER",
                "params": {
                    "mainFormContent": false,
                    "bodyContent": "<p>Thank You</p>",
                    "headerContent": ""
                }
            }, {
                "commandName": "FINISH",
                "params": {}
            }],
            "actionResults": {
                "previousPageName": "PAGE1",
                "results": {
                    "PAGE2": {
                        "0": {
                            "CONFMESSAGE": [{
                                "page": "PAGE2",
                                "properties": {
                                    "MESSAGE": "Thank You"
                                },
                                "type": "CONFMESSAGE",
                                "fieldName": "FIELD10",
                                "instance": "0"
                            }]
                        }
                    }
                },
                "currentPageInstance": "0",
                "previousPageInstance": "0",
                "currentPageName": "PAGE2"
            }
        }
    }
}