How to: Affect Logging of Staging Tasks
In this blog post I will show you how you can easily affect the logging of staging tasks for documents and objects using the LogChange handler(s) introduced in version 7.
UPDATE: An updated version of the code used in this article can now be found in our documentation here: Example
Intro
We often that you, our customers, need to be able to disable logging of staging tasks for particular documents or objects so that changes are not transferred to production. In versions prior to 7, you were only able to disable logging for the whole object type using the TypeInfo static information. In version 7 we have provided you with new handlers that enable the disablement of logging on a per object basis.
You can find general information about the handlers, as well as the list of supported handlers, in our documentation.
Let's move on to real-world examples.
Tasks for documents
Let's say you have a /Archive document section where you store expired news items. You want to make sure that an unwanted change made in this section won't log a staging task. You can use the DocumentEvents.LogChange handler to implement this behavior:
using System;
using CMS.DocumentEngine;
using CMS.SettingsProvider;
/// <summary>
/// Excludes documents under '/Archive' path from staging.
/// </summary>
[CustomDocumentEvents]
public partial class CMSModuleLoader
{
/// <summary>
/// Attribute class that ensures the loading of custom handlers
/// </summary>
private class CustomDocumentEventsAttribute : CMSLoaderAttribute
{
/// <summary>
/// Called automatically when the application starts
/// </summary>
public override void Init()
{
// Assign custom handlers to the appropriate events
DocumentEvents.LogChange.Before += new EventHandler<LogDocumentChangeEventArgs>(LogDocumentChange_Before);
}
void LogDocumentChange_Before(object sender, LogDocumentChangeEventArgs e)
{
// Get current document
var doc = e.Settings.Node;
// Check the document section
if (doc.NodeAliasPath.StartsWith("/Archive/"))
{
e.Settings.LogStaging = false;
}
}
}
}
As you can see, you have the context of the current document available. For this example, I used the
NodeAliasPath property to identify the section.
Tasks for objects
For the objects, there is a separate handler - ObjectEvents.LogChange. The usage is similar to documents. So let's say you have an external service to execute your custom code and this service uses a dedicated user account to distinguish the changes made by this service. You want to exclude these changes from being synchronized.
using System;
using CMS.SettingsProvider;
/// <summary>
/// Excludes objects of the object type 'cms.user' whose code name is 'custom.service' from staging.
/// </summary>
[CustomObjectEvents]
public partial class CMSModuleLoader
{
/// <summary>
/// Attribute class that ensures the loading of custom handlers
/// </summary>
private class CustomObjectEventsAttribute : CMSLoaderAttribute
{
/// <summary>
/// Called automatically when the application starts
/// </summary>
public override void Init()
{
// Assign custom handlers to the appropriate events
ObjectEvents.LogChange.Before += new EventHandler<LogObjectChangeEventArgs>(LogObjectChange_Before);
}
void LogObjectChange_Before(object sender, LogObjectChangeEventArgs e)
{
// Get current object
var obj = e.Settings.InfoObj;
// Object is user with specific user name
if ((obj.ObjectType == PredefinedObjectType.USER) && (obj.ObjectCodeName == "custom.service"))
{
e.Settings.LogStaging = false;
}
}
}
}
Using the object context, you can identify the
user object type and disable the logging of these tasks if the code name (
user name) is equal to a specific one.
Not just the staging tasks
The LogChange handler is called when document or object is changed. This extends the range of usability beyond the staging module.
For documents, you can also limit logging of integration tasks.
For objects, you can limit not just the logging of integration tasks, but also the exporting of "import delete tasks" for incremetal deployment as well as the creation of object version.
Was this helpful?
I believe it was! :) As of version 7, you have a pretty straightforward way of limiting the logging of staging tasks to being on an object/document basis which should cover all your previously mentioned requirements. Are you missing any additional context in these handlers? Please let us know in comments below.