Set

Description

Set worker fields such as status and/or create an event and/or set a file and/or set data, optionally interacting with the user to do so, and optionally choosing an outcome.

Overview

The set step is a general-purpose "workhorse" for managing worker processes.

It can:

  • Set the worker status
  • Set the worker message
  • Set whether the worker requires action or if it is of interest
  • Set whether the worker is active
  • Create a worker event, with
    • Event type
    • Description
    • Status
    • Attachments
  • Set one or more files associated with the worker
  • Set data associated with the worker
  • Publish the status and data to subscribers.
  • Set the step state to control flow to subsequent steps

The step can interact with the user or can run without user input. This is controlled by the show configuration property or by the show parameter.

When run interactively (which is the default), the form can:

  • Show content
  • Solicit a message
  • Upload one or multiple files
  • Allow the user to choose between multiple outcomes (e.g. to accept or reject an item).

Other functionality can be associated with running interactively, for example to set the worker as requiring action if the user submits the form.

When running interactively, the user is shown a cancel button. If they press cancel, no updates are made (though the state may be set - see configuration below).

When run without user input, set can perform any of its functionality except setting state.

Configuration

Set can be configured using a block of JSON or by creating an instance of the Set step type and setting fields. The JSON properties are described below.

When show is false, many of the same properties can also be passed in within the JSON in the "data" parameter. This includes the data property, i.e. the data property may be passed as a property within a request parameter called "data".

Request properties generally override config properties, but see the permit property. All properties are optional. Properties in bold can be passed in the request.

show Whether or not to show the form. Defaults to true. Can also be set by passing the setting request parameter show to "false".
title A title for the form.
content Content to show at the top of the form. Marked up HTML.
showMessage Whether to show an area to input a message. Default false.
messageMandatory Set to true to make the message mandatory.
messageMandatoryMessage If messageMandatory is true, message to show if user has not entered a message.
showMessageHeading Indicates whether a message heading should be shown. Defaults to true.
messageHeading HTML for the message heading. If not given, a suitable heading will be generated.
messageEditor Set to true to turn on the message editor. Set to a string to set an additional editor class, such as "editor-basic". See documentation on the editor CSS class for details.
message

When show is true, initial value for message.

When show is false, default value for the message. May be overridden by the data parameter.

status

The status to set on the form. This can either be a string or a lookup based on the reference of the buttons on the form (the lookup can only be used when show is true).

For example, in the following the status is set to "accepted" or "rejected" depending on whether the user pressed the accept or reject button.

"status": {
"reject": "rejected",
"accept": "accepted"
}

If an event is created, the status is written to the event. Use the "*" property to specify a status for any other button.

You cannot set a status when the cancel button is pressed. (If you need to do this, you can achieve this by defining another Set state to set the status, and linking this step to that step on the cancel outcome.)

When show is false, may be overridden by the data parameter.

createEvent

Set to true to create an event.

By default this will use the message (if any) as the description, set the status, and set attachments. Attachments will be sourced from the attachments data or from the uploaded files.

If you don't set the status, you can use createEvent with eventType and eventDescription just to create an event. If you set the status, the worker will be updated as well as the event being created.

May be overridden by the data parameter.

eventType

Type for the event.

When show is false, the eventType can be overridden by the "eventType" request parameter.

May be overridden by the data parameter.

eventDescription

Description for the event, to override the message.

May be overridden by the data parameter.

attachments

Attachments for the event, an array of nodes or file info objects.

If set to true, take all the file info objects from the data as the attachments.

dataReferenceAttachments

Data area in which to store attachments, which defaults to 'attachments'.

confirm If set to true, shows a check box that the use must check before proceeding with a button press other than cancel. Only applies when showing the form.
confirmContent Content to associate with the confirmation checkBox. Defaults to 'I confirm'.
notConfirmedMessage Message to show user if they do not select the confirmaiton. Defaults to 'Please confirm'.
button

This specifies the caption for the button or buttons.

If this holds a single string, it uses that as the caption.

For example

"button": "Confirm"

Would give

Alternatively, it can provide an object with caption, value and class, or an array of these objects to create multiple buttons. The class can be CSS classes or one of the standard Bootstrap reference (default, primary, success, warning, danger or default).

For example

"button": [
{
"value": "accept",
"caption": "Accept",
"class": "success"
},
{
"value": "reject",
"caption": "Reject",
"class": "danger"
},
{
"value": "cancel",
"caption": "Cancel",
"class": "default"
}
]

This would give

