With Unified Service Desk (USD) for Microsoft Dynamics CRM, I get one question more often than any other. I have “xyz” happening because my window navigation rule isn’t loading or isn’t behaving as expected, why?
In an attempt to help, in this post I will try to cover the theory connected with window navigation rules. You will, of course, find detailed technical information on the Microsoft website. Here I will try to give a different slant on the information. I will cover each aspect and give tips / ideas on how these might be used. But PLEASE PLEASE also refer to the technical documentation here ….
https://msdn.microsoft.com/en-us/library/dn864949.aspx
This post maybe long but hopefully also informative. J Because I get lots of questions on navigation rules I am going to make this post as detailed as possible.
What is a window navigation rule?
Whenever a window is loaded within USD window navigation occurs, in many situations window navigation rules can be used to trap this event and govern what will happen next. For example, when clicking on an account in a search screen you might want to start a new session or when selecting an account from a incident form open the account in a tab within the existing session.
But window navigation rules aren’t just about loading tabs! They can be used to react to results being returned from searches or even CTI events. But more on those later.
In my introduction I stated that “in many situations” window navigation rules can be used to trap the loading of windows. I phrased it like this as there is an action / approach that can be used when you don’t want to evaluate the navigations rules. That being the “navigate” action on any hosted control. Having an exception to the rule is often handy!
Whenever a window load event happens it triggers the navigation rules to be evaluated. All of the rules are evaluated in order. When a rule is found that matches the criteria for the current event that rule is “fired”. And evaluation of further rules stops. Meaning the first matching rule is used and no others. This concept means that in many situations the order of navigation rules can be VERY significant. Getting the order wrong is a common source of confusion.
I guess considering default behaviour at this point is worthwhile. Say a navigation event occurs and you have no window navigation rules that match that situation, the default behaviour then occurs. Often this is exactly what you want but it can be confusing when tabs don’t load as expected. The default behaviour in a session is to load the new window in the current tab, often this isn’t what is required as that would overwrite the currently selected record!
Let’s look at each field on the navigation rule in turn. And I will try to explain a few things to consider along the way.
| Field | Comments |
| Name | This is simply a text description of the rule. You can call your rules whatever you like. But I suggest you try to keep the name meaningful and unique. I like to stick to a naming convention something like “<<Entity/Item>> from <<Hosted Control>>”.
So I would have things like “Account from Search” or “Account from Incident”. I also often have things like “Account from a session”, when my “from” field might be blank. (More on that later!) |
| Order | I can’t stress enough how important the order field is! You will hopefully see many comments about it in this post. Keep in mind that the rules are always all evaluated IN ORDER and this evaluation stops when the FIRST suitable rule is found. |
| From | The from field can contain the name of the hosted control (tab) that triggered the window navigation. For example, if the from field is set to “Search” you might want a rule that creates a new session. I commonly leave the from field blank! Say whenever something happens you always want to load an entity in the same way. Then simply leave the “from” blank. This concept helps reduce the number of navigation rules that need to be created.
Think about order here! You might decide that when an account is clicked on a search tab you want it to create a new session. But when clicked anywhere else to load in a tab. (Route Window.) To achieve this, you would have one rule with a low order, say 10, that has the “from” set to “Search”. Then a second rule with a higher order, say 20, and the “from” field left blank. Another tip on the “from” field is that it doesn’t need to be a visible. You may, for example, have a “Popup” action from a hidden hosted control. (Often that hosted control is you global manager.) If the from field contains the name of your CTI hosted control then some “special|” logic kicks in that is specific to handling CTI events. I will mention this special type of route again later! |
| Entity | This field will contain the schema name of the CRM entity being loaded. If applicable! I say this as you might not be loading s CRM entity. (USD is about more than “just” CRM entities.) In some situations, this field will be blank and maybe the url populated instead. (More on url later!)
One thing that can confuse on the entity field is that the options of this field are not populated by default. You kinda expect all of the existing system and custom CRM entities to exist. But they don’t. The first time you refer to any entity it will need to be added. (Not forgetting it is the schema name that is added not the display name!) |
| URL | URL, sometimes you will be loading pages that aren’t CRM entities. (Shock!) In those circumstances enter the url of the page being loaded. Say you wanted to load the BBC site in a tab. You’d enter http://www.bbc.co.uk, keep in mind that relative urls can be entered. Which is useful when working with a url that may contain a GUID or other fields as parameters.”*”, a special option for url exists that can apply to ALL windows being opened. Both CRM pages and standard web pages. Entering * in the url becomes your anything else rule. I often have a navigation rule called “ANYTHING ELSE from xyz” with the url set to *. Say you want to load incidents and opportunities from an account in a new tab. But you’d like to prevent any other tabs from loading. This is when a “*” url can be used in conjunction with a “none” action. Obviously with an appropriate order to the rule, did I mention that the order of rules was important??? |
| Route Type | There are only two “main” options for route type “in place” and “Popup“. Simple, right? You’d have thought so but I get so many questions that revolve around route type. To understand this field, you should always consider what happens in internet explorer outside of USD.
For example, consider a sub grid on a form and what happens in the browser. If I am viewing an account and I click on a case in the recently viewed cases sub grid the case will load in the current browser tab. If I wanted to return to the account I would press the back button. This is an example of an in place route. Now consider, back on the account form if I press the “+” on the recent cases sub grid I will create a new case. But the new case form will open in a new window. This is an example of a popup route. Quite simple really! If a new window opens it is a popup otherwise it is an in place route. Commonly you will want the popup and in place routes to do the same thing. I commonly create two naviugation rules with the same order but different route types when this happens. In my example above of a sub grid, creating a new case or opening an existing case could then both be opened as tabs in the existing session. But you might have examples when the popup should create a new session and the in place route should open in the current session. So they won’t always be the same. If you are struggling with route type, don’t stress. If you have a popup navigation rule simple change to in place to see what happens! Also see my comments later on how to debug navigation rules. Two other options exist, On Load and Menu Chosen. On Load, the on load route type is triggered as a result of a search. When a record is loaded as a result of a search this route happens allowing you to decide what to do with the newly loaded record. Menu Chosen, the idea of menu chosen is to decide how tabs are loaded when selected from the navigation bar. I typically supress this navigation so I have to be honest and say I have never actually used this route type! Also when I came to test it I couldn’t get it to work. So I will skip trying to explain it here. Sorry! |
| Destination | Two options exist. Tab and Entity Search.
Tab, this will be your most commonly selected option as more often than not you will want to show the “thing” being loaded in a tab. A tab could be a hosted control in the MainPanel, as you’d expect. But the hosted control could have a display group of FloatingPanel making it appear to be a popup. (But it is still a tab.) Entity Search, rather than opening the selected record you may wish to conduct a search. The results of which may in turn trigger a different navigation rule to fire. |
| Action | Action, several options exist including None, Route Window, Create Session. Create Session, some confuse often exists with this action! The option is always present but the create session action should only be selected if the route type is popup. As the name suggests rather than adding a tab to the current session a new session is created if this action is selected. Show Outside, A useful action but you need to be aware of its limitations / features! Show outside will cause the window to popup in an Internet explorer window outside of USD. When you select this action leave the target and show tab fields blank. (If you don’t you’ll get a blank tab opening in USD!) It is important to consider what show outside implies, as once this action has been called USD can play no further part in any interactions with the window that has been opened. Although it will update the calling window. Say you open a contact tab directly from the primary contact lookup field on an account. Saving the contact in the window opened outside of USD will still update the parent window, so the primary contact field will be correctly populated. Route Window, this action is very commonly used. When you attempt to open a tab from within a session use the route window action to open the entity in a new tab in the existing session. If you are using a hosted control with multiple pages set to yes a new page will be added to that tab if already open. Or if you aren’t using multiple pages and the destination tab is already the current contents will be overwritten. None, the simplest action is “none”. This does what it says on the tin. Nothing! This is more useful than you might think. Firstly, I often use this option to restrict access to certain entities. When using CRM in a contact centre I have often seen advantages in limiting the number of tabs the operator can load. Sometimes less is more! Alternatively, I have had the navigation option to none to prevent the tab loading but then added actions to the window navigation rule to do something slightly different. (In one example I triggered a popup action from an in place route with this concept!) In Place and Default, neither of these are mentioned in the Microsoft technical notes! And to be honest I have never actually used them. The reason being that in place is effectively the default behaviour that happens when no navigation rule is present. So I have never felt the need to use these. But if I do find a useful example I will update this post! |
| Target Tab | Assuming your destination is a tab that tab will be entered here. Simply enter the name of the hosted control that will become the container for the tab which is loading.
Note: This field only shows if the destination field is set to Tab. |
| Show Tab | The show tab is used to decide which tab will get focus after the navigation rule has run. Very often I set the show tab to be the same as the target tab. However, in very rare circumstances it has been useful to focus on a tab other than the one being loaded.
Note: This field only shows if the destination field is set to Tab. |
| Entity Search | If the navigation rule is to trigger a search rather than open a tab the name of the search is entered here.
Note: This field only shows if the destination field is set to Entity Search. |
| Hide Command Bar | More often than not I leave this option at “no”, the default. The ribbon bar contains options like “save”, “Assign” and “Share”. So typically you will show this. However, it would be possible to enter “yes” here to hide the ribbon bar. An approach that might be useful if you create a USD navigation toolbar that will become a replacement for the out of the box ribbon. |
| Hide Ribbon Bar | Very similar concept to the hide command bar option, expect this one will hide the blue ribbon bar. I routinely set this option to yes when opening tabs within a session. As it is often desirable tom restrict the navigation in this way. |
| Condition | The idea here is that you can add a condition to the window navigation rule just as you can with actions etc. I have used it to only open something in the destination tab if currently unused.
I have found some “limitations” with this condition. Actually limitation might not be the right word! You need to think carefully about the timing of the navigation rule execution. The rule is fired before the tab is loaded so you haven’t yet got the replacement data parameters available for the record being loaded. This has caught me out in the past! But if you think about it makes complete sense. |
Adding Actions to Navigation Rules
By using the ribbon navigation, you can add actions to window navigation rules. Keep this in mind as it is often very useful to fire one or even several actions as sessions or tabs start. For example, I commonly add actions calls that use the “SetUserCanClose” action. Allowing me to decide if / when users can close tabs.
Another common use is to start a specific agent script by calling a GotoTask action from you agent scripting hosted control.
Navigation and CTI events
In this post I don’t intend on covering the logic of CTI events in great detail. Although I have blogged about them before so you can refer to that post. What is important to understand though is that there is some “special” additional logic that can be applied to CTI events by using window navigation rules. In essence what happens is yo0u get some additional fields / logic when the from field is set to your CTI hosted control. These fields let you govern what should happen if one, multiple or no match is found for the results of the CTI event. For example: If you find only one contact with a mobile number that matches the calling number that you could automatically create a session containing that contact. (And maybe also trigger some actions to pre-create a phone call record.)
Related Posts
In the past I have published multiple posts related to navigation rules giving examples of many specific circumstances. A few of them I hope you’ll find useful are listed here,
How to open multiple tabs for same entity.
How to create a session from an “in place” route!
How to open a session from a session.
Some example of navigation rules I commonly use.
I hope this post has been comprehensive and given you all of the details you’ll require connected with navigation rules. If anyone can think of anything significant I have missed please comment below and I will try to add.
J
NEIL PARKHURST 
Leave a comment