[00:00] In this lesson, we're going to take a look at how the Message Handler feature works. The Message Handlers are unique in that they allow you to write a script, or a Message Handler, on either the Client, or the Gateway. You can then invoke that script from either another project, or even another Gateway entirely. This allows you to do something simple, such as sending messages between two different projects, or even two different Gateways. Or something more complex, such as executing code that modifies your project or Gateway in some way. To get to these Message Handlers, you need to go to the project browser, and look under the Scripting section for either the Client Event Scripts, or the Gateway Event Scripts. Where the script will execute will depend on where you put it. Let's first take a look at Client Message Handlers by going under the Client Event Scripts and going down to the Message Handlers Section. To add a new Message Handler, you'll want to click the button with the little plus sign, which will bring up the Message Handler Settings. I can then give my Message Handler a name, and decide if I want it to use shared, dedicated, or EDT threading. I can then write my Message Handler in the script area here. All Message Handlers will have a payload object, which is a dictionary of the objects that are passed into this Message Handler. You can reference objects in the payload, using the syntax payload, and the name of the dictionary key within brackets. I can then use that payload argument in my script in any way that I would like, such as printing it out. Once I have my script written here, I can then call it using one of any three functions. The three functions are all located in the system.utils block, and they are SendMessage, SendRequest, and SendRequestAsync. You can learn more about each of those functions by going to the appendix section of the user manual. Now the SendMessage script will simply call a particular Message Handler. The SendRequest and SendRequestAsync functions, however, will actually wait for a return value from the Message Handler. So in your Message Handler script it's important to put a return value at the end. Now because this is a Client Message Handler this script will be run on all open instances of the Client. However, the three scripting functions do allow you to filter which Clients the Message Handler will run on. By specifying a username, a role, or even a Client session ID. Now Gateway Message Handlers differ from Client Message Handlers. Let's go take a look at how they differ. Here in my Gateway Event Scripts Message Handlers I can add a Message Handler and right off the bat you see it looks a little bit different. Because running a script on the Gateway can have potentially harmful consequences, we've added in a role-based security to the Gateway Event Message Handlers. What these allow you to do is specify a Security Zone and a Role that the user must have if they want to call this Message Handler. So even if I were to have permission to get into a project and push a button that had a script on it that called the Message Handler, I might not necessarily have permissions to call that Message Handler. So it would give me an error instead. This allows you to lock down who is running scripts on your Gateway and where they're running them from. Now other than the security, the only other difference, of course, is that these scripts are run on the Gateway and won't actually run on any of the projects on that Gateway including this one. Now Message Handlers can get a bit confusing, so let's take a look at an example that I have already set up. Now my project here called Test, I have a window with a TextArea component, and a Button component. The Button component has a simple script on it. It's callingsystem.util.sendMessage This means that this button is going to invoke a Message Handler somewhere. If we take a look at my first argument, MessageHandlerTest, that's the name of the project that the Message Handler resides on. My second argument is then TestMessage. This is the name of the Message Handler that I'm going to invoke. Finally the last argument is the payload. It only has one key, called Message, and its value is whatever text is in the TextArea component. I can then switch over and instead of this project, take a look at my MessageHandlerTest project. If I go into the Client Event Scripts and go to the Message Handlers, you'll see my TestMessage Message Handler and inside it, a simple script. This script is calling system.gui.messageBox which will make a message box pop up on the Client. First part of the function is the message part of the message box. Since I'm calling my payload here, this means that whatever I have in the TextArea is going to appear as the message in my message box. The last argument is the title of the message, which simply says "Message from the Boss." Now if I minimize this you'll notice that I already have some Clients opened up. This larger one is the Test project, which has the TextArea and the Button in it. The two smaller Clients are then both my MessageHandlerTest project. These are the projects that have the Message Handler on them. You'll notice I've already typed in a simple message into my TextArea, making sure my employees know to do their work. I can then click on the button, which invokes my Message Handler, and you'll see that a message box has popped up on both of my MessageHandlerTest Clients. As you can see, Message Handlers allow you to easily execute scripts between different projects and even different Gateways.