SharePoint Server 2010 is a great platform for storing information about the users in an organization. Using the User Profile Service application and its related components, you can configure SharePoint to store a variety of information about users and synchronize that information with external storage, such as Active Directory (AD) or any other data source to which you can connect using Business Connectivity Services (BCS). Users can then edit their information using the user profile pages. The external storage sources will then be updated automatically with this new information, thereby making the information more relevant and timely throughout the organization.
However, allowing users to update their own information introduces new problems when it comes to governance, particularly in terms of security of information, privacy, and ethical conduct. Fortunately, one component of the User Profile Service application is the User Profile Change Service. The User Profile Change Service isn’t a true service but rather a series of tables within the User Profile Service’s profile database and a timer job (i.e., User Profile Change Cleanup Job) that’s used to clear stored changes older than 14 days. By default, the User Profile Change Cleanup Job runs once a day. You can adjust this frequency by editing the schedule for this timer job.
You can use the User Profile Change Service to view and report on changes. Unfortunately, however, there isn’t a UI to view these changes, so you must use the SharePoint API to query the system to view changes.
But what kind of changes can you query the system for? The answer is simple: all user profile properties. You can see the properties that are available by navigating to the Manage Service Applications page in the Central Administration site, selecting a User Profile Service application, and clicking Manage to view the User Profile Management page. (If a User Profile Service application doesn’t exist, you must create one in order to store and manage user details.) Click the Manage User Properties link to see all the available properties. From here you can create, delete, or edit any properties that you want your users to populate with data. When a user edits any of the values for one of these properties, a change record will be created. However, it’s important to remember that changes will persist for only 14 days, assuming the User Profile Change Cleanup Job is running. If you need to keep these changes longer, you can change the retention period by running a simple STSADM command. (There’s no Windows PowerShell equivalent way to do this.) The following example changes the retention period to 28 days:
stsadm -o profilechangelog -userprofileapplication "My User Profile Service App"
-daysofhistory 28
(Although the command wraps here, you'd enter it all on one line. The same holds true for the other commands that wrap.) You can gain access to these change records using the objects in the Microsoft.Office.Server.UserProfiles namespace, which is part of the Microsoft.Office.Server.UserProfiles.dll assembly. Specifically, you use the UserProfileManager, UserProfileChangeQuery, and UserProfileChangeToken classes.
Retrieving User Profile Changes
To retrieve user profile changes, you must first create an instance of the UserProfileManager class. This class is the gateway for all programmatic manipulations of the user profile properties and their properties. To create an instance of this class, you must provide it with a Microsoft.SharePoint.SPServiceContext object. This context object makes sure that you’re working with the correct User Profile Service application.
There are two ways to retrieve the SPServiceContext object:
- You can provide a specific service application proxy object and a site subscription identifier. (Site subscriptions are only relevant in multi-tenancy scenarios. Most users can use the default site subscription, which is essentially just an empty globally unique identifier—GUID.)
- You can provide a site collection that’s associated with the service application.
Listing 1 demonstrates the first approach using PowerShell. Alternatively, you could use code in which the URL to the site collection is passed to the GetContext method. Either approach is perfectly acceptable.
Now that you have the SPServiceContext object, you can create the UserProfileManager object:
$manager = New-Object Microsoft.Office.Server.
UserProfiles.UserProfileManager $context
The UserProfileManager class contains the GetChanges method. This method has three overloads:
- GetChanges(), which retrieves all changes
- GetChanges(UserProfileChangeToken), which retrieves all changes from a given date or event
- GetChanges(ProfileBaseChangeQuery), which retrieves specific changes given a query object
All the GetChanges overloads return a UserProfileChangeCollection object. This object contains all the changes stored as either a UserProfileChange object or one of its derivative types:
- UserProfileColleagueChange
- UserProfileCustomChange
- UserProfileLinkItemChange
- UserProfileMembershipChange
- UserProfileOrganizationMembershipChange
- UserProfilePropertyValueChange
- UserProfileWebLogChange
Each object type stores the resultant change in a manner most appropriate for the given type. It’s important to note that a separate object will be returned for every change. So, if a user edits two profile properties, you’ll have at least two objects (one for each property). As the phrase “at least” implies, you could have more than two objects. For example, if the user edits the Skills property by adding several skills, a separate change object will be returned for each skill added (i.e., one object for each value entered).