Creating a Custom User Site Provisioning Solution with SharePoint Server 2007 (Part 1 of 2)

Article
10/16/2013

Summary: Examine new capabilities built into the Microsoft Office SharePoint Server 2007 Enterprise Edition, which enable business process automation and simplify the business process. This article is part 1 of 2. (18 printed pages)

Sonya Zidek, Microsoft

August 2007

Applies to: 2007 Microsoft Office System, Microsoft Office SharePoint Server 2007, Windows SharePoint Services 3.0

Download the accompanying code sample, MOSS2007CustomSiteProvisioning.exe

Read Part 2: Creating a Custom User Site Provisioning Solution with SharePoint Server 2007 (Part 2 of 2)

Contents

Overview of a Custom User Site Provisioning Solution
Employee SharePoint Permissions within the Enterprise
The Request InfoPath Form
Additional Resources

Overview of a Custom User Site Provisioning Solution

This article examines some of the new capabilities that are built into the Microsoft Office SharePoint Server (MOSS) 2007 Enterprise Edition, which enable business process automation and simplify the business process. This article demonstrates the tight integration between the Office SharePoint Server 2007 portal, including Microsoft Office InfoPath Forms Services and the Business Data Catalog, and the various other 2007 Office system applications and features, such as InfoPath 2007 and Microsoft Office SharePoint Designer 2007. In addition, the solution that accompanies this article shows how accessing and manipulating various SharePoint Server components programmatically—such as the Member group and user permissions, and Business Data Catalog and legacy line-of-business (LOB) data sources—with the built-in SharePoint Server APIs enable this type of business process automation. The automation was developed primarily by using Visual Studio Tools for Office 2007 Second Edition and the Visual Studio 2005 Extensions for Windows Workflow Foundation. Additionally, you can develop traditional .NET Framework console and Windows Forms applications to make use of the SharePoint Server APIs and 2007 Office system APIs that will also facilitate the automation and simplification of business processes within the enterprise.

Employee SharePoint Permissions within the Enterprise

Most organizations have an approval process in place that allows employees’ managers to approve any costs that are associated with using new IT resources implemented in the enterprise. Usually the employee who requires access to the new system initiates the process, which spans several approval cycles by various managers, as well as a long delay and many e-mail messages. This is often a monotonous process, which consumes not only the time of the employee, but also that of the approving manager.

This article presents a solution that integrates Active Directory domain controllers, LOB data, InfoPath Forms Services, and workflow with the 2007 Office system to support the submission and automation of such requests. The solution uses employee information contained within the Active Directory domain controller and the human resources database to support the submission of the request. The data pulled from these two sources provides all the employee’s relevant information and the approving cost center manager’s information. In this scenario, an employee uses a solution based on InfoPath 2007, and the Business Data Catalog and InfoPath Forms Services features of MOSS 2007 Enterprise Edition to submit a request for permission to create SharePoint sites within the enterprise SharePoint portal.

The Business Data Catalog is a new, powerful feature of MOSS, which allows developers to surface LOB data up to MOSS from disparate legacy systems and LOB systems that exist within the enterprise. By default, the Business Data Catalog can connect to Oracle, CRM, and SAP databases, and other systems without extra development. The new and powerful InfoPath Forms Services feature of MOSS is a browser-based, thin-client run-time version of InfoPath, which allows users to read and complete InfoPath forms through the browser when the forms are integrated with MOSS.

The solution also allows the employees’ cost center manager to review the requests submitted, and approve or reject them. After the cost center manager reviews the request, the custom workflow and custom workflow activity, designed with Microsoft Visual Studio 2005 and Visual Studio 2005 Extensions for Windows Workflow Foundation, automatically sends out the appropriate e-mail messages and adds the appropriate permissions for the employee within the SharePoint portal.

To clarify the overall process of this custom permission request solution, the following diagram depicts the entire process flow logically and all of the various pieces and steps that make up the process.

Figure 1. Overview of entire permission request process

Overview of entire permission request process

The Request InfoPath Form

