"Hands On" Guide to List Rollup Web Part

Before I dive into a hands on approach to our List Rollup Web Part (referred to as LRWP throughout the rest of this article), let me give you a quick high-level snapshot into LRWP.

LRWP is actual made up of two main components: a Web Part (I like to nickname Designer), and the resulting Data View (more technically in WSS v2/SPS 2003 it is a Data View, while in WSS v3/MOSS 2007 it is a Data Form) of the rolled up data.  The Data View/Data Form (for simplicity I'll refer to the List Rollup Data View or Data Form as LRDF throughout the rest of this article) can then be displayed to the end user or consumed by a number of other Bamboo products.

To create the resulting LRDF the user would complete the following steps using the LRWP:

1. Enter URL to where the list (or library) resides.
2. Select the list to be rolled up.
3. Select the view to filter the list items or use optional CAML Query.
4. Select if Auto Discovery should be used to find other similar lists based on set of conditions.
5. Include List.
6. Repeat steps 1-5 for each additional list or auto discovery query.
7. Select the Master List/View,  This defines which columns to display in the LRDF.
8. Provide a Name for the LRDF.
9. Click Create.  Your LRDF is created!

If only it was that easy, BUT HEY, don't give in yet!  Once you go through the process once, you become a master for life (it's just like learning to ride a bike, once you do it successfully once, you will always remember).  So let's walk through this together, eh?

With the powerful engine of the LRWP, it has the ability to go across all the sites within a given SharePoint Farm.  As a result, the first step of the process is to narrow the scope of the list to include. The scope LRWP is seeking is Site level (for those who think in the world of SP Features, that would be Web ).  As shown below, you enter in the URL to the SP site where the list resides:

Note: Relative URLs are now supported, see the following article for more information http://community.bamboosolutions.com/blogs/bambooteamblog/archive/2008/12/02/relative-urls-and-list-rollup-web-part-a-perfect-marriage.aspx

When the green arrow is clicked, the drop down menu for Lists is refreshed.  What LRWP has just done is it gathered a filtered listing of all Lists and Libraries found on the specified site.  The reason it is a "filtered listing" is because LRWP currently supports all list and library types with the exclusion of list type Survey.  Below is an example of lists and libraries that exist in the specified site P508 (you may notice that the listing of Libraries and Lists are the same as a team site template):

When the user selects an option in the List menu, the Views drop down menu refreshes with all views of that specified list or library:

When a user selects a view, they are actually filtering that list.  So for example, if I selected My Tasks view, My Tasks view is actually made up of a filter where Assign To equals [Me].  If you are not familiar with the [Me] variable, this is a dynamic variable, i.e., when used, it is substituted with the current logged in user.  As a result, if I viewed this list view, I will see only items where the Assign To field is equal to my user name.  Another useful dynamic filter provided by SharePoint is the filter [Today].  The filter [Today] translates to the current date.  As a result, if you have a date column, you could say End Date is less than or equal to [Today] and you will see only items where the date of the End Date column is before or after today to show overdue items.

Anyway, got off subject, sorry about that.  if you would prefer to create a more complex filter, you can get even more creative by using the CAML Query option.  If a CAML Query is listed, the LRWP will ignore the selected view and utilize what is supplied in the CAML Query.  An example CAML Query is listed below:

With each list you want to include in the LRDF, you can choose to either have the filter based on the selected View or the defined CAML Query.  If you choose to work with CAML Query, you have the option to start off based on an already existing view.  You do this by selecting the appropriate view in the Views drop down then clicking on Get View Query link to the left of the CAML Query box.  This will import the selected View's current filter to provide you a starting base.  Note: if you choose to work with CAML Query, omit the opening tag <Query> and closing tag </Query> that is commonly found in CAML Query calls.  LRWP adds these tags automatically in the final stage of creating the LRDF.

