Workflow Sub-Actions

Last Updated: May 26, 2023
documentation for the dotCMS Content Management System

A variety of Workflow sub-actions can be triggered when a Workflow Action is executed.

Built-In Workflow Sub-Actions

dotCMS includes all of the following built-in sub-actions. You may select any number of these sub-actions, and execute them in whatever order you wish, for each Workflow Action.

The Workflow Sub-Actions Pull-Down

Sub-Actions with No Parameters

The following sub-actions do not require (or accept) parameters. These sub-actions always perform the same action on the content item the Workflow Action is executed on.

Sub-Action Description
Archive Content Archives the content item.
Auto-Tag Images (AWS) Submits an image content item to the Amazon Rekognition image analyzer, and adds Tags to the Tag field of the content item based on the Amazon Rekognition results.
  • This sub-action must come after the Save Content or Save Draft Content Sub-Action, or any new changes to the image will not be included when the image is analyzed.
  • The content item must be of a Content Type that has a Tag field.
Copy Contentlet Creates a copy of the content item.
  • The copy will have the same value for all fields as the original, except the Identifier and Inode.
Delete Content Deletes the content item.
  • Only deletes a single currently viewed or specified language version of the content.
  • To delete all language versions of the content, use the Destroy Content Sub-Action (above)
Destroy Content Deletes all language versions of the content item.
  • The user must have permissions to delete all language versions, and any version which is locked by another user will not be deleted.
Lock Content Locks the content item.
Publish Content Changes the state of the content item to Published.
Push Publish Displays the Push Publishing popup to the user who initiated the Workflow Action.
  • This sub-action allows (and requires) the user who initiated the Workflow Action to select both the push method and the Environment to push to, at the time the Workflow Action is executed.
  • For a sub-action that performs a push without popping up a window and without requiring the user to enter any information about the push, please see the Push Now Sub-Action, below.
Reset Approvals Resets the list of users who have approved the content using the Four Eyes Approval or Require Multiple Approvers Sub-Actions.
  • Information about previously executed Actions which include previous approvals will remain in the Workflow Task History, but the approval process will be restarted.
Reset Workflow Resets the content item back to the initial Workflow step.
  • If the Content Type has multiple Workflows assigned to it, the content item will be taken out of the Workflow completely, so a new Workflow can be selected for the content.
Save Content Saves changes to the content and creates a new version of the content.
Save Draft Content Saves changes to the content, and attempts to do so without creating a new version of the content.
  • If the user taking the action is the user that last modified the content, no new version is created.
  • If the user taking the action is _not_ the same as the user that last modified the content, a new version is created.
Unarchive Content Unarchives the content item (changing it from the Archived state to the Unpublished state).
Unlock Content Unlocks the content item.
Unpublish Content Unpublishes the content item (changing it from the Published state to the Unpublished state).

Sub-Actions with Parameters

The following sub-actions each accept (and may require values for) one or more parameters. The values entered for the parameters change how these sub-actions work, so Workflow Actions with the same sub-actions may behave differently, depending on the values entered for the parameters. In the list below, all parameters listed are required, unless they are explicitly marked as (Optional).

To change the parameters for any sub-action in this list, click the sub-action name in the Sub-Actions section of the Workflow Action configuration.

Sub-Action Parameters Description
'Four Eyes'
  • User IDs or Emails
  • Email Subject (Optional)
  • Email Message (Optional)
Requires that the specified number of users from among the list of specified users take the Workflow action.
  • If the specified number of users have not yet approved the content, then any sub-actions following the Four Eyes Approval Sub-Action will not be performed, and the content will not be moved into the "Next Step" specified in the Workflow Action.
Comment on
  • Workflow Comment (Optional)
Adds a comment to the content item [Workflow Task](workflow-tasks).
  • If no Workflow Comment parameter is specified, the user will be prompted to enter a comment.
Large Message
  • User IDs
  • Message
  • Title
  • Width
  • Height
  • Language (Optional)
  • Code (Optional)