The main user-centric piece of this process is the employee request form. This request form is an InfoPath form that the employee submits with the relevant data needed to review the request. Many of the fields on the form are pre-populated when the employee creates a request, to ensure data integrity throughout the process and to eliminate the amount of data that the employee is required to provide.

Figure 2 shows the request form that is used by the employees. The form pre-populates the following fields when the user creates a request:

Employee NT ID
Employee Full Name
Employee Email
Employee Cost Center
Cost Center Approver Name
Cost Center Approver Email

Figure 2. Sample form with prepopulated fields

Sample form with prepopulated fields

The form completes these form fields with the appropriate values with the use of two lookup Web services that are called from the form’s internal code. The data is pulled from the enterprise Active Directory domain controller by using one Web service, and from an application that is set up within the Business Data Catalog within MOSS that points to LOB data by using another Web service. Here, the LOB system is an Oracle database that contains the human resources data on employees and cost centers. However, you can just as easily use the Business Data Catalog to connect to any back-end database system.

Summary of Key Sample Files

The InfoPath form template used to enable users to submit their requests through MOSS is located in the InfoPathForm folder in the sample files directory. The form template is named UserAccessRequest.xsn. The form should be opened by using the Microsoft Office InfoPath 2007 client application. Install Visual Studio Tools for Office Second Edition before attempting to open the managed code in the code-behind; however, after it is installed, you can access the form code by clicking Tools, pointing to Programming, and then clicking Microsoft Visual Studio Tools for Applications. This opens the form code in Visual Studio 2005.

InfoPath Permission Request Form Code

InfoPath 2007 provides new capabilities by allowing direct integration with Visual Studio 2005. The Microsoft Visual Studio 2005 Tools Second Edition for the 2007 Microsoft Office System add-in allows you to directly integrate managed code into InfoPath 2007 forms. You can directly access this integration from the InfoPath 2007 menus by clicking Tools, pointing to Programming, and then clicking Microsoft Visual Studio Tools for Applications.

This new integration feature with managed code allows access through the .NET Framework Microsoft.Office.InfoPath namespace to the following InfoPath form events, through the EventManager class:

Loading
Submit
VersionUpgrade
ViewSwitched

These new integrated features allow you to call custom event handler methods within the form execution procedures when the previous form events are activated. This lets developers create custom managed code that is executed throughout the execution of the form internal code.

For the permission request solution, this was used to directly call the two Web services (AD Lookup and BDC Lookup) from the InfoPath form code-behind, and set the various form field values to prepopulate the fields on the form for the employee. Figure 3 shows the InfoPath form in design view with the various form fields and where the prepopulated form data originates.

Figure 3. InfoPath permission request form with panels designating how form fields are prepopulated

InfoPath permission request form

To call the two Web services and properly set the value of the form fields, two of the form events are assigned to custom event handler methods. This event handler assignment is done within the InternalStartup() form launch method. This method works first when the form starts and therefore, all of the event handler methods must be initialized within this method. The EventManager.FormEvents.Loading event is assigned to a custom FormEvents_Loading() event handler method. The EventManager.FormEvents.Submit event is assigned to a custom FormEvents_Submit() event handler method. The following code example to assign the event handlers works the same as assigning an event handler in any type of managed code.

public void InternalStartup()
{
EventManager.FormEvents.Loading += new 
LoadingEventHandler(FormEvents_Loading);
EventManager.FormEvents.Submit += new SubmitEventHandler(FormEvents_Submit);
}

The FormEvents_Loading() event handler method populates all of the prepopulated fields by capturing the current employee’s user ID information. The user ID and the user’s domain are captured from the .NET System.Environment namespace and assigned to the UserNTID and the UserNTIDHidden form fields. To ensure that the form data is properly populated when the employee creates a request and then remains unchanged when another employee (for example, the cost center approver) opens the form again to review it, the original employee’s user ID and Active Directory domain information is stored in the UserNTIDHidden field. This field is populated the first time the form loads, and then on subsequent openings of the form a check is performed to determine whether this field is populated. If the field is populated, the FormEvents_Loading() code is not executed. This ensures that the fields contain the original data as submitted by the original requestor. In addition, a timestamp is populated into the DateTimeHidden field on the form that is used to provide a unique name for the submitted form. The code to set the UserNTIDHidden field and the DateTimeHidden field, and to properly pull in the original employee’s user ID and domain information follows.

