Magnolia 5.4 reached end of life on November 15, 2018. This branch is no longer supported, see End-of-life policy.

Page tree
Skip to end of metadata
Go to start of metadata

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>1.7.1</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 fileRejectAbort
  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 (Reject).
    • abort (Abort) .
  • reviewTranslation:
    • claim (Assign to me).
    • approve (Approve & import) allows translated content into the JCR.
    • review (Review) opens reviewTranslatedContentdialog.
    • 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 startTranslationWorkflowCommandcommand.

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 uploadTranslatedFileCommandcommand.

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. 
    ExamplestartTranslationWorkflow 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. 
    ExamplestartTranslationWorkflow 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. 
    ExampleTranslate by workflow action and dialog in the Tours app.