The CTS Workflow module allows you to process content translation in a defined workflow.

The module extends Magnolia's basic workflow functionality. Translators and translation reviewers interact in the Pulse in a four eye workflow process similar to that of the Workflow module.

You can enable content translation workflow in any content app. The CTS Demo module enables workflow translation in the Tour Categories app. 

Installing

Maven is the easiest way to install the module. Add the following dependency to your bundle:

<dependency>
  <groupId>info.magnolia</groupId>
  <artifactId>magnolia-module-content-translation-support-extend-workflow</artifactId>
  <version>2.0.0</version>
</dependency>

Pre-built jars are also available for download. See Installing a module for help.

Configuration

The module is configured at /modules/magnolia-module-extend-content-translation-support-workflow.

Node name

 modules

 content-translation-support-extend-workflow

 tasks

 config

 dialogs

 commands

 workflows

 fieldTypes

 messageViews

 workItemHandlers

How content translation workflow works

The CTS Demo module:

  • Enables translation workflow in the Tour Categories app 
  • Adds two new groups in the Security app: reviewers and translators. superuser is assigned to the reviewers group and eric to the translators group. 

Here's how content translation workflow works:

  1. Reviewer (superuser):
    1. Selects an item for translation in the app.
    2. Clicks Translate by workflow
    3. Selects the target language/s and adds a comment.
    4. Clicks Translate.
  2. Translator group:
    1. Is notified of the task in the Pulse (Task status: New).
    2. Translator (eric):
      1. Assigns himself the task (Task status: In Progress).
      2. Has the following actions available: Download file to translate,  Upload translated file, Reject, Abort. 
  3. Translator (eric):
    1. Downloads file for translation. The download filename is created from the file path in the workspace, with dots replacing forward slashes such as category.tour-type.mountains.csv. The file has the following columns (comma separated headings in CSV or elements in XLIFF):
      1. Modification date
      2. Key: Internal identifier that consists of component UUID and field name. This is used by Magnolia to store and render translated content. Do not edit this value.
      3. Link: URL for easy access to see the translatable text in context.
      4. Title: A pseudo-title created by combining component type and field name, for example tourCategories:displayName. 
      5. Default language: Default language text.
      6. <language_code>: Columns for each locale requested. This is where the translator types the translation. 
    2. Uploads the translated file.
  4. Reviewers group:
    1. Is notified of the task in Pulse (Task status: New).
    2. Reviewer (superuser):
      1. Assigns himself the task.
      2. Has the following actions available: Approve & import, Review, Reject, Abort.
      3. Reviews the translated text and if satisfactory imports it into the workspace.

You can bypass the content review process (step 4) by enabling auto import.

Enabling auto import

The autoImport property allows you to bypass the content review process (step 4) and import translated content directly into the JCR.

The property is configured in /modules/content-translation-support-extend-workflow/config/autoImport.

Node nameValue

 content-translation-support-extend-workflow


 config


 autoImport

false

Properties:

config

optional

Configuration properties node.

autoImport

optional, default is false

Imports translated content directly into JCR

Workflow process

Magnolia's workflow engine is built upon the jBPM Business Process Management Suite. See Workflow for more.

The module includes a BPMN2 workflow process: TranslationRequestProcess.

Here's the visual representation of the process.

The process is registered in /modules/content-translation-support-extend-workflow/workflows/content-translation-support-workflow-publication.

Node nameValue

 workflows


 content-translation-support-workflow-publication


 id

info.magnolia.module.contenttranslationsupport.workflow.TranslationRequestProcess

 name

TranslationRequestProcess

 resourcePath

TranslationRequestProcess.bpmn2

 type

bpmn

Properties:

content-translation-support-workflow-publication

required

CTS worklow publication node.

id

required

Id. used to identify process in jBPM.

name

required

Name used in Magnolia to identify the process.

resourcePath

required

Path to the .bpmn file in the module resource directory.

type

required

Process type.

Workflow user tasks

