SharePoint List Management Agent for ILM 2007

The SharePoint List Management Agent for ILM 2007 is an attempt to provide an easy-to-use, familiar interface between ILM 2007 and a WSS 3.0 or MOSS 2007 list. It is deployed as a "PackagedMA" to help alleviate some of the more tedious tasks involved with the development of extensible management agents (ex. run profile configuration, object type configuration, data manipulation, etc.).

Features

• Support for both full and delta imports.
• Support for export to SharePoint.
• Support for Multivalue list columns.
• Support for Lookup list columns.
• Support for Person or Group list columns.
  • UserMulti columns are currently only supported for import.
• Support for most other column types.
• Support for "Reference (DN)" attributes.
• Allows configuration using the display names of the columns, rather than the internal SharePoint column name (i.e. "First Name" instead of "First_x0020_Name").
• Packaged MA, so it shows up in the list of available management agents, with most of the basic configuration already in place (including pre-configured run profiles).

How It Works

ILM

The SharePoint List MA is implemented as a packaged call-based extensible management agent. For synchronization, it provides two connector space object types with the following attributes by default (see the Configuration section for details on configuring the listItem object):

• listItem - Represents the list item itself.
  • ID - The SharePoint list ID of the item.
  • Delta - The type of change to process during delta imports.
  • ObjectType - The attribute used to determine the object class.
• reference - Represent a reference to an object for use with "Reference (DN)" attributes.
  • ID - Depends on the "Reference (DN)" attribute
    • If a Lookup column, the column chosen for display.
    • If a Person or Group column, the UserInfo name (username).
    • If any other column type, the value of the column.
  • ObjectType - The attribute used to determine the object class.

SharePoint

The SharePoint List MA uses CAML and the Lists and Users and Groups web services to communicate with SharePoint. The list columns to synchronize are configured in the management agent, so only the necessary columns are queried for.

Imports

The SharePoint List MA uses the attribute-value pair import file format to provide support for both multi-value and reference attributes. Upon import, it first retrieves the list schema using the GetList method of the Lists web service, parses the schema into a more useable format, and verifies the attribute configuration while generating the list query CAML. It then uses the GetListItemChangesSinceToken to retrieve the list items, passing a null token for full imports, or the last token used for delta imports (as stored in the customData parameter of the GenerateImportFile method). The results are then parsed and written out to the AVP import file as listItem objects. For multi-value Person or Group columns, the username is retrieved from the built-in SharePoint UserInfo list using the ID from the column and the GetListItems method of the Lists web service. For attributes defined as "Reference (DN)", a reference object type is written to the file.

Attribute-value pair import file example

ObjectType: reference
ID: ver3\stevenkean

ObjectType: reference
ID: ver3\robginsburg

ObjectType: listItem
ID: 1
Group Name: AppAdmins
Display Name: Application Administrators
Membership: ver3\stevenkean
Membership: ver3\robginsburg

NOTE: A full import is necessary for proper processing of reference attributes.

Exports

The SharePoint List MA uses call-based exports, so each list item update is exported individually. Updates are made using CAML and the UpdateListItems method of the Lists web service. For Person or Group columns, if a user's SharePoint UserInfo list ID cannot be parsed from the value, it is looked up using the GetUserInfo method of the UserGroup web service. With the exception of multi-value Person or Group columns, all default SharePoint column types are supported for export.

Installation

Installation of the SharePoint List Management Agent is fairly straight forward. Simply launch the SharePointListMA.msi and all required files should be installed to their correct location.

Configuration

To configure the SharePoint List Management Agent, open Identity Manager, switch to the Management Agents tab, and click the "Create" action.


Select the "SharePoint List Management Agent (CSI/Version3)" management agent from the list, specify a name and description, and click Next.


On the "Configure Connection Information" page, enter the following information, and click Next:

• Connect To - The URL to the SharePoint site (NOTE: This is the URL to the site that hosts the list, not the URL to the list itself.).
• User - The domain\username of a user who has read/write permissions to the list.
• Password - The password of the user who has read/write permissions to the list.

NOTE: If no username and password are specified, the management agent will use the context of the Microsoft Identity Integration Server service.


On the "Configure Additional Parameters" page, set the following values, and click Next:

• SharePoint_List_Name - The name of the SharePoint list to synchronize.
• Use_DisplayNames - True if the column names are configured using the display names (ex. "Group Name" of "First Name"). False if the internal SharePoint column name is used (ex. "Title" or "First_x0020_Name").

On the "Configure Attributes" page, add a new attribute for each list column that should be imported, and click Next.

NOTE: Specifying a type of "Reference (DN)" will cause the management agent to create reference objects during import.

On the "Map Object Types" page, ensure the listItem and reference objects are both mapped correctly, and click Next.


On the "Define Object Types" page, select the listItem object, click Edit, and add the newly defined columns to the object. Click Next.


Configure your connection filters, attribute flows, join and projection rules, and deprovisioning as you would any other management agent, and you should be ready to go!

Known Issues

• Multi-value Person or Group columns are not supported for export.
• Currently, one million records are requested at a time to avoid the need for paging.
• Reference (DN) attributes are not fully supported for delta imports.
• Lookup columns currently use the display value as the ID for Reference (DN) attributes. If that value cannot be related back to the parent list item, then exports will not work. Using a calculated column with a parseable ID in it is a good way to deal with this for now. Ideally, the MA can be updated to look up the proper ID in the parent list.
• ID should not be used for joins, as the list ID may change if the list is rebuilt in SharePoint.

Special Note

While work on this management agent was done independently, it is important to note that Alex Tcherniakhovski has done some good work on this topic as well. For anyone interested, it's worthwhile to read his article: ILM 2007 with SharePoint Services Lists.