Basic use of WBCollection and WorkBox classes

Each work box is, in effect made up of both a SharePoint site (and SPWeb object) and an item in the WBCs list of all work boxes (and SPListItem object). Rather than having to manage these two objects yourself, the WBF provides a wrapper WorkBox class that pulls these two together and provides various useful properties and functions.

Similarly there is a class for a WBCollection that also provides various useful properties and functions. Together, they make possible bits of code such as the following:

using (WBCollection collection = new WBCollection("http://collection/foi"))
    WorkBox workBox = collection.FindOrCreateNewByLocalID("123456");

    if (!workBox.IsOpen)
        workBox.Open("Opening FOI case file 123456 as an example");

    // ... do something with the work box object


This code simply gets hold of the FOI case management WBC, then finds or creates the WB with the local ID (i.e. case file ID) 123456. If this case file isn’t open already then it opens it. Then you can do whatever you need to with that work box and finally the code disposes of the WB.

Note that these steps will have created a new SharePoint site for this work box if it didn’t exist already. The default metadata values for this new work box can be specified when configuring the WBC through the admin UI.

Note also that both the WBCollection and the WorkBox object need disposing as they potentially are being backed by an underlying SPWeb object that they have created. The disposal method only disposes of the underlying SPWeb object if it has indeed been created locally by the wrapper object.

If you need access to the underlying SPWeb, SPList and SPListItem objects then these are easily available through properties:

SPWeb workBoxCollectionWeb = collection.Web;
SPList allWorkBoxesList = collection.List;
SPList workBoxTemplatesList = collection.TemplatesList;

SPWeb workBoxWeb = workBox.Web;
SPListItem workBoxListItem = workBox.Item;
SPDocumentLibrary workBoxDocumentLibrary = workbox.DocumentLibrary;

Creating a new work box with an automatically generated ID

If you know that you need to create a new work box, and you want the WBF to generate the unique ID you can simply use the following code:

using (WBCollection collection = new WBCollection("http://collection/myWBC"))
    WorkBox workBox = collection.RequestNewWorkBox();

    workBox.Open("Created and opened by automatic process.");

    // ... do something with the work box object


The 'RequestNewWorkBox' method will create a work box in the 'Requested' state, so at this point no SPWeb is created for the work box but a new SPListItem will be created in the list of Work Boxes in Collection. The call to the ‘Open’ method will first ‘Create’ the work box (which creates the SPWeb, but doesn’t give anyone permission to use it) and then ‘Open’ it (which gives the relevant teams and people permission to use the work box), leaving it in the ‘Open’ state.

Creating a Work Box when the SPListItem already exists

There are many circumstances when a workflow might need to use a work box, but certainly not as the first step of the workflow. A typical example would be for some kind of case management system when the need for the case first needs to be assessed before it is created.

The WBF can support this pattern by first letting the SPListItem be used for the business process that assesses the need for a Work Box, and then later, if necessary, adding the Work Box details to the SPListItem. This step to create a Work Box is often driven by some code behind a button on a custom form.

The following code demonstrates how this pattern can be implemented. The assumption in this code is that it is running as the code behind a form where the SPContext.Current.Web is the WBC management web site. And item is the SPListItem that needs to have a work box created:
WBCollection collection = new WBCollection(SPContext.Current);
WorkBox workBox = new WorkBox(collection, item);

workBox.ShortTitle = "A short title"; // This short title should be captured in the form

// The SPLongOperation is being used because opening a work box can take time as it
// involves creating a new SPWeb

using (SPLongOperation longOperation = new SPLongOperation(this.Page))
    longOperation.LeadingHTML = "Creating a new work box.";
    longOperation.TrailingHTML = "Please wait while the work box is being created.";


    workBox.Open("Created and opened by " + SPContext.Current.Web.CurrentUser.Name);

    // ... maybe do something else with the work box object

    // Then go to a success page.

// The collection doesn't really need to be disposed as the 
// SPWeb it uses is from the current context

Last edited May 7, 2014 at 11:45 PM by OliSharpe, version 13


No comments yet.