I was recently involved in my first USD project with USD 2.0 and Dynamics CRM 2015.
At first it was really slow going as we tried to figure out how things worked. The MSDN documentation was at times confusing and a lot of the blogs we found out there were more aimed at the old CCA framework and the methods are no longer always appropriate.
I decided I would write a blog series on the lessons we learned and one some of the basics that might help others get things going a bit quicker.
First a few of my own explanations on the core entities in CRM that USD used to make the magic happen.
- Hosted Controls - It's probably easiest to view a hosted control as a class or module within an application. In this case the application is USD and a hosted control is a class. Just as a class can inherit another class or interface, so can hosted controls. When created, a hosted control will automatically create the UII Events and UII actions that it can "implement".
- UII Actions - The naming of UII actions and action calls is probably what confused us the most, especially when explaining things to each other or discussing how we should solution something. If it were up to me, I would rename these to "Hosted Control Functions". Just like a class can have public functions that can be called with parameters, hosted controls have UII Actions. As mentioned, certain hosted control types will auto create some UII Actions in CRM that can then be handled by the hosted control. You can also create your own custom UII actions in USD that will then need to be handled in your hosted control's code/assembly.
- Action Calls - Action calls are now simply calls to the above uii actions/hosted control functions. In the action call you specify the parameters that you want to pass to the function. You can obviously have multiple action calls, calling the same uii action with different parameters in each. The action call can also be used y multiple flows in USD These action calls are what we need to attach to an event or windows navigation rules to make something happen in USD. You never try call a UII action directly, it is always done using an action call.
- UII Events - These again I would rename to "Hosted Control Events". These are things that are occur relating to the hosted control, for example, the session tabs hosted control has events for "Close Session" or "Session Close Requested". These events can then have multiple action calls attached to them to perform actions in USD that should occur when this event is fired. One of the important patterns we needed to understand was how we get one hosted control to call a UII action from another hosted control. If Hosted Control A needed something to trigger something to happen in hosted control 2 via code, the following is the best pattern to make this happen.
- Trigger an event from code in hosted control 1
- Create an action call for hosted control 2 to call the uii action/function in hosted control 2.
- Associate the action call to the event created above.
- What will then happen is whenever the event in 1 is fired, the action call for hosted control 2 will be called. The advantage of doing things this way is that hosted control 1 has no knowledge of hosted control 2 and its functions, it merely triggers its own event, the rest happens in configuration inside CRM, and can be changed accordingly. (Note: you are able to pass parameters from the event to the action call if required)
- Windows Navigation Rules - Windows navigation rules are extremely important! You can have everything 100% correctly setup above, but without an appropriate windows navigation rule, nothing will ever happen. The windows navigation rules tells USD what it should do when a action call requires it to show a hosted control page, normally a CRM entity. If for example have an action call that opens the CRM page for the contact associated to a case, I would need to define a windows navigation rule to define how that page should be shown. Should USD pop the page in the current session, create a new session, or just pop the page outside of the context of USD completely. The windows navigation rule defines this. If you have no windows navigation rule that matches the behaviour, USD will simply cancel the behavior and do nothing. A trick we were shown by one of the USD product group guys was to setup a "catch all" windows navigation rule with an order greater than all the other rules, and set it up to "show outside" or show the page outside of USD. Then once if you have any behaviour that doesn't match another rule, it will pop the record outside USD and you will immediately know you need a windows navigation rule, not that something else has gone wrong somewhere in your configuration. This can save you A LOT of time trying to debug issues.
I've tried to depict the flow of how things should occur in USD and provide some code snippets and "gotchas" that we came across.