Excluding content from staging and integration

Event handlers allow you to disable content staging and integration bus synchronization for certain documents or objects. The system provides two types of events that you can use:

• Handling the changes of documents or objects
• Handling the creation of staging or integration tasks

Excluding content by handling document or object changes

When changes are made to documents and objects (such as creating, editing or deleting), the system logs the change data. Content staging and the integration bus use the data to create synchronization tasks, which then transfer the changes to the target server or application.

To completely prevent the system from starting the staging or integration process, handle the following events:

• DocumentEvents.LogChange.Before
• ObjectEvents.LogChange.Before (or <name>Info.TYPEINFO.Events for specific object types)

You can use two different approaches to disable staging or integration inside the event handlers:

e.Settings.LogStaging = false;
e.Settings.LogIntegration = false;

OR

e.Using(new CMSActionContext() {LogSynchronization = false, LogIntegration = false} );

Example

The following example demonstrates how to use LogChange handlers to disable content staging and integration for the /Archive section of a website.

1. Assign handlers to the DocumentEvents.LogChange.Before and PageTemplateInfo.TYPEINFO.Events.LogChange.Before events. The example uses a custom class in the App_Code folder:

   Copy

   
   
   
    using CMS.Base;
    using CMS.DocumentEngine;
    using CMS.PortalEngine;
    using CMS.DataEngine;
    using CMS.Helpers;
   
    [LogChangeHandlers]
    public partial class CMSModuleLoader
    {
        /// <summary>
        /// Custom attribute class.
        /// </summary>
        private class LogChangeHandlers : CMSLoaderAttribute
        {
            /// <summary>
            /// Called automatically when the application starts
            /// </summary>
            public override void Init()
            {
                // Assigns a handler to the DocumentEvents.LogChange.Before event
                // This event occurs when documents are modified, before the system starts logging the changes
                DocumentEvents.LogChange.Before += LogDocumentChange_Before;
   
                // Assigns a handler to the LogChange.Before event for PageTemplateInfo objects
                // This event occurs when page templates are modified, before the system starts logging the changes
                PageTemplateInfo.TYPEINFO.Events.LogChange.Before += LogPageTemplateObjectChange_Before;
            }
        }
    }
   
   
    

2. Define the handler methods (inside the custom CMSLoaderAttribute class):

   Copy

   
   
   
    // Disables logging of staging and outgoing integration tasks for the content of documents in the /Archive section of the website
    private void LogDocumentChange_Before(object sender, LogDocumentChangeEventArgs e)
    {
        // Gets the synchronized document
        TreeNode document = e.Settings.Node;
   
        // Excludes documents under the "/Archive" path from content staging and integration bus synchronization
        if (document.NodeAliasPath.StartsWithCSafe("/Archive"))
        {
            e.Using(new CMSActionContext()
            {
                LogSynchronization = false,
                LogIntegration = false
            }
            );
        }
    }
   
    // Disables 'Create' and 'Update' staging/integration tasks for ad-hoc page templates of documents in the excluded /Archive section
    private void LogPageTemplateObjectChange_Before(object sender, LogObjectChangeEventArgs e)
    {
        // Gets the synchronized object
        GeneralizedInfo obj = e.Settings.InfoObj;
   
        if (obj != null)
        {
            // Continues only for ad-hoc templates
            if (!ValidationHelper.GetBoolean(obj.GetValue("PageTemplateIsReusable"), false))                
            {
                // Checks if the template is used by a document in the /Archive section
                TreeNodeDataSet nodeSet = TreeHelper.SelectNodes("/Archive%", false, null, "NodeTemplateID = " + obj.GetValue("PageTemplateID"), null, -1, false);               
                if (!DataHelper.DataSourceIsEmpty(nodeSet))
                {
                    // Disables logging of staging and integration tasks
                    e.Settings.LogStaging = false;
                    e.Settings.LogIntegration = false;
                }
            }
        }
    }
   
   
    

3. Save the class.

The custom handlers ensure that the system does not create synchronization tasks for:

• The content and metadata of documents in the website’s /Archive section
• Ad-hoc page templates of the documents in the /Archive section (only Create and Update synchronization tasks, does not disable Delete tasks)

Excluding content by handling synchronization tasks

Content staging and the integration bus use synchronization tasks to transfer changes to the target server or application. You can cancel the creation of synchronization tasks during the following system events:

• StagingEvents.LogTask.Before
• IntegrationEvents.LogInternalTask.Before

Excluding content via the LogTask events provides the following advantages and disadvantages:

• Allows you to access the data of the synchronization task inside the event handler. For example, you can disable only specific types of synchronization tasks.
• The system needs to prepare the synchronization data for every object/document change, which requires more overhead than when excluding content through LogChange handlers.

Example

The following example demonstrates how to use the LogTask handler to disable content staging for the deletion of role objects and for content synchronization of certain documents.

1. Assign a handler to the StagingEvents.LogTask.Before event. The example uses a custom class in the App_Code folder:

   Copy

   
   
   
    using CMS.Base;
    using CMS.Synchronization;
    using CMS.DocumentEngine;
    using CMS.DataEngine;
   
    [LogTaskHandlers]
    public partial class CMSModuleLoader
    {
        /// <summary>
        /// Custom attribute class.
        /// </summary>
        private class LogTaskHandlers : CMSLoaderAttribute
        {
            /// <summary>
            /// Called automatically when the application starts
            /// </summary>
            public override void Init()
            {
                // Assigns a handler to the StagingEvents.LogTask.Before event
                // This event occurs before the system creates content staging synchronization tasks
                StagingEvents.LogTask.Before += LogTask_Before;
            }
        }
    }
   
   
    

2. Define the handler method (inside the custom CMSLoaderAttribute class):

   Copy

   
   
   
    private void LogTask_Before(object sender, StagingLogTaskEventArgs e)
    {
        // Handles content staging exclusion of documents
        if (e.Object is TreeNode)
        {
            // Gets the synchronized document
            TreeNode document = (TreeNode)e.Object;
   
            // Cancels the creation of content staging tasks for documents under the "/Archive" path
            if (document.NodeAliasPath.StartsWithCSafe("/Archive"))
            {
                e.Cancel();
            }
        }
        // Handles content staging exclusion of objects
        else
        {
            // Gets the synchronized object
            GeneralizedInfo obj = e.Object.Generalized;
   
            // Gets the synchronization task
            StagingTaskInfo stagingTask = e.Task;
   
            // Cancels the creation of content staging tasks for the deletion of role objects
            if ((obj.ObjectType == PredefinedObjectType.ROLE) && (stagingTask.TaskType == TaskTypeEnum.DeleteObject))
            {
                e.Cancel();
            }
        }
    }
   
   
    

3. Save the class.

The handler ensures that the system does not create staging tasks:

• For changes made to documents in the website’s /Archive section
• When a role is deleted from the system