//Search through Active Directory to get the following properties for the user:
// - Full name
// - Email address
// - Cost Center
string userDomain = System.Environment.UserDomainName;
string userLoginID = userNTIDField.Value.ToString();

//AD Lookup
GetUserInfoFromAD.UserRequest adUserInfo = new 
GetUserInfoFromAD.UserRequest();
GetUserInfoFromAD.GetUserInfoFromAD ADLookupProxy = new 
GetUserInfoFromAD.GetUserInfoFromAD();
ADLookupProxy.Credentials = System.Net.CredentialCache.DefaultCredentials;
adUserInfo = ADLookupProxy.SearchAD(userDomain, userLoginID);

//Set value to UserFullName field on form.
string xpathFullName = "/my:UserSPSRequest/my:UserFullName";
XPathNavigator userFullNameField = 
MainDataSource.CreateNavigator().SelectSingleNode(xpathFullName, NamespaceManager);
userFullNameField.SetValue(adUserInfo.UserFullName);

//Set value to UserEmail field on form.
string xpathEmail = "/my:UserSPSRequest/my:UserEmail";
XPathNavigator userEmailField = 
MainDataSource.CreateNavigator().SelectSingleNode(xpathEmail, NamespaceManager);
userEmailField.SetValue(adUserInfo.UserEmail);

//Set value to UserCostCenter field on form.
string xpathCostCenter = "/my:UserSPSRequest/my:UserCostCenter";
XPathNavigator userCostCenterField = 
MainDataSource.CreateNavigator().SelectSingleNode(xpathCostCenter, NamespaceManager);
userCostCenterField.SetValue(adUserInfo.UserCostCenter);

The final code that is processed within the FormEvents_Loading() event handler method instantiates the BDC Lookup Web service proxy object, retrieves the relevant cost center approver information based on the cost center retrieved from Active Directory previously, and then populates the appropriate form fields with the cost center approver information. The code to execute these steps follows.

//BDC Lookup
BDCLookupWebService.ApproverInfo requestApprover = new BDCLookupWebService.ApproverInfo();
BDCLookupWebService.BDCLookup BDCLookupProxy = new 
BDCLookupWebService.BDCLookup();
BDCLookupProxy.Credentials = System.Net.CredentialCache.DefaultCredentials;
requestApprover = 
BDCLookupProxy.BDCApproverLookup(userCostCenterField.Value.ToString());

string xpathApproverName = "/my:UserSPSRequest/my:ApproverName";
XPathNavigator approverNameField = 
MainDataSource.CreateNavigator().SelectSingleNode(xpathApproverName, 
NamespaceManager);
approverNameField.SetValue(requestApprover.ApproverName.ToString());

string xpathApproverEmail = "/my:UserSPSRequest/my:ApproverEmail";
XPathNavigator approverEmailField = 
MainDataSource.CreateNavigator().SelectSingleNode(xpathApproverEmail, NamespaceManager);
approverEmailField.SetValue(requestApprover.ApproverEmail.ToString());

The permission request solution also ensures that the employee selects at least one type of SharePoint site to create. Otherwise, there is no reason for the employee to submit the request. The FormEvents_Submit() event handler method is responsible for checking that at least one of the site type check boxes is selected; otherwise, an error message is displayed to the employee indicating the error. Additionally, the FormEvents_Submit() method sets the value for the UserNTIDHidden field to the employee user ID and domain to ensure the integrity of the data within the form. The code to process these steps follows.

void FormEvents_Submit(object sender, SubmitEventArgs e)
{
//Deteermine whether at least one check box is selected. Otherwise, throw a //messagebox error.
string xpathPersonalSite = "/my:UserSPSRequest/my:PersonalSite";
XPathNavigator userPersonalSiteField = 
MainDataSource.CreateNavigator().SelectSingleNode(xpathPersonalSite, NamespaceManager);

string xpathTechnicalSite = "/my:UserSPSRequest/my:TechnicalSite";
XPathNavigator userTechnicalSiteField = 
MainDataSource.CreateNavigator().SelectSingleNode(xpathTechnicalSite, 
NamespaceManager);

string xpathBusinessSite = "/my:UserSPSRequest/my:BusinessSite";
XPathNavigator userBusinessSiteField = 
MainDataSource.CreateNavigator().SelectSingleNode(xpathBusinessSite, NamespaceManager);

while ((userBusinessSiteField.Value != "True") && 
(userPersonalSiteField.Value != "True") &&   
(userTechnicalSiteField.Value != "True"))
{
mbox("You have not checked at least one type of site that you would like permission to create.  Please check at least a Personal, Technical or Business site checkbox.");
}

//Set the User ID hidden field to preserve form values.
string xpathNTID = "/my:UserSPSRequest/my:UserNTID";
XPathNavigator userNTIDField = 
MainDataSource.CreateNavigator().SelectSingleNode(xpathNTID, NamespaceManager);
string xpathNTIDHidden = "/my:UserSPSRequest/my:UserNTIDHidden";
XPathNavigator userNTIDHiddenField = 
MainDataSource.CreateNavigator().SelectSingleNode(xpathNTIDHidden, NamespaceManager);
userNTIDField.SetValue(userNTIDHiddenField.Value.ToString());
}

After all of the previous data is populated for the employee in the form, the employee must select which of the three site types he or she wants to have permission to create within the enterprise SharePoint portal. The employee then submits the request. At this point, the custom workflow is initialized and begins processing the request to the cost center approver. The workflow piece is addressed in the Custom Permission Request Workflow section of this article.

InfoPath Form Deployment

To make form templates available to users within MOSS through InfoPath Forms Services, the form templates must be verified, uploaded, and deployed to the server running MOSS. Form templates that do not contain business logic, do not require full trust, and do not use data connections that are managed by an administrator can be published directly to a document library by any site collection user who has the appropriate privileges, without any action on the part of an administrator. However, forms that contain business logic, require full trust, or use administrator-managed data connections have a different deployment process. The permission request solution uses managed code to include business logic in the form, and therefore requires the more complex deployment process. The managed code that provides the business logic to the form template requires that the form be deployed with full trust as well. To complete the form deployment process, the administrator must have access to MOSS Central Administration.

Form Options

The form template Form Options, Submit Options, and Data Connections must be configured properly before deploying the form template to the server running MOSS. The Form Options determine how the form is executed, depending on whether it is used with InfoPath Forms Services. To access the Form Options, on the Tools menu, click Form Options. In the Form Options dialog box, the form developer can set various form configuration properties; however, the following options are significant to ensuring that the form is compatible with InfoPath Forms Services:

Browser
Property Promotion
Security and Trust
Compatibility

The Browser section of the Form Options dialog box allows the form developer to determine which options are available for the user when the form is opened by using InfoPath Forms Services in the browser. Figure 4 shows the options that are enabled in the permission request form.

Figure 4. Browser form options for the permission request InfoPath form template

Browser form options for permission request form

The Property Promotion section of the Form Options dialog box allows the form developer to determine which form fields to promote to forms library columns in the SharePoint forms library in which this form will be used. Figure 5 shows the Property Promotion options that are set for the permission request form. Notice that not all of the fields are promoted to form library columns, because only some of the fields in the form are used later for the approval workflow.

Figure 5. Property Promotion form options for the permission request form template

Property Promotion form options

The Security and Trust section of the Form Options dialog box allows the form developer to assign full trust options and certificate information to the form template. This ensures that the form is executed with the appropriate permissions on the server running MOSS with no loss of functionality. The certificate also ensures integrity when processing the form code behind on the server running MOSS. The certificate can be created by using the Create Certificate button in the Form Template Signature section. This certificate must then be exported and deployed on the server running MOSS. You can access the certificate through Internet Explorer. On the Tools menu, click Internet Options, click the Content tab. In the Certificates section of the Internet Options dialog box, click the Certificates button to open the Certificates dialog box. Select the certificate that was created for the InfoPath form, and then click Export under the certificates list. Complete the Export Wizard and save the certificate file locally, and then copy the certificate file to the MOSS server hard disk. Logon locally on the MOSS server, go to the same Certificates dialog box in Internet Explorer, and this time click the Import button. Complete the Certificate Import Wizard to deploy the certificate. After the InfoPath form is deployed to the MOSS server, it uses this certificate automatically. Figure 6 shows the Security and Trust configuration for the permission request form template.

Figure 6. Security and Trust form options for the permission request form template

Security and Trust form options for form template

In the Compatibility section of the Form Options dialog box, the form developer can set the browser compatibility options depending on whether the form will be used with InfoPath Forms Services. Based on the Compatibility selection, InfoPath performs compatibility verification before publishing the form to ensure that there are no errors within the form configuration that could interfere with the InfoPath Forms Services features. Figure 7 shows the compatibility configuration for the permission request form template.

Figure 7. Compatibility form options for the permission request form template

Compatibility form options for form template

Form Deployment

After all Form Options settings are completed properly, the form deployment process begins by first publishing the form template to a location on the MOSS server. This location can be either the local hard disk or a SharePoint site on the server. The publishing can be done from the InfoPath client by clicking Publish on the File menu. The Publishing Wizard guides the form developer through the publishing process.

The first option in the Publishing Wizard asks the form developer to select the type of location to which the form template should be published. The location options are the following:

To a SharePoint server with or without InfoPath Forms Services
To a list of e-mail recipients
To a network location
As an installable form template (requires Microsoft Visual Studio)

Here, the permission request is published to a SharePoint site, and therefore, the first option is selected. The next screen of the Publishing Wizard asks for the address of the specific location to which to publish the form template. In the case of a SharePoint site location type, the actual URL of the SharePoint site should be typed into the text box. Otherwise, the appropriate types of information must be entered for the three other location types to publish the form template.

After the appropriate SharePoint site URL is entered for the permission request form, the next publishing option determines whether to enable the browser-compatibility options set within the form. Because this form has form options set that do this already and there is managed code in the form code behind, the Publishing Wizard allows only the Administrator-approved form template option as shown in Figure 8.

Figure 8. Publishing Wizard advanced option for form templates with managed code in the code-behind

Publishing Wizard advanced option

The Publishing Wizard requests the URL and the actual form template name that should be used to identify the form after it is published. The Publishing Wizard then confirms the promoted properties that should be accessible within MOSS. Finally, a confirmation page appears with the Location, Target Site, and Security Level settings for the form template. If the settings are correct, the form developer clicks the Publish button, and the form is published to the specified location.

The next step in the deployment process is to verify and upload the form template to the Central Administration administrator-approved form repository. The user performing this upload must have access to Central Administration. The user follows these steps to upload the form template.

To upload the form template

Navigate to the Central Administration page, and then click the Application Management tab.
On the Application Management page, under InfoPath Forms Services, click Upload form template.
On the Upload Form Template page, in the Deploy Form Template section, click Browse.
In the Choose File window, select the template to verify, and then click Open.
Click Verify to check the form template for problems. If there are problems with the form template, they are displayed in the Report Details section of the Form Verification Report.
Click OK to return to the Upload Form Template page. When you return to the Upload Form Template page after verifying a form template, you must browse for the template again.
On the Upload Form Template page, in the Deploy Form Template section, click Browse.
In the Choose File window, select the template to upload, and then click Open.
Click Upload. The upload process can take a few minutes to finish, especially in a farm with multiple front-end Web servers. You can check the status of the upload on the Manage Form Templates page.

The form template is deployed to the administrator-approved form repository, as shown in Figure 9.

Figure 9. Manage Form Templates page in Central Administration, displaying the uploaded administrator-approved form templates

Manage Form Templates page

The final step in form template deployment to MOSS is to activate the form template to a site collection so that the form can be used as a content type within MOSS. You perform this step directly from the Manage Form Templates page, by pausing over the name of the form template, and then clicking the drop-down menu that appears. The user then clicks the Activate to a Site Collection option, as shown in Figure 10.

Figure 10. Form Template menu in Central Administration - Manage Form Templates

Form template menu

The Activate Form Template page appears, with the form template properties and a drop-down menu to select a site collection. After the appropriate site collection is displayed in the Activation Location menu, the user clicks the OK button at the bottom of the page to activate the form to the selected site collection. After activation is complete, a confirmation page is displayed.

Setting Form Library Content Type

The final step in using an InfoPath form template with managed code as the content type for a forms library in MOSS is to set the content type. The form is activated to the site collection, and therefore, is a potential content type for form libraries within the particular site collection.

This process is simple and should be performed from the settings of the SharePoint form library where the form will be used. The site administrator should open the appropriate SharePoint site in the browser, and then browse to the form library. After the form library is open, the following steps set the form as the content type of the form library.

To set the form as the content type of the form library

Click the Settings button at the top of the form library page, and then click Form Library Settings on the drop-down menu.
On the Form Library Settings page, click the Advanced Settings link in the General Settings section.
On the Advanced Settings page, click Yes under Allow management of content types; click Display as a Web page under Browser-enabled Documents, and then click OK at the bottom of the page.
On the Form Library Settings page, in the Content Type section, click the Add from existing content types link.
On Add Content Types page, click Microsoft Office InfoPath in the Select site content type from drop-down menu. In the Available Site Content Types box, click the appropriate content type and then click Add. Click OK at the bottom of the page.

The form template is now the content type for this form library.

The Active Directory Lookup Web Service

The Active Directory (AD) lookup Web service is a standard Web service written in Visual Studio 2005 by using the .NET DirectoryServices namespace. The DirectoryServices namespace allows .NET developers to access the enterprise ActiveDirectory store and query it for Active Directory profile information. You can use the query mechanism to find one specific user or a set of users that match a set of filter values.

For the permission request solution, the DirectoryServices namespace and the Web service using the namespace, are used to find a specific user who matches a particular user ID. This is the user ID of the employee who is submitting the permission request InfoPath form, and therefore, the user ID is pulled directly from the InfoPath form metadata properties.

The custom Web service developed for the permission request solution is a standard Web service that references the DirectoryServices namespace. In addition, the Web service uses a custom support class named UserRequestInformation to transport the data retrieved from the Active Directory domain controller. The Web service SearchAD() Web method is provided to allow developers to call the Web service and retrieve the employee’s information based on his or her Active Directory domain and user ID. Two parameters are required for the Web method call, the user’s domain and user ID, as these are used to search Active Directory.

The code within the Web method is standard Active Directory lookup code that instantiates a DirectoryEntry object (with the appropriate LDAP search path), and then instantiates a DirectorySearcher object, setting the DirectorySearcher object SearchScope and Filter properties. Then the FindOne() method is called on the DirectorySearcher object. The following code example demonstrates the this set of operations.

DirectoryEntry adFolderObject = new DirectoryEntry(LDAPSearchPath);
DirectorySearcher adSearcherObject = new DirectorySearcher(adFolderObject);
adSearcherObject.SearchScope = SearchScope.Subtree;
adSearcherObject.Filter = "(&(ObjectClass=*)(samAccountName=" + userID + "))";

SearchResult adObject = adSearcherObject.FindOne();

Next, if an employee is found within the Active Directory domain who matches the designated user ID, the following three properties are returned and assigned to the UserRequestInformation data class that is returned to the InfoPath form.

userADInfo.UserEmail = adObject.Properties["mail"][0].ToString();
userADInfo.UserFullName = (string)(adObject.Properties["displayName"][0]);
userADInfo.UserCostCenter = (string)(adObject.Properties["company"][0]);

Figure 11 shows a sample of the employee information that is returned from the SearchAD() Web method call.

Figure 11. Active Directory Lookup Web service sample returned data

Web service sample returned data

After this data is returned to the InfoPath form, the data is used to populate the form fields so that the employee does not need to complete them, and the cost center ID is sent into the BDC Lookup Web service to retrieve the cost center approver information for the permission request solution. The BDC Lookup Web service is described in the next section, The Business Data Catalog Lookup Web Service.

Summary of Key Sample Files

GetUserInfoFromAD.asmx is the Web service code file that contains all of the code for the Active Directory Lookup Web service. This file is located in the ActiveDirectoryLookupWebService folder in the SampleFiles directory. The solution and project files are also included in the ActiveDirectoryLookupWebService folder. To view the code, the GetUserInfoFromAD.sln file should be opened from Visual Studio 2005.

The Business Data Catalog Lookup Web Service

The Business Data Catalog is a feature found in the enterprise version of MOSS, which allows developers to connect to disparate LOB systems by using a standard set of .NET classes and interfaces. These LOB systems are exposed as data sources to various MOSS features (such as Web Parts, list columns, and user profiles), and as custom applications that can be developed to be used with MOSS. This application is of the latter category.

Developers are responsible for configuring the Business Data Catalog connection to various LOB systems, and for determining which data is returned from the legacy application. This is accomplished by creating an application definition file. This file contains all of the necessary configuration data that determines how the Business Data Catalog connects to the remote system and which requested data to make available through the Business Data Catalog interface.

The application definition file also determines what data is returned by modeling the business entities that are contained within the remote LOB system. For the purpose of this request system, only a single entity, called HRLookup, is defined. This entity, HRLookup is like a class; the fields are its properties, and the filters are its methods. The application definition file also defines the fields and the filters to apply to the entity to help search through the LOB data.

Summary of Key Sample Files

The BDCLookupWebService file in the SampleFiles directory contains the code for both the BDCLookupUtility and the BDCLookupWebService, each in its own subfolder. The solution and project files are also included in the BDCLookupUtility and BDCLookupWebService respective subfolders. To view the code, you should open the BDCLookupUtility.sln or BDCLookupWebService.sln file from Visual Studio 2005.

The BDC Application Definition

Application definition files are XML files that define the data connection and business entities needed to retrieve the desired data from the LOB database. Application definition files require many items to be defined to connect properly to the remote system. Application definitions follow a schema defined in the file BDCMetaData.xsd, which you can use to help in authoring the XML. This file is located in the path Program Files\Microsoft Office Servers\12.0\Bin.

This permission request solution uses an application definition to connect to the internal Human Resources rollup database to pull the appropriate cost center approver information for each employee’s cost center. The complete application definition is available with the code that is available for download with this article. For details about which files are used, see Summary of Key Sample Files. Because of space considerations, the application definition file is not explained here. For more information, see the Business Data Catalog resources listed in Additional Resources.

The Approver Class

Creating the BDC Lookup Utility and Web service begins by defining an Approver class that contains the entity data returned from the Business Data Catalog. The class is serialized and sent to the InfoPath form for use in the permission request process. The class itself is unremarkable and is used strictly to house the information retrieved from the Business Data Catalog cost center lookup for the employee submitting the request. The permission request solution uses this link to assign a task by using the custom workflow that is discussed later in this article, so that the cost center approver can review the employee’s request and either approve or deny permission to create SharePoint sites. The complete Approver class is available with the code that accompanies this article.

The BDC Lookup Utility

The BDC Lookup Utility is a custom library that uses the Business Data Catalog .NET APIs to connect to the Business Data Catalog within MOSS. The utility code, which actually connects to the Business Data Catalog and retrieves the relevant information, is isolated into its own library to demonstrate decoupling Business Data Catalog lookup code from a generic Web service that is used to call the utility. In addition, it is more secure to separate the code that retrieves HR data into a compiled class library so that the lookup information is not exposed within the Web service code.

The BDC Lookup Utility uses the Microsoft.Office.Server.ApplicationRegistry namespace to connect to the Business Data Catalog from the class library. The first step in setting the connection is to designate the Shared Services Provider (SSP) that provides the Business Data Catalog. This is accomplished by using the following call to the SqlSessionProvider singleton Instance property.

