Workflow

ACE workflow is a feature meant to help organisations ensure all editorial content managed in ACE adheres to organisational rules and regulations whenever such exist. Such regulations might for example require content to be reviewed prior to be being made public in a public output channel.

ACE workflow can be conceptualized as a state machine where a content or a change to a content has to reach any of the end states before it is either dismissed or allowed to be made publicly available.

There can only ever be one workflow definition for a specific content type, and a content can only have one active workflow at a time. Until that workflow is ended, no changes to workflow configuration will apply to the specific content.

Any workflow state for a content is stored in the aceWorkflowState content metadata aspect and indexed in the ace_workflowstate_state_s index field.

NOTE: The current implementation of ACE workflow is implemented strictly as a client feature, and will not be enforced on the server when creating or updating content. All content managed through the ACE Content Developer application will however be subject to following any configured workflow.

Defining a workflow

A workflow is defined using a workflow definition, which declares how a content using the workflow will behave during its editorial lifecycle. The workflow definition is stored in ACE as a content of the content type aceWorkflowDefinitionContent with an alias in the _workflow alias namespace.

ACE workflow definitions consists of three important concepts: states, transitions and operations.

Possible properties:

• label - a human readable label for the workflow. Can be localized.
• description - a human readable description for the workflow. Can be localized.
• transitions - a list of transitions that can be used to enter a content into the workflow.
• states - a list of states for the workflow state machine.

Workflow states

A workflow state is one of the possible states a content can have during its editorial lifecycle. Each state can then allow transitions to zero or more other states.

Possible properties:

• name - the name of the workflow state. Can be any string, but should not include any whitespace. Required.
• label - a human readable label for the workflow state. Can be localized.
• description - a human readable description for the workflow state. Can be localized.
• editableBy - a list of user roles that will enable editing of a content while in the state.
• transitions - a list of possible transitions to other workflow states. An empty list will make the state an end state which will end the workflow.

Workflow transitions

A workflow transition describes how a content can move from one workflow state to another. The transition can also be configured to execute workflow operations whenever a content use the transition.

Possible properties:

• name - the name of the workflow transition. Can be any string, but should not include any whitespace. Required.
• label - a human readable label for the workflow transition. Can be localized.
• description - a human readable description for the workflow transition. Can be localized.
• targetState - the end state of the transition.
• allowedBy - a list of user roles that will enable the usage of the workflow transition.
• properties - a list of properties definition additional (mostly UI related) attributes of the transition. The only recognized value at this time is the color property, which will define the visual look and feel of the associated action button in the ACE Content Developer. Any valid CSS color value (either in hex, rgba or by simple color name) as well as the special color strings progressive / regressive will be usable.
• operations - a list of operations to execute whenever the transition is executed for a content.

Workflow operations

A workflow operation is an action that will be executed whenever a content in a workflow performs a transition from one state to another.

Possible properties:

• name - the name of the operation.
• data - the input value for the operation.

The only recognized operation at this time is putOnView, which will publish the latest content version to a view. The following example operation will publish the latest version of the content to the acePublic view:

operations:
    - name: putOnView
      data: acePublic

Workflow permissions

There are two ways to configure permissions in a workflow definition:

• Using the allowedBy property on a workflow transition. This property is a list of roles and controls who is allowed to perform the transition. Defaults to nobody being allowed to perform the transition.
• Using the editableBy property on a workflow state. This property is a list of roles and controls who can edit the content while it is in that state. Defaults to nobody being allowed to edit the content.

Please the example workflow below for more information.

Workflow configuration

Workflow is defined per content type and is configured using the configuration content _config/aceWorkflowsConfig (content type aceWorkflowsConfigContent).

Example:

{
  "importerMetadata": {
    "alias": "_config/aceWorkflowsConfig",
    "updateMode": "merge"
  },

  "system": {
    "contentType": "aceWorkflowsConfigContent"
  },

  "aspects": {
    "aceWorkflowsConfig": {
      "workflows": [
        {
          "workflow": "testWorkflow",
          "contentTypes": ["articleContent"]
        }
      ]
    }
  }
}