User tasks display in the Pulse. Translators and reviewers can claim tasks to start working on them. Tasks have a clear status and an assignee.

Two user tasks that ensure that users assigned to the translators and reviewers groups receive appropriate messages in the Pulse are configured in the module.

Tasks are configured in  /modules/content-translation-support-extend-workflow/tasks.

Node nameValue

 tasks


 translation


 groups


 translators

translators

 viewMapping


 default

content-translation-support-extend-workflow:translate

 title


 label

Translation request

 class

info.magnolia.module.workflow.jbpm.humantask.definition.PublicationTaskDefinition

 parameterResolver

info.magnolia.module.contenttranslationsupport.extend.workflow.GroupsTaskParameterResolver

 presenterClass

info.magnolia.module.workflow.jbpm.humantask.view.PublicationTaskPresenter

 taskJobFactoryClass

info.magnolia.module.workflow.jbpm.humantask.schedule.PublicationTaskJobFactory

 reviewTranslation


 groups


 extends

override

 reviewers

reviewers

 viewMapping


 default

content-translation-support-extend-workflow:reviewTranslation

 title


 label

Review translation

 extends

../translation

Properties:

tasks

required

User tasks node.

<task name>

required

Name of task:

  • translation: Displayed to translators.
  • reviewTranslation: Displayed to reviewers.

groups

optional

Maps the task to a group. Value must match a group in Security app. Property name is arbitrary.

  • translation task maps to the translators group.
  • reviewTranslation task maps to the reviewers group.

title

optional

Task title displayed in the Pulse.

viewMapping

required

Maps the task to a message view in <module name>:<message view> format :

  • translation task maps to translate view.
  • reviewTranslation task maps to reviewTranslation view.

<properties>

required/optional

See User tasks for more.

Workflow message views

Workflow message views define how messages display in the Pulse during translation workflow. See Message view definition for more.

Message views for workflow user tasks are configured in /modules/content-translation-support-extend-workflow/messageViews.

Node name

 messageViews

 translate

 form

 actions

 actionbar

 reviewTranslation

 form

 actions

 actionbar

Properties:

messageViews

required

Message views node.

<view name>

required

  • translate: Displayed to translators group.
  • reveiwTranslation: Displayed to reviewers group.

form

required

Message view form definition.

  • translate: Form displayed to translators group.
  • reviewTranslation: Form displayed to reviewers group.

actions

required

Message view action definitions.

  • translate:
    • claim (Assign to me).
    • download (Download file to translate).
    • upload (Upload translated file).
    • confirmRejection (R eject).
    • abort (Abort) .
  • reviewTranslation:
    • claim (Assign to me).
    • approve (Approve & import) allows translated content into the JCR.
    • review (Review) opens reviewTranslatedContent dialog.
    • confirmRejection (Reject).
    • abort (Abort).

actionbar

required

Message view action bar definition.

Work item handlers

Work item handlers map work items to a handler. The mapping is based on the work item name which is added to the jBPM environment. Magnolia observes the work item registry in the workItemHandlers folder of a module.

Work item handlers (which execute commands in this case) are configured in /modules/content-translation-support-extend-workflow/workItemHandlers.

Node nameValue

 workItemHandlers


 approve


 catalogName

workflowTranslation

 class

info.magnolia.module.contenttranslationsupport.extend.workflow.workitem.TranslationWorkItemHandlerDefinition

 commandName

importTranslationAndSendMailCommand

 reject


 catalogName

workflowTranslation

 class

info.magnolia.module.contenttranslationsupport.extend.workflow.workitem.TranslationWorkItemHandlerDefinition

 commandName

rejectTranslationResultCommand

 abort


 catalogName

workflowTranslation

 class

info.magnolia.module.contenttranslationsupport.extend.workflow.workitem.TranslationWorkItemHandlerDefinition

 commandName

abortTranslationCommand

 error


Properties:

workItemHandlers

required

Work item handler folder.

approve

optional

Handles importing translated content after approval.

