Using the User Message Definition Type
The User Message definition type is a special type used in a chain definition to represent a manual task to be performed by an operator. User Message process definitions do not have an editable script source, however, you can set the following user message-specific properties:
| Tab | Field | Description |
|---|---|---|
| User Message Definition | Text | Specify the text that is presented to the user. The field accepts a combination of printable UTF-8 characters. |
| User Message Definition | Notify Method | Select the notification method: Individual Emails - each interaction generates an email.None - no emails are sent.One Email - only one email is sent per user message. |
| Response | Map replies to process statuses (Completed or Error), return codes, and optionally jump to specific steps. | |
| Attachments | Attach files to the user message. Additional information can be saved in attachments, for example reports. | |
| Participants | Users that can interact with the user message. |
Other process definition properties behave like traditional process definitions.
Variables
Variables are used in the text field that will be sent to users requesting interaction.
The following table lists the built-in variables:
| Name | Data Type | Description |
|---|---|---|
| ${description} | String | The description of this process. |
| ${finishtime} | Date | The time when this process finished. |
| ${jobdefinition} | String | The name of this process. |
| ${jobid} | Number | The ID of this process. |
| ${jobname} | String | The name of this process. |
| ${jobowner} | String | The owner of this process. |
| ${processserver} | String | The process server this process is running on. |
| ${queue} | String | The queue the process is running on. |
| ${requestedstarttime} | Date | The requested start time of this process. |
| ${starttime} | Date | The start time of this process. |
Variables can also be used in the Go To Step field, a list can be found in the Scripting Contexts and Implicit Objects topic.
Parameters
Parameters allow you to specify additional information in the user message Text field. You can retrieve data from tables, other process definitions within the chain, for example, for use in the Text field.
Parameters are specified as ${parameters.<parameter_name>}.
Example
Please make sure the ${parameters.reportName} is consistent with the results of the ${parameters.check}. See the attachments.
Response
The Response tab allows you to specify one or more possible reactions to the user message. For example, you use the user message in step 2 to go to the previous step if the data from Step 1 do not add up. In this case, you create two responses as follows:
| Field | Value |
|---|---|
| Name | Accept data |
| Description | Data from Sales and Finance match +/- 0.5% |
| Status | Completed |
| Return Code | 0 |
| Go To Step | Step 3 |
| Field | Value |
| --- | --- |
| Name | Reject data |
| Description | Data from Sales and Finance don't match +/- 0.5% |
| Status | Completed |
| Return Code | 0 |
| Go To Step | Step 1 |
note
The Go To Step functionality only works when the status is Completed, there is already a GoToStep status handler for Completed Goto NextStep on the step, and there is only one process in the step of the user message. This last prerequisite ensures that only one process defines the step to go to.
Attachments
User messages support a number of different attachment types:
URL- a URL to a website or file, for examplehttp://www.redwood.comDocument- A Redwood Server document, for exampledoc:/Redwood/myImage.png<process_spec>:<file_spec>[<options>]
tip
Attachments have a mandatory description field which will be used to identify the files in the user message reply dialog. Using clear descriptions for attachments further streamlines the processing of the user message by the addressees.
Specifying <process_spec>
Job <process_ID>- where<process_ID>is the ID of the process.<step_name>, Job <n>- where<step_name>is the name of the step (not the description) and<n>is the order of the call in the step.parent- the immediate parent of the current user message process; note that in chains, the parent is usually the step. The keyword is used when you submit a user message from within a RedwoodScript process definition, for example.
Specifying <file_spec>
<short_file_name>- the technical file name, such asstdout.log.?type=<type>- where<type>is eitherlogoroutput; will attach all files matching the typelog- log files contain the output of standard error, for example all error messagesoutput- output files contain the output of standard out, for example the report
Specifying <options>
?range=<start>,<end>- specify a range of line numbers, negative numbers are counted backwards (from the end of the file)?search- search for the occurrence of a string in the file, by default, the line with the first occurrence is copied.?options- customize the behavior of searchWildCard- Used with a search string of "*" to specify a wild card searchReverse- Returns the last line in the file matching the search stringIgnoreCase- Performs a case insensitive searchEntireLine- An entire line in the attachment must match the specified stringRangeResult- Returns all lines that match the search string
Example
Job 123:stdout.logStep 2, Job 2:stderr.logparent:GL_Accounts.xlsxGL Quarter Close EMEA, Job 4:stderr.log?range=-15,-1Step 1, Job 3:stderr.log?search="caused by"?options=RangeResult,IgnoreCase
Addressees of the user message will be able to view, delete, and add new attachments to the user message when they reply.
Participants
Specify users/roles that can react upon the user message. Participants are automatically granted the required privileges to reply to the user message. The users/roles will need Edit processes privileges to manage attachments.
Reacting on User Messages
Once a user message has been created, you can navigate to Business > User Messages to react on the user message. The following actions are available:
| Action | Description |
|---|---|
| Notify Assignee | A notification is sent to the user message assignee again |
| Delegate | The user message is delegated to another user; the user will be granted privileges to see and reply to the user message automatically |
| Forward | The user message is forwarded to another user for comment; the user will only be allowed to view the message, if the user is not on the participants list |
| Reply | Select one of the available replies to the user message |
note
Each user message process will have the associated user message listed in the Related Objects field.
On User Message Operation Action
User message process definitions have a special type of script action named On User Message Operation; it is available alongside On Change, Pre-Running, and Post-Running Actions on the Actions tab of the process definition editor. It is used to react to any interaction a user has with the user message such as replying, adding attachments or forwarding.
See Also
usermessage user message