If a button with a value of "cancel" is not specified a cancel button will always be generated. (If you really don't want a cancel button, define it in the button list and give it a class of "hidden".)

The default button has a value of "submit", a caption of "Submit" and a class of "primary".

The default cancel button has a value of "cancel", a caption of "Cancel" and a class of "default".

state

Set the in-memory outcome state of the step.

This is a different concept than status. status is written to the worker node and, using status rules, controls what actions are offered to the user. state is an in-memory value which is used to select the next process step to run immediately after this one, i.e. it us used immediately to run another step, not used later to offer different options to the user.

The default is to set the state to the value of the button press, typically "submit" or "cancel".

You can change the "submit" state to another value by setting the state propery. Alternatively, and more usefully, you can specify an object that link the states to button values. This is the same syntax as the status, but does allow cancel to be specified also.

"state": {
"accept": "accepted",
"reject": "rejected",
"cancel": "cancelled"
}

This would allow additional process steps to be linked to the accept, reject and cancel button presses.

When the form is not shown, state is set to "success". However, through process step introspection, if the step has a "submit" branch and not a "success" branch, the state will be set to "submit". This means that "submit" can be used in place of "success", for consistency with when the form is shown. Generally, you would not set state when show is false.

active

Can be set in the config to true or false to set whether the worker is active.

May be overridden by the data parameter.

actionRequired

Can be set in the config to true or false to set whether action is required.

May be overridden by the data parameter.

ofInterest

Can be set in the config to true to indicate that the worker is of interest. Automatically set when actionRequired is set to true.

You cannot set "ofInterest" to false - it times out automatically.

showUpload Whether to show an area to upload files. Default is false.
uploadMandatory Set to true to make the upload mandatory.
uploadMandatoryMessage If uploadMandatory is true, message to show if user has not uploaded a file.
showUploadHeading Indicates whether an upload heading should be shown. Defaults to true.
uploadHeading HTML for the upload heading. If not given, a suitable heading will be generated.
uploadMultiple Set to true to allow the upload of multiple files.
uploadFirst Set to true to put the upload area before the message area. If false (the default) the message area precedes the upload area.
dataReference

Reference at which uploaded files should be stored, or at which passed in data should be stored. Note that you cannot store both files and data within a single Set step. (The data reference identifies a single node in which either files or passed data can be stored.)

This is used to build a node reference for the data node relative to the worker node. It must be a valid local reference, i.e. only alphanumeric or _ and must not start with a number.

Data reference defaults to "files" for uploaded files or when fileData is true, and "data" for other data.

May be overridden by the data parameter.

Set the dataReference to null to not store data. This can be useful when using the publish option, to publish data without storing it.

fileData

Indicates that file data may be being stored. This requires additional processing, and so is optional.

If fileData is true but there is no file data, no error is raised.

May be overridden by the data parameter.

data

Data to store. This can be set in the config, but is more likely to be passed as the data property of the data request parameter. If the form has an upload, you cannot store data (the upload produces data).

This can be any JSON object or array.

To store files (which is what upload does), an array of file specifications is required. Each file specification has the following properties:

node

Node at which the file is stored.

storage_key The file storage key.
size Size of the file, in bytes.
extension Extension for the file.
name Name for the file, including extension. This is used when formatting links and as a suggested download name.
local_reference Node local reference, relative to the storage location. Nodes will be stored at this reference relative to the data storage node.
hash An optional SHA-256 hash of the file content, used to verify content. If present, then it must be correct.

Typically files would be passed in as nodes, and then details extracted as before these are stored. Because the files are copied to a new storage location, the node properties will be changed.

publish

Indicates that the status and data should be published. 

The status is the status passed to Set or previously set on the worker. If the status has a / in it, only the portion before the / is passed.

The data is the data passed to Set, or null.

If publish is set to true, the data is published using a topic of the eventType passed to Set or null. If the event type has a / in it, only the portion before the / is passed.

If publish is set to a truthy value that is not true (i.e. a string), that is used as the topic of the publication.

Publication takes place after changes to the worker, and runs asynchronously.

permit

A list of property names that may be passed in the data parameter. If not set, all are permitted. Can only be set as a configuration property.

Set to exactly false to disallow any properties other than "action".

redirect

A URL to which the user should be redirected after completing the form (unless a linked step changes this). Defaults to returning to the worker.

Passed as a request parameter, not in the "data" request parameter.

remote

Config property only. Set to true to allow the set to be called from a remote partner. If this is false, the set operation will reject incoming calls with a channel parameter set.

Can also be set to a partner role, or an array of partner roles, to permit calls from just those partners. For example "permit":"owner" would permit calls through the owner channel, but not through a different channel.

removeRequest

If set to true, resets the request attribute to a dummy request, to prevent parameters to this set call being passed to the next step.

Call supports runtime placeholders.

Request parameters

When show is false, the following request parameters are used.

data

Data JSON, used to override the config JSON. This can override or set the following properties:

  • message
  • status
  • createEvent
  • eventType
  • eventDescription
  • active
  • actionRequired
  • dataReference
  • fileData
  • data
channel When called remotely, the node version reference of the channel node that called it.
action The action parameter.
show The show parameter.

Examples

Example 1 - Set a status

If the user clicks on Open, then set the status to open. Allow them to enter a message if they wish.

{
"title": "Open",
"content": "Confirm you want to open this item.",
"showMessage": true,
"status": "open",
"createEvent": true,
"eventType": "open",
"button": "Open"
}

Example 2 - Choose

Let the user choose between two options. Use a confirmation to make sure they don't make a choice accidentally.

Subsequent steps would then perform different actions.

{
"title": "Ethics",
"content": "Choose between good and evil.",
"confirmation": true,
"confirmationContent": "I understand that this may impact my moral standing",
"button": [
{
"value": "good",
"caption": "Good",
"class": "success"
},
{
"value": "evil",
"caption": "Evil",
"class": "danger"
}
]
}

A Cancel button will automatically be generated.

Example 3 - Upload a profile photo

{
"title": "Profile photo",
"content": "Please upload a profile photo",
"showUpload": true,
"dataReference": "profile_photo"
}

Example 4 - Receive form data from a channel

Assuming we wanted to store the data as an order form, and log it as an event, something like this would suffice. The permit property means that the caller can only set data, and cannot do other things (like change where the data is set or use a different status).

{
"show": false,
"dataReference": "order_form",
"createEvent": true,
"eventType": "order_received",
"permit": ["data"],
"remote": true
}

Member Type List

Tab/SequenceWeightMember Type
Basic/
0
Basic/
0
Basic/description
0
Basic/tagList
0
Config/
0
Flow rules/flowRules
0

Set Tags

Tag List