USD – Window Navigation Rules

In my series of posts about learning Unified Service Desk (USD), I thought it might be appropriate to talk about window navigation rules ….

Window navigation rules are used to govern how tabs will load, for example, when you click on a contact record USD needs to know if a new session should be started or if the contact details should be loaded in a fresh tab.

There are a multitude of settings possible with window navigation rules, including some “special” ones connected with CTI integration. I don’t plan to cover CTI here that will be the subject of a future post.

In this post I am purely focusing on the logic for window navigation rules, meaning I am assuming you understand the concepts behind the hosted controls and actions that might be needed to trigger the rules.

Rather than simply quoting from the Microsoft Technical documentation, I will explain some examples of combinations I commonly use. I’m not going to cover every combination possible just give you a few examples that I think might be useful. But if you’d like to refer to the full documentation the link is;

Options I will cover include;

  1. Creating a new session.
  2. Loading a new tab in a session.
  3. Triggering a second tab to load from a search.

Window Navigation Rule to start a new session

Say you have a list of accounts (or anything) and you wish to load a new session when an account is selected. You’ll need a window navigation rule to instruct the USD to load a session containing the account which has just been clicked.

An example navigation rule to start a new session is shown below. Things to note include;

  • “From”, the hosted control in my example is search. As I have a tab called search which includes a view of accounts.
  • “Entity”, obviously in this example the entity I have selected is account. This concept is useful, as in my search tab might display accounts, contacts or leads. (or any entity) Meaning this particular rule is only triggered when an account is selected from my search tab.
  • “Route Type”, this time it is popup. As the account would popup from the search results.
  • “Destination”, as is typical my destination is a tab.
  • “Action”, Create session as I want to create a new session. (Don’t forget you’ll need to use “Session Lines” to define the session name and optionally an session overview.
  • “Target and show Tabs”, both are set to the Account hosted control.
  • “Hide Navigation Bar”, it is quite common that I set the hide navigation bar to yes.

Window Navigation Rule to load a tab within a session

A common use of navigation rules is to load a tab from within a session. Say I have an account session open and click on a contact record within the account tab. This might be the primary contact or one in a sub grid of associated contacts. Having clicked by default this contact would be loaded in the current tab. A much better approach would be to load a new tab within the current session. Below is an example of how to achieve this.

Some things to note include;

  • “From”, this time my “from” tab is account.
  • “Entity”, this time contact. You can quickly see that I might have several entities on the account tab that could be selected. You will need to define a rule for each.
  • “Route Type”, “In place”, meaning the loading of a CRM form.
  • “Action”, route window as I want to load a new tab. (Rather than a session.)
  • “Destination”, tab as I want to load a tab.
  • “Target and show Tabs”, both are set to the Contact hosted control.
  • “Hide Navigation Bar”, it is quite common that I set the hide navigation bar to yes.

Window Navigation Rule to load a tab from a search

This one might be a little more complicated!

In this example, I show how to load a tab as a result of doing a search. Consider this ….. Whenever an account is loaded I trigger a search to pull details about the primary contact. A window navigation rule can be triggered when that search loads the data parameters for the contact. Then we can load a second tab for the primary contact.

Fields to notice include;

  • “From Search”, instead of triggering the rule from a tab this time it is triggered from the search.
  • “Entity”, this is the entity that will be returned in the search results.
  • “Route Type”, OnLoad as the rule is triggered when the contact data is loaded into the data parameters.
  • “Destination”, this is tab as I intend to load a tab.
  • “Action”, route window as I want to load the tab within the current session.
  • “Field”, this field isn’t mentioned in the Microsoft documentation. Fun! J But I found that I needed to enter the ID of the entity returned. I worked out the exact field name by looking in the debugger at the parameters returned by my search.
  • “Target Tab”, in this case the tab (hosted control) I am using is “Contact”.
  • “Show Tab”, normally I would set the show tab to be the same as the target tab! But here I want the account tab to keep focus and just load the primary contact in a separate tab.

17 thoughts on “USD – Window Navigation Rules

  1. Pingback: Learning Unified Service Desk | Microsoft Dynamics CRM and Unified Service Desk

  2. Neil have you found a way to handle new window popups from a CRMPage hosted control, with an Action of ShowOutside? I didn’t want to have a new HC tab for child record creation but instead throw it in IE outside of USD: as native CRM UI would. Tried InPlace and Popup Route Type, specifying the Entity, and it doesn’t work wih either combination. Instead, it still presents the new record form of the child record In Place of the parent record.

    The reason I choose the behaviour is to prevent the hideous ‘Attempting to close the web page’ dialog when Save & Close a child entity record.



    • What you describe should work, I don’t routinely use it but I am sure I’ve seen it work.

      I would expect the route to be “In Place” but try “pop up” if that fails!

      Then instead of the action being route window you would enter show outside. I think as you have described.

      If it isn’t working I would try three things,

      1. Swap the action to Route window, just to prove your navigation rule is firing. Doing so should give you the entity in a new tab, if it doesn’t you know the problem isn’t caused by the action of show outside.
      2. Look in debugger to see if your rule is firing and see if any errors are happening.
      3. Also, is your hosted control global? This is a guess but when you show outside the hosted control is not part of the session, if steps 1 & 2 fail to give you an answer try opening the entity in a global hosted control.

      Hopefully these suggestions will help you pin down your problem.


    • Hi Rob

      ShowOutside works but your question got me thinking about the implications for agent scripts, toolbars etc.

      So I did a test and documented my results in this post.

      Hopefully this gives you all the detail you need regarding Show Outside.

      if I have missed anything, please ask.

      Tip: Start off with a Route Window. So a “normal” navigation rule. Then change it to Show Outside. You then know that any problems you see do or don’t relate to Show Outside.


  3. Morning Neil and thank you so much for the nocturnal efforts on my problem!
    I had tried the suggested configurations previously and they didn’t work.
    May I check your trigger context for your successfully popped Case. Did you use an Agent Script Answer as the trigger?

    My situation is:
    – Custom entity form, presenting as a HC
    – One WNR for this HC to Popup Route Window, From itself Target itself (for situations of creating this ‘parent’ record)
    – Once saved, selecting on a sub-grid of child records to Add (+)
    – Wanting the child record to Show Outside.

    If I configure the WNR From parent HC Target child HC, with either In Place or Popup (Route Window or Show Outside) I cannot get the WNR to even fire in the debugger. Instead I get In Place routing to the child record. Incidentally, this overrides default CRM UI behaviour for this entity model, where Add on the sub-grid will popup in a new IE window.

    I suspect your proving of the concept was using the ASA as a trigger, rather than a sub-grid Add New. I would be happy to hear that I’ve got that wrong!



    • In my example I tested loading incidents from a sub grid. Which I think should mirror your requirement.

      I have one thought …. Check in your debugger, is your BrowserDocumentComplete event firing just once on the tab being loaded. (You might find it doesn’t fire or fires twice!)

      If it doesn’t fire have a look at your replacement parameters. Do they look as expected?

      This might seem like a strange check but I have recently seen an issue with the latest version of USD in this area. One symptom I got was after the BrowserDocumentComplete didn’t fire my navigation rules did some strange things.

      This might not be your problem but worth ruling out.

      Your problem doesn’t sound related to show outside. Something else is wrong that means the navigation rule isn’t firing. It could be a “simple” bug in your rules. But unfortunately very hard for me to see reason why!


      • Thanks for the reply Neil. After using Agent Script Answer to pop up outside, I still encountered the ‘the webpage is closing the window’ confirmation dialog that I am trying to avoid In Place: so have moved away from the design. You are right that the WNR wasn’t even firing in the debugger so may be the USD version as you say.

        For reference I have instead used the following design to avoid the webpage closing dialog for child records:
        – one Hosted Control to show all records
        – one WNR for each entity (parent and child from sub-grids) that I want to display the form for. Config is Popup/Route Window
        – added the N:1 lookup to the parent record to each of the child record forms.
        – toolbar on the one HC offering Back and Save action calls
        – hid the Command Bar of the child records to prevent the Save and Close


      • Hi Rod,

        I have twice faced the problem you describe on closing windows. In my examples it has been when marking a phone call as complete.

        Both slightly different ways of achieving the result you have managed with a toolbar. Your idea becomes a third approach I might consider in the future. 🙂

        My two approaches have been;

        1. On the CRM form. We created a custom mark as complete button that closed the phone call and didn’t close the form. Then replaced the out of the box button with the custom button.

        2. In USD, on the close of a session the phone call was automatically saved and then a CloseActivity action marked the phone call as complete. Meaning the users didn’t need the mark as complete button.

        All of the approaches have pros / cons. I am not suggesting any will be perfect in all situations!

        Glad you have found something that works.



  4. Pingback: USD – Window Navigation Rules Theory | Microsoft Dynamics CRM and Unified Service Desk

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

  6. Hi Neil,

    I have small have written “As the account would popup from the search results.” But when i tried from search if we click on a record there will not be any pop up. the record will open on same window. Can you please let me know where my understanding is wrong.



    • Hi Arindam

      Thanks for reading and commenting on my blog. I will try to explain route type in a little more detail …..

      You are right that in USD the default behaviour will be to open a popup in the current window. This doesn’t look like a popup!

      But initially forget about USD and consider the default browser behaviour. If we load an account from a list in IE or Chrome. (Or any browser.) A new window would open. So a popup. This is the behaviour being described when we say popup.

      The window navigation rule is saying, if in the browser you get a route type of popup what should we do?

      For a popup, depending on its souse we might want to create a session or open a new tab. Which means the navigation rule is needed to change the default behaviour of opening in the current tab to do something different.

      I hope this helps.



  7. Hi Sir,

    Good Morning !

    I had created a window navigation to open my phonecall activity records into another tab from case entity form (Note : My case form opened into the session) which is working fine , when i click on associated/related case’s existing Phonecall record (i.e. It opened that phonecall activity record into a new tab for me). But when i try to create a new Phone call record (from related case i.e. I go to the associated activity view & click on new activity dropdown & chose Phonecall) then it overwrite my case form (What I required is the NEW phonecall activity record should also be open into NEW tab).

    Here is my window navigation rule:

    From : Case session
    entity: phonecall
    Action: RouteWindow
    Targettab: Phonecall
    Showtab: Same as above.

    Do I need to create a separate window navigation rule for this need ?


    • I think you will find opening an existing phonecall will trigger an “In Place” route. You haven’t stated your route type but I am guessing it is “In Place”.

      Opening a new phone call within the social pane doesn’t normally need a navigation rule as it opens within the CRM form. I guess you might be creating a new phone call from an agent script or toolbar button.

      Either way, or if opening another way, creating a new record will typically trigger a “Popup” route. So to solve your problem I think you would create a second navigation rule on case / phonecall. Keep all the details the same on the second rule except have it for a popup route type. (FYI: Typically when I do this the order will be the same on both rules. But not essential!)

      Hopefully my guess here is correct.


  8. Hi Neil, all your aticles are very interesting.

    I don’t know how to implement a window navigation rule to do the follwing scenario.
    I need to simulate an IVR and open more than one entity in USD. The idea is to have two parameters, the telephone number of the caller (cti.telephone1) and an order id (cti.orderid) that the caller “writes” in IVR. The USD has to open the contact related to the telephone numebr and the order in the same session. I have no problem to open the contact but i don’t know how to search the order and open it.

    Thank you for your help !


    • Hi Massimo

      Thanks for reading my blog and sending the message.

      Your problem doesn’t really sound CTI related, as you have said you can open the contact correctly from the CTI event. And you have an order in a replacement parameter.

      Meaning, once your contact tab has loaded, if you have an order number you need to search for it and when found open in a tab.

      This is actually very similar to something I have described in a previous post. In my example I loaded an account and searched for a primary contact and then displayed. I think you could adapt that logic to search for an order instead.

      Try reviewing the post above it will hopefully give you enough information to adapt for your order loading.




Leave a Reply to Neil Parkhurst Cancel reply

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

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

Facebook photo

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

Connecting to %s