The Microsoft Dynamics CRM Blog
News and views from the Microsoft Dynamics CRM Team

List Web Part for Microsoft Dynamics CRM 4.0: Understanding Connections

List Web Part for Microsoft Dynamics CRM 4.0: Understanding Connections

  • Comments 16

List Web Part supports three different types of connections that you can use to build various dashboards on a SharePoint portal. They are:

  1. Field to field connections
  2. Row to row connections
  3. Table to table connections

Let us walk through each of them to understand how they work, and what job they are best suited for. But before we dive into greater details, I’ll briefly put together the concept of connections in web parts for the uninitiated.

A web part connection is like a contract between two web parts to exchange some data. There are two parties in a connection: provider, and consumer. The provider sends the data as agreed in the contract to the consumer. The consumer can then use this data in whatever way it wants.

While one List Web Part provider can provide data to many consumers simultaneously, a List Web Part consumer can consume data only from a single connection at a given point of time. The same instance of List Web Part can act as both a provider and a consumer at the same time, thus enabling branched connections and cascaded connections. More on this in a bit after we go through each of the connection types List Web Part supports.

Field to Field connections:

The field to field type connections enable filtering based on relationships between two entities in CRM. For example, let’s consider Accounts and Orders in CRM. They are related by a one-to-many relationship on the attribute Customer. So if you enable a field-to-field connection between Account and Order List Web Part instances, with Account being provider, and Orders being consumer, then selecting a record in Account grid will show you all those records in Order, which have Customer as that selected account.

If there is more than one relationship between two entities, then the result in the consumer is an OR of all the relationship fields. For instance, let’s say, order has one more relationship with account on an attribute called Partner Customer. Then selecting an account record in the provider will return all those order records, which have the selected account either as Customer, or Partner Customer, or both.

List Web Part supports this connection for all the three types of relationships in CRM: One to Many, Many to One, and Many to Many.

How to create a field to field connection:

i. Add two List Web Part instances on a SharePoint web page.

ii. Open the web part page in Edit mode.

iii. Choose one of the web parts as provider, and other as consumer.

iv. Click the provider part’s connection menu. Select ‘Send Selected Field To’, and choose the consumer web part from the list that shows up.

clip_image002

Figure 1: Configuring field to field connections

That’s it! Your field to field connection is ready to be used.

Field to Field Connections with custom web parts

Custom web parts can connect to a List Web part using field to field connections, if they implement the following interface:

   1: public interface IWebPartCrmData
   2:     {
   3:         /// <summary>
   4:         /// Schema name of the CRM entity
   5:         /// </summary>
   6:         string EntityLogicalName{ get; }
   7:  
   8:         /// <summary>
   9:         /// Display Name of the CRM entity
  10:         /// </summary>
  11:         string EntityDisplayName{ get; }
  12:  
  13:         /// <summary>
  14:         /// Schema name of the primary key of the CRM entity
  15:         /// </summary>
  16:         string PrimaryKeyLogicalName{ get; }
  17:  
  18:         /// <summary>
  19:         /// Display name of the primary key of the CRM entity
  20:         /// </summary>
  21:         string PrimaryKeyDisplayName{ get; }
  22:  
  23:         /// <summary>
  24:         /// Value of the Primary Key of a particular instance of CRM entity.
  25:         /// </summary>
  26:         string PrimaryKeyValue{ get; }
  27:  
  28:         /// <summary>
  29:         /// Value of the Primary Attribute of a particular instance of CRM entity.
  30:         /// </summary>
  31:         string PrimaryAttributeValue { get; }
  32:  
  33:     }

If your custom web part is a provider, then it needs to implement this interface. If it is a consumer, then its consumer method should consume an instance of this interface.How to write custom web parts is beyond the scope of this blog, but more details can be found here.

Row to Web Part Parameter Connections:

This type of connection enables one set of fields from provider web part to be mapped to another set of fields from the consumer web part. While configuring this connection between two List Web Parts, you need to perform a mapping between various columns shown in the provider grid to another set of columns in the consumer grid. The consumer then filters its results based on the data from provider.

