Understanding IncludeMandatoryColumns and SharePoint’s Web Services…

For a while now this has baffled me and several other people I know whom use SharePoint’s web services religiously.  The problem starts with incorrect documentation and since it has never been updated, new people to SharePoint continue to have issues with <IncludeMandatoryColumns>.  This post should give some clarity into what to expect when using this…

<IncludeMandatoryColumns>False</IncludeMandatoryColumns>

When setting this to option to: False; you’d expect a whole bunch of columns to not show up in the results of the XML.  That’s just, well: FALSE.  The only thing that changes in your data set is the Title column.  Nothing more, nothing less…  Here’s a sample data set that was retrieved using SPServices (which btw, you should use for all of your web service interactivities).

<!-- Mandatory Columns = False -->
<rs:data ItemCount="1">
   <z:row ows_MyDollars='567890.000000000' ows_Boolean='1' ows_MultiSelectLookup='' ows_ID='404' ows__ModerationStatus='0' ows__Level='1' ows_UniqueId='404;#{2541C25E-1D9A-4480-8F97-570B64077E37}' ows_owshiddenversion='3' ows_FSObjType='404;#0' ows_Created='2012-02-06 13:55:17' ows_PermMask='0x7fffffffffffffff' ows_Modified='2012-02-06 16:17:24' ows_FileRef='404;#mySite/Lists/GrandChild/TestFolder/TestSubFolder/MovedItem' />
</rs:data>

Did you notice the owsHiddenVersion in the XML?  According to the documentation, it should not be there.  For posterity, here’s a screenshot of the parameters passed to SPServices. If you are keen, you’ll notice my <ViewFields> do not contain the Title column:

<IncludeMandatoryColumns>True</IncludeMandatoryColumns>

So being coy and after a few trial and errors, I decided that <IncludeMandatoryColumns> had to be related to the required fields within the list.  Since Title was the only required field, it seemed like a logical step.  Within this list, I have a column called Hyperlink.  I decided to make that required.  Notice in my <ViewFields>, Hyperlink is not present nor is Title for that matter.

<!-- Mandatory Columns w/ 2 columns required -->
<rs:data ItemCount="1">
   <z:row ows_MyDollars='567890.000000000' ows_Boolean='1' ows_MultiSelectLookup='' ows_ID='404' ows__ModerationStatus='0' ows__Level='1' ows_Title='InSubFolder' ows_UniqueId='404;#{2541C25E-1D9A-4480-8F97-570B64077E37}' ows_owshiddenversion='4' ows_FSObjType='404;#0' ows_Created='2012-02-06 13:55:17' ows_PermMask='0x7fffffffffffffff' ows_Modified='2012-02-07 20:12:48' ows_FileRef='404;#mySite/Lists/GrandChild/TestFolder/TestSubFolder/MovedItem' />
</rs:data>

Is that ows_Title that I see?  Why yes, YES IT IS! As a matter of fact, it’s the only thing that’s different from the two sets of XML.

What have we learned?

<IncludeMandatoryColumns>True</IncludeMandatoryColumns> += Title. If Title is already in your <ViewFields>, then you’ll get nothing new. Yes, I know ID is in my <ViewFields> in the examples above.  Nothing changes except Title.

The documentation on MSDN is invaluable, however, it must be used with caution.  I’ve been running into a few whammies, gotchas, kablooey your code is busticated situations while building roboCAML.  The SP Namespace is another beast altogether, but that’s not what this post is about… yet.