SqlSessionProvider.Instance().SetSharedResourceProviderToUse(yourSSPName);

The variable yourSSPName is a local variable that is set when creating an instance of the BDC Lookup Utility to designate the relevant SSP.

The next code used to look up the approver information within the Business Data Catalog is the actual connection to the appropriate Business Data Catalog application and system instance. The connection is established by indicating the LobSystemInstance and Entity objects with the following statements.

NamedLobSystemInstanceDictionary sysInstances = 
ApplicationRegistry.GetLobSystemInstances();
LobSystemInstance HRInstance = sysInstances["HRLookupInstance"];
Entity prodEntity = HRInstance.GetEntities()["HRLookup"];

After the connection is made to the appropriate Business Data Catalog application, the FindSpecific() method is called by using the filter specified in the application definition file and the specific LobSystemInstance object defined previously. For the permission request solution, the filter defined in the application definition is the cost center ID. This is an alphanumeric ID that is used to identify each cost center uniquely. The cost center ID for the particular employee submitting the request is passed into the BDC Lookup Utility and then is used as the filter for the Business Data Catalog data to retrieve the appropriate cost center approver information.

The data retrieved based on the filter value provided is returned into an IEntityInstance interface object. This object is enumerated to find the specific field of the required entity. In the case of the permission request solution, the cost center approver NTID, full name, and e-mail are needed. These three fields are found within the returned Business Data Catalog data and assigned to an instance of the Approver data class. This instance of the Approver data class is then returned to the Web service calling the BDC Lookup Utility, as described later in The BDC Lookup Web Service. The code for the retrieval of the cost center-specific data is follows.

object IdentifierValue = userCostCenter;

IEntityInstance IE = prodEntity.FindSpecific(IdentifierValue, HRInstance);

foreach (Field f in prodEntity.GetSpecificFinderView().Fields)
{
if (f.Name == "ENT_ADMIN_FLL_NM")
{
internalApprover.ApproverName = IE[f].ToString();
}
}

foreach (Field g in prodEntity.GetSpecificFinderView().Fields)
{
if (g.Name == "ENT_ADMIN_WKR_WRK_EMAIL_AD")
{
internalApprover.ApproverEmail = IE[g].ToString();
}
}

return internalApprover;

The BDC Lookup Web Service

The BDC Lookup Web service allows for complete decoupling of the BDC Lookup Utility and the HR data from the permission request solution. The BDC Lookup Web Service makes use of the standard .NET Web service methodology to create a proxy class of the BDC Lookup Utility library. The appropriate data is retrieved and passed back to the InfoPath form calling the Web service.

The Web Methods

The custom Web service in our solution supports a method named BDCApproverLookup that invokes the Business Data Catalog SpecificFinder method. The InfoPath form code retrieves the cost center approver information by passing in only the cost center ID to this Web method.

Before the BDCApproverLookup method can return Approver entity data, it must first connect to the Business Data Catalog and gain access to the application definition. In the permission request, solution the connection information is encapsulated within the BDC Lookup Utility (as described earlier), and therefore, does not need to be provided to the Web service. The Web method creates an instance of the Approver class (into which the retrieved approver information is returned) and a BDCLookupUtility class instance.

After the BDCLookupUtility class is instantiated, the SSP name is assigned, and the FindApprover method of the BDCLookupUtility is called, passing in the cost center filter value. (The filter value is passed in from the InfoPath form into the BDC Lookup Web service call, which is discussed in InfoPath Permission Request Form Code.) Following is the BDCLookupApprover Web method code that calls the BDC Lookup Utility.

[WebMethod]
public ApproverInfo BDCApproverLookup(string CostCenterNumber)
{
ApproverInfo costCenterApprover = new ApproverInfo();
BDCLookupUtility BDCLookup = new BDCLookupUtility();

BDCLookup.SSPName = "SharedServices1";
costCenterApprover = BDCLookup.FindApprover(CostCenterNumber);

return costCenterApprover;
}

Figure 12. BDC Lookup Web service sample returned data

BDCLookup Web service sample data