reject

optional

Handles rejecting translated content.

abort

optional

Handles cancelling translation tasks.

error

optional

Handles errors for failed tasks.

Workflow commands

The module includes a full set of commands that are used in the workflow process.

Commands are configured in /modules/content-translation-support-extend-workflow/commands.

Node nameValue

 commands


 workflowTranslation


 startTranslationWorkflowCommand


 startWorkflowCommand


 class

info.magnolia.module.workflow.commands.LaunchWorkflowCommand

 parameterMapName

mgnlData

 workflow

content-translation-support-workflow-publication

 exportCommand 


 uploadTranslatedFileCommand 


 uploadCommand 


 updateWorkflowTaskStatusCommand 


 importTranslationAndSendMailCommand 


 importCommand 


 updateWorkflowTaskStatusCommand


 sendMailCommand 


 updateWorkflowTaskStatusCommand 


 updateTranslationStatusCommand 


 rejectTranslationResultCommand 


 abortTranslationCommand 


Properties:

commands

optional

Commands folder.

workflowTranslation

required

Workflow translation catalog.

class

required

Command class. See table below.

<other properties>

required/optional

Properties supported by the command class.

Command classes:

Command nameClassOther properties

startTranslationWorkflowCommand



startWorkflowCommand

info.magnolia.module.workflow.commands. LaunchWorkflowCommand

parameterMapName=mgnlData

workflow=content-translation-support-workflow-publication

exportCommand

info.magnolia.module.contenttranslationsupport.extend.common.command. ExportTranslationCommand

-

uploadTranslatedFileCommand

uploadCommand

info.magnolia.module.contenttranslationsupport.extend.workflow.command. UploadTranslatedFileCommand

-

updateWorkflowTaskStatusCommand

info.magnolia.module.contenttranslationsupport.extend.workflow.command. UpdateWorkflowTaskStatusCommand

decision=approve
importTranslationAndSendMailCommand

importCommand

info.magnolia.commands. DelegateCommand

commandName=common-scheduleImportCommand

updateWorkflowTaskStatusCommand

info.magnolia.module.contenttranslationsupport.extend.workflow.command. UpdateWorkflowTaskStatusCommand


sendMailCommand

info.magnolia.module.contenttranslationsupport.extend.workflow.command. SendNotificationMailCommand

mailCommand=<> (not yet implemented)

mailTemplate=rejected

updateWorkflowTaskStatusCommand

info.magnolia.module.contenttranslationsupport.extend.workflow.command. UpdateWorkflowTaskStatusCommand

-
updateTranslationStatusCommand

info.magnolia.module.contenttranslationsupport.extend.workflow.command. UpdateWorkflowTaskStatusCommand

-
rejectTranslationResultCommand

info.magnolia.module.contenttranslationsupport.extend.workflow.command. UpdateTranslationStatusCommand

status=rejected
abortTranslationCommand

info.magnolia.module.contenttranslationsupport.extend.common.command. CancelTranslationCommand

-

Workflow fields

The module includes two custom fields that are used in workflow dialogs.

The field types are registered in /modules/content-translation-support-extend-workflow/fieldTypes.

Node nameValue

 fieldTypes


 previewTranslationTableField


 definitionClass

info.magnolia.module.contenttranslationsupport.extend.workflow.field.TranslatedPreviewTableDefinition

 factoryClass

info.magnolia.module.contenttranslationsupport.extend.workflow.field.TranslatedPreviewTableFactory

 simpleUploadField


 definitionClass

info.magnolia.module.contenttranslationsupport.extend.workflow.field.SimpleUploadFieldDefinition

 factoryClass

info.magnolia.module.contenttranslationsupport.extend.workflow.field.SimpleUploadFieldFactory

Properties

fieldTypes

optional

Field types folder.

<field name>

required

Field name:

  • previewTranslationTableField: Allows reviewers to review translated content. Used in reviewTranslatedContent dialog.
  • simpleUploadField: Allows translators to upload content files. Used in uploadTranslationFile dialog.

