Programmatically modifying configuration data – Part 1: Configuration managers

We often get asked how to work with the object model to programmatically modify or establish the configuration data for a site or list.  This is often done by customers as part of site provisioning.  This article is part 1 of a series of articles regarding how to work with configuration data.  This article describes the fundamentals that you must understand about how to retrieve and save configuration data.

This article assumes that you are doing the development on a SharePoint server that has the HP TRIM SharePoint integration installed.

References
Firstly you will need a reference to the right assemblies.  Add a reference in your project to the following assemblies:

  • HP.Integration.SharePoint.dll
  • HP.Integration.SharePoint.Common.dll
  • HP.HPTRIM.Integration.SharePoint.Common.dll

You will find these assemblies in the GAC and can select them by browsing (in the “add reference” dialog) to C:\Windows\assembly\GAC_64

Understanding “resultant” and “specified” configuration
When you save a specific set of configuration i.e. the equivalent of what the user actually enters in the UI, this is known as the “specified” configuration.  What is actually used by the integration though may be different taking into consideration:

  • Inheritance
  • Template defaults

The configuration that is actually used as calculated based on the specified configuration and taking these variables into consideration is known as the “resultant” configuration.

The integration always uses resultant configuration, but it is specified configuration that you create and save.


The configuration manager
When it comes to retrieving and saving configuration, at the core of managing configuration is a class called the “Configuration Manager”.   The fully qualified name of this class is:

HP.Integration.SharePoint.Configuration.ConfigurationManager

This class provides the core functionality for saving and retrieving configuration.  Configuration data is stored by SharePoint in its property bags. 

What the configuration manager does for you is:

  • Ensure you don’t overwrite newer configuration data with yours (in the case that somebody else changed it since you retrieved it)
  • Clears the in memory cache on every machine in the farm so that your change applies on all machines (otherwise one machine may have the new value but other machines may have cached old configuration values)
  • Logs issues during saving and retrieval

Typically though, you will not use the configuration manager directly, instead using the specialized configuration managers.

Specialized configuration managers
While the configuration manager provides core configuration management functionality, you must use the specialized configuration managers that are built on top of the configuration manager.  These are:

  • HP.Integration.SharePoint.Configuration.RmoManager: management of RMOs
  • HP.Integration.SharePoint.Configuration.LmoManager: management of LMOs
  • HP.Integration.SharePoint.Configuration.Mapping.MappingManager: management of mappings such as column mappings, CT2RT and RT2CT

Specialized configuration managers provide you with methods specific to the type of configuration being managed as well as the ability to return you the resultant configuration taking into consideration inheritance and template defaults.

Specialized configuration managers are what we use in our code.  If you use them in your code and don’t try to bypass them, everything will be ok.  So whenever you are planning on retrieving or modifying configuration, the first thing you will generally do is create an instance of the relevant specialized configuration manager.

Get methods
You will see that the specialized managers have a number of methods that start with “Get”.  Each of these methods is designed to retrieve a particular type of configuration data.  For example:

  • HP.Integration.SharePoint.Configuration.RmoManager.GetListRmo: retrieves the specified RMOs for a list
  • HP.Integration.SharePoint.Configuration.RmoManager.GetResultantSiteRmo: retrieves the resultant RMOs for a particular site
  • HP.Integration.SharePoint.Configuration.LmoManager.GetResultantListRmo: retrieves the resultant LMOs for a particular list
  • HP.Integration.SharePoint.Configuration.MappingManager.GetSiteColumnMapping: retrieves the column mapping for a particular site


A subsequent post will describe the relevant get methods for each manager.

Save methods
Similarly, there are a number of methods in specialized configuration managers that start with “Save”.  Each of these methods is designed to save a particular type of configuration data.  For example:

  • HP.Integration.SharePoint.Configuration.RmoManager.SaveListRmo: saves the specified RMOs for a particular list
  • HP.Integration.SharePoint.Configuration.RmoManager.SaveSiteRmo: saves the specified RMOs for a particular site
  • HP.Integration.SharePoint.Configuration.LmoManager.SaveLmo: saves specified LMOs for a particular site or list
  • HP.Integration.SharePoint.Configuration.MappingManager.SaveSiteColumnMapping: saves the column mapping for a particular site

A subsequent post will describe the relevant save methods for each manager.

 

Author: Jaimie Tilbrook