Form Action Fields and Scripted Actions

Form actions are executed when the page they are on is submitted. That could be when the whole form is submitted if the action is on the final page of the form, but could also happen between pages on multipage forms. As well as the Action Fields available in the forms designer, it's possible to manually create actions using the script field.

The Form Lifecycle: Control and Action Processing article describes the order actions are processed in and whether they are performed by the form family or passed back to the Forms Service worker for processing. It's important to understand how and when actions are processed before creating them.

Not Scripting Actions

Before manually scripting form actions, check to see if the standard fields can do the job for you. The action fields are very flexible, and should cover almost every situation you find yourself in. The fields let you fetch the values of other fields on your form (using the ## notation) and most include JavaScript functions so you can extend their behaviour and manipulate the data they work with.

Action fields can also be placed inside conditional layout fields. That means you can write conditional functions that will determine whether any of the fields inside the layout are processed or not. If the condition isn't met (ie the fields aren't displayed) the actions won't be processed.

There are also two helper functions, .utilRemoveAction and .utilRemoveAllActions you can use to remove actions from a page when it is submitted.

Manually Scripting Actions

The form helper library includes two helper functions you can use to manually generate actions using a standard Script Action field.

helper.utilCreateAction

.utilCreateAction function creates and returns an action object, representing an action performed by one of the action fields. The actions you can create are:

• Confirmation Message - "CONFMESSAGE" (you can also use the helper.utilCreateConfMessageAction(fieldName, message) function)
• Database Save - "DATABASE"
• Email - "EMAIL"
• History Write - "HISTORYSAVEFORMDATA"
• Redirect - "REDIRECT"
• Save Form - "SAVEFORMSESSION"
• XML over HTTP - "XMLHTTP"

For example, the first step in creating an email action is:

function(helper, processor, props, context) {
    let actionObject = helper.utilCreateAction(props.FIELD.NAME, "EMAIL");
    return actionObject;
}

The fieldName should be a unique string to identify the action you are creating. props.FIELD.NAME will use the name of your script action field.

helper.utilAddActionProperty

.utilAddActionProperty function adds a named property value to your action. The properties you can add are best understood by looking at the action fields in the form family.

Here's the standard email action field:

As you'd expect, the email action needs details like the "to" and "from" addresses, the email subject and the body. These properties are added one by one to the action, and can use the values of other fields and variables, so:

function(helper, processor, props, context) {
    let actionObject = helper.utilCreateAction(props.FIELD.NAME, "EMAIL");
    helper.utilAddActionProperty(actionObject, "CLASS", "form, com.gossinteractive.community.form.actions.EmailAction");
    helper.utilAddActionProperty(actionObject, "EMAIL_FROM", "noreply@gossinteractive.com");
    helper.utilAddActionProperty(actionObject, "EMAIL_SUBJECT", "The subject line");
    helper.utilAddActionProperty(actionObject, "EMAIL_TO", helper.getFieldValue("TO"));
    helper.utilAddActionProperty(actionObject, "EMAIL_BODY", helper.getFieldValue("MESSAGE"));
    return actionObject;
}

In this example the CLASS property is hidden in the form designer, but you can see its default value in the definition:

The action skeletons (ExecuteActionSkel) of each action field type are also good sources of information for how actions are built. Here's the ExecuteActionSkel of the email action field.

<%
var helper = Context["HELPER"],
    actionObject, emailData = {};
actionObject = helper.utilCreateAction(Props["FIELD"]["NAME"], "EMAIL");
helper.utilAddActionProperty(actionObject, "CLASS", Props["FIELDPROPERTIES"]["CLASS"]);
helper.utilAddActionProperty(actionObject, "EMAIL_SUBJECT", helper.utilExpandTemplate(Props["FIELDPROPERTIES"]["SUBJECT"]));
helper.utilAddActionProperty(actionObject, "EMAIL_TO", helper.utilExpandTemplate(Props["FIELDPROPERTIES"]["TO"]));
helper.utilAddActionProperty(actionObject, "EMAIL_CC", helper.utilExpandTemplate(Props["FIELDPROPERTIES"]["CC"]));
helper.utilAddActionProperty(actionObject, "EMAIL_BCC", helper.utilExpandTemplate(Props["FIELDPROPERTIES"]["BCC"]));
helper.utilAddActionProperty(actionObject, "EMAIL_FROM", helper.utilExpandTemplate(Props["FIELDPROPERTIES"]["FROM"]));
helper.utilAddActionProperty(actionObject, "EMAIL_BODY", helper.utilExpandTemplate(Props["FIELDPROPERTIES"]["BODY"]));
helper.utilAddActionProperty(actionObject, "EMAIL_BODY_FORMAT", Props["FIELDPROPERTIES"]["BODYFORMAT"]);
helper.utilAddActionProperty(actionObject, "EMAIL_INCLUDEUPLOADS", Props["FIELDPROPERTIES"]["INCLUDEUPLOADS"] == true ? "true" : "false");
helper.utilAddActionProperty(actionObject, "EMAIL_GENERATEPDF", Props["FIELDPROPERTIES"]["GENERATEPDF"] == true ? "true" : "false");
helper.utilAddActionProperty(actionObject, "EMAIL_PDFNAME", helper.utilExpandTemplate(Props["FIELDPROPERTIES"]["PDFNAME"]));
helper.utilAddActionProperty(actionObject, "EMAIL_PDFBODY", helper.utilExpandTemplate(Props["FIELDPROPERTIES"]["PDFBODY"]));
if (Props["FIELDPROPERTIES"]["EMAILDATAFUNC"].indexOf("function") === 0) {
    eval("emailData=" + Props["FIELDPROPERTIES"]["EMAILDATAFUNC"] + "( helper, emailData );");
}
helper.utilAddActionProperty(actionObject, "EMAIL_DATA", JSON.stringify(emailData));
helper.utilAddAction(actionObject, Props["FIELD"]["NAME"], Context); %>

Redirect Action

Redirects should be used with caution. You should take care not to interrupt the processing of other form actions and not to leave form sessions active once the redirect has taken place.

Properties

Example

function(helper, processor, props, context) {
    let actionObject = helper.utilCreateAction(props.FIELD.NAME, "REDIRECT");
    helper.utilAddActionProperty(actionObject, "URL", "https://www.gossinteractive.com");
    helper.utilAddActionProperty(actionObject, "endSession", true);
    return actionObject;
}