definitionClass

required

Field definition class.

  • TranslatedPreviewTableDefinition
  • SimpleUploadFieldDefinition : Gets and sets caption properties for SimpleUploadField. Supports same caption properties as Basic Upload field with the following defaults:
    • selectNewCaption : Select new
    • selectAnotherCaption : Select another
    • deleteCaption : Delete
    • dropZoneCaption : Drop here
    • inProgressCaption : Uploading...
    • inProgressRatioCaption : Uploaded
    • fileDetailHeaderCaption : File header
    • fileDetailNameCaption : File name
    • fileDetailSizeCaption : File size
    • fileDetailFormatCaption : File format
    • fileDetailSourceCaption : File source
    • successNoteCaption : Upload success!
    • warningNoteCaption : Warning note
    • errorNoteCaption : Error note
    • sizeInterruption : Upload interupted size
    • typeInterruption : Upload interupted type
    • userInterruption : Upload interupted user

factoryClass

required

Field factory class.

  • TranslatedPreviewTableFactory : Implements a custom table for reviewing translated content.
  • SimpleUploadFieldFactory : Implements a basic upload field factory (without an image provider).

Workflow dialogs

The module includes three workflow dialogs configured in /modules/content-translation-support-extend-workflow/dialogs.

Node name

 dialogs

 workflowTranslationRequest

 uploadTranslationFile

 reviewTranslatedContent

Properties:

dialogs

optional

Dialogs folder.

workflowTranslationRequest

optional

Translation request dialog starts the workflow process.

  • targetLangs  field uses Languages select field that allows a user to request content translation by workflow in specified languages.
  • commit action uses a custom action definition class to call the startTranslationWorkflowCommand command.

uploadTranslationFile  

optional

Upload translated file dialog allows a translator to upload a translated file.

  • Opened by uploadTranslationFile action in translate message view.
  • commit action uses custom action definition class to call uploadTranslatedFileCommand Workflowcommands.

reviewTranslatedContent

optional

Translation dialog allows a reviewer to review translated content in a table.

  • Opened by review action in reviewTranslation message view.
  • content field uses a custom field definition class TranslatedPreviewTableDefinition  to display translated content in a table.

Enabling translation workflow in content apps

You can enable translation workflow in any content app.

Example: Enabling translation workflow in the Tours app. 

  1. Ensure that the fields you want to translate have an i18n property (set to true) in the detail subapp. See Enabling mulitlanguage content for more.
    Example: description text field in the tours tab in /modules/tours/apps/tours/subApps/detail/editor/form/tabs/tour/fields/description.

    Node nameValue

     editor


     form


     tabs


     tours


     fields


     name


     description


     class

    		info.magnolia.ui.form.field.definition.TextFieldDefinition

     i18n

    		 true

     rows

    		3

  2. Add the Translate by workflow (startTranslationWorkflow) action to the browser supapp. The CTS Demo module adds the Tranlsate by workflow action to the Tour Categories app. You can copy the action configuration from there. 
    Example: startTranslationWorkflow action in /modules/tours/apps/tours/subApps/browser/actions/startTranslationsWorkflow.

    Node nameValue

     browser


     actions


     startTranslationsWorkflow


     class

    		info.magnolia.module.contenttranslationsupport.extend.common.action.OpenTranslateDialogActionDefinition

     dialogName

    		content-translation-support-extend-workflow:workflowTranslationRequest

     icon

    		icon-content-translation-app

     label

    		Translate by workflow

  3. Add the action to the action bar. 
    Example: startTranslationWorkflow action in /modules/tours/apps/tours/subApps/browser/actionbar/sections/item/groups/translationActions/items/startTranslationsWorkflow.

    Node name

     browser

     actionbar

     sections

     item

     groups

     translationActions

     items

     startTranslationsWorkflow

  4. Test the action in the app. 
    Example: Translate by workflow action and dialog in the Tours app.
       
#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))