Working With Custom Hooks: OnWorkflowAdvanceAsset

Workflows in the CMS are designed to navigate content teams through a controlled editorial process. They provide end-users with parameters that ensure content is edited, reviewed, and published according to the requirements defined by site Administrators and other key stakeholders.  

Administrators can build as many workflows as they like in the CMS, but content items can be added to only one workflow at a time. Once added to a workflow, content items are transitioned through the process. The act of transitioning a content item to another stage in the workflow process is referred to as “advance” in the user interface for end-users. Each stage in the process is referred to as a “workstate” in the CMS.  

Administrators can apply parameters to users and groups to determine who can transition content in workflows. 

In our previous article on custom hooks for workflow, we focused on advancing content items in the Site Tree (e.g., pages and components). Here, we’ll look at how assets fit into the equation.  

How To Trigger the Hook  

This method is triggered through the following actions: 

• Right-clicking the content item in the Asset Tree, selecting Advance, and finishing the prompts in the wizard. 
• Right-clicking the content item in the Asset Tree, selecting Add to Workflow. 
• Clicking the Advance in Workflow button on the toolbar of an asset and finishing the prompts in the wizard. 
• Clicking the Add to Workflow button on the toolbar of an asset, selecting a workflow from the list, and clicking OK. 
• Using any action that triggers a Transition or AddToWorkflow method for an asset in the CSAPI or REST API. 

When to Use This Custom Hook  

Administrators can use this hook to further control requirements as an asset transitions through workflow. Through the API you can validate all content in the asset metadata (including size and dimensions) that is being advanced, look at the users who are involved and adjust as necessary, or communicate with outside systems such as updating a ticket in an issue tracking system. 

Considerations 

If all items are in workflow in your system this hook could be called often, so make sure that scripts are concise and well-tested. 

Working with workflows and transitions can be complex as there are a lot of objects involved in the API surrounding the process. Verify that you have the right objects and that you are targeting them in the correct workflow, as different workflows could share objects. 

Avoid calling a transition method from within this hook to limit chances of an infinite loop. 

Transitions can have actions attached to them that may conflict with your hook script, test as they will exist in production and avoid changing the workflows after making a script to reduce regression risk. 

Example  

Stop workflow advance if an image asset is larger than 2300 pixels wide 

Content managers often must deal with the issue of images being placed in content that are much too large for the space they are being used. The CSS of a site will obscure the fact by making it look like the image fits, while it is actually just being visually shrunk. 

This script attempts to help with that issue by checking the image size when a user attempts to transition it through workflow. If the pixel width of the image surpasses the allowed size, the script will prohibit the asset from being transitioned to the next workstate/user.  

First, we need to get into the technical metadata of the asset, this is where the CMS stores the physical size of the image asset. 

In the metadata, check the asset’s width property. Here we are looking for a size of 2300 (measured in pixels.) 

If the item is not less than 2300 pixels wide, then we throw an exception and prevent the advancement, giving the user a message as to why.