Saturday, February 5, 2011

How to provisioning a site column with CAML

A SharePoint list can be thought of as a data table with columns describing the fields and rows for each record.  The columns (or fields) are defined within the list and are only defined in a single list instance.  The are many business cases where your data contains the same column in many different lists and each time you will need recreate this column in each list, an example may be a Customer Account Number which is in many lists.
In WSS 3.0 there is a site column, which simply is a reusable field definition.  The site column allows you to define the field with all it's settings, once done you simply can add it to many different lists.  This becomes really handy when you have complex fields and want reusability.
Now there are three ways to create your site columns:
  1. Manually create it using the web front-end. 
    The problem with this approach is that you will have to recreate this on different web applications and server farms, e.g. dev, test and production.  This could be prone to error
  2. You can write code to create the site column.
    This is the long and hard way as you will need to test your code well and will require a programmer to do this.  You most probably will land up provisioning your code through features and site definitions anyway and I feel this is just too much effort.
  3. Create the column using CAML.
    This is most probably the best way when it comes to reusability as you will create an element manifest and include this manifest in a feature.  Then you can simply deploy the feature and activate it where needed.
In this post, I will only focus on the last step as this is the best way to do provision a site column.

Summary of steps

This post will walk you through the steps below in order to create a site column,  the most important step is Step 3 which
  1. Create a feature project
  2. Create a feature manifest
  3. Create a site column elements manifest file
  4. Deploy the feature
  5. Provision and Activate the feature
  6. Verify the columns exist

Creating a feature to provision a site column

Download the code

Step 1 - Create a feature project

In creating a project for SharePoint, I somewhat follow the project structure as defined in the Microsoft Press Book: Inside Microsoft Windows SharePoint Services 3.0 by Ted Pattison and Daniel Larson. 
  1. Create a Library project in visual studio, in this example I have called it Grounding.Demo.SiteColumn
    In this project we will not be deploying the actual DLL, so I will skip the steps of creating a strong named assembly
  2. Create a directory structure to mimic the feature folder in the 12 hive where we are going to deploy the feature to. 
  3. Edit the build events to deploy your SharePoint solution onto your development box.
    Please note that you should be provisioning your solution using a site definition, however I did not want to complicate this post.

    For this demo, the post-build event command line is:
    XCOPY "$(ProjectDir)TEMPLATE" "C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\" /s

Step 2 - Create a feature manifest

In this step, we need to create a SharePoint feature for our content types in order to set up a proper deployment environment for our content types.  Once completed the feature will be used to deploy to other server environments, i.e. test and production.
  1. Create a feature.xml file in the TEMPLATE\FEATURES\Grounding.Demo.SiteColumns folder.
  2. Add the following xml to the file.
    xml version="1.0" encoding="utf-8" ?>
    <Feature xmlns=""
             Id="{1EED8F45-4FF6-473d-9B8F-99CB6599D50C}"         Title="Grounding Demo - Provision Site Column"         Description="This demonstration teaches you how to provision a site column using CAML"         Version=""         Hidden="FALSE"         Scope="Site">
        <ElementManifest Location="SiteColumns.xml" />
    < P>
Important points to note
  • The site columns are provisioned to the "Site" scope i.e. the site collection
  • The feature has a unique GUID, which you can generate from Visual Studio menu, Tools\Create GUID (Use the registry format).
  • The ElementManifest points to a file (created in the next step) that includes the site columns.

Step 3 - Creating a site column

Creating a CAML site is done by placing a field element into an element manifest file which is explained in the steps below.  For demonstration purposes I have created a simple customer account number field.
  1. The first thing to do is create a element manifest file using an XML editor.
    In this case the it was called SiteColumns.xml (see the ElementManifest in the feature above).
  2. Add the following XML to the file
    xml version="1.0" encoding="utf-8" ?>
    <Elements xmlns="">
      <Field    ID="{63590418-87F5-4fa7-AF50-B371C88F2F56}"    Name="CustomerAccountNumber"    DisplayName="Customer Account Number"    Description="A customer account number used within the company."    Type="Text"    MaxLength="10"    Group="Grounding Site Columns"    >
Important points to note
  • The ID must be a unique GUID which you can create using visual studio, Tools\Create GUID.  Use the registry format.
  • Type and Title are mandatory.
  • You can provision several fields in a single element manifest file, just create as many elements as you need.
  • Grouping your fields makes them easier to find and use from the front-end

