Working With Custom Hooks: OnCheckInAsset
Checking in an asset in the Asset Tree is a common action and a necessary step in the go-live process in the CMS. We explore how - and why - paramaters might be set on the action of checking in an asset using this custom hook.
When you check in an asset in the Asset Tree in Ingeniux CMS, the current state of the asset (metadata fields as well as the file attached) is committed to history. An asset must be checked in before it can be marked for publish or published to a publishing target.
How To Trigger the Hook
This method is triggered through the following actions:
- Clicking the Check In button in the toolbar above the edit form.
- Using the right-click context menu in the Site Tree and selecting Check In.
- Using the right-click context menu in reports results and selecting Check In.
- Advancing a content item in a workflow that includes a check-in action.
When to Use This Custom Hook
Checking in a content item is an essential step to the go-live process in the CMS. Enhancing this action with a custom hook can give you more control over the content that's being prepared to be published to your website or application. However, adding too much to this process can bottleneck your CMS functionality. Make sure that your scripts are concise and fit well in with your work process.
That said, CMS Administrators might be interested in setting up parameters around how and when an asset is checked in to:
- Prevent a content item from being checked in when certain requirements are not met (see example below).
- Notify owners of pages that use the asset of changes.
- Update third party DAM systems with relevant changes.
Considerations
You will need to think about how these hooks interact with your workflows and avoid taking actions that would put things in states they don’t belong in as that could confuse your users and mess with your internal content management and publishing processes.
If your users are using workflow, use workflow in your hooks. If, instead of workflow, they manually check in pages and components, then feel free to take those same actions in your hooks.
Keep in mind that check in can be prevented by many things (e.g., empty required fields) and cancel your script. If your assets have strict security settings, many required content fields, or other requirements that could prevent check-in, you’ll need to account for that in your scripts.
Be careful when cancelling this action and ensure that you have thoroughly communicated your expectations with the user. Even the best trained CMS user will sometimes automatically click “OK” on a pop up without realizing its purpose. Then, they may be confused when content does not appear as expected.
Remember that this action isn’t called individually for each contained asset when a folder and its children are checked in, so you will want to add extra checks if you are worried about batches of items.
Example
Prevent Check In
One thing you can easily accomplish in a custom hook is prevent the check-in action from happening when something doesn’t meet the requirements of check-in.
By “requirements of check-in” we’re not referring to things like required content fields, which are handled by the system itself on schemas with required fields. In this case, we’re focusing on more complex requirements such as fields being filled in with specific types of data or associated content items (e.g., components, categories, assets, or databases) that need to be in a certain state for the asset that contains them to go live.
As mentioned before, throwing an exception in your code will cancel the process of the custom hook, as if the user never took the action. In this example, an error is thrown when the asset is not categorized. You will note that the error message is going to contain the stack trace for the error that you throw, so some extra padding is added to the message in this example to make sure the user sees why we are stopping their progress.
var assetCategories = contentItem.AssociatedCategories(out outVar);
if(!assetCategories.Any())
{
throw new Exception(Environment.NewLine + "Please add categories to your asset by going to the Categorize tab before checking in." + Environment.NewLine);
}
Ways to Extend the Functionality Further
You may consider other scenarios to incorporate here. Perhaps only some of your assets require categories. You may want to limit the hook to apply only to certain types of assets, folders, or users/groups.
This script is also a great candidate to move to a custom workflow action, since you can display much more information to the user and give them options. Instead of just stopping the action you could give them a list of categories to apply there. In the custom hook, you don’t have that option.
There are no comments yet.