How to use the special actions, ExecuteOnTimeout, ExecuteOnDataAvailable, ExecuteOnExpressionTrue
In Unified Service Desk, Action Calls execute Actions, which are pieces of code implemented by hosted controls. When creating hosted controls, you would implement the code you would want to run when someone calls your action. By piecing together actions from various controls, USD delivers a loosely coupled system of independent components (hosted controls) that can interact with each other without having design time knowledge of each other.
There are a few actions that exist in USD that, while added to any hosted control, are not actually implemented by the hosted control. These actions are intercepted by the Global Manager hosted control and executed without ever touching the target hosted control. On the other hand, these can be defined against any hosted control you wish for the purposes of attaching them to related controls. This article will describe each of these 3 special actions and what they do.
ExecuteOnTimeout
This action provides a method of creating a timer. After the timer expires, the subactions assigned to the Action Call will execute. This action takes a single parameter, "milliseconds" that indicates the number of milliseconds the timer should wait before executing it's actions. If this action is defined against a control that is session based, it will automatically be cancelled if that session is closed.
Suppose I add the ExecuteOnTimeout action to my Contact hosted control. I could setup the following ExecuteOnTimeout Action Call and add it to the BrowserDocumentComplete event for Contact hosted control.
Hosted Control:
Contact
Action:
ExecuteOnTimeout
Data:
milliseconds=5000
I would then save the Action Call, then in the Sub Action Call list, I would add an action call. For the purposes of an example, suppose I just show a message…
Hosted Control:
CRM Global Manager
Action:
DisplayMessage
Data:
text=hello world
Now, 5 seconds after the Contact page is loaded, the user will see a dialog message indicating, "hello world".
Note that which control you add the ExecuteOnTimeout action is not particularly relevant and more for the admin's convenience and organization. It will behave the same regardless. Most choose to add it to the CRM Global Manager but as shown in the example above, it can just as easily be added to the Contact hosted control. It also means that no USD Hosted Control should implement this action as that would mean that could never get called. The system would implement this version before ever reaching the control's implementation.
ExecuteOnDataAvailable
Similar to ExecuteOnTimeout, the ExecuteOnDataAvailable action can be added to any hosted control. This action will execute it's subactions when all the replacement parameters in it's parameter list contain values. The action doesn't discriminate in terms what value the replacement parameter contains, just that it must have a value. If this action is defined against a control that is session based, it will automatically be cancelled if that session is closed.
Suppose I want to display the contacts phone number in a dialog as soon as a contact is loaded within a session. One way to do this might be to add an Action Call to the Contact's BrowserDocumentComplete event, but suppose a contact could be loaded with an EntitySearch as well. In this case, you'd need to add the action call to both places. As you might imagine, this can get even more complicated very quickly. Instead we can use the ExecuteOnDataAvailable and display the message no matter how the contact got loaded.
Add the ExecuteOnDataAvailable to the CRM Global Manager hosted control. Then add a new Action Call to the CRM Global Manager's SessionNew event so that it runs at the beginning of the session creation process.
Hosted Control:
CRM Global Manager
Action:
ExecuteOnDataAvailable
Data:
[[contact.mobilephone]]
In the data field, you can provide a list of replacement parameters. It will wait until all replacement parameters have a value at the same time before executing the subactions.
Save the Action and go to sub actions. Create a new action call.
Hosted Control:
CRM Global Manager
Action:
DisplayMessage
Data:
text=[[contact.mobilephone]]
Save these and run it. Open a session and click around until contact information is loaded either by an EntitySearch or a contact being loaded in the Contact tab. Note that we are waiting for the mobilephone so if your contact doesn't have a mobilephone, the trigger will not be tripped. Once you load a contact with a mobilephone, the subactions will run and the message displayed.
ExecuteOnExpressionTrue
ExecuteOnExpressionTrue is a more advanced version of ExecuteOnDataAvailable. It has a bit more overhead in that it evaluates its data parameter as a javascript expression so use it only when the other two aren't a good fit for what you require. This action evaluates it's data parameter and execute's its subactions as soon as the data parameter evaluates to true. If the script throws an exception or returns false, the action will continue to wait. Keep in mind that this script will be executed every time data parameters are changed in the same so it is important to keep your script short and fast to ensure a performant application. If this action is defined against a control that is session based, it will automatically be cancelled if that session is closed.
Let's say we want to display a message to the user whenever a contact is loaded that is marked DoNotPhone to remind them to not try and call. Add ExecuteOnExpressionTrue to
the CRM Global Manager hosted control (or any one of your choice). Then add a new Action Call to the CRM Global Manager's SessionoNew event so that it runs at the beginning of the session creation process.
Hosted Control:
CRM Global Manager
Action:
ExecuteOnExpressionTrue
Data:
"[[contact.donotphone]$+]" == "true"
Now to display the user message, let's add a subaction to our newly created Action Call.
Hosted Control:
CRM Global Manager
Action:
DisplayMessage
Data:
text=Do not call this customer!
Now when you run USD and load up a session. When you set the donotphone flag and save the record or you load a contact with the flag already set, a message will display to the user. Note that once the message has been displayed to the user for that session, it will not display again for that session.
These 3 special actions are documented in the Global Manager documentation: