Jardalu Inc

SPD (WCF connection) - Cannot find any matching endpoint

2010-05-18T08:22:00.000-07:00

When adding a WCF connection to SPD 2010, you will hit "Cannot find any matching endpoint configuration" error, if you did not know the service endpoint URL (see figure 2).

Figure 1: Cannot find any matching endpoint.

Figure 2: WCF connection properties

If you look into the SharePoint ULS logs, you will see a corresponding error message "Could not initialize the endpoint components".

If you are connecting to ASMX based web service, the "Service Endpoint URL" is the ASMX service url. For example, if the ASMX service is hosted at http://myserver/service.asmx then the values for "Service Metadata URL" and "Service Endpoint URL" are as follows -

Service Metadata URL - http://myserver/service.asmx?wsdl
Service Endpoint URL - http://myserver/service.asmx

If you are connecting to WCF service, these values can get interesting. Now with WCF service, the service may not expose metadata endpoint, can expose WSDL endpoint or can expose MEX endpoint.

a) Metadata endpoint not exposed

When the metadata endpoint is not exposed by the WCF service, SPD (BCS) cannot consume that WCF service.

b) Metadata endpoint exposed as WSDL

When the WCF service exposes metadata as WSDL, its "Service Endpoint URL" can be determined by looking in the WSDL. Simply load the WSDL in the web browser ( http://myserver/service.svc?wsdl) and search for soap12:address in the WSDL. Typically it will appear in the end of the WSDL (see figure 3).

<wsdl:service name="Service">
<wsdl:port name="WSHttpBinding_IService" binding="tns:WSHttpBinding_Service">
<soap12:address location="http://myserver/Service.svc" /> 
<wsa10:EndpointReference>
<wsa10:Address>http://myserver/Service.svc</wsa10:Address> 
<Identity xmlns="http://schemas.xmlsoap.org/ws/2006/02/addressingidentity">
<Spn>host/myserver.com</Spn> 
</Identity>
</wsa10:EndpointReference>
</wsdl:port>
</wsdl:service>

Figure 3: Service Endpoint URL in WSDL

There can be more than one soap address in the WSDL, if the service exposes different bindings for these addresses. Depending on your requirement you can choose one of the service address.

c) Metadata endpoint exposed as MEX

When the metadata is exposed as MEX, you will need to read the endpoint addresses using svcutil.exe (http://msdn.microsoft.com/en-us/library/aa347733.aspx). When you execute svcutil.exe against the MEX endpoint, it will generate a config file. In the config file, search for "client" tag (it appears at the end of config file). Look at the addresses for the endpoint.

<client>
  <endpoint address="http://myserver/service.svc/basicHttpBinding"
                binding="basicHttpBinding" bindingConfiguration="MyService"
                contract="IServiceInterface" name="ConsoleService" />
</client>

Figure 4: Service Endpoint URL through MEX endpoint

The addresses mentioned in the config file are the "Service Endpoint URL" that SPD will understand.

Secure Store and .Net Connectivity Assembly

2010-05-11T21:46:00.001-07:00

Awesome post at BCS blog which shows how to use Secure Store API.

http://blogs.msdn.com/bcs/archive/2010/05/11/how-do-i-leverage-secure-store-from-within-my-net-connectivity-assembly.aspx

Writing Custom Connector for BCS

2010-03-05T11:43:00.000-08:00

BCS in SharePoint 2010 provides following connectors - Database, WebService, WCF, .NET and custom connector. This blog explains how you can write and deploy your own custom connector, if one of the BCS connectors do not meet your requirements.

This documentation (http://msdn.microsoft.com/en-us/library/ee554911(office.14).aspx) explains when to use .NET assembly connector and when to write your own custom connector.

Assuming that you are required to write your own custom connector, lets look at the steps to achieve the goal.

The steps for custom connectors are

Write code for custom connector
Deploy custom connector in SharePoint
Write model for custom connector

Writing Custom Connector

Writing custom connector requires implementing ISystemUtility (http://msdn.microsoft.com/en-us/library/microsoft.businessdata.runtime.isystemutility(office.14).aspx) interface. The simple most custom connector requires implementing ExecuteStatic method in the interface. Other methods/properties can be boiler plate code.

Here is the simple most custom connector. Although the connector does not do anything, technically it can be deployed in SharePoint 2010.

using System;
using System.Collections;
using System.Collections.Generic;

using Microsoft.BusinessData.MetadataModel;
using Microsoft.BusinessData.Runtime;
using Microsoft.BusinessData.Infrastructure;

namespace SharePointConnector
{
    public class Connector : ISystemUtility
    {

        #region ISystemUtility Members

        public IEnumerator CreateEntityInstanceDataEnumerator(object rawStream, 
            ISharedEntityState sharedEntityState)
        {
            // implement your enumerator
        }

        public IConnectionManager DefaultConnectionManager
        {
            get { return null; }
        }

        public ITypeReflector DefaultTypeReflector
        {
            get { return null; }
        }

        public void ExecuteStatic(IMethodInstance mi, 
            ILobSystemInstance si, 
            object[] args, 
            IExecutionContext context)
        {
            // implement your logic
        }

        #endregion
    }
}

Figure 1: Simple most custom connector

Let's take a look at the various methods and properties in the ISystemUtility interface.

CreateEntityInstanceDataEnumerator

This method converts line-of-business data stream into an enumerator of raw AdapterObjects. Implementing this method is necessary. If your connector gets IEnumerable as raw stream, you can just return the corresponding enumerator from the method.

DefaultConnectionManager

This property allows you to manage connections for your external system. You can return null if you don't want connection management. BDC (Business Data Connectivity) will use its own default connection manager.

DefaultTypeReflector

This property allows you manage the type reflection for your objects. For example, if your external system returns stream, BDC will unable to do a meaningful type reflection and you will have to write your own type reflection. If your external system returns .NET types than you don't need to provide any type reflection. For default implementation this property should return null.

ExecuteStatic

This method is the most important method in the interface. In the method, you should implement CRUDQ (create, read, update, delete and query) stereotypes for the connector.

public void ExecuteStatic(IMethodInstance mi, 
            ILobSystemInstance si, 
            object[] args, 
            IExecutionContext context)

Lets take a look at the method parameters

mi : This parameter represents the MethodInstance that is being executed by BDC. This parameter corresponds to the

<MethodInstance>

element with the LobSystem/Entity/Method in the BDC metadata model.

si : This parameter represents the LobSystemInstance the method instance is being executed against. This parameter corresponds to the

<LobSystemInstance>

element with the LobSystem in the BDC metadata model.

args : This parameter is the Parameters of the MethodInstance that is being executed. The last item in the array is reserved for the return parameter for the method instance.

context : This parameter sets the execution context of BDC. For all practical purposes this parameter can be ignored because External List in SharePoint does not set the execution context and you or BDC will not control this variable. The context can be different for BDC running under Office client.

Ok, now that we understand ISystemUtility interface, lets do some fun stuff.

Sample
In this sample, I will create a custom connector that will return "Movie" entity from an external system. For simplicity, the connector will support only "Finder" and "SpecificFinder" stereotypes. This sample will use in-memory data (external system).

Since the external system returns .NET types, implementation of the custom connector is simple.

public IEnumerator CreateEntityInstanceDataEnumerator(object rawStream, 
    ISharedEntityState sharedEntityState)
{
    IEnumerable enumerableStream = rawStream as IEnumerable;
    if (enumerableStream != null)
    {
        return enumerableStream.GetEnumerator();
    }

    throw new InvalidOperationException("not valid stream returned");
}

Figure 2: CreateEntityInstanceDataEnumerator implementation

In the method CreateEntityInstanceDataEnumerator, the base Enumerator is returned. Off course, for a real external system you may have to write an enumerator.

ExecuteStatic method will check what kind of stereotype is being executed and will execute corresponding methods on the external system. As said before, this connector just supports Finder/SpecificFinder stereotype, so it will throw for other stereotypes.

public void ExecuteStatic(IMethodInstance mi, 
    ILobSystemInstance si, 
    object[] args, 
    IExecutionContext context)
{
    // provide only read functionality
    switch(mi.MethodInstanceType)
    {
        case MethodInstanceType.SpecificFinder:

            IParameterCollection parameters = mi.GetMethod().GetParameters();

            // make sure there is only one input parameter for the method
            // and one return parameter.
            if (parameters.Count != 2 )
            {
                string message = "Method " + mi.GetMethod().Name +" must have one input and one return parameter";
                throw new InvalidMetadataObjectException(message);
            }

            // check if the input parameter is integer type
            // and the return parameter is "Movie" type
            Type param1Type = Type.GetType(parameters[0].GetRootTypeDescriptor().TypeName, false);
            Type param2Type = Type.GetType(parameters[1].GetRootTypeDescriptor().TypeName, false);

            if ( param1Type == null || param1Type != typeof(Int32))
            {
                string message = "Method " + mi.GetMethod().Name +" must contain input of type System.Int32";
                throw new InvalidMetadataObjectException(message);
            }

            if ( param2Type == null || param2Type != typeof(Movie))
            {
                string message = "Method " + mi.GetMethod().Name +" must contain input of type " + typeof(Movie).ToString();
                throw new InvalidMetadataObjectException(message);
            }

            int id = (int)args[0];
            args[1] = MovieData.GetMovie(id);

            break;

        case MethodInstanceType.Finder:
            args[args.Length-1] = MovieData.GetMovies();
            break;

        default:
            throw new NotImplementedException();
    }
}

Figure 3: ExecuteStatic implementation

The method verifies the Finder/SpecificFinder signature in metadata model. This way the connector can ensure that the metadata model is not invalid. Finally it executes the external system and sets the return value in args parameter.

I have attached complete source code at the end of this post.

Deploying Custom Connector in SharePoint

Deploying custom connector in SharePoint 2010 is pretty straight forward. All you need is to GAC the assembly in all the SharePoint machines. This includes web-front ends as well as application servers in the farm. If you have the requirement to execute custom connectors on Office client ( take External List to Outlook or Workspaces ) you will need to GAC the assembly in client machines as well.

Writing Models for Custom Connector

Now that you have written the custom connector and have already deployed in the SharePoint, lets get a sample external list for the custom connector.

The LobSystem Type for custom connector must specify "Custom". When custom connectors are used, the model must contain the SystemUtilityTypeName property for LobSystem.

<LobSystems>
    <LobSystem Type="Custom" Name="CustomLobSystem">
      <Properties>
        <Property Type="System.String" Name="SystemUtilityTypeName">SharePointConnector.Connector, SharePointConnector, Version=1.0.0.0, Culture=neutral, PublicKeyToken=dc97b363e814985e</Property>
      </Properties>

Figure 4: LobSystem properties for custom connector

SystemUtilityTypeName is the fully qualified name for custom connector type. The following figure shows snippet of the metadata model.

Figure 5: Metadata model snippet for custom connector

The sample metadata model is also attached in the source code (see end of post).

Custom connector in action

Now that we have our metadata model for custom connector, lets fire it up in the SharePoint. The following screen shots show the external list running against custom connector.

Figure 6: Choosing external content type

Figure 6 shows the external content type displayed for custom connector. At this point the custom connector is not being executed.

Figure 7: Finder stereotype executed in custom connector (via External list)

Figure 8: SpecificFinder stereotype executed in custom connector

Figure 7 and Figure 8 shows Finder and SpecificFinder stereotyped operations running in custom connector. Our custom connector executes the external system methods and returns appropriate data.

Source Code

Sample with complete source code can be downloaded from here.

As-is
The source code/software is provided "as-is". No claim of suitability, guarantee, or any warranty whatsoever is provided. Source Code and executable files can not be used in commercial applications.

SharePoint - Non root site collection caution

2010-03-01T02:24:00.000-08:00

SharePoint allows one to create non root site collection without having a root site collection. For example, you can create a site collection as "http://sharepoint/sites/" without having any site collection at "http://sharepoint".

Caution : Even though SharePoint does not prevent you creating a non-root site collection without a root site collection, not having a root site collection is not a supported configuration. Some SharePoint features break without a root site collection.

Client OM (Microsoft.SharePoint.Client) Samples for SharePoint 2010

2010-01-24T03:48:00.000-08:00

SharePoint 2010 introduces a new client side object model for retrieving data from SharePoint. The client OM is included in Microsoft.SharePoint.Client.dll and Microsoft.SharePoint.Client.Runtime.dll. Library reference for client OM is at http://msdn.microsoft.com/en-us/library/ee536622(office.14).aspx

Client OM is counterpart to the Server OM with notable differences

Client OM works on both on SharePoint server and client
Client OM does not fetch data implicitly
Client OM is supported for .NET as well as for ECMA (javascript etc)

The essence of the Client OM lies in ClientContext class ( Microsoft.SharePoint.Client.ClientContext ). This class allows you to get connected with the SharePoint server and then fetch data as required.

In this blog, I will covering few samples on how to use the Client OM.

Basics

First you will need to reference Microsoft.SharePoint.Client.dll and Microsoft.SharePoint.Client.Runtime.dll and then use Microsoft.SharePoint.Client namespace.

using Microsoft.SharePoint.Client;

To connect to the SharePoint server, you will need SharePoint URL and create a ClientContext object.

ClientContext context = new ClientContext("http://sharepoint");

At this moment the client context for SharePoint is defined but no connection has been made. Now lets initialize the Web object (equivalent to SPWeb in Server OM).

Web web = context.Web;

To connect/fetch data from the SharePoint, ExecuteQuery needs to be call on ClientContext object.

context.ExecuteQuery();
Console.WriteLine("Web '{0}' [Id:{1}]",web.Title, web.Id);

If you run the above code, it will throw PropertyOrFieldNotInitializedException exception with following message

The property or field has not been initialized. It has not been requested or the request has not been executed. It may need to be explicitly requested.

The code throws exception because client OM does NOT fetch data implicitly. So, we will modify the code to fetch the data the data explicitly. Since we are only interested in Id and the Title of the Web, the code will explicitly request those data. Retreive method in the Web class to tell the client OM which data needs to be fetched. The complete code will look like

ClientContext context = new ClientContext("http://sharepoint");
Web web = context.Web;
web.Retrieve(
    WebPropertyNames.Id,
    WebPropertyNames.Title
);
context.ExecuteQuery();

Console.WriteLine("Web '{0}' [Id:{1}]",web.Title, web.Id);

The above code will print the title and the id for the Web.

ClientObject class is the base class for all Client OM object. ClientObject exposes the following important methods that code will use again and again.

IsPropertyAvailable(string propertyName) - Returns a flag that indicates whether the specified property has been retrieved or set, or has not been retrieved or set.
Retreive() - Retreives all properties associated with the object
Retreive(params string[] propertyNames) - Retreives the specified properties associated with the object

All classes deriving from ClientObject class has a property names class ( for example, Web class has WebPropertyNames class ) which tells what properties can be fetched for the object.

Sample 1: Get all lists in web

The following sample will get all the lists in a web. For the list, the code will fetch the list id, list title and the type of the list.

public void GetAllList()
{
    ClientContext context = new ClientContext("http://sharepoint");
    ClientObjectPrototype allListsPrototype = context.Web.Lists.RetrieveItems();
    allListsPrototype.Retrieve(
        ListPropertyNames.Title,
        ListPropertyNames.Id,
        ListPropertyNames.BaseType);
    context.ExecuteQuery();

    foreach (SPClient.List list in context.Web.Lists)
    {
        Console.WriteLine("List : {0}, Id: {1}, BaseType : {2}", list.Title, list.Id, list.BaseType);
    }

}

Sample 2: Get list details
In this sample, given a list the code gets the details for the list. The details include the Fields and Views of the list.

public void GetListDetails(string listName)
{
    ClientContext context = new ClientContext("http://sharepoint");
    List list = context.Web.Lists.GetByTitle(listName);            

    // get fields name and their types
    ClientObjectPrototype allFieldsPrototype = list.Fields.RetrieveItems();
    allFieldsPrototype.Retrieve( FieldPropertyNames.Id,
        FieldPropertyNames.Title, 
        FieldPropertyNames.FieldTypeKind);

    // get view title
    ClientObjectPrototype allViewsPrototype = list.Views.RetrieveItems();
    allViewsPrototype.Retrieve(
        ViewPropertyNames.Id,
        ViewPropertyNames.Title);

    context.ExecuteQuery();

    foreach (Field field in list.Fields)
    {
        Console.WriteLine("Field '{0}', Type : {1}", field.Title, field.FieldTypeKind);
    }

    ViewCollection views = list.Views;
    foreach (View view in views)
    {
        Console.WriteLine("View '{0}', Id : {1}", view.Title, view.Id);
    }

}

Sample 3: Get list items
The following code gets the list items in the given list.

public void GetListItems(string listName)
{          
    // build the CAML query to get ALL items
    CamlQuery query = new CamlQuery();
    query.ViewXml = "";

    ClientContext context = new ClientContext("http://sharepoint");
    List list = context.Web.Lists.GetByTitle(listName);
    ListItemCollection items = list.GetItems(query);
    items.RetrieveItems().Retrieve();
    context.ExecuteQuery();

    foreach (ListItem item in items)
    {
        // assumes that the list has a field with name 'Title'
        Console.WriteLine("Item : {0}, Id : {1}", item.FieldValues["Title"], item.Id);
    }
}

Sample 4: Add item to a list
The following code adds a list item in the given list.

public void AddItemToList(string listName)
{
    ClientContext context = new ClientContext("http://sharepoint");

    List list = context.Web.Lists.GetByTitle(listName);
    ListItemCreationInformation lic = new ListItemCreationInformation();
    ListItem item = list.AddItem(lic);

    //add the item information
    item["Title"] = "Adding a new Item";

    // List has a field name Checkbox which is a checkbox type field
    item["Checkbox"] = true;  

    item.Update();
    item.Retrieve(ListItemPropertyNames.Id);

    context.ExecuteQuery();

    Console.WriteLine("Id : {0}", item.Id);

}

Client OM is very useful however it takes time to understand how to use the API and get the best out of it. Enjoy !!

Reading BDC model properties in .NET Assembly Connector

2010-01-22T23:28:00.000-08:00

Introduction

BDC in SharePoint 2010 support connectors for "Web Service", "Wcf Service", "Database", ".NET Assembly" and "Custom". ( BDC in MOSS 2007 has support for "Web Service" and "Database" only ).

.NET Assembly Connector basically allows to host a virtual LobSystem. The concept for .NET assembly connector is very similar to my suggestions of hosting .NET assembly in MOSS 2007 - BDC : Beyond Web-Service and Database. Since .NET assembly is natively supported in SharePoint 2010, it has way more capabilities than my suggested approach. The following article (http://msdn.microsoft.com/en-us/library/aa868997.aspx) explains how to create a .NET Assembly Connector in BDC.

This blog explains how you can use BDC model properties within your .NET assembly code.

IContextProperty Interface

To use the BDC model in the .NET assembly, lets first take a look at the IContextProperty interface [r1]. IContextProperty interface is defined in Microsoft.BusinessData.SystemSpecific namespace ( in Microsoft.BusinessData.dll )

namespace Microsoft.BusinessData.SystemSpecific
{
    public interface IContextProperty
    {
        IExecutionContext ExecutionContext { get; set; }
        ILobSystemInstance LobSystemInstance { get; set; }
        IMethodInstance MethodInstance { get; set; }
    }
}

Figure 1: IContextProperty interface

.NET assembly connector in BDC uses IContextProperty interface to communicate the context in which BDC is executing the method in the class. If your class implements IContextProperty interface, BDC will initialize the three properties of the interface. Here is an example how you can write your class to implement the interface.

using Microsoft.BusinessData.SystemSpecific;

namespace MyNamespace
{
    public class MyClass : IContextProperty
    {
        private IExecutionContext context;
        private ILobSystemInstance lobSystemInstance;
        private IMethodInstance methodInstance;

        #region Implementing IContextProperty interface

        public IExecutionContext ExecutionContext 
        { 
            get { return this.context; } 
            set { this.context = value; }
        }

        public ILobSystemInstance LobSystemInstance
        { 
            get { return this.lobSystemInstance; } 
            set { this.lobSystemInstance = value; }
        }

        public IMethodInstance MethodInstance
        { 
            get { return this.methodInstance; } 
            set { this.methodInstance= value; }
        }

        #endregion
    }
}

Figure 2: IContextProperty implementation

At this time "MyClass" class is ready to get the context from BDC.

Defining properties in BDC Model

Depending on what kind of information you need in the .NET code, you can define your property at appropriate element in the BDC model. For example, if your class needs to connect to different server for different region, LobSystemInstance would be a good place to define your property. In the case method needs to know which Locale is preferred by the user, it can look into the properties of Method or MethodInstance.

In this example, the class connects to a different database server based on which region the code is getting executed.

private string GetDbConnectionString(string region)
{
    string dbConnectionStringFormat = "Data Source={0};Initial Catalog=myDataBase;Integrated Security=SSPI;";
 
    // default DB Server
    string regionDbServer = "northamericaDBServer"; 

    if (region == "emea")
    {
        regionDbServer = "emeaDbServer";
    }
    else if (region == "asia")
    {
        regionDbServer = "asiaDbServer";
    }

    return string.Format(dbConnectionStringFormat, region);
}

Figure 3: Customize connection string

The above code relies on the region information to format DB connection string. Unfortunately, when the code gets executed in SharePoint, the method has no idea where it is being executed and would default to using north america db server.

To solve this issue, you can define a property in the BDC model which tells the code which DB server to use. Lets say the property name is "Region" and is defined within the LobSystemInstance.

<LobSystemInstances>
  <LobSystemInstance Name="NorthAmerica">
    <Properties>
      <Property Name="Region" Type="System.String">northamerica</Property>
    </Properties>
  </LobSystemInstance>
  <LobSystemInstance Name="Default">
    <Properties>
      <Property Name="Region" Type="System.String">northamerica</Property>
    </Properties>
  </LobSystemInstance>
  <LobSystemInstance Name="EMEA">
    <Properties>
      <Property Name="Region" Type="System.String">emea</Property>
    </Properties>
  </LobSystemInstance>
  <LobSystemInstance Name="Asia">
    <Properties>
      <Property Name="Region" Type="System.String">asia</Property>
    </Properties>
  </LobSystemInstance>
</LobSystemInstances>

Figure 4: BDC model properties

In this example, different LobSystemInstances are used for each region, where the "Region" property is defined in LobSystemInstance. This is particularly useful when the user creates an external list. The user can choose the appropriate LobSystemInstance depending on its region.

Reading properties in the method

So now that the properties are defined in the model, its time to read the property in the code. The class "MyClass" exposes a method ReadAllItems for Finder stereotype. In this method, LobSystemInstance property returns the LobSystemInstance (BDC context). LobSystemInstance.GetProperties() method returns all the properties defined for the LobSystemInstance.

public MyItems ReadAllItems()
{
   // get the LobSystemInstance properties via context from BDC
   INamedPropertyDictionary properties = this.LobSystemInstance.GetProperties();

   string region = null;

   // search for "Region" property in model
   if (properties.ContainsKey("Region"))
   {
        region = properties["Region"] as string;
   }

   //get the db connection string
   string dbConnectionString = GetDbConnectionString(region);

   //do normal db processing
   //return the items for method

}

Figure 5: Use the BDC model property

Once we have all the properties, the code checks if the "Region" property has been defined or not and reads the "Region" property accordingly. Once the Region property is read, it is used to create the DB connection string and the DB query is executed against that particular DB server.

Conclusion

BDC model is the right place to define custom properties. These properties should be used in .NET assembly connector code to customize solutions.

References

r1: IContextProperty interface: http://msdn.microsoft.com/en-us/library/microsoft.businessdata.systemspecific.icontextproperty(office.14).aspx

Business Connectivity Services (BCS) - Profile Pages

2010-01-18T00:28:00.000-08:00

Profile Page

A profile page in BCS (Business Connectivity Services) allows to display all the information for an external content (entity instance). For example, a profile page can display all the fields in a record for a specific customer. It can also display all the orders associated with the customer.

NOTE: A profile page is different from user profile. User profile is a SharePoint feature where as profile page is specific to BDC (Business Data Connectivity).

Profile page has a unique url, as each entity (External Content Type) has its own profile page. Profile page in SharePoint 2010 is not created automatically anymore (it was created automatically in MOSS 2007).

If the profile page is not enabled for the entity, clicking on the entity instance will load the view items page.

Figure 1: View item for External Content Type

Figure 2: View Item Page

To create a profile page for an entity, you will need to configure where the profile page will be hosted. To configure, click on the configure button in the BDC administration page/ribbon (figure 3).

Figure 3: Configure profile page button

This loads a wizard where you can enter the host location for the profile page. Profile page can only be hosted on SharePoint sites.

Figure 4: Profile page host

At this time, you can enable your entity to have a profile page. To do so, click on the External content type and click "Create/Upgrade Profile Page".

Figure 5: Create/Upgrade Profile Page

Figure 6: Profile page confirmation

Once the profile page has been created you will notice there is an default action associated with the external content type (figure 7).

Figure 7: Default action

Unfortunately, external list does not allow to go the profile page from the list (hopefully it gets fixed in RTM). To view the profile page load the default action URL in browser and set the ContactID.

Profile page is particularly useful to view entity associations. Figure 8 shows a Contact profile page, where sales order from the contact is displayed along with the contact information.

Figure 8: Contact and its sales order

Links

Adding associations - http://msdn.microsoft.com/en-us/library/ee558417(office.14).aspx
Associations Support in SPD - http://blogs.msdn.com/bcs/archive/2010/01/15/tooling-associations-in-sharepoint-designer-2010.aspx

Secure Store Service - Installation (Farm mode)

2010-01-03T21:46:00.000-08:00

This blog shows how Secure Store Service can be installed in farm mode. Please refer to blog for information on how to install Secure Store Service in standalone mode.

Figure 1, figure 7, figure 9 and figure 12 mentioned in this blog are the figures from "Secure Store Service - Installation" blog.

Server Farm Installation
To install SharePoint in server farm mode, first prerequisites installer needs to be run. After the prerequisite installer has installed all the prerequisites components, start the SharePoint installation (figure 1). Enter the product key in the next screen and then agree to license terms. On the next screen, click the “Server Farm” button (figure 7). This will start SharePoint installation in server farm mode. Setup will present a screen to do a “Complete” install or standalone install. Select “Complete - Install all components” checkbox (figure 21).

Figure 21 : Selection Server Type

Click “Install Now” button. Setup will show installation progress and after the installation is complete, setup will give an option to run the configuration wizard (figure 9). Choose to run the configuration wizard.

When the configuration wizard continues, it will warn about services being stopped (figure 12).

In the server farm mode, the wizard gives an option to create a new server farm or join an existing server farm (figure 22).

Figure 22: Connect to existing or new farm

Choose to create a new server farm by selecting “Create a new server farm” checkbox. Click 'Next' button to continue. Installing SharePoint in farm mode requires a database server where SharePoint stores its configuration and content. In standalone mode, SharePoint installs the database automatically.

Figure 23: Database Settings

In the database settings screen (figure 23), enter the database server, name and the credentials for the domain user which has database creation rights. Click 'Next'. This will bring up the farm passphrase screen (figure 24). To create or join a farm, SharePoint administrator needs a passphrase. Choose a passphrase and store the passphrase in a safe location, as SharePoint does not store the passphrase.

Figure 24: SharePoint Passphrase

Passphrase must meet complexity requirement. If the complexity requirement is not met, wizard will display an error (figure 25) and will let to enter a new passphrase.

Figure 25: Passphrase Complexity Requirement

Once the passphrase has been entered, installation configuration will allow choosing a port on which central administration will be hosted as well as will allow configuring security settings (figure 26).

Figure 26: Central Admin Port and Security Settings

Click 'Next' to continue. Configuration wizard will display the summary of the settings and let you to change any setting if required.

Figure 27: Configuration Summary

At this time, clicking ‘Next’ will start installation in farm mode. After SharePoint has been installed, the wizard will again display the summary. Click 'Finish' in the installation summary.

When SharePoint is installed in farm mode, the wizard will not automatically configure SharePoint, instead it will launch the browser to configure SharePoint (figure 28).

Figure 28: Initial Farm Configuration Wizard

Select “Walk me through the settings using this wizard.” checkbox and click ‘Next’ (figure 28). In the next screen, SharePoint will need an account on which the shared services will run (figure 29). Choose an account which is different than the farm admin account. In the same screen (figure 30), SharePoint will give an option to select the services that will run on the server. Make sure “Secure Store Service” is selected (figure 31).

Figure 29: Service Account

Figure 30: Services

After making sure Secure Store Service is checked, click ‘Next’. The configuration wizard will install and start the services that were selected.

Configuration wizard will also ask to create a site collection. At this time Secure Store Service is already installed on the server. You may choose to create a site collection.

Figure 31: Secure Store Service

In the above figure, Secure Store Service has been installed and started by the configuration wizard.

Secure Store Service - Configuration ( SharePoint 2010 )

2009-12-20T08:47:00.000-08:00

This blog is written for Beta release of SharePoint 2010. As of Beta, Secure Store Service is available on SharePoint 2010 but is not available on SharePoint Foundation.

Secure Store Service (SSS) adminsitration can be done through the central administration of SharePoint. Central adminstration can be started from the Start > Microsoft SharePoint 2010 Products > SharePoint 2010 Central Adminstration ( see image 1 ).

In the Central Administration page, click Manage services on server (within System Settings block ) to load the Services on Server administration. Make sure the Secure Store Service is in Started mode. If the service is not in Started mode, click on Start link for Secure Store Service. This would start the Secure Store Service.

SharePoint 2010 can host mutliple applications of the same type within a farm. Secure Store Service is actually a Shared Service in SharePoint. In the Central Administration, click Manage service applications ( within Application Management block ) to load the service applications page. It shows all the Shared Services Application ( and Shared Services Application Proxy ) within the farm. To create a new Secure Store Application, click on New button and then select Secure Store Service ( see image ). If you have installed SharePoint in standalone mode, there should already be a Secure Store Application with the name "Secure Store Service" running.

In the Create New Secure Store Service Application dialog box, choose appropriate name for your secure store. When creating a secure store, you will need to choose a database server and database where secure store will store its information. Secure Store Service will automatically create database for secure store application . Secure Store Service supports both Windows authentication and SQL authentication for database creation. It is recommended that you use Windows authentication. When windows authentication is used, make sure the farm administrator has DB create permission on the database server.

You will also need to choose a web application pool which secure store will use to host its service. You can choose one of the existing application pools or create a new application pool. For secure store, it is recommended that you always choose a new application pool. When creating a new application pool, choose a managed account which will be the owner of the application pool. Since secure store stores confidential information, always choose a managed account which is a non-interactive account ( account that does not have login privileges ). The account that is used in secure store application pool can decrypt confidential information from secure store database, so you should be very careful in choosing the account. Click OK to create the application.

Once the secure store application has been created ( or pre-existing application with Standalone installation ), you will need to set a passphrase for the application. This done by clicking on the application link ( Central Administration > Manage service applications ). This will bring the secure store application adminstration page.

Click on "Generate New Key" to generate a new key for secure store application. Every secure store application needs a key to encrypt/decrypt the stored information in database.

When generating a new key, you will need to supply a pass phrase. Pass phrase is used by secure store to protect the key itself. Pass phrase must be atleast 8 characters long, must contain atleast one numberal, one capital alphabet and one special character. This pass phrase is not stored in the secure store, so make sure that you keep a copy of the pass phrase securely.

Now Target applications can be created on secure store. Target application is a secure store concept where the credentials of the users can be grouped together. Within target application you define what kind of information will be stored. For example, you may want to club all user connecting to CRM in one target application.

To start with, you need to define the target application. Fill the information for target application as asked by the screen. Click Next. On the next page, you can define what user information will be stored in the target application. For example, for CRM target application, we will be storing user name, password, system number, client number and language. To add a new field type, click on the "Add Field" link. At the user input time, if you want to mask any field, check the mask checkbox corresponding to the field.

Each target application can be managed by its own administrator. The next page asks you to define an administrator for the target application.

Click OK to finish the creation of the target application. At this time the target application is ready to be consumed by applications such as web-part, external list, etc.

Farm administrator ( or target application administrator ) can now set user credentials/information for this particular target application. To set the user credentials, right click on the target application ( see next image ) to bring the entry form.

The next page will ask you to enter the user credentials for CRM.

Enter the CRM credentials on this page and click OK. This would save the credentials for the Credential Owner ( jardula\usera in the above page ). Note, the credential can be retreived by any application that runs on behalf of the credential owner.

Secure Store does not display the list of the credentials owner for a target application for security reasons. So in other words, there is no way to figure out if a credential has been set for a particular credential owner through Secure Store UI.

Secure Store Service - Installation

2009-12-15T23:39:00.000-08:00

Installation

Secure Store Service installation is done by installing SharePoint 2010. SharePoint can be installed in Standalone mode and Server Farm mode. Secure Store Service is available in both Standalone and Farm configuration.
In standalone configuration, SharePoint 2010 server is installed on one physical machine. Standalone configuration does not allow adding of new servers and thus has limited scaling. This configuration is best for development, test and demo purposes.

In server farm configuration, SharePoint 2010 server can be installed on multiple machines. Server farm configuration allows choosing separate SharePoint database server, web front ends (WFE) and backend (application servers). This configuration also allows adding web front ends and backend to the existing farm.

Requirements

The basic software requirement for SharePoint 2010 is
• 64-bit Windows Server 2008 or 64-bit Windows Server 2008 R2.
• 64-bit SQL Server 2008 or 64-bit SQL Server 2005

To get a complete list of hardware and software requirement visit http://technet.microsoft.com/en-us/library/cc262485%28office.14%29.aspx

Prerequisites Installer

SharePoint 2010 installation comes with a prerequisites installer. To execute the prerequisites installer, double click OfficeServer.exe (Beta release can be downloaded from http://sharepoint2010.microsoft.com/)
This would bring the SharePoint Server 2010 installation screen (figure 1). On the installation screen, click “Install software Prerequisites” link.

Figure 1: SharePoint Server 2010 Installation Screen

Clicking on the “Install software prerequisites” link will display the preparation tool. It displays the list of the software the prerequisites tool will install. Click on Next button.

Figure 2: Prerequisites Installer (Preparation tool)

This would bring the license agreement screen (figure 3). Agree to the license terms (by checking the checkbox) and click Next.

Figure 3: License Agreement

This would install all the perquisites for SharePoint 2010. If there is any error in installing the prerequisites, the tool will display a link to the log file (figure 4).

Figure 4: Error reporting in prerequisites installation

Once the prerequisites have been installed, actual installation of the SharePoint server can be started. Click on “Install SharePoint Server” link (figure 1). It will bring the “Product Key” screen. Enter the product key for SharePoint sever and click continue button (figure 5).

Figure 5: Screen to enter product key

Product key for Beta can be obtained from http://technet.microsoft.com/en-us/evalcenter/ee391660.aspx
Agree to the Microsoft Software License Terms in the next screen by checking the checkbox and click continue button (figure 6).

Figure 6: Agreement to software license and terms

At this time the installer will present you an option to install SharePoint in “Standalone” or “Server Farm” configuration (figure 7).

Figure 7: SharePoint Installation Configuration

Standalone Installation

To install SharePoint 2010 in standalone mode, click the Standalone button. This will start the installation (figure 8) in standalone mode. The installation process can take a while to finish depending on the machine configuration.

Figure 8: SharePoint installation in progress

When the installation is done, it gives an option to run the configuration wizard (figure 9). Configuration Wizard must be run before the SharePoint is useable. Click on Close button to continue the installation.

Figure 9: Configuration wizard

If the checkbox was unchecked and the installation did not continue, the configuration wizard can be started from the Windows Start menu (figure 10). Configuration Wizard can also be used to repair SharePoint installations.

Figure10: Starting configuration wizard

The installation will continue with configuration wizard. The first screen will be a welcome screen, click on Next button to continue.

Figure 11: Welcome screen

SharePoint configuration wizard stops few services in the installation process. It will warn about the services that will be stopped before the installation can continue. Click Yes.

Figure 12: Warning for services being stopped

NOTE: If the configuration wizard was started to repair SharePoint, make sure no one is using the SharePoint; otherwise the site will unavailable till the repair is complete.

When the configuration wizard resumes, it will complete its entire task. Depending on the machine’s configuration, wizard may take several minutes to complete.

Figure 13: Configuration Wizard Continues

At the end of the process, the wizard will display a configuration successful screen.

Figure 14: Successful Configuration

Click on the finish button. The configuration wizard will close and open the explorer to select the template for the site. Chose the template based on the requirement.

Figure 15: Template Selection

When the template has been applied for the site, SharePoint gives an option to set up groups for the newly created site.

Figure 16: Setup Groups

At this time installation and configuration of the site is complete. SharePoint will automatically redirect to the site’s home page.

Figure 17: Site Welcome

In standalone configuration a Secure Store Service is running by default and there will also be a Secure Store application running (default name for the Secure Store is “Secure Store Service”). To check Secure Store Services status, open the SharePoint central administration.

Figure 18: Central Administration

Click on “Manager services on the server” link to check the services status (this link is within System Settings block). The “services on server” page contains the services status from where a particular service can be started or stopped. Make sure Secure Store Service is in started status (figure 19).

Figure 19: Services on SharePoint

In the standalone install, SharePoint will create a default Secure Store Service application with the name “Secure Store Service”. This application can be viewed from Central Administration page (figure 18), by clicking on “Manage service applications” (Application Management block).

Figure 20: Service Applications on SharePoint

The default Secure Store application will be in Started status.

Secure Store Service - Introduction

2009-12-10T00:50:00.000-08:00

Secure Store Service is a shared service in SharePoint 2010 that provides functionality to store credentials [1] securely and associate the credential to a specific identity or group of identities. The main objective of the service is to help SharePoint components and/or custom web-part perform Single Sign-On (SSO)[2].

Consider a scenario where a web-part needs to authenticate with external system (such as database). Off course the web-part can ask the user credential when it loads to authenticate. Although it works fine, the user experience will not be that good. The user experience can be enhanced if the web-part stores the credential. To store the credential, web-part would need a secure storage and would have to provide functionality to manage the credential.

What happens if the user does not have access to the credentials? Instead the credentials are managed by the system administrators? How would the web-part deal with expired credentials?

A simple requirement of web-part authenticating with external system can become an extensive feature. This is where Secure Store can be utilized. SharePoint components such as Business Connectivity Services (BCS), Excel Service, Performance Point Service, Search and other services also use Secure Store to solve authentication issues with external system.

Secure Store Service replaces Microsoft Office SharePoint Server 2007 (MOSS 2007) Single Sign-On feature. The name has rightfully changed from Single Sign-On to Secure Store, as this service does not provide the Single Sign-On functionality. Secure Store is available in SharePoint 2010 and SharePoint 2010 Search however is not available in SharePoint Foundation.

Footnote
[1] Credential: An information (such as username, password) that is verified when presented to a system before the system allows access to its resources.

[2] Single Sign-On: A user can log in once into a system and can gain access to all systems (that he/she has access to) without being prompted to log in to all the systems.

Shared Services in SharePoint 2010

2009-10-27T13:57:00.001-07:00

Shared Service Provider (SSP) in SharePoint 2007 has been replaced by Shared Services in SharePoint 2010. SSP in SharePoint 2007 was confusing and had its share of limitations which SharePoint 2010 seems to solve by introducing Shared Services.

Key differences between SSP and Shared Services

SSP in 2007	Shared Services in 2010
MOSS only	Available in WSS
Different services shared the same db	Services can have its own db
Internal to MOSS	Public APIs to create own Shared Services
Only one application of service	Multiple instances of service allowed
Restricted to the farm	Cross farm support

SharePoint 2010 provides the following Shared Services ( not an exhaustive list )

Access Services : Allows viewing, editing, and interacting with Access databases in a browser.
Business Connectivity Service : Provides read/write access to external data from line-of-business (LOB) systems, Web services, databases, and other external systems. Also available in SharePoint Foundation.
Managed Metadata Service : Provides access to managed taxonomy hierarchies, keywords, social tags and Content Type publishing across site collections.
Secure Store Service : Provides capability to store data (e.g. credential set) securely and associate it to a specific identity or group of identities.
State Service : Provides temporary storage of user session data for Office SharePoint Server components.
Usage and Health data collection : This service collects farm wide usage and health data and provides the ability to view various usage and health reports.
Visio Graphics Service : Enables viewing and refreshing of published Visio diagrams in a web browser.
Web Analytics Service Application : Enable rich insights into web usage patterns by processing and analyzing web analytics data .
Word Conversion Service Application : Provides a framework for performing automated document conversions

SharePoint 2010 and BDC

2009-10-17T08:10:00.000-07:00

Very excited about BDC ( now renamed Business Data Connectivity ) in SharePoint 2010 (http://sharepoint.microsoft.com/2010/Sneak_Peek/Pages/default.aspx).

BDC Model Schema in SharePoint 2010 - http://msdn.microsoft.com/en-us/library/dd921790.aspx

Few exicting new things from BDC
- Full CRUD ( Create, Read, Update and Delete ) support (http://msdn.microsoft.com/en-us/library/dd963707.aspx)
- Support for .NET assemblies :) ( http://msdn.microsoft.com/en-us/library/dd774467.aspx )
- Now supports WCF ( http://msdn.microsoft.com/en-us/library/dd953870.aspx )

Watch for this space.

Custom Web Part using BDC Object Model

2009-03-02T17:06:00.000-08:00

Sharepoint ( MOSS 2007 ) provides two BDC related web parts namely Business Data List Web Part and Business Data Related List Web Part. This blog will demonstrate writing custom web parts that read data through BDC APIs.

In this example a simple web part reads data from BDC APIs and displays it in web part panel. The custom web part (XBdc) is shown in the following figure.

Figure 1 : Custom web part reading data from BDC APIs

To create a custom web part, I will be using Visual Studio 2008 without Visual Studio .NET Extensions for SharePoint 3.0. If you download Visual Studio .NET Extensions for SharePoint, it will be a bit easier. Since extensions are not available ( as of March2009 ) for x64, I will create XBdc Web Part without using extensions.

First create a Visual Studio project of "Class Library" type. Lets name the project "XBdc" for extended BDC. The name is not important and can be anything. After creating the project add references to Microsoft.SharePoint.Portal.dll ( the dll can be found in %system drive%\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\ISAPI folder ).

Figure 2 : Class Library project in Visual Studio

You will also need to sign the assembly as the web part assembly will be deployed to GAC. For signing the assembly, load project properties and check the "Sign the assembly" checkbox and choose private key file.( see following figure ).

Figure 3 : Signing custom web part assembly

The goal of the web part is to display BDC entities in a DataGrid. For this we will need references to System.Data.dll and System.Web.dll in the project.

Implementation

XBdc web part class needs to inherit from
System.Web.UI.WebControls.WebParts.WebPart . There is another WebPart class in SharePoint, but it should be avoided for the reasons listed here. Also XBdc class will override
CreateChildControls and Render methods to attach DataGrid and populate it with BDC entities.


[System.Xml.Serialization.XmlRoot(Namespace = "http://jardalu/Samples")]
public class XBdc : System.Web.UI.WebControls.WebParts.WebPart
{
    protected override void CreateChildControls(){ ... }
    protected override void Render(System.Web.UI.HtmlTextWriter writer){ ... }
}

To use BDC APIs, we will need to use the following namespaces

using Microsoft.Office.Server.ApplicationRegistry.MetadataModel;
using Microsoft.Office.Server.ApplicationRegistry.Runtime;

For simplicity sake, only these two namespaces are used. For complete list of APIs please visit MSDN site. Also, to keep things simple the Entity Name/Lob System Instance Name/Entity columns is hardcoded in the code.


// hardcoded entity fields
private string[] headers = { "Id", "Name", "Contact", "Phone", "Address" };

Method LoadCustomersFromBdc() will read entities from BDC and create a DataTable that can be bounded to the DataGrid in the web part. In the method, LobSystemInstance and Entity is searched through ApplicationRegistry object. Once entity is found, the method instance of type Finder is loaded. MethodInstance is executed to get all the entity instances for the finder. Finally instances are added in the data table using EntityAsDataRow method. Please note BDC also provides EntityAsDataTable property to create the data table itself.


private DataTable LoadCustomersFromBdc()
{
    DataTable dt = new DataTable();
    foreach (string header in headers)
    {
        dt.Columns.Add(new DataColumn(header));
    }

    // hardcoded LobSystemInstance and Entity name
    LobSystemInstance lsi = ApplicationRegistry.GetLobSystemInstanceByName("CustomerLobSystemInstance");
    Entity entity = lsi.GetEntities()["Customer"];
    MethodInstance mi = entity.GetFinderMethodInstance();
    IEntityInstanceEnumerator enumerator = entity.FindFiltered(mi.GetFilters(), lsi);
    while (enumerator.MoveNext())
    {
        IEntityInstance instance = enumerator.Current;
        if (instance == null) continue;
        instance.EntityAsDataRow(dt);
    }

    return dt;
}

Its time now to create the DataGrid control and attach the control to Web Part ( see method CreateChildControls() )


protected override void CreateChildControls()
{
    this.grid = new DataGrid();
    this.grid.Width = new Unit(100, UnitType.Percentage);

    this.grid.HeaderStyle.Font.Size = 10;
    this.grid.HeaderStyle.Font.Bold = true;
    this.grid.AlternatingItemStyle.BackColor = Color.Gray;

    foreach (string header in headers)
    {
        BoundColumn column = new BoundColumn();
        column.HeaderText = header;
        column.DataField = header;
        this.grid.Columns.Add(column);
    }
    this.grid.AutoGenerateColumns = false;

    this.Controls.Add(this.grid);
    base.CreateChildControls();
}

Finally DataGrid is bond to the BDC entities

protected override void Render(System.Web.UI.HtmlTextWriter writer)
{        
    this.grid.DataSource = this.LoadCustomersFromBdc();
    this.grid.DataBind();

    this.grid.RenderControl(writer);
}

Once the custom Web Part is compiled, its time to hook it up in the SharePoint. Before hooking the XBdc Web Part, we will upload the "Customer" application definition file as the custom Web Part has hardcoded entity/lob system instance names ( see accompaning source code for model file and LOB code ).

Uploading Customer Model

Compile the project CustomersLob accompanying in the source code

GAC the assembly using gacutil tool

Upload the accompaning model (customer.xml) into BDC

Registering XBdc Web Part in SharePoint

GAC the Web Part assembly using gacutil. Please note the public key token for the assembly.

Locate the virtual directory for SharePoint web site ( in the IIS Manager ). Typically the virtual directory is %system drive%\INETPUB\WWROOT\WSS\80 ( assuming web site is on port 80 )

In the virtual directory, edit the web.config and add XBdc custom part in SafeControls section ( choose appropriate assembly and namespace ).


<SafeControl
Assembly="XBdcWebPart, Version=1.0.0.0, Culture=neutral, PublicKeyToken=def61931772d3147"
Namespace="Jardalu.Samples.XBdcWebPart"
TypeName="*" Safe="True" AllowRemoteDesigner="True" />

Then browse to the WebSite, and go to Site Actions -> Site Settings -> Modify All Site Settings. Under that, click on "Web Parts" under Galleries.

Click on "New" in the toolbar, and find the XBdc custom webpart as shown below

Check the checkbox, go to the top, click on "Populate Gallery".

At this time XBdc custom web part is ready to be consumed.

Source Code

Sample with complete source code can be downloaded from here.

As-is
The source code/software is provided "as-is". No claim of suitability, guarantee, or any warranty whatsoever is provided. Source Code and executable files can not be used in commercial applications.

Implementing custom SSO Provider

2009-01-13T01:31:00.000-08:00

Single Sign-On (SSO*) is a feature in MOSS that provides storage and mapping of credentials. BDC and SSO are two different components in MOSS, however, SSO discussions in this article is tied with BDC and how SSO is used in BDC.

Following article (http://technet.microsoft.com/en-us/library/cc262932.aspx) shows how SSO can be configured in MOSS.

Limitations of SSO:

a) SSO works when MOSS is installed in domain ( SSO does not work when SharePoint is installed in Workgroup ).
b) SSO does not work when MOSS is configured in Forms Based Authentication mode ( FBA ).
c) Master key backup is allowed only on a floppy disk (A:)
d) No localization
e) No tools for bulk upload (credentials)

Fortunately, MOSS allows us to write our own "SSO" by implementing ISsoProvider interface. ISsoProvider interface is defined in Microsoft.SharePoint.SingleSignOn namespace and Microsoft.SharePoint.Portal.SingleSignOn.dll assembly ( url: http://msdn.microsoft.com/en-us/library/microsoft.sharepoint.portal.singlesignon.issoprovider.aspx )

Implementing ISsoProvider:

Rather than iterating the implementation of the ISsoProvider, here is a walkthrough (http://msdn.microsoft.com/en-us/library/ms566925.aspx) of implementing ISsoProvider.

Registering SSO with BDC

MOSS allows only one default SSO provider ( default is SpsSsoProvider ), however BDC can work with multiple SSO providers. SSO provider for BDC is defined in BDC metadata model.

In the metadata model, register your SSO provider with the following code

<Property Name="SsoApplicationId" Type="System.String">AppId</Property>
<Property Name="SsoProviderImplementation" Type="System.String">MySsoProvider, My.SingleSignon, Version=1.0.0.0, Culture=neutral, PublicKeyToken=71e9def111e9429c</Property>

The above code assumes that your SSO provider is "MySsoProvider" and is present in "My.SingleSignOn" assembly.

Notes:
* SSO in MOSS is a misnomer. From the name, Single Sign-On, it appears that SSO will automatically log user into other systems. However, in reality, it only provides storage, retrieval and mapping of credentials. Other components ( such as BDC, Excel Services, Access Services etc. ) logs the user to other systems by retrieving user credentials from SSO.

BDC : Beyond Web-Service and Database

2008-10-19T17:00:00.000-07:00

As discussed in the previous post, Business Data Catalog only supports LOB of type web-service and database. What if you want to display your business data from your LOB through adapters ?

A little known fact of BDC is, its support of web-service through GACed proxy. Typically BDC generates web-service proxy at runtime from the WsdlFetchUrl property specified in the metadata. Instead of using WsdlFetchUrl property if
WebServiceProxyType property is used, BDC loads the proxy from GAC. The property WebServiceProxyType is specified at the LOBSystem level.

Sample

In this sample, an entity Employee will be displayed in the Business Data List where the entity is is fetched from local assembly ( GACed assembly ).

Figure 1: Employee Business Data List

Employee entity contains the following fields as described below


Employee
    Id - int
    LoginId - string
    FirstName - string
    LastName - string
    Title - string

AdventureWorks class (data fetched from AdventureWorks sample database) defines finder and specific finder (namely GetEmployees and GetEmployee methods).


public class AdventureWorks : HttpWebClientProtocol
{
    public IList GetEmployees(string filterName){ ... }
    public Employee GetEmployee(int id){ ... }
}

The point to note is AdventureWorks is a subclass of HttpWebClientProtocol. Once the assembly is created with AdventureWorks class and Employee class and GACed, its time to hook Employee entity with BDC.

Assuming the namespace of the AdventureWorks and Employee class to "Beyond" and FullName of the assembly is "BeyondAdvWorks, Version=1.0.0.0, Culture=neutral, PublicKeyToken=22c970e70e320837".

The following metadata defines a LobSystem of type WebService and registers Beyond.AdventureWorks class as the proxy for the webservice using WebServiceProxyType property.

Click on the following figure to see the LobSystem definition.

Figure 2 : LobSystem

Entity Employee is defined in the metadata, with identity "Id" of type int ( see following figure ).

Figure 3 : Entity

Finally the two methods are modeled in the metadata ( the figure contains Finder method, download the sample for complete metadata ).

Figure 4 : Methods

In the methods, fully qualified name is used to define the TypeDescriptor for Employee class.

After hooking the Employee entity with Business Data List, the following figure shows the individual Employee.

Figure 5 : Individual entity page

See the previous post for how to hook finder and specific finder methods to the Business Data List.

Source Code

Sample with complete source code can be downloaded from here.

As-is
The source code/software is provided "as-is". No claim of suitability, guarantee, or any warranty whatsoever is provided. Source Code and executable files can not be used in commercial applications.

Business Data Catalog

2008-09-19T00:13:00.000-07:00

Business Data Catalog (BDC) is a feature of Microsoft Office SharePoint Server ( MOSS 2007) which provides a mechanism to bring and display business data on SharePoint. BDC is simple yet powerful to use because of its no-code solution.

Power of BDC

Consider this, there is a web-service (or database) which exposes your Line of Business (LOB) data and you want to see the data on SharePoint. This can be done by writing a custom web-part. You will need a developer to write that custom web-part. Now assume the web-service requires credentials based authentication. Hopefully the developer can still handle that. If the web-service requires unique credentials for each SharePoint user, you will require a smart developer. What about you want to search the data fetched by the web-part ?

BDC's goal is to enable you to surface business data (some of the aspects described above) in Office SharePoint Server 2007 with minimal coding effort. BDC requires one to write [n1] XML based metadata.

BDC Web Part - Adventure Works Sample

MOSS 2007 comes with five Business Data Web Parts [r3] which can display a list of entity instances, display details of an entity instance, display list of related entity instances, display a list of actions associated with an entity and create a Business Data item.

In this sample, a list of entity instances are displayed using Business Data List (BDL) with Adventure Works [r4] database as LOB.

Figure - List of Products in Adventure Works.
Steps in displaying the products list
Step 1 : Install the adventure works 2000 database [r4]
Step 2 : Install SharePoint Server 2007 SDK [r5]
Step 3 : Upload BDC metadata model for Adventure Works from SDK
- Open MOSS Central Administration
- Goto Shared Services Administration page for your shared service
- Click on "Import application definition" in the Business Data Catalog block
- Browse the adventure works model XML from SDK (C:\Program Files\2007 Office System Developer Resources\Samples\Business Data Catalog\AdventureWorks Samples\AdventureWorks2000.xml)
- Click upload

Figure - Model for Adventure Works uploaded.
At this step the BDC application definition for adventure works is uploaded.

Step 4 : Add BDL for AdventureWorks products.
- Goto your site (MySite)
- Click on Site Actions > Edit Page
- Choose to add a new Web Part

- Select Business Data List and Click OK
- A Business Data List will appear within the "Add a web part" block
- Click on "Open the tool pane"
- A Business Data List tool bar will open on the right side
- Click on the picker button and choose "Product"

- Click OK in BDL pane
- Exit the edit mode

- In the search criteria, enter your criteria where you will get all the products associated with the criteria.

Limitation of BDC

BDC only allows read functionality on business data. That means BDC does not support CUD (Create, Update, Delete) on business entities.

BDC metadata XML is tough to understand. If one is not using tools, model is hard to manage and will not necessarily qualify as "no code" solution.

BDC supports only web-service and database based LOB.

References
r1 : Business Data Catalog Overview [link]
r2 : SharePoint 2007: BDC - The Business Data Catalog [link]
r3 : Business Data Web Parts [link]
r4 : Adventure Works [link]
r5 : SharePoint Server 2007 SDK [link]
Notes
n1 : There are tools (Microsoft and Third parties) that help write BDC metadata XML.