Displays a large popup message to the specified users.
  • Similar to the Message actionlet, but capable of displaying a much larger message, with dimensions specified in the parameters.
  • A large message can displaying plain text, HTML or other code, and can support Velocity interpolation.
  • The User IDs field may contain a comma-separated list of User IDs or Roles.
Link Checker
  • List of fields to check
Uses the Link Checker to verify that any links found in the specieid fields are valid.
  • If the link check on the content fails, the sub-actions following the Link Checker Sub-Action will not be executed.
  • This means, for example, that if a Save Sub-Action follows the Link Checker Sub-Action, then if the link check fails, the content will not be saved.
  • User IDs
  • Message
  • Severity
  • Life Seconds
Displays a popup message to the specified users.
  • The popup displays the specified message in the corner of the window for the specified number of Life Seconds before automatically dismissing.
  • The User IDs field may contain a comma-separated list of User IDs or Roles.
  • Default value (Optional)
Allows users to move content to a host or folder which they select or have defined in the default.
Notify Assignee
  • Email Subject (Optional)
  • Email Message (Optional)
  • Is Html (Optional)
Notifies all assigned users that the Workflow Action was taken.
  • If the assignee is a single user, that user will be notified.
  • If the assignee is a Role, all users assigned that Role will be notified simultaneously.
  • Any parameters which are not specified will be filled in with automatically assigned default values.
More information below.
Notify Users
  • Users, Emails and Roles
  • Email Subject (Optional)
  • Email Message (Optional)
  • Is Html? (Optional)
Sends an email with the specified information and format to the specified dotCMS users. More information below.
Push Now
  • Name of the Environment
  • Force Push
Push publishes the content item to the specified Push Publishing Environment.
  • The acceptable values for the Force Push parameter are true or false.
  • This sub-action will not display a popup to the user who executes the Action, and the content item will be pushed to publish immediately on the target environment, with no option to set the publish date or to remove the content from the target enironment.
    • For a sub-action that allows the user to Push Remove, set the push parameters, and select the target Environment, please see the Push Publish Sub-Action, above.
Reindex Content
  • Optional Index Policy
Reindexes the content the Workflow Action is executed on.
  • Valid values for the Optional Index Policy field are DEFER, WAIT_FOR, and FORCE.
Require Multiple Approvers
  • User IDs or Emails
  • Email Subject (Optional)
  • Email Message (Optional)
Requires that all of the specified users take the Workflow Action before the following sub-actions are performed.
  • If the Workflow Action specifies a Next Step, the content will not be moved into that step until all users specified in this sub-action take this Workflow Action.
Send an Email
  • From Email
  • From Name
  • To Email
  • To Name
  • Cc Email (Optional)
  • Bcc Email (Optional)
  • Email Subject
  • Email Body
  • Condition (Optional)
  • Attachments (Optional)
Sends an email with the specified content to the specified list of addresses.
  • If any of the sub-action parameters are not filled in, they will be left blank in the email sent (they will not be filled in with default values).
More information below.
Send Form Email
  • From Email
  • From Name
  • To Email
  • Email Subject
  • Email template to Parse
  • Condition (Optional)
  • Bcc Email (Optional)
This actionlet sends information submitted via form to the email addresses defined in the form. If the content is not a form, then this actionlet will do nothing.
  • The template field expects a VTL parse statement along the lines of #dotParse('path/file.vtl').
Set Value
  • velocityVar Name
  • Value to set
Sets the value of the specified field in the content item to the specified value.
  • The velocityVar Name must match the Velocity variable name of a field in the content.
  • The Value to set may be plain text or Velocity code.
  • The value of the content field will not be updated on the content editing screen unless the changed value is saved (by following this sub-action with a "Save Content" or "Save Draft" Sub-Action).
Translate Content
  • Translate to
  • Translate Field Types
  • Ignore Fields (Optional)
  • Service API Key