Some field attributes

ID The ID is a globally unique identifier (GUID) which you should generate for each field. This ID will be used in lists when referencing the site column
The type indicates the data type of the column and can be of the any following:
AllDayEvent The all day event flag is used in calendar lists.
Attachments The URL of an attachment.
Boolean A boolean indicator with Yes/No.
Calculated Indicates that the column is a calculated column based on a expression.
Choice Indicates that the column is choice from a list of items
Computed Indicates the field's value is dependant on another field's value.
ContentTypeId A Content Type ID value.
Counter An internal unique ID's / counter for each item.
Currency A currency value (its format depends on the locale).
DateTime A Date and Time field.
File A file object when used in document libraries.
GridChoice A rating scale as used in surveys
Guid A globally unique identifier.
Integer An integer number field.
Lookup The field is a lookup which is a choice, however the choice is from another list.
LookupMulti A lookup field, however multiple selections are allowed.
ModStat An approval status.
MultiChoice A choice field, however multiple selections are allowed
Note Multiple lines of text which can be plain or formatted.
Number A numerical field which allows decimal places.
PageSeparator A page separator field, for surveys.
Recurrence An indicator that identifies the field as a reoccurring calendar event.
Text A single line of text
ThreadIndex The ID of a discussion thread.
Threading Indicates the field supports threading (in discussions).
URL A Unified Resource Locator (URL) is stored.
User A person or group.
UserMulti A person or group, however multiple people or groups can be selected.
WorkflowEventType Contains the type of workflow history event (used in workflow history list).
WorkflowStatus The status of a workflow is stored.
Title The name of the field as displayed in the user interface.  This title may be set using a resource file.
Name (optional) The name of the field which should be guaranteed to never change.  The default is the Title with spaces and invalid characters removed.
StaticName (optional) The logical name of the field which is similar to Name, however this can be programmatically changed.
DisplayName (optional) See title.
Description (optional) A description of the field which will be displayed in front ends.  The description can be placed into a resource file.
Required (optional) Indicates whether or not the field is mandatory. The default is FALSE.
MaxLength (optional) The maximum number of characters allowed.
Hidden (optional) Indicates that the field should be hidden from the interface. If TRUE, this field will not be shown on views or forms. The default is FALSE.
ReadOnly (optional) The field should be read-only and can be displayed and not edited.  The default is FALSE.
ShowInDisplayForm (optional) Indicates whether the field should be shown on a display form. The default is TRUE.
ShowInEditForm (optional) Indicates whether the field should be shown on an edit form. The default is TRUE.
ShowInListSettings (optional) Indicates whether the field should be shown in the list settings screen. The default is TRUE.
ShowInNewForm (optional) Indicates whether the field should be shown on a New form. The default is TRUE.
ShowInVersionHistory (optional) Indicates whether the field should be shown in the version history of an item. The default is TRUE.
ShowInViewForms (optional) Indicates whether the field should be shown on a view form. The default is TRUE.
Group (optional) A group name allowing you to group fields together.

Step 4 - Deploy the feature

In my sample, I have inserted a post build event into the project properties which copies the feature to the 12 hive.  This is simply for demonstration purposes and you should provision your features correctly using a site definition.

Step 5 - Provision and Activate the feature

The next step is to actually deploy the feature and then activate the feature on a site
  1. Open the command console. Start, Run, cmd.exe\
  2. (OPTIONAL)Create an environment variable to the STSADM.EXE by typing
    SET STSADM=C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\BIN\STSADM.EXE
  3. Install the feature by typing the following command:
    STSADM -o installfeature -filename Grounding.Demo.SiteColumn\feature.xml -force
  4. Open your web site
  5. Click Site Actions
  6. Click Site Settings.
  7. Click  Site collection features under Site Collection Administration.
  8. Activate the Grounding Demo - Provision Site Column feature
Note you could have activated the feature using stsadm -o activatefeature

Step 6 - Verify the site columns exist

Now the feature is activated, verify the column exists
  1. Open your web site (should still be open).
  2. Click Site Actions
  3. Click Site Settings.
  4. Click Site columns under Galleries Scroll down to find the column


  1. Good post. This helped me a lot

  2. Thanks for the detail explanation. Would love to see more of this kind!