As a SharePoint implementor, I am often confronted by administrators, even very sophisticated ones, who refuse to accept the changes that are part of adopting a new knowledge management platform.  There are many reasons for this mindset: they might have unsuccessfully implemented some inferior technology in the past; they might have met with a lot of resistance from their users when they tried to deploy some new system in the past; and most frequently, they have not taken the time to plan a change management strategy for releasing a new system or features.

Recently, a client told that they weren't letting their users use web parts and web part pages as part of their SharePoint implementation.  The result was that their departments were using horribly kludgey techniques for storing and exposing documents and information that would only serve to lower satisfaction and cripple adoption and uptake.

For example, rather than using a SharePoint task list to track "to-do's", they created a document library, with folders for each user in a department, into which the users would upload a Word document with daily, weekly and monthly objectives.  "So what?" you might ask - they are following established processes that are familiar and comfortable.

The consequence is that the end user now has one more process to follow with absolutely no improvement in productivity to the enterprise.  Not only does the end user have to still maintain the Word document, but now he or she has to synchronize that document with one that is SharePoint.  To view the list, one has to navigate to the folder in the document library and open the file in Word.  It's obviously easier for the user to manage the same file offline with the document on their own desktop.  Even if you just manage the online version, you STILL have to incur the additional step of opening the document in Word just to view its contents.

Doing it the SharePoint way, the user could navigate to an individual or shared Task list, add to or update the list at any time, broadcast that change through SharePoint alerts, and have increased visibility into changes to the task list in a web part on a departmental landing page.  Increased visibility and efficiency are why enterprises invest considerable time and money and effort into implementing knowledge management systems.  So why don't they use them?

I think that the answer to this comes in two parts.  One, users and administrators are not aware of how these implementation choices affect the return on investment that they make in their knowledge management systems.  It therefore falls to the consultant to share his or her experiences with different implementations in order educate the client about how best to implement these systems, even though they might feel that they know their users better than the consultant.  Secondly, time and resources must be reserved in project to manage change to the enterprise.  Communication and training of the end user (and often, the administrators) is necessary if everyone is to get on board with a time and money-saving knowledge management solution.

If you are a consultant implementing SharePoint or extending its reach, take the time to remind your client why they are implementing SharePoint and of the value that it can bring to an enterprise by using the breadth of its abilities, rather than familiar paradigms that are already available.  If you are an end user or an administrator seeking the advice of an experienced consultant, try and leverage that experience because it is entirely possible that the consultant has been in situations like yours where reluctance to embrace new technologies and new processes have resulted in long-term pain.

- g

I'm sitting at a chain coffee shop in my home town of Edmonton, the day after doing a technical presentation to a large enterprise client about SharePoint technology and best practices.  Whenever I find myself in such a situation, I feel a little apprehensive at first because I never know what level of complexity and detail and challenge I'll be met with.  However, almost always, that apprehension gives way to the thrill and excitement of sharing experiences in technology with other enthusiasts - comparing field notes if you will in the exploration of the knowledge management landscape.

There was a pretty good attempt at an ambush yesterday that I think I managed to avoid!  I raised the subject of automated deployments in response to a challenge the client was having resolving crawl issues that were working differently in development environements and staging and production environments.  Currently, the client is using MSBuild to create MSI packages to deploy code updates, and I recommended using NAnt because it seems to me to offer more flexibility and fewer opportunities for introduction of errors from the developer's machine to the produciton server.  Since no one in the room indicated that they had used NAnt, and a couple of people pressed me a little harder on the subject, I elaborated on the benefits of NAnt:

• that build scripts can be segmented to rapidly implement small changes that allow a developer to quickly test and debug changes to code;
• scripts can be chained together so that the same steps that were used to verify the working code are used to deploy the code - no potential for introduciton of transcription errors because it's the same script;
• scripts can reference static config files that reside on each deployment environment to accomodate changes between environments separately from changes in the deployment script;
• NAnt scripts can be readily stored and versioned in source control;
• If you don't have the deployment command that you want, you can very quickly generate a NAnt extension command that can wrap the funciton you need.

The punchline to this rather academic comparison of the advantages of NAnt to MSBuild is that after the presentation, I had a chance to walk with some of the group back to their offices to visit an old friend of mine.  On the way there, the scamp who had asked me to elaborate on the NAnt proposition admitted that he had already created NAnt deployment scripts for his own use to enable continuous integration testing!!!

I guess it goes to show you that good ideas travel faster than speakers who try and spread them!

I'm working on a POC for [a major national client] using the Business Data Catalogue feature for MOSS.  We are also developing a webservice from [a major enterprise CRM solution] (in .NET) to expose contract data that the client would like to have searchable from MOSS.  I haven't found too many resources to support BDC design and development, and much of what there is is fairly academic and works with communicating directly with databases rather than through webservices (except for this excellent one [1])  With some pain, I learned this one piece of design advice that I think is pretty important to share, especially since I have found more questions than answers in Googling my problems online.

Basically, the BDC is a connector that employs a Application Definition File (ADF) written in eXtesible Markup Language (XML), often employing some Single-Sign-On (SSO) authentication scheme, to request and return data from a remote source not directly associated with MOSS. 

While it is still early in my investigation, there is one important piece of information that should be considered in designing a webservice that is to be consumed by BDC.  System.Web.Services will automagically serialize typed objects to XML that will describe complete entities  as return objects from your webservice.  The mistake that we initiailly made in our quick and dirty first draft of the webservice was to retrieve the data we wanted from our legacy database, and then just stringbuild a response to be returned and express it with an XML content type.  This didn't work very well because the stringbuilder could be easily escaped and corrupted by concatenation of unusual characters or by URLencoding the "<" and ">" symbols that described our XML elements.  More imporrtantly, the SOAP envelope for our webservice methods declared that the response object would be XML, but gave no instructions on what the response object's schema would look like.  As an additional erroneous step, we instead tried to return an XmlDocument, which, while well-formed and far more reliable an approach to encoding XML, was still not illustrative of the contents that it was returning.  I first noticed this when I looked at the SOAP wrappers that present themselves when browsing the .ASMX:

HTTP/1.1 200 OK

Content-Type: text/xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

  <soap:Body>

    <GetSomeListBySomethingResponse xmlns="http://www.mydomain.com/">

      <GetSomeListBySomethingResult>xml</GetSomeListBySomethingResult>

    </GetSomeListBySomethingResponse>

  </soap:Body>

</soap:Envelope>

Wow - you mean I'm sending you a request and you're going to send me a result of type "xml"?  Fantastic!  Well, not so much actually.  The real problem in my particular case was then when I employed the Business Data Catalogue Definition Utility (included with the SharePoint Server 2007 SDK [2]) to analyze the webservice, the return object, in my case, a collection of typed objects that I wanted to handle, was not recognizable as any kind of a "typed" object at all - all that I could reliably say about the response that it would be an XmlNode.

Properly speaking, I could probably have just manually constructed the entity definitions that I needed, but managing and maintaining these relationships would have been pretty tedious and using the tool allows one to manage schema changes quickly and to redeploy with a reduced amount of fuss.  I was hoping for that level of convenience and maintainability, rather than having to reconstruct all of the typing manually.

What makes this process much simpler (and perhaps what should have been made more explicit in some examples) is that in the webservice can return collections of class objects rather than XmlDocuments or strings.  So for example, if you have a webservice to fetch a customer record from a database, you would create a class file with all the declarations of the properties that make up a "customer" entity, and when you return your results, create a collection of customer entities (e.g. Customer[] customersToReturn = new Customer[upperbound]; ).  You can easily verify that your object typing is providing meaningful semantic information by re-checking the SOAP wrapper:

HTTP/1.1 200 OK

Content-Type: text/xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

  <soap:Body>

    <GetSomeListBySomethingResponse xmlns="http://www.mydomain.com/">

      <GetSomeListBySomethingResult>

        <TheObjectIWant>

          <FirstProperty>string</FirstProperty>

          <SecondProperty>string</SecondProperty>

        </TheObjectIWant >

        <TheObjectIWant >

          <FirstProperty>string</FirstProperty>

          <SecondProperty>string</SecondProperty>

        </TheObjectIWant >

      </GetSomeListBySomethingResult >

    </GetSomeListBySomethingResponse >

  </soap:Body>

</soap:Envelope>

Notice that now, the typing that describes our entities is described in the envelope - handy, right?  The BDC Definition Utility will now properly parse the result as a typed object that will inform the BDC of the typing of your elements, and this will allow SharePoint to use or index or otherwise handle the responses from your legacy system without manual configuration.

So once you return properly typed XML-serialized values, the whole job or configuring your ADF becomes much less mysterious and frustrating.... but not completely so...  but that's for another blog post.

- g

[1] http://www.microsoft.com/downloads/details.aspx?FamilyID=6d94e307-67d9-41ac-b2d6-0074d6286fa9&DisplayLang=en

[2] http://blah.winsmarts.com/2007-4-SharePoint_2007__BDC_-_The_Business_Data_Catalog.aspx