Workflow - Message Action

Messages can be sent by form submissions to the workflow engine and be caught by intermediate and boundary message events.

When sending a message you must be able to identify the process instance you are sending the message to (generally that means you need to know the business key). That means that this field cannot be used in a stand-alone form to send messages because, without additional work, there is no way for the field to know which process instance to send the message to.

This field is used when building cancellation into workflow models that are used with the Self Service and User Requests products. When interacting with a process using these products the instance to send the message to is held in the WORKFLOWPROCESSID context variable and picked up automatically by this field type. The special GOSS_StarterCancel message reference is also used.

For more information about messages and cancellation see the Messages and Signals and Building Cancellation into your Workflow Models reference articles.

Properties

Action Results

The following can be accessed using .utilGetActionResults once the action has been processed.

"FIELDNAME": {
    "success": "true"
}

"FIELDNAME_CONF": {
    "MESSAGE": "Message sent successfully",
    "success": "true"
}

Adding Additional History Properties

Rather than providing static values in the forms designer for subject and event properties, you can instead build them programmatically. To add additional properties to an event or the history subject, return a JSON object from the subject/event additional properties functions:

function(helper) {
    var additionalProps = {};
    additionalProps.additionalPropertyKey = "additionalPropertyValue";
    additionalProps.totalCost = parseInt(helper.getFieldValue('PRICE')) * parseInt(helper.getFieldValue('QUANTITY'));
    return additionalProps;
}

Overriding Properties

To override an existing property, include a property with the same name in your JSON object. The following property names can be overridden:

Subject Properties: 

• description
• userId
• proxyUserId

Event Properties: 

• event (the event name)
• description
• userRole
• userId
• proxyUserId
• historyDescription (used in SUMMARY events)
• private (note that this must be a boolean, not a string, so the value of another field cannot be used directly)

For example, to override a description with the value of a field:

function(helper) {
    var additionalProps = {};
    additionalProps.description = helper.getFieldValue("TEXT1");
    return additionalProps;
}

Or to dynamically set the privacy setting of the event:

Manipulating Process Variables

By default the fields and values submitted with your form are passed to the workflow engine as process variables. The process variables function lets you manipulate the variables that are created.

For example, the following will remove a specific process variable from the map:

You can also create process variables. This example is taken from the GOSS Contribute product:

function(helper, processVars) {
    processVars.CONFIGNAME = "contributeevent";
    // Additional tasks
    processVars.ADDITIONALTASKS = [{
        "form": "CONTRIBUTE",
        "name": "Contribute Event"
    }, {
        "form": "PRICES",
        "name": "Default Prices"
    }];
    return processVars;
}

Data Types

Form fields always submit their values back to the server as strings, which means the values of your process variables will also be strings. Take care when manipulating process variables server-side or updating the values of fields using .setFieldValue - the values you set should also be strings.

Having said that, it is possible to create and pass JavaScript objects to a workflow process using the prefix js_. Variables with this prefix will remain as objects in the workflow engine.

For example, this function would create two new variables. js_objectExample would behave as an object if you used it in a workflow script activity:

function(helper, processVars) {
    processVars.new = "test";
    processVars.js_objectExample = {
        "key": "value"
    };
    return processVars;
}

See Creating and Updating Process Variables in the workflow knowledge base for more information.