Working With Custom Hooks: OnWorkflowAdvance
Workflows in the CMS are designed to navigate content teams through a controlled editorial process. In this article, we take a look at how custom hooks can be utilized to enhance the action of advancing a content item through this process.
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.
How To Trigger the Hook
This method is triggered through the following actions:
- Right-clicking the content item in the Site Tree, selecting Advance, and finishing the prompts in the wizard.
- Right-clicking the content item in the Site Tree, selecting Add to Workflow.
- Clicking the Advance in Workflow button on the toolbar of a page or component and finishing the prompts in the wizard.
- Clicking the Add to Workflow button on the toolbar of a page or component, selecting a workflow from the list, and clicking OK.
- Using any action that triggers a Transition or AddToWorkflow method in the CSAPI or REST API.
When to Use This Custom Hook
Administrators can use this hook to further control requirements as a content item transitions through workflow. Through the API you can validate all content in the page or component 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
Prevent workflow advance with prohibited words
Sometimes organizations must avoid using certain words in the content they publish on the web. This may be for legal reasons, branding purposes, or issues around cultural sensitivity and company creed.
This script searches the content for a list of disallowed words and prevents the content item from advancing through workflow if those words are present.
First, make a list of the prohibited words. Then you can serialize the whole content item content into one string to make it quicker to search through instead of going field by field.
Loop through the prohibited words and see if any of them are in the content. If one is found, throw an exception that will cancel the hook.
string[] prohibitedWords = {"stop", "nono", "test"};
var serializedContent = page.DOM().ToString();
foreach (var word in prohibitedWords)
{
if (serializedContent != null && serializedContent.IndexOf(word, StringComparison.OrdinalIgnoreCase) >= 0)
{
throw new Exception("Cannot Continue Workflow due to Prohibited Word - " + word + " - found on the Page");
}
}
Ways to Extend the Functionality Further
If you only have one or two fields that a user might type content into, it could be faster to only check those fields instead of serializing the whole page.
The script currently stops at the first word it finds, so they might have to make multiple attempts if they included multiple incorrect words. Instead, you could gather all of the information, then give them one warning at the end with all the words they had wrong.
You might also want to notify an administrator or save in the logs that a user is attempting to send disallowed words to the website.
There are no comments yet.