Working With Custom Hooks: OnEntitySave

This is a general-purpose method for capturing all saves for CSAPI entities (such as pages, assets, users, and system options). All items that have a custom hook related to them invoke these methods. The methods are called upon saving a change or changes to those objects. 

Entities can be thought of as individuals in a group. The groups in the CMS are systems that contain similar types of things, like pages, categories, and users. This general catch-all allows you to gather information about actions that are happening when you don’t know exactly what someone, or some code, is doing in the CMS. 

How To Trigger the Hook  

These hooks are triggered by the following actions: 

• Saving changes to a content item (page, component, folder, or asset) in any edit mode. 
• Moving a content item. 
• Transitioning a content item through workflow. 
• Deleting a content item. 
• Assigning a content item. 
• Checking in a content item. 
• Checking out a content item. 
• Marking a content item for publish. 
• Unmarking a content item for publish. 
• Pasting a content item. 
• Copying and pasting a content item cross-locale. 
• Special pasting (holding ALT while dragging and dropping) a content item. 
• Renaming a content item. 
• Creating a new content item. 
• Using Undo Checkout on a content item. 
• Using Rollback on a content item. 
• Publishing a content item. 
• Saving any localization. 
• Saving changes to a Page Creation Rule. 
• Saving changes to a Presentation Content Unit. 
• Saving changes to a Publishing Target. 
• Saving changes to a Redirect. 
• Saving changes to a Schema. 
• Creating a new taxonomy category. 
• Saving changes to a taxonomy category. 
• Moving a taxonomy category. 
• Removing an association from a taxonomy category through the Taxonomy Manager. 
• Adding an association to a taxonomy category through the Taxonomy Manager. 
• Copying and pasting associations from one category to another. 
• Deleting a category. 
• Creating a user. 
• Saving changes to a user. 
• Deleting a user. 
• Creating a group. 
• Saving changes to a group. 
• Deleting a group. 
• Creating a workstate. 
• Saving changes to a workflow. 

Any new types of entities that get added in future versions will also likely trigger these hooks. 

When to Use This Custom Hook  

These hooks should be used sparingly, as they target so many objects and actions in the CMS. Typically, a developer might use these for debugging their code or an administrator’s set up to see how work is flowing through the CMS and identify problems. 

These hooks can also be on actions that might not have a specific custom hook already prescribed, for example, changes to system options. 

Considerations 

Again, use these hooks very carefully as their code is called with almost every action a user takes in the CMS. Slow code here can severely hinder usability for CMS users. 

When testing these, note that a single action might call this hook multiple times since many changes might be queued up at once to a single action. Infinite loops and extreme recursion may result. 

Example  

Add entity save information to debug logs 

Debugging is a much-needed practice in development. This simple example adds information about the entity that was saved and the user that did the action that led to the save. You will need to enable debugging in your project, following the parameters of your development platform.