USD – Window Navigation Rules Theory

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 ….

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 opening 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 issues / 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, 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.)

USD – CTI Generic Listener

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.

Show Outside

Preventing window navigation.

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.

11 thoughts on “USD – Window Navigation Rules Theory

  1. Great post !!!!!!!

    Just one query, I want when a user click on convert to case button on email activity (i.e. when a user wish to convert an email into a case) then a case form should be open into a new tab (as currently it just overwrite the email activity page).

    Will this be possible using window navigation rule & how ?

    Just a quick comment can help me to met this requirement.

    Please try to help🙂


    • Yes it is possible. You will simply need a rule that has the from of “email” and entity to be “incident”. You will then need the actoin to be Route Window.

      Without testing I am not 100% confident on route type. But I suspect it woudl be “In place”. So try that first and if not working change to “popup”.

      Tip, if the rule you create seems not to be firing always have a look in the debugger as that can sometimes show the route type you need to create.


  2. Pingback: USD – The Book | Microsoft Dynamics CRM and Unified Service Desk

  3. Hi sir, In this post you mention the importance of ORDER in window navigation rules, I am facing another challenge😦 wherein if i go to my case session then go to the associated open activity related to that case & open one of the activity & click save & case button then the same case is opened into another tab

    When i go to debugger to check the issue then I found that my another window navigation rule which is created to open case from the Recent case grid on the case form to another tab is getting trigger, I suspect that ORDER of my window navigation rule is creating issue here, as when I remove the same then everything is working as desired but the case from the Recent case grid on the case form to another tab is not getting trigger.

    Please help !!!!!!!!!! (as i tried changing the window navigation order but not find a desired result) but only when your broken hand is on a position to work. Thanks🙂


    • Hmmm … hard to say without looking at your navigation rules in some detail! I have had a similar problem, in my case I found a navigation rule that had a blank from field. Due to the order that was being incorrectly triggered regardless of which tab the entity was being loaded from. Try filtering you rules based on entity. Then sort them by the order column. The problem might then stand out.

      Have I read correctly! Are you saying that you are clicking on an activity (e.g. phone call) and a case is being loaded. As that would be quite strange.

      Please double check your rules and then maybe send me a more detailed explanation of exactly what is happening.

      FYI: Hand doing ok! It will be sore for a few weeks and my typing is slow. But no long term damage.🙂


  4. Thanks for your reply. I had mailed you the document where i tried to explain the issue in a simpler way by attaching the required screenshots. Please have a look on this. Thanks !


  5. I’m trying to catch all ‘contact’ entity popups coming from some simple methods in one hosted control…but I need to route to 2 different controls depending on if we’re opening the form for a NEW contact or an EXISTING one (i.e. the urls in are different). I noticed in the debugger the “[[SUBJECTURL]]” parameter passed to the routing rule. Have you had any success referencing this [[SUBJECTURL]] parameter in conditions? Everything I do seems to evaluate to ‘false’ and my rule just doesn’t run.


    • Hi Kyle

      Thanks for reading my blog and asking this great question.

      There are two replacement parameters that contain the URL. [[SUBJECTURL]] and [[URL]].

      I have tried to use them several times to add conditions to window navigation rules to govern what happens next.

      I think this post hints at a possible answer to your problem!

      I suspect the problem with these replacement parameters is a matter of timing. As the content might not be available to you until the rule has already run. Which means by the time you get the URL value the tab is already loading.

      So, in my previous post I found a “hack” around this problem. I was actually also struggling as I wanted to create a session at the same time. So I let my ordinal window navigation rule run but the target tab was to a hidden tab. So it showed nothing to the user. Then I added actions to the window navigation rule.

      If you are trying a route action in your navigation rule you may get away with changing that to “None”. Rather than displaying a hidden tab as I did in my post.

      In your actions on the navigation rule you could use a navigation action to open the tab. (FYI : Using a navigate action would not run further window navigation rules, use a popup action if you want to re-evaluate the rules.)

      You’ll need to be creative with your navigate actions, so that based on the url you open the correct tab (hosted control). I can think of a couple of possible answers to that! It will involve using a scriptlet. (As you will need to look at the url and return “something” to help you decide what to do next.)

      Hopefully this answer has enough detail to point you in the right direction.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s