Automatically translates all specified fields types of the content item to the specified languages using the Google Translation API.
  • Although this sub-action does perform basic translations, it is intended only as an example of how to perform translation actions automatically from within your workflow.
    • To perform professional translations from within your Workflow, it is recommended that you create a Custom Workflow Action Plugin to integrate dotCMS with a professional translation service.
    • The open-source code which implements this Sub-Action is available in the dotCMS Github Repository, and can be used as a template for building your own translation sub-action.
  • You must apply for and use your own unique Google Translate API key when using this sub-action.
Twitter Status Update
  • Consumer Key
  • Consumer Secret
  • Access Token
  • Access Token Secret
  • Field to Post (Optional)
Posts the value of a content item field or the Workflow comments to Twitter.
  • If the "Field to Post" property is set to the Velocity variable name of a field on the content item, the value of that field will be posted.
    • If no "Field to Post" is supplied, the comments entered into the workflow comment box will be posted.
  • To get an access token for Twitter, please visit the Twitter Apps page and create a new dotCMS application.
Velocity Script Actionlet
  • Script Code
  • Result Property Name
Executes the specified Velocity code.
  • The Velocity code is executed silently (no messages or popups are displayed to the user executing the Action).

Emails: Notify Asignee vs. Notify User vs. Send an Email

Three of the above sub-actions involve sending an email, but they differ in parameters and purpose:

  • Notify Asignee sends an email to dotCMS users who have just been assigned content, to notify them that they're now responsible for it. This is the narrowest of the three.
  • Notify Users is slightly more general-purpose, sending a message to dotCMS users on the same system, irrespective of their assignment status on a given piece of content.
  • Send an Email is the most generic of the three, which is intended for emailing anyone — including non-users. It provides the most control over the format and content of the email.

Additionally, there are three other sub-actions that involve email. One of these, Send Form Email, simply executes the emails that a given form is configured to send. The other two, related to approvals, are detailed in Multiple Approval Sub-Actions.

Execution Order

When the Workflow Action is executed by a user, each of the sub-actions assigned to that Action are triggered, in the order the sub-actions are listed in the Action configuration.

This means, for example, that if a sub-action changes a value in the content item, that sub-action must be followed by a “Save Content” or “Save Draft content” Sub-Action, or the changes made by the first sub-action will not be saved to the content item. Similarly, if a Push Publish Sub-Action comes before a Save Sub-Action in the sub-action list, then the old version of content will be pushed, before the changes to the content are saved.

Stopping Sub-Action Execution

If any of the sub-actions fails or encounters an error, execution of the sub-actions stops, and all sub-actions which follow the failed sub-action will not be executed. In addition, if any of the sub-actions fail, then the Next Step property of the Action will not be executed, and the Workflow Step of the content item will not be changed.

For example, when using the 'Four Eyes' Approval Sub-Action, this sub-action is specifically designed to stop execution of the sub-actions unless the required number of users has taken the action. This means that when using this sub-action, you can set the Next Step property of the Action, and add additional sub-actions after the 'Four Eyes' Approval Sub-Action, and none of those will be executed until all the required users have taken the action.

Sub-Action Permissions

Permissions are always checked for all sub-actions. Specifically, the permissions of the user executing the Workflow Action are always checked, for all sub-actions that are part of the Action, in relation to the content item the Workflow Action is being executed against, and, if applicable, any other objects in the system that any of the sub-actions may access (such as content or objects accessed via the Velocity Script Sub-Action).

This means that, regardless of which users are able to execute the Action (via the Action properties), the user's permission on the content item will still always be checked and enforced for each sub-action.

Custom Sub-Actions

In addition to the built-in sub-actions, you may create Workflow Actions which have custom sub-actions in one of two ways:

  1. Implement custom behavior via the Velocity Script Sub-Action.
  2. Create your own custom sub-actions by using an OSGi plugin to create a Custom Workflow Actionlet.

Note that you may also add custom code and behavior to a Workflow Action using the Custom Code field in the Action properties. However code in this field is not executed in the same way as code within sub-actions; for more information on when and how different types of code is executed within a Workflow Action, please see the documentation.

On this page


We Dig Feedback

Selected excerpt: