Creating an Event Handler
An Event Handler is a piece of functionality that is triggered when a certain type of event happens to a certain Content Manager item. Create an Event Handler by creating a class that extends Tridion.ContentManager.Extensibility.TcmExtension. You then need to compile your Event Handler into an assembly (DLL) and register it.
About this task
You can implement various Event Handlers, for example:
- when a Component is created, you automatically associate the Component with a specific Component Template, put the resulting Component Presentation on a Page and publish the Page.
- you can log any action performed on the Content Manager to a back office as part of preserving an audit trail.
Procedure
- In Visual Studio, create a class that extends Tridion.ContentManager.Extensibility.TcmExtension. This class must have a unique class attribute, say,
[TcmExtension("MyUniqueEventHandlerExtension")]. - In the constructor of this class, execute code that subscribes to one or more events using the following methods:
Method Description SubscribeAsyncSubscribe asynchronously to an event. Select this method if your Event Handler code does not affect the data being handled in the Content Manager. For example, if your Event Handler saves data to a backup system or a log file, you can select this method. SubscribeSubscribe synchronously to an event. Select this method if your Event Handler code changes the data being handled. For example, if your Event Handler analyzes a Component and then adds metadata to it, ensure that you select this method. The methods have the same signature:
Subscribe<TSubject, TEvent>(TcmEventHandler<TSubject, TEvent> eventHandler, EventPhases phases, EventSubscriptionOrder order) SubscribeAsync<TSubject, TEvent>(TcmEventHandler<TSubject, TEvent> eventHandler, EventPhases phases, EventSubscriptionOrder order)where the parameters mean the following:Parameter Description TSubject(type parameter)The type(s) of the object you are checking events for. This can be any item of class Tridion.ContentManager.IdentifiableObject or any of its subclasses, which includes any kind of content item (such as Component, Schema or Target Group), organizational item (such as Folder or Structure Group) or system-wide object (such as User or Group). TEvent(type parameter)The type(s) of event that trigger this code if applied to an item of the object type specified in TSubject. This can be any event of class Tridion.ContentManager.Extensibility.TcmEventArgs or any of its subclasses.TcmEventHandler<TSubject, TEvent> eventHandlerThe name of the method that contains the code you want to be triggered when the event occurs. This method should be contained in the same class and should have the same parameters as the type parameters of this SubscribeorSubscribeAsyncmethod.EventPhases phasesThe exact moment during the event at which the event code should be triggered. Note that this parameter is an enumwithFlagsAttribute, meaning that you can select multiple moments, which in turn means that a single event could trigger the same code multiple times.EventSubscriptionOrder orderThis optional parameter specifies when the event code should be executed if the same event triggers multiple Event Handlers. - Now, in the same class, implement your event code in a method with the name specified in the
eventHandlerparameter of theSubscribeorSubscribeAsyncmethod. In this method, you can perform any action you wish, including any type of querying, modification or other manipulation of items in the Content Manager. Include any namespace you need to access these items.When you write this code, note the following:
- You can make changes to the members of the
TEventparameter (the members are different depending on the event type) by exchanging information between Event Handlers. - When executed, the code you write may result in other event code being triggered.
- From your event handling method, you can identify the specific user who triggered the event through the
Sessionproperty of your first parameter of type<TSubject>. For example, if your method has a signatureHandlerForSave(Component subject, SaveEventArgs args, EventPhases phase), get the name of the user by checkingsubject.Session.User.Title.
- You can make changes to the members of the
- If you intend to enable the (optional or mandatory) use of a custom configuration file for this Event Handler, use the
AddonConfigurationproperty of theTcmExtensionclass to have the custom configuration automatically accessible to the extension through the .NET client,AddonService.SDK. - Once you are satisfied with your code, shut down the following services on your Content Manager server:
- IIS
- Any SDL Tridion Sites-related COM+ services
- If your code is related to publishing, the Publisher service of SDL Tridion Sites
- Compile your class to a .NET assembly.
Note: If your event code contains a bug that raises an exception, it can cause the event that triggered it to hang. Especially if your event code is likely to be triggered very often, this can easily cause the system to freeze. Always test your event code before deploying it.
- If this Event Handler constitutes an Add-on feature to your product all by itself, or if this Event Handler is part of a larger Add-on feature for which you have not yet created an Add-on ZIP file, create a new ZIP file for your Add-on feature.
- Add your Event Handler .NET assembly file to the Add-on feature ZIP file to which it belongs. Feel free to add it to a new or existing folder in the ZIP file.
- Extract the Add-on feature manifest file, manifest.json, from the Add-on feature ZIP file, and open it for editing.
- If you enabled the use of a custom configuration file for this Event Handler, ensure that the top-level section of the file has a property
requireConfigurationset to the valueyes(if you want the uploading of a custom configuration to be mandatory) oroptional(if you want such uploading to be optional). If you omit the property altogether, its value defaults tooptional. - In the
extensionsarray, insert the following JSON fragment:{ "name": "EHNAME", "type": "CMEventHandler", "properties": { "assemblyFileSource": "PATH\\TO\\EHFILE.DLL" } }where:- EHNAME is the name of your Event Handler
- PATH\\TO\\EHFILE.DLL is the relative folder path (if any) to the .NET assembly, followed by the filename of the .NET assembly, with the .dll extension
- Save and close the modified manifest.json file and update it in the Add-on feature ZIP file.
- Deploy or redeploy the Add-on feature ZIP file from the Add-ons screen in Content Manager Explorer. If you specified the ability to upload a custom configuration separately, create and upload a configuration as needed.
- Restart the services you stopped.
Results
- Event hierarchy
Because the events are organized in a hierarchy, you can catch multiple events at the same time. You select this event in your call toSubscribeorSubscribeAsync. - Event phases
In your call toSubscribeorSubscribeAsync, an event handler can be triggered at one or more phases of an event:Initiated,Processed,TransactionCommitted,TransactionAbortedorTransactionInDoubt. - Event subscription order
To ensure that Event Handlers are triggered in the order in which you want them to be triggered, you can specify the priority of the current Event Handler by setting theorderparameter in your call toSubscribeorSubscribeAsync. - Event Handler implementation guidelines
This topic provides some more insight into how Event Handler subscription and disposal works, and how to implement it.