Toggle menu

Scripted Form Actions

Form actions are processed when a page is submitted, including between pages on multipage forms. They control what happens to your form once a user has finished filling it in. 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.

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

This function creates and returns an action object, representing an action performed by an action field. The actions you can create are:

  • Confirmation Message - "CONFMESSAGE" (you can also use the helper.utilCreateConfMessageAction(fieldName, message) function)
  • Database Save - "DATABASE"
  • Data Integration (the Talend job upload) - "DATAINTEGRATIONUPLOAD"
  • 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) {
    var actionObject = helper.utilCreateAction(Props.FIELD.NAME, "EMAIL");
    return actionObject;
}

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

helper.utilAddActionProperty

This 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:

Email Action Properties

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 query the values of other fields and variables, so:

function(helper, processor, props, context) {
    var 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 a hidden field in the form designer's action field, but you can see its default value in the definition:

Email Action Class

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

PropertyTypeDescription
URLString, requiredThe URL to redirect to
endSessionBoolean, requiredWhether or not to end the form session (this should generally always be true)

Example

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

Not Using Scripted Actions

In practice we've rarely found the need to use scripted actions. The action fields themselves are very flexible, with most properties able to use the values of other fields using the standard ## notation. More complex fields like Write History and Email also include function properties you can use to manipulate data before it is passed to the field.

Action fields can also be placed inside conditional layout fields. This allows you to write condition functions that will determine whether any of the fields inside the layout are processed or not.

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

Last modified on 11 November 2022

Share this page

Facebook icon Twitter icon email icon

Print

print icon