Example Usage

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

Generate a PageSessionId via generatePageSessionId which will be supplied for all subsequent getCommands calls for the lifetime of forms on a given page
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.

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
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
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
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" } } } }

Last modified on September 11, 2023

This website uses cookies