For every entry in the workflows entry list, you specify a workflow identifier and a list of content types which you want to use the workflow definition for.

Notes

• If multiple workflow configuration entries include the same content type, only the first entry will be applicable for the type.
• Workflow is applied at the time of content creation in the ACE Content Developer. Content existing prior to workflow configuration will not be affected in any way. For these content, the workflow will start being applied the next time they are edited.

Importing workflow definitions

Workflow definitions are defined using YAML files with workflow file extensions and are imported into ACE using the normal content import functionality. Please see importable files for more information.

When a workflow definition is imported, it will automatically be created as an ACE content of the aceWorkflowsConfigContent content type with an alias like _workflow/<X> where is the name of the file imported (without the .workflow prefix).

For example: importing the workflow definition file testWorkflow.workflow will create a workflow definition content with an alias of _workflow/testWorkflow. testWorkflow will also be the effective identifier of the workflow.

An example workflow with comments

The following is an example workflow definition that describes a likely editorial workflow where a content or a change to a content has to be reviewed by a specific group of users before being published.

(start) -- (done) -> [inReview] - (publish) -> [Published] -> end workflow
                  |
                  +- (reject) -> [Rejected] -> end workflow
                  |
                  +- (abort) -> (aborted) -> end workflow

##
# This workflow definition defines a simple workflow where content have to
# pass through a review process before being made publicly available.
#
# Note that labels and descriptions have not been localized in this example.
##

name: simpleWorkflow
label: Simple workflow
description: An example simple review workflow

# These transitions define how the workflow is initiated and in
# what state the content will start out in the workflow.

transitions:
    - name: requestReview
      label: Request review
      description: Request a review of the changes performed to this content.

      # The content will be placed in the 'inReview' state.
      targetState: inReview

      # Any workflow action using this transition in the ACE
      # Content Developer application will be colored using a shade of green.
      properties:
          - color: progressive

      # Only users with the 'editor' role is allowed to use the transition.
      allowedBy: [editor]

states:
    - name: inReview
      label: In review
      description: This content has to be reviewed before being published.

      # Only users with the 'reviewer' role is allowed to edit a content in this state.
      editableBy: [reviewer]

      transitions:
          - name: reject
            label: Reject
            description: Reject the changes made to this content and do not publish them.

            # The content will be placed in the 'rejected' state.
            targetState: rejected

            # Any workflow action using this transition in the ACE
            # Content Developer application will be colored using a shade of red.
            properties:
                - color: regressive

            # Only users with the 'editor' role is allowed to use the transition.
            allowedBy: [reviewer]

          - name: publish
            label: Publish
            description: Approve and publish the changes made to this content.

            # The content will be placed in the 'published' state.
            targetState: published

            # Any workflow action using this transition in the ACE
            # Content Developer application will be colored using a shade of green.
            properties:
                - color: progressive

            # Only users with the 'reviewer' role is allowed to use the transition.
            allowedBy: [reviewer]

            # Automatically put the latest version of this content on
            # the 'acePublic' view when the transition is used.
            operations:  
                - name: putOnView
                  data: acePublic

    - name: published
      label: Published
      description: The changes to this content has been approved and published.

      # There are no outgoing transitions from this state, making
      # it an end state. The workflow ends when the content is transitioned here.
      transitions: [] 

    - name: reject
      label: Rejected
      description: The changes to this content has been rejected and not published.

      # There are no outgoing transitions from this state, making
      # it an end state. The workflow ends when the content is transitioned here.
      transitions: []

The example workflow above has three states: inReview, rejected as well as published. Both the published and the rejected states are end states, and using the transitions to them (publish, reject) will lead to the workflow finishing.

Aborting a workflow

As long as a workflow haven't progressed past the initial state, it can be aborted by the same user that initiated it.