Working With Custom Hooks: OnRollbackAsset
The rollback action replaces the checked out version of an asset with the state it was in at an earlier time in history. This custom hook can save you from falling into the traps sometimes associated with this action.
In the context of the Ingeniux CMS platform, assets refer to content items like images, PDF documents, and even sometimes code that are stored in the CMS and published out to a publishing target. Assets differ from page types and components – which are created, edited, and managed directly in the CMS Site Tree – in that they are uploaded, or brought into the CMS, from outside of the platform. Once uploaded, they are stored in the Asset Management System (and usually placed into an Asset Schema) where they can be managed, edited in certain ways, and have metadata assigned to them.
When a user does a rollback on an Asset it has to be checked out and assigned to them. The current checked out version of the item is replaced with the content of the most recently checked in version’s content. There is no undo on this action and the content of the checked-out version that is replaced is deleted irretrievably. Rollback leaves the item checked out to the user at the end of the process.
How To Trigger the Hook
This method is triggered through the following actions:
- Right-clicking on an Asset and selecting Rollback from the context menu.
- Having a script use the rollback() method in the CSAPI.
When to Use This Custom Hook
This hook is typically used to avoid taking a rollback action that would cause some sort of damage or have an undesired effect.
You might want to use this hook to check the previous version against the current version and prevent the hook from finishing if there are any differences that don’t work for your CMS. This usually means checking the version of the previous schema, the content fields, the naming convention, or anything else that you try to enforce with your assets. Users don’t see the previous version of content before they rollback, unlike when they revert from the history tab.
Considerations
Rolling an item back permanently deletes the checked-out version of a content item and returns it to the content of the last checked in version. On pages and components, this can be quite drastic, as there is a lot of content that could have changed. With assets, however, the editable content is mostly metadata for searching in the CMS. Taxonomy categories do not rollback, so they are not a consideration here. The only content that is usually of concern in an asset rollback is the name of the asset and the file attached to the asset.
It’s important to note that rollback and revert are not the same thing. Performing a revert from the history tab, or other means, does not trigger the rollback hook.
Rollback is a rare action and only accessible through a single interface, so this hook won’t be manually triggered often. Avoid calling the methods to rollback in the CSAPI from within these rollback hooks to avoid infinite loops.
Example
Prevent Rollback to Previous Schema Versions
When a developer makes a change to a schema (such as adding or removing content fields) the version of the schema changes by auto-incrementing. Content items are created to match the current version of the schema and can be synced to match newer versions of schemas by a developer.
When a content item is checked in, the version that is made in history contains data that matches the version of that item to the version of the schema. Some actions, including rollback, can take a content item back to a version that isn’t on the current schema.
This script prevents the rollback if the current version of the schema doesn’t match the version that the previous check in was.
//Prevent rollback if the previous version isn’t on the same schema version as the current version.
int currentVersion = contentItem.LastVersion.SchemaVersion.VersionNumber;
int assetLastVersion = contentItem.CheckedInVersion().SchemaVersion.VersionNumber;
if (assetLastVersion != currentVersion)
{
throw new Exception("Cant Rollback the current version isn’t on the same schema version as the current schema version." );
}
The code above gets the two values we need to compare and then throws an error if the versions don’t match with a message that the versions don’t match. Any error thrown will cancel the execution of the action that triggered the script.
Ways to Extend the Functionality Further
This script could be enhanced in the following ways:
- Instead of canceling, write a log that the item was rolled back and is out of sync with the schema so it could be put into sync by an administrator or a developer.
- Only allow rollback by users that are developers or administrators and understand the implications and be able to revert any undesired changes.
There are no comments yet.