Here's an example that'll help explain this. Suppose you want to reach out to all contacts in CRM who belong to the same city as yours, then this is how you'll do it:

i. Add two list Web Part instances on a SharePoint web page. Configure first for User Entity, and second for Contacts. User will act as provider and Contact will be the consumer. For our example scenario, you should configure both User and Contact with a view that has City in its column set.

ii. Open the web part page in Edit mode.

iii. Click the provider part’s connection menu. Select ‘Send Selected Row To’, and choose the consumer web part from the list that shows up.

clip_image004

Figure 2: Configuring row to web part parameter connections

iv. A Configure Connection webpage dialog shows up, which will let you map one or more columns from the provider to respective columns in the consumer. Please note that only those columns show up in the list, which are present on the grid. Map the City from User to Address1_City in Contact. Keep clicking Next until you reach Finish.

clip_image006

Figure 3: Configuring connection mappings

The connection has been configured. Now select yourself from the list of users shown in the User web part, and you should see only those contacts which have the same city as yours. Select any other user with a different city, and the results in contact web part should change to reflect the new city.

You can configure this connection so as to filter on a group of columns instead of a single one. Just map as many columns from the provider to respective consumer columns as shown in the transformer screen, and you should be good to go. The result shown is an AND of all columns. What this means is that if you apply a filter on City, and zip code, only those contacts which satisfy both the city AND zip code will be shown.

Also, if you map more than one column from the provider to the same consumer column, then consumer will filter results only on the last mapped column from provider.

This connection is really powerful as it enables you to filter data crossing the organization boundaries in CRM. You can connect List Web Parts from two different CRM organizations, or two different CRM Server deployments, and filter data. You can even connect and filter data from other LOB applications, if you have custom web parts built for them.

Row to Web Part Parameter Connections For Advanced Scenarios

While configuring Row to Web Part Parameter type of connection, you'll notice that there are some columns which appear twice on the Transformer screen. For example, for a Contact Web Part, you should be able to see two columns with respect to Parent Customer, namely Parent Customer and Parent Customer: Id.

And here's why: Every CRM column has a property called Attribute Type, which represents the nature of data a column is used to store. The Attribute Type could be a boolean, a picklist, an integer, a nvarchar, and so on and so forth. While some of these columns store their values in text format, others store them using IDs, and do a reference lookup when showing up in the text format.

Examples of the latter kind are Lookup Types, Booleans, Picklists , Integers(of type Time Zone, Duration, or Language), etc.

Let's get back to the previous example of Parent Customer, which is a lookup field from Account in Contact. In CRM, lookup fields are referenced using GUIDs, and while displaying, their display names are shown. So from a provider web part, if you map Parent Customer to some consumer attribute, the actual data passed will be its display value. For example, if the Parent Customer in a record is called Active Cycling, and behind the scenes, has an ID as {E6E82758-99BB-4717-8D46-BC6A848A3442}, then mapping Parent Customer from provider will send the value 'Active Cycling' and mapping Parent Customer: Id will send the value ' {E6E82758-99BB-4717-8D46-BC6A848A3442}' to the consumer.

The point to note here is that mapping IDs will make sense as long as the two web parts in the connection have been configured for the same CRM organization. Also, if we choose to map Parent Customer: Id, then the receiving field in the consumer should be of a type that accepts a GUID, i.e. in a mapping, the data type of the receiving field should be compatible with the data that provider is sending. In case, it is not, the consumer web part will show an appropriate error message, telling you that your field mappings are incorrect.

You should use ID fields to map, in case you are connecting two web parts configured for the same organization. This will give you a better performance, and accurate results.

You can still choose to map the Non-ID fields(example Potential Customer) even when in the same organization. But because you are mapping on display names now, then all the records with the same display name on the mapped attribute will be considered while applying filtering on the consumer.

Of course, Non-ID field mappings make sense when you are connecting across CRM organizations, or to other custom web parts, which do not understand CRM IDs.

Removing Row to Web Part Parameter Connections:

You can remove this connection by following the steps below:

i. Open the web part page in Edit mode.

ii. Click the provider part’s connection menu. Select ‘Send Selected Row To’, and choose the consumer web part from the list that shows up.

iii. The configure Connection web page dialog shows up as shown in the figure below:

clip_image008

     Figure 4: Removing row to web part parameter connection

iv. Click on Remove Connection.

Table to Table Connections:

List Web Part acts as a Table Provider, and you can connect it to any other web part that consumes the IWebPartTable interface. The provider sends the entire data displayed in the grid to the consumer, and the consumer is free to use it in whatever way it wants. Possible examples of consumers could be: A charting web part, that takes a view containing revenue, and customer cities, and then creates a city wise distribution of revenues.

Please note that List web Part by itself does not consume any table data.

Dashboard creation using connections:

Now that we know the various connection types supported by List Web Part, we can use them to build dashboards, which give you a 360⁰ view of you data. You can create cascaded connections, branched connections, and also combine various type of connections.

For example, you can create the following dashboard to take a look at all Opportunities and Orders associated with a particular account that belongs to a certain user:

butter

Figure 5: CRM dashboard using List Web Part

butter2

Figure 6: CRM Dashboard

To accomplish this, create a Row to Row Connection between User and Account on the column Owner(present in both User and Account), with User being Provider, and Account being Consumer.

Next create a connection between Account and Order using Field to Field Connections, with Account being provider and Order being Consumer. Similarly, you can create a field to field connection between Account and Opportunity.

NOTE: While configuring the connections above, please ensure that you add web parts on the web page and configure connections in the same order in which data is flowing from provider to consumer. For example, in the above scenario, data flows from User -> Account -> Order, and User -> Account -> Opportunity.

Hence the order of steps here can be:

1. Add User web part

2. Add Account web part

3. Add Order web part

4. Add Opportunity web part

5. User to Account connection

6. Account to Order connection

7. Account to Opportunity connection

I believe you are pretty excited to try your own hands on connections by now, and hopefully, you have all the raw material to get started. Happy dashboarding!

