SharePoint is build upon lists. These lists contain items. So the action to retrieve items from these lists is quite common. But when you’re coding against the object model. You might run into surprises. In the previous post I already talked about internal names and display names of fields. Today I’ll talk about an issue when retrieving items from a list, and more specifially from a view.

When SharePoint is retrieving items from a list or view, SPList.GetItems is always called. This method will actually create a new collection of items. Those items will actually be retrieved by a query. To query in SharePoint we use a SPQuery object. This object is a container for SQL like queries. You select the fields you want to see, you have some conditions, a rowlimit, … And this is were a possible problem can reside. When retrieving items from a view, the query will only retrieve the fields defined in the SPView. In other words: the SPListItems you will get do not include all the data. This can be very confusing, as you expect a one-to-one relationship between the data of an object and the SPListItem. You should not forget however that the SPListItem is actually a proxy container for XML data. The object encapsulates the data for easy access and is not the actual full (logic) list item.

So how can we solve this? Well pretty easily actually. We create a real SPQuery object to retrieve our items with:

SPView view = myList.DefaultView;

SPListItemCollection myColl = myList.GetItems(query);

Pretty easy, huh. The thing to remember here: SPListItem objects encapsulate XML data and are not the actual list items! Have a great week, everyone!

When creating columns (more commonly called fields) in SharePoint through the interface, you have to enter a name for it. This name is used throughout the lists and sites, included internally. Except when you try to change the name, it’ll only reflect on the outside. Internally the old name will be kept. This is because a field has two names: an internal name and a display name. When creating a field, you set both. When renaming it, you only change the display name. (There is actually no way to change the internal name afterwards)

But why is this a concern? Well, in the object model it can become quite vague when to use the internal name and when to use the display name. Here is a short list with some common methods and the name they need.

• SPFieldCollection[name] : SPField
  name: DisplayName
  unexistent: exception
• SPFieldCollection.GetField(name) : SPField
  name: internalName, displayName or internalName and displayName from the current context
  unexistent: exception
• SPFieldCollection.GetFieldByInternalName(name) : SPField
  name: internalName
  unexistent: exception
• SPFieldCollection.ContainsField(name) : bool
  name: displayName or internalName
  unexistent: boolean
• SPListItem[name] : object
  name: internalName, displayName or internalName and displayName from the current context
  unexistent: null
• SPListItem.GetFormattedValue(name) : string
  name: internalName, displayName or internalName and displayName from the current context
  unexistent: exception

If I find more relevant functions, I will update this list. On a related note, there also exists a static name. This is a name used by the field type. This is different from the internal name, as the internal name must be unique in its list and could have changed.

Hope this clears up some confusion about field naming in SharePoint. See ya.

Hey guys,

Just a quick post to wish you all a happy new year. May your resolutions be fulfilled! :-p I hope I’ll achieve mine.

Sorry for the long delay for the previous article. Correlation is a very tricky technology. It’s still very vague and such. I hope I explained it clearly. Other hickups for the delay were, well, the holidays and some strange wordpress problems… which still need to be fixed, actually. :p

Anyway, Happy 2008!

Correlation is one of the key concepts in Workflow Foundation to understand when developping workflows. Most of the time people are confused about what correlation exactly is. They can’t really describe it, they can’t really explain it. Unfortunately, when you do not fully grasp this concept, it can lead to some major confusion when developping advanced scenarios and custom activities.

So what is correlation? Correlation is the machanism created to map an inbound message for a specific instance (sent from an external source) to the specific handler within the activity. There are two levels here:

• specific instance
• specific handler within the activity

Each level has his own differentiater. The specific instance (known by the external souce in the outside world) is defined by the CorrelationParameter and the specific handler within the activity (note that a workflow is an activity too) by the CorrelationToken.

But how is this implemented? Well, let’s first recap the basic objective: we are trying to establish external communication. The Workflow Foundation achieves this by using interfaces as a “channel”. The implementation of such a “channel” interface is a service which is added to the workflow runtime. This is actually the heart of correlation. As there are many instances (in the outside world) the service can work on, Workflow Foundation needs to know with which instance it must work on. This is why we need to define the CorrelationParameter in our “channel” interface. This is how an interface for external communication can look like.

[ExternalDataExchange]
[CorrelationParameter("taskId")]
public interface ITaskService
{
  [CorrelationInitializer]
  void CreateTask(string taskId, string assignee, string text);
}


In this example we define a CorrelationParameter “taskId” that will help us differentiate tasks – the instances – in the outside world. This name will stand for the correlation paramater throughout the whole interface. So when you use this name in a member (eg. CreateTask) as a parameter, Workflow Foundation considers the parameter as a correlation parameter for that member. Note that a correlation parameter can be a guid, int or whatever.
You also see a CorrelationInitializer attribute in there, which decorates the CreateTask member. When calling a member with this attribute, Workflow Foundation will know that the correlation parameter is initialized with this member. It will then reset internal pointers.

Now that the channel is defined, you can use it within your activity. You can use the channel directly by querying the runtime for the correct service. Workflow Foundation however gives you another possibility to ease working with different instances and handlers for those instances WITHIN your activity. This is where Correlation Tokens come into play. A correlation token encapsulates the correlation parameter and a value, together as a correlation property. For our task example, we could create a correlation token named “taskToken” which encapsulates the correlation property of property parameter “taskId” with the value 25. In other words this correlation token will hold the reference to the task 25.
Workflow Foundation also provides two activities that use this correlation token: CallExternalMethodActivity and HandleExternalEventActivity. A common way to use these activities consists of overriding their methods when developping custom activities (most sharepoint activities are implemented this way). Another method is to use them directly by setting the correct service, member name and parameters. As you probably already figured out, the first activity is able to call external methods. The HandleExternalEventActivity, on the other hand, will wait and listen for a specified event (after which it can trigger methods). Both of those activities use the correlation token to determine which instance they have to work with. It, however, makes most sense with the HandleExternalEventActivity, as an event cannot handle parameters, while the method called from a CallExternalMethodActivity specifies which instance to work on by one of the parameters.
To resume, here is a little schema of how to look at correlation tokens:

I hope this article helped you guys understand correlation a bit more. Untill next time..