Management Injector - Using a custom processor to programmatically alter how records are created in HPRM

Many thanks to Zoltan Eiserle on the team, for putting together this comprehensive article on the new custom management injector capabilities.

One of the new features introduced in 8.11 of the HPRM SharePoint Integration is the concept of allowing a custom processor to modify the way records are created and modified in HPRM.

Some background information needs to be covered before describing these custom processors.

When a SharePoint document or item has one of the four core processes applied to it ( Manage, Finalize, Relocate, or Archive ), a record is created in HPRM that captures the details of the SharePoint document or item. This record is known as a List Item Record ( LIR for short ). After the LIR is created there are some changes to certain properties. These changes are captured and used to update the SharePoint document or item. The SharePoint document or item is now referred to as a Managed List Item ( MLI for short ).
When a change is made to a MLI in SharePoint, the corresponding LIR is updated with the changes. This process is known as LIR Maintenance.

Now back to the new custom processor feature.

A new interface called IManagementInjector has been provided to allow creation of these external custom processors. There are four entry points where custom processing can be performed:

  1. Before an LIR is created (InjectPreRecordCreation method )
  2. After an LIR has been created (InjectPostRecordCreation method )
  3. Before an update to an LIR is made during LIR Maintenance (InjectPreRecordMaintenance method )
  4. After an update to an LIR has been made during LIR Maintenance (InjectPostRecordMaintenance method )

It should be noted that the custom processor is only called during a core process action ( Manage, Finalize, Relocate, or Archive ) or during LIR Maintenance. It is not called if a change is made to the LIR directly in HPRM.

To create a custom processor, create a .NET 4.5 Class Library project that implements IManagementInjector and add code to the methods where you require customisation of the core or maintenance processes. If customisation is needed only for some of the available entry points but not all, add the custom code to those entry point methods where customization is required and create an empty method for those that don’t require customization.

The IManagementInjector is located inside the HP.HPRM.Integration.SharePoint.dll assembly. The fully qualified interface name is HP.HPTRIM.Integration.SharePoint.IManagementInjector

There is a sample custom processor project available ( SampleManagementInjector ) for download here, as a starting point. This demonstrates how the different entry point methods can be used to inject custom processing. It also details the other HPRM Integration SharePoint assemblies that need to be referenced as well as the reference to the HP.HPTRIM.SDK assembly. I would recommend opening this and referring to it as you read this article.

Once the custom processor has been implemented the assembly needs to be copied to the bin folder under the installation folder of the HP Records Manager SharePoint Integration component (by default the install location is C:\Program Files\Hewlett-Packard\HP Records Manager\HP Records Manager SharePoint Integration). The bin sub-folder contains all the HPRM Integration SharePoint assemblies

The HP.HPTRIM.SDK assembly is located a couple of levels up (by default at C:\Program Files\Hewlett-Packard\HP Records Manager).

It is recommended that the HP Records Manager SharePoint Service (a Windows service) is restarted after copying the custom processor assembly to the bin folder.

The final step is to configure the Default Integration Settings page (accessed from the HPRM Governance and Compliance SharePoint App page) to specify the custom processor to use. Enter the required details in the Management Injector section at the bottom of the Default Integration Settings page.

The custom processor is now ready to be used during core and LIR maintenance processes. If a problem is encountered during an attempt to load and call the custom processor, the error is logged in the SharePointIntegration.log file inside the Logs sub-folder of the installation folder of the HP Records Manager SharePoint Integration component.

The last topic we need to cover in this article is how to make changes inside the creation and maintenance methods of the custom processor in order to affect the record creation and update.

The post-creation and post-maintenance methods are straight forward, the supplied Record object is provided and changes can be made to its properties. If the Record object is saved before exiting the ‘Post’ method the changes will flow on to update the MLI, so long as there is a valid Column Mapping between a SharePoint Site or List column and the Record Property or User Field being modified. The Item and ManagementDetails objects are provided as a reference only, they should not be changed by the ‘Post’ methods.

The pre-creation and pre-maintenance methods are supplied with the Item and ManagementDetails parameters. Through modification of select properties on these two objects, the custom processor can modify the creation or maintenance process.

Currently the only supported change to Item is changing the value of a DataStoreProperty.Value property inside the MappedProperties collection.

The MappedProperties is a collection of DataStoreProperty objects. Each DataStoreProperty has a property called Column and another called Value. The DataStoreProperty.Column property in turn has a property called Qualifier and another called Id. The DataStoreProperty.Column.Qualifier and DataStoreProperty.Column.Id properties can be used to determine which Record Property or User Field the current DataStoreProperty object corresponds to. The DataStoreProperty.Column.Qualifier will be either ‘Property’ or ‘Field’ (use of ‘ArtificialField’ is not supported). The DataStoreProperty.Column.Id will contain either the name of the Record Property (when Qualifier is ‘Property’, the Record Property names are available from the HP.HPTRIM.SDK.PropertyIds enumeration), or it will contain the integer identifier of the Record User Field (when Qualifier is ‘Field’).

Once the DataStoreProperty object has been identified through its Column properties, the DataStoreProperty.Value can be modified if required. The DataStoreProperty.Value property stores an object which can be a basic type such as String, Integer, Boolean, or DateTime. It can also hold a complex type such as DataStoreObject or SharePointUser.

When the DataStoreProperty.Value property holds a basic type the modification process is simple, however the DataStoreProperty.Column.DataType.Name property should be used to assist with determining what values are valid to assign to the DataStoreProperty.Value property. The DataStoreProperty.Column.DataType.Name property matches Property and User Field data types available on Records. These data types have limits imposed by HPRM that must be adhered to when modifying the DataStoreProperty.Value property.

Discussion of how to modify DataStoreProperty.Value, when it holds a complex type, is outside the scope of this article and will be handled by a more advanced article at a later date.

The second parameter passed in to ‘Pre’ methods is ManagementDetails. Currently the only supported change to ManagementDetails is to modify its Rmos property which is the resultant List RMO settings. Within the ManagementDetails.Rmos property the modifications should be restricted to the following sub-properties:

  • DoNotCreateContainer
  • UseSpecificContainer
  • CreateContainer
  • CreateContainerForTopLevelFolder
  • CreateContainerForSubFolders

Note that DoNotCreateContainer, UseSpecificContainer, and CreateContainer are mutually exclusive and one and only one must be set to True (having all set to False is not a supported configuration either).

If UseSpecificContainer is set to True then a valid DataStoreObject must be set for SpecifiedContainer. It is strongly advised the implementer first understands how HPRM Records are represented by the DataStoreObject type before modifying these settings. The Record specified must have a behavior type of Folder. The DataStoreObject must have correct values set for its Id (the Unique Identifier of the HPRM Record) and Name (the Title of the HPRM Record) properties. The same requirements apply to modifying the SiteParentContainer property. HPRM Record Types and Classifications can also be represented by a DataStoreObject in a similar manner.

CreateContainerForSubFolders should only be set to True if CreateContainerForTopLevelFolder is also True.

The following properties of ManagementDetails.Rmos.DataStoreSettings can be modified with following restrictions:

  • When DoNotCreateContainer is set to True
    • RecordClassification (a DataStoreObject representation of a HPRM classification)
  • When CreateContainer is set to True the following container creation options can be modified:
    • UseSpecified (use the Folder Record Type specified in SpecifiedRecordType or use the default Folder Record Type specified in Default Integration Settings)
    • SpecifiedRecordType (a DataStoreObject representation of a Folder record type, used only if UseSpecified is set to True)
    • UseDefaultClassification (use the default container classification specified in the Default Integration Settings or use the classification specified in SpecifiedContainerClassification)
    • SpecifiedContainerClassification (a DataStoreObject representation of a classification, used only if UseDefaultClassification is set to False)
  • When CreateContainerForTopLevelFolder is set to True the following container creation options for creating containers to represent SharePoint Folders can be modified
    • UseSpecifiedFolderRecordType (use the Folder Record Type specified in SpecifiedFolderRecordType or use the default Folder Record Type specified by Default Integration Settings)
    • SpecifiedFolderRecordType (a DataStoreObject representation of a Folder record type, used only if UseSpecifiedFolderRecordType is set to True)
    • UseDefaultClassificationForFolder (use the default container classification specified in the Default Integration Settings or use the classification specified in SpecifiedFolderClassification)
    • SpecifiedFolderClassification (a DataStoreObject representation of a classification, used only if UseDefaultClassificationForFolder is set to False)

It is highly recommended that the implementer understands RMO behavior thoroughly before attempting to make modifications to any of the ManagementDetails.Rmos properties. On the Programmatically Setting RMOs – Part 2 article there is a screen shot showing the alignment of the above properties to the fields of the RMO settings page, this should be consulted when attempting to modify them. Please note that some underlying data types have changed since that article was published but in general it contains useful information for making changes to the ManagementDetails.Rmos properties.

Any property of the Item or ManagementDetails parameters that have not been described here are not supported for modification. Changes to these unsupported properties can result in unexpected or incorrect behavior. This applies to the ‘Pre’ methods. The ‘Post’ methods do not support modification of the Item or ManagementDetails parameters at all.