Nimisha Saboo

  • PingBack from http://blog.a-foton.ru/index.php/2009/01/19/list-web-part-for-microsoft-dynamics-crm-40-understanding-connections/

  • Nice article and very well described the connections.

  • Javista recently announced the release of the Sharepoint 2007 List Web Part for Microsoft Dynamics CRM

  • Hi,

    Nice in depth article indeed. However i still have some questions. My main question is how to go around with the external connector (license type) regarding the list web part possibilities.

    I'd like to build one web page and depending on the customer or relation who want's to view the data it should only show his or her data (relation is the main filter and not user).

    How can i accomplish this, since the relation is not a user and the logon via the external connector is not making any difference on who is loggin on through too CRM (correct?).

    Hope you can help me with this.

    Kind Regards,

    Max

  • Hi,

    Nice in depth article indeed. However i still have some questions. My main question is how to go around with the external connector (license type) regarding the list web part possibilities.

    I'd like to build one web page and depending on the customer or relation who want's to view the data it should only show his or her data (relation is the main filter and not user).

    How can i accomplish this, since the relation is not a user and the logon via the external connector is not making any difference on who is loggin on through too CRM (correct?).

    Hope you can help me with this.

    Kind Regards,

    Max

  • Hi Max,

    Can you please elaborate, what an external connector is? Also, some more details on the complete scenario will help me understand your requirements better.

    Cheers!

    Nimisha

  • Hi Nimisha,

    The external connector is a license for Dynamics CRM, used for non-employees of the organisation owning the CRM application. The external connector is of use when retreiving or writing data to CRM via a client that is not of Dynamics CRM (wpf application, aspx page, sharepoint e.g.).

    My wish would be to create one sharepoint page where a customer could retreive and write data into CRM.

    Since this can really add up the amount of users Microsoft Dynamics CRM offers a external connector (for non employees only). However Microsoft Dynamics CRM sees a external connector as one user (let's say Webuser).

    Since i cannot use this user id, my customer would see all customers when this is my webpart. But i want that they can only see their own data. It seems i have to build someting for this (a login frame, and intelligence in CRM) to filter this data in the webpart (provide the webpart with this data). At the same time i want to ensure that customer A could have acces to his account and his service calls but customer B only has acces to account information. Since the account is not an user, i probably cannot use the authorization of standard CRM.

    My question would be, is there a way to use the out of the box list web part functionality, having one sharepoint page and display only data relevant to one customer who is getting acces via a external connector license.

    Hope this helps?

    Regards,

    Max

  • Hi Max,

    Given that external connector always uses the same ID to connect to CRM, your scenario can't be enabled using List Web part.

    However, you might want to take a look at the CRM eService Accelerator:

    http://blogs.msdn.com/crm/archive/2008/08/12/crm-accelerators-part-ii-eservice-accelerator.aspx

    This probably addresses your problem for a few entities, and you can build upon this to suit your requirements as the source code is available.

    Hope this helps!

  • Hi Max,

    Given that external connector always uses the same ID to connect to CRM, your scenario can't be enabled using List Web part.

    However, you might want to take a look at the CRM eService Accelerator:

    http://blogs.msdn.com/crm/archive/2008/08/12/crm-accelerators-part-ii-eservice-accelerator.aspx

    This probably addresses your problem for a few entities, and you can build upon this to suit your requirements as the source code is available.

    Hope this helps!

  • Great post Nimisha.  This all makes sense to me and I am having mostly no trouble connecting my webparts.  Hoever I have one webpart where the connection just won't work for me, the consumer webpart indicates there are no records for the parent record.  There definitly is.  I can see this in CRM on the Parent record.  I can also open in Adv Find the view displayed in the consumer webpart and filter by the parent record and get to what I should see back in SharePoint.  I have tried field to field and row to row and neither are working for me.  Field to field should work.  Are there certain entity relationship configurations not supported?  Any ideas?

  • Hi Gareth,

    List Web Part supports all three types of relationships between provider and consumer: 1 to many, many to 1, and many to many.

    So if there exist one or more relationships between your provider and consumer, then field to field should work.

    But as you mention, you can't see any data in the consumer, I have few quetions:

    1. When not connected, are you able to see data in the consumer web part in the same view that you are trying to connect?

    2. Are you sure that you have some records in the consumer web part which actually refer to the selected record in the provider web part?

  • Hi Nimisha,

    I am trying to consume data from my CRM Web part and push it into a custom list in order to run simple KPI indicators upon that data. I can get the connections to take but upon completing the transformer process I do not receive any data. Any suggestions?

  • Hi Trey,

    I have a few questions for you:

    1. Which of the three connections of List Web Part are you trying to consume data from?

    2. What is the interface your custom list is implementing?

    3. How are you writing your transformer?

    Regards,

    Nimisha

  • Hi Nimisha,

    I stumbled on this blog and it has been very helpful. I am trying to link a custom web part to the CRM List Web Part. I have constructed a basic web part using VS2005; it just prints “Hello World”. I have defined a consumer method using the “ConnectionConsumer” attribute. The method also consumes an instance of the “IWebPartCrmData” interface. After I deploy the web part to the page with the CRM List Web Part, I go to the “Connections” menu for my web part and the choices for connections are disabled since “The Connection Type ‘My Row’ is not compatible with any other Web Parts on the page”. How would I be able to get this connection working?

    My ultimate goal is to have my web part show details of the record currently selected in the CRM List Web Part. I am new to MOSS/WSS so I may be missing something very fundamental. Any suggestions you may have would be much appreciated.

    Thanks for your time.

    -Andrew-

  • Hi Andrew,

    I am really sorry, I read this a bit too late.

    Please let me know, if this is still an issue, and we can work on getting you a resolution.

    Thanks,

    Nimisha

Page 1 of 2 (16 items) 12
Leave a Comment
  • Please add 8 and 8 and type the answer here:
  • Post