Now that we have an understanding of filtering of lists or libraries, let's talk about Auto-Discovery.  If you are like us here at Bamboo, we have a dedicated site template for all our project sites.  Within the project site template, there is a task list and bug list.  As you can tell from our storefront (http://store.bamboosolutions.com), we have  A LOT of products and each product has their own project site.  It would be painstaking to include each individual list into the rollup, and that is where Auto-Discovery Mode comes in.

Auto-Discovery Mode comes in 2 main flavors: Match by List name, or Match by List type.  Match by List name is fairly straightforward, and means LRWP is to locate all lists within the scope of sites that match the provided List name in the earlier step.  This is useful if you have, say, multiple Task lists in your project site template (for example, Engineering Tasks and Product Management Tasks) and you were looking to rollup only Product Management Tasks lists.  Match by List type, on the other hand, is designed for when there is a single list of a particular type (could be more if you choose) within each site you want to rollup.  For example, there might be a list of type Calendar in each project site that you want to rollup, so you would select that type of list in the Lists drop down and select Match by List type.

The next step of configuring Auto-Discovery is to define the scope of the Auto-Discovery process.  The scope is defined by 3 parts, beginning with which sites, based on relationship.  When we talk about relationships we talk about Siblings and Sub-Sites. 

A Sibling is a site that resides on the same level as the selected site in the specified Sites URL.  For example, if I entered in the URL:

http://MOSS2007.BambooSolutions.com/SiteDirectory/P508

And I have the following associated sites in my portal:

http://MOSS2007.BambooSolutions.com/Corporate
http://MOSS2007.BambooSolutions.com/SiteDirectory/P509
http://MOSS2007.BambooSolutions.com/SiteDirectory/P508/i14

Only http://MOSS2007.BambooSolutions.com/SiteDirectory/P509 would be included in the rollup.

A Sub-Site on the other hand is a site that resides underneath the specified site in the Sites box.  For example, If I entered in the URL:

http://MOSS2007.BambooSolutions.com/SiteDirectory/P508

And I have the following associated sites in my portal:

http://MOSS2007.BambooSolutions.com/Corporate
http://MOSS2007.BambooSolutions.com/SiteDirectory/P509
http://MOSS2007.BambooSolutions.com/SiteDirectory/P508/i14
http://MOSS2007.BambooSolutions.com/SiteDirectory/P509/i10

Only http://MOSS2007.BambooSolutions.com/SiteDirectory/P508/i14 would be included in the rollup.

The Second part to configuring the Auto-Discovery is to define how many Sites/Lists to consume:

If in the Sibling and Sub-Site selection step, you selected either Find matches in sub-sites or Find matches in siblings and sub-sites, the input box for sub-levels deep is enabled.  This means how many sub sites deep should the Auto-Discovery go?  Another way to put it is, how many sub-sites within sub-sites should LRWP dig?  The second option allows you to define how many lists TOTAL the LRWP should discover.  Both options can be disabled by clearing the check box to the left of the appropriate inbox field.

The final part of configuring Auto Discovery is to specify any sites that should not be included in the rollup:

This option allows you to enter as many sites to be ignored by the rollup as you choose, by simply entering the site URL in the multi-line text box.  Each entry needs to be separated by a semicolon (i.e., ;)

Limitation Note: Auto-Discovery has a known limitation that it is only able to discover sites within a single Site Collection.  if you would like to rollup lists across multiple Site Collections, include multiple lists where the root site is on a different site collection, and repeat the above steps.

After you have successfully selected your list, view, CAML query, and optionally enabled the Auto-Discovery mode, click Include List:

Notice that the next section of the LRWP, Included Lists, is updated.  Here is an example of my Included Lists section:

Several interesting details are provided in this view.  First, notice the icon difference for each included list.  You will notice that if you have Auto-Discovery enabled, the icon looks like , whereas if you included a list with Auto-Discovery disabled, the icon, looks like .  The second item you will notice is that the URL is active.  This allows you to click on the list path to confirm that it is the correct list you want to include.  If Auto-Discover was enabled, the configuration of Auto-Discovery is provided in the listing, including any sites you have Excluded (not shown above).  You can remove lists by clicking on the radio button to the left of the appropriate list URL, and clicking Remove Selected, or remove all lists by clicking Remove All.

The MOST important component of this section is selecting the Master List View.  A selected Master List View is defined by selecting the list and view of choice by clicking on the radio button to the left of the appropriate Included List.  So what does the selected Master List View do, you might ask?  The selected Master List View defines which columns to display in LRDF and what format to display them in.  For example, if I had included 2 lists, let us call them Task List A and Task List B for simplicity purposes, and the lists had the following columns in the specified view:

Task List A                    Task List B
Title                               Title
Project                           Owner
Owner                            Due Date
Due Date                       Description
Description

And I selected Task List B as my Master List View, only the columns Title, Owner, Due Date, Description, would be displayed in the LRDF.  Even though Task List B has Description column in the list, the selected view does not include it, so it will not be displayed in LRDF.  Subsequently, if Task List B had, for example, Start Date column in the selected view, and Task List A does not have a column called Start Date, its item entries in the LRDF would simply be blank for that column.  To further clarify, only the selected Master List View must include all columns desired to be shown in the LRDF.  The other included lists do not require the columns to exist in the selected view.

In the final step of setting up the LRWP, you will:

Provide a Name and Description of the resulting LRDF.  The Name will of course be displayed in the title bar of the LRDF, while the Description is displayed in a tool tip when you hover over the title with your cursor.

Select if you want to display Site Path and/or List Name.  If you select the option Site Path, a column will be added to the far right of the resulting LRDF called Site Path and it will display the name of the site where the item resides, with a link to that site.  If you select List Name, a column will be added to the far right of the resulting LRDF called List Name, and it will display the name of the list where the item exists, along with the path to the default view of that list.

Cache Timeout Value is available to assist in performance.  In the example above, the timeout setting is set to 10 minutes.  As a result, when the first user hits the LRDF, they have cached the items found at that time for the next 10 minutes.  This means anyone else who views this LRDF will see the same set of items for the next 10 minutes for items they have access to.  If you were to set the value to 0, every person that hits the LRDF will see a real time listing of all items that they have access to. 

Let me side track for a second because this would be a great time to talk about list and item level security when it comes to LRWP and the resulting LRDF.  LRWP maintains ALL SharePoint list and item level security!  So lets put an expample behind this.  A SharePoint user creates a new LRDF that includes the following lists: P508 Tasks, P509 Tasks, and P520 Tasks.  Each list has a different set of permissions:

List Name                 Group Allowed to View List
P508 Tasks             Contributors; Owners
P509 Tasks             Owners
P510 Tasks             Contributors; Owners

As a result, if the above 3 lists were rolled up in a LRDF, and a member of the Owners logs in, they can see items for all three lists.  If a member of the Contributors logs in they will only be able to see items from lists P508 Tasks and P510 Tasks, items from P509 is not shown, even if Cache Timeout Value is set to greater than 0.  This is also true for item level security.

Display items in batches of allows the user to define how many items to view on a given page within the LRDF.  If, for example, they selected 15 items, and there are 32 items in the LRDF, the LRDF will only show 15 items with the option to switch to another page of results within the LRDF.

The final 2 options in the creation of a LRDF is:

 gives you the ability to view the results of the configured LRWP without creating the LRDF.  A sample of the resulting view will be shown just below the LRWP.  This is useful to confirm that the results are what you were expecting.

 will create the final resulting LRDF.

To see if the resulting LRDF was created successfully, navigate to the top of the LRWP and confirm that you see the following message:

So now you are probably looking all over the page but do not see your newly created LRDF anywhere and wondering, what gives?????  By default, when a LRDF is created, it is marked as Hidden.  To make the LRDF visible, complete the following steps:

1. In the upper right hand corner of the page, click Site Actions and select Edit Page.
   
   
2. Locate your newly created LRDF.  Notice that in the Title of the LRDF, the text (Hidden) is displayed.  On the far right of the title bar, click on the edit menu down arrow and select Modify Shared Web Part.
   
   
   
3. In the right hand side of the browser window, the LRDF Web Part Tool Pane will display.  Expand the section labeled Layout and clear the check box Hidden.
   
   
   
4. Click Apply, then OK.
5. Click on the option Exit Edit Mode, located just below the Site Actions menu.
   
   

You have now successfully created your first resulting List Rollup Data Form!

Just a few additional options I want to go through and we will close up for the day.

One feature that I skipped over in reference to the LRWP is the Available Templates section.  This section provides the ability to create new LRDF using existing LRDFs.  You will notice that the list of Available Templates is made up of LRDFs that currently exist on the same page as the LRWP. 

Simply select the appropriate LRDF by clicking on the radio button next to the LRDF of your choosing, then click Load Template.  You will notice that the LRWP refreshes with all the appropriate selected lists already defined.

If you want to remove a template (this is usually due to your having created a new LRDF that renders obsolete a previously created one), select the appropriate LRDF in the Available Templates and click Delete Template.  This will actually delete that LRDF from the page.

The final subject I want to talk about is the ability to move the newly created LRDF from the current page, and import it to a different Web Part Page either on a different site, site collection, or even Web application.  To accomplish this, follow these steps:

1. Click on the drop down Web Part edit menu and select the option Export...
   
   
   
2. You will receive a dialog prompt that allows you to save the LRDF to your local machine (note that the file type is .webpart).
   
   
3. After you have saved the LRDF, navigate to the destination page where you want to display the resulting LRDF.  Once you have reached the page, click on Site Actions menu located in the top right hand corner of the window and select Edit Page.
   
   
4. Notice a yellow bar appears in the page with the label Add a Web Part (note that you might have multiple bars as there is one per Web Part Zone or section within the given Web Part page).
   
   
5. Click on the Add a Web Part yellow bar corresponding to the section where you want the LRDF to reside, and an Add Web Parts window will appear.  At the bottom of this window, click on the link Advanced Web part gallery and options.
   
   
6. The current Add Web Parts window will close, and on the right side of the browser window an Add Web Parts panel will appear.
   
   
7. Click on the Browse bar just below the Add Web Parts header, and select Import.
   
   
8. In the updated Add Web Parts panel, click the Browse button and locate your saved LRDF (remember that the file type of the LRDF is .webpart).  When you select the LRDF, you will then need to click Upload.
   
   
   
9. Notice now that the LRDF is listed below the Upload button.
   
   
10. You can now click and drag the LRDF (in my example, it is called My Tasks) and drop it into the section of the Web Part Page of my choosing.

You have now successfully moved an existing LRDF from one Web Part Page to another.

Now that you have become an expert in List Rollup Web Part, give it a try in your own environment!  All our products come with a full functional 15-day trial to allow you to try it out yourself.  To get the free trial, go to this URL: http://store.bamboosolutions.com/ps-32-5-list-rollup-web-part-release-32.aspx, scroll to the bottom of the page, and select Add to Cart the Trial Download as shown below:

If you've already got List Rollup comfortably under your belt, check out these additional options you can try out (I will blog in the future about how to achieve each item listed below):

• Rollup multiple calendars into a single view.(List Rollup Web Part + Calendar Plus Web Part and/or Mini-Calendar Web Part)
• Rollup multiple task lists into single view and have the ability to group or filter in real time. (List Rollup Web Part + Data-Viewer Web Part)
• Display a single list from one site collection to another site collection (List Rollup Web Part)
• Ability to alert on tasks across all project sites (List Rollup Web Part + Alert Plus Web Part)
• Ability to view graphical data across all site statistic lists (List Rollup Web Part + Chart Plus Web Part)