Sparkle XRM is a framework which is built to allow you to create complex user interface solutions in Microsoft Dynamics CRM using C# mainly and with very little client side configuration or heavy design work.
Sparkle doesn’t just give you the pre-built code framework to make creating your own so much easier, it even comes with samples for you to try. These are seen as samples but they can be full blown applications for you to use as you want within a live production environment if they fit the need for you or your customer.
One of those samples is called ‘Network Visualizations’ which provides a data visualisation for the user that is built on the fly using the Account as the root and the related Activities, Contacts, and Connections it linked to it into nodes. It then provides a tactile interface for you to drag and drop nodes and arrange as you see fit if you wanted to focus on a particular area or if you wanted to group records. It even provides a rotational highlighting of users who own those records.
The challenge with Network Visualizations is that a user would get so excited they think it will use every single connection everywhere, which it doesn’t do as that’s not what it is designed for. Can you imagine being able to see every single connection, every single link? It would be a mess and certainly break almost every data visualisation principle out there. It starts with a basic configuration and allows for custom extensibility both from the configuration side, and of course, the code. This post aims to breakdown the configuration so you can take advantage of it as much as possible.
If you didn’t know already…
To get started, you need to install the main Sparkle XRM Managed Solution, and then followed by the Network Visualisation Managed Solution, both of which can be found here. Why do you need both? Because Network Visualisation references the Sparkle XRM Framework!
Once you’re ready just go take a peek at an Account, you will see the button ‘Visualize’. Click it, it will open a new window and you’ll see your sparkly new functionality in action!
Let’s get down to business…
The solution comes with a web resource which can be configurable. You can find this within your default solution, navigate to web resources, filter on name and you’ll see near the top, one beginning with “dev1_”. This is it! Open it up and you’ll find your config code. Any updates you make need to be to this file (which I’d recommend doing outside of the CRM text editor and into something which gives you at least code highlighting, like visual studio or notepad++ and pasting it in).
The solution has three types of ‘Network’ connectivity:
You’ll find the activity configuration within the ‘Load Activities’ parameter of the ‘entities’ item and it can be set to “true” or “false”. If it is set to true, when you load the parent entity for the item (e.g. Account) it will also load the related activities for that too.
Activities are also a critical entity record to have on any entity where you have not got any joins or connections, for example if you have a Case linked to an Account (via the ‘Customer’ field) but it has no activities or connections that are linked to that Account then it will not display on the network visualisation map. Reason being is it has not been set up with the joins like the Account and Contact is in the standard configuration (you will see the joins is empty) so as far as the network visualisation is concerned, if you have simply an Account referenced by the Case, that’s not enough to display the connection, it needs to have at least one activity.
Why? Because there isn’t much point loading an entity if there is nothing related to it when the concept of this functionality is to load interactions. Above i mentioned that you can’t consume all data, so this is a configurable way of limiting that data. If you want it to be linked and visible on the map, then you need to use the join or connection functionality described below.
It is also important to remember that Activities are more slightly limiting than the ‘Connection’ link, so if you have an Account, and you have a Case, linked to the Account via the ‘Customer’ field, but also have an activity on it which is linked back to the Account, the map will load the Case and the Activity, and nothing else.
Connections are similar to Activities, in that their configuration is in the ‘Load Connections’ parameter which can be set to “true” or “false”.
If you set an entity to load Connections, it will load all the Connections from that entity, and the link to the related entity. What is slightly different about the connections link is that it provides you more information and more ways to connect from the entity to entity and not reliant on an activity being generated. So if you have an Account, and a Contact which has a Connection to an Case, it will not only load the connection link from Contact to Case, but also link all activities (if load activities is set to true on the entity) It will also generate the related records to those activities via the ‘To’ or ‘From’ where they match the entity configuration provided in the config file.
Joins used if you want to make a specific entity-to-entity join using N:1 lookups. You’ll need the lookup field and an understanding where you are going from and to. All of this starts from an Account as this is where the button is by default and cannot currently be changed via configuration). The default join configuration is why you will see the Contacts display on the map that are connected to your Account, but don’t have activities against them. For the Case entity you need activities to be able to display them on the map, because in the standard configuration, you’ll notice the joins are empty. If you want to change this behaviour or if you wanted to add any entity-to-entity relationships without using connections joins will be the way to go.
I have put together a diagram below to show you the associations from how network visualisations sees the connectivity:
A real custom entity example
So let’s start with extending the configuration so that it includes some custom entities. I have created two custom entities, customentity1 which starts from the Account and the second, customentity2, which is linked to the the first custom entity via a lookup.
I added these in the config file as you can see below:
Displaying Custom Entities using Activities: The main direct Account to the customentity1 relationship will only appear if I have an an activity that references my Root Account, this brings through the rest of the links for Account:
As far as the code is concerned, there is technically no direct relationship to the Account from customentity2 so the only way for this to appear on the visualisation map is to create an activity that references the Account. If you think about it, how can this be displayed in any other way? That’s right, the only other way is to now link things via Joins, but we will get onto that in a moment.
Connections: I removed all activities and used different records for this example. Now lets connect the customentity1 to an Account and you can see the activity linked to the entity but also any Accounts that are linked from those activities (such as the Phone Call):
The same thing also applies for my customentity2:
So if using activities and connections are not what you require, joins might be what you need. If you want to show the direct connection using lookups between entities (starting from Account) then lets look at configuring this which I have done so below. I have configured the join from Account to customentity1:
You can see in the example below, this has brought through the entity and a related Task (which is only related to the Join1 record and not directly related to the Account as before):
Lets take this even further and say we also want to display our other connected custom entity (customentity2) from customentity1. Lets add another join, but this time it will be on the joins area of the customentity1:
And here it is in action where you can see both custom entities displaying with no specific activities linking back to the original Root Account, with only the direct join between the first customentity1 to Account:
The final code is below:
You download scripts and code at your own risk and it is not recommended you use the example in a production environment.
I hope that helps! Any questions, please feel free to leave them in the comments below and I’ll do my best to answer you. Alternatively you can tweet me @dynamiccrmcat