ClearSCADA includes a built-in user messaging system—a user can select the Notify User action and send a message to any other logged on user. By default, the message is displayed in a standard message dialog box on the recipient’s client. However, by using the OnMessageReceived function in the global script for a client, you can instruct the client to perform other functions when a message is received. However, as the feature provides no means of directly indicating that the recipient has responded to a message, it should not be used for sending control requests or asking the recipient to perform other system-relation operations.
WARNINGUNEXPECTED LACK OF EQUIPMENT OPERATION
The OnMessageReceived function can only be used in the Global Script for a client. When any user that is logged on via that client receives a message (from another user), ClearSCADA checks to see if the client’s global script contains the OnMessageReceived function. If it does, the OnMessageReceived function is performed and the message is handled in the way defined by the script. If the global script does not contain the OnMessageReceived function, the message is displayed in a standard message dialog box.
A common use for the OnMessageReceived function is to create customized dialog boxes for user messages. These customized dialog boxes are displayed instead of the standard message boxes. However, by using VBScript, it is possible to create more complex procedures for user messages, for example, it is possible to create message boxes that contain user input fields that allow the recipient of a message to send a specific type of response to the sender. This response can then be used to trigger functions on the sender’s client. Keep in mind that any script associated with a user message will run according to the permissions defined for the user receiving the message.
The ability to send notifications to other users becomes dependent on any script that uses the OnMessageReceived function. Before running such script in a 'live' system, thoroughly test the script to verify that it operates as intended. Such testing should include, but is not limited to, ensuring that the script:
- Does enable Notify User messages to be displayed on the intended recipient's ViewX client
- Only performs actions that are appropriate for the system.
WARNINGUNEXPECTED EQUIPMENT OPERATION
|
Syntax |
OnMessageReceived (UserName, Title, Message) |
|
Description |
Instructs ClearSCADA to handle incoming user messages in the manner defined in the client’s global script. |
|
Arguments |
UserName {string} The User Name argument allows ClearSCADA to include the user name of the message sender in the message display.
Title {string} The Title argument allows ClearSCADA to include the message’s title in the message display.
Message {string} The Message argument allows ClearSCADA to include the body of the message in the message display. You have to enter UserName, Title and Message as the actual arguments. ClearSCADA will take the string values for the UserName, Title and Message from the message that is received. |
|
Returns |
Nothing. There is no return value. |
Example: Displaying a User Message in a Customized Dialog Box
In this example, a user named J Thomas sends a message to a user named M Noble. The OnMessageReceived function is used in the global script on M Nobel’s client to instruct ClearSCADA to display the message in a customized dialog box.
On the client that is used by M Noble, the Global Script contains the OnMessageReceived function and defines the settings for the custom dialog box:
- Sub OnMessageReceived( UserName, Title, Message )
- MsgBox "Message from " & UserName & vbCRLF & Message, vbOKOnly, Title
- End Sub
Working on a different client, the user J Thomas uses the Notify User action to send a message to M Noble. J Thomas defines the title and body of the message and then sends it to M Noble.
When the message arrives at M Noble’s client, ClearSCADA detects that the client’s global script contains the OnMessageReceived function and so the message will not be displayed in the standard, default dialog box. Instead, ClearSCADA handles the message in the manner defined in the global script - it takes the UserName (the name of the sender is included with the message automatically), Title, and Message (body) of the incoming message and displays it in a message box that contains 'Message from' and the sender’s User Name on one line and the message body on another line, with an OK button below.
If the OnMessageReceived function had not been present in the client’s global script, the message from J Thomas would have been displayed in the default message dialog box (shown below):
Further Information
Notify User: see Send a Message to a User on another ViewX Client in the ClearSCADA Guide to ViewX and WebX Clients.