Diagram workflow is a comprehensive tool to navigate the workflow of a document.

The tool is highly configurable and can be tailored to the customers' requests.

General information

In order to customize the Diagram Workflow, it is necessary to add the customized code in a JS file placed under

{SWING}/app/plugins

It is suggested to place the custom code under a folder, e.g. /app/plugins/diagram-workflow/

How to configure plugins in an external folder

Additional plugins may be made available to Swing application by defining one or more nested components in Swing web context in server.xml. (for further details on Tomcat 9.x Resources configuration, please refer to Resources configuration).

This is an example of the external widgets configuration.

<Context docBase="com.eidosmedia.webclient.web-app"
    path="/swing" reloadable="false">
    <Resources
        className="org.apache.catalina.webresources.StandardRoot">
        <PreResources
            className="org.apache.catalina.webresources.DirResourceSet"
            base="/methode/meth01/extension/plugins" readOnly="true"
            webAppMount="/app/plugins" />
    </Resources>
</Context>

Basic configuration

Inside the customization, it is possible to override the default configuration for the Diagram Workflow.

Configuration registration

To override the default configuration, it is necessary to override the

eidosmedia.workflowMap.defaultConfiguration

object. It is possible to override single properties, or the full object.

Configuration example

eidosmedia.workflowMap.defaultConfiguration = {
    addin:                  'default',
    nodeShape:              'circle',
    subnodeShape:           'roundrectangle',
    nextStatusOnly:         true,
    showStatusColor:        false,
    allNodesEqual:          false,
    showWorkflowAfterMetadataSave: false,
    showAssignTo:               true,
    showFilename:               true,
    showComment:                true,
    showWarnings:               true,
    showSuccessfulConstraints: false,
    hideDiagram: false,
    buttons: ['save', 'saveclose']
};

Configuration properties

Table 1. Configuration properties
Property Default Value Description

addin

"default"

Defines the addin to be used with the Diagram Workflow. Refer to the Customize the Diagram Workflow behaviour section for further details.

nodeShape

"circle"

Defines the shape for the "fast track" nodes. Valid values are circle, roundrectangle and rectangle

subnodeShape

"circle"

Same as nodeShape, but for nodes outside of the "fast track".

nextStatusOnly

true

If true, the Diagram Workflow shows a simplified map with the current and the next steps available.

showStatusColor

false

If true, each status in the Diagram Workflow as its color as the border.

allNodesEqual

false

If true, there is no difference in UI between the Main nodes and the Sub nodes.

showWorkflowAfterMetadataSave

false

If true, after saving the metadata panel, the focus is brought back to the Workflow panel

showAssignTo

true

Hides or shows the Assign To input

showFilename

true

Hides or shows the Filename input

showComment

true

Hides or shows the Comment input

showSuccessfulConstraints

false

If true, besides the constraints and the warning yet to be solved, the successful constraints are shown.

showWarnings

true

Hides or shows the Warnings tab [deprecated. See here]

buttons

['save', 'saveclose']

It lists all the visible buttons. Values can be ['save', 'saveclose'], ['save'] or ['saveclose']

hideDiagram

false

If true, the diagram workflow is not shown.

visibleTabs

['errors', 'warnings', 'reminders', 'comments', 'info']

If lists all the visible tabs. It is possible to configure which tabs are visible and in which order they are presented. Possible values are: 'errors' (constraints), 'warnings', 'reminders', 'comments' and 'info' (properties)

showWarnings is deprecated. It has been substituted by visibleTabs configuration.

Customize the Diagram Workflow behaviour

It is possible to customize the Diagram Workflow behaviour by registering new "add-ins", also known as specific configurations.

To decide which add-in is in use, the addin property of the Diagram Workflow configuration must be set to the addin name.

Plugin registration

eidosmedia.workflowMap.addMode( name, options );

The name property must be equal to the addin property in the default configuration. See Basic configuration for further information.

Available options

Here is an example of the registration of a custom add-in for the Diagram Workflow

eidosmedia.workflowMap.addMode( 'custommode', {
    options: {},
    maps: [],
    onStatusClick: function( ctx, data ) {},
    onStatusHover: function( ctx, data ) {},
    onTransitionClick: function( ctx, data ) {},
    onTransitionHover: function( ctx, data ) {},
    onShowHistory: function( ctx, data ) {},
    onShowHelp: function(ctx) {},
    onEvent: function(ctx, evt) {},
    onLoad: function( ctx, callback ) { callback(); },
    onBeforeSave: function( ctx, callback ) { callback(); },
    onAfterSave: function( ctx, callback ) { callback(); },
    getTitle: function( ctx, callback ) { callback(); }
});

options

The options property allows to override the configuration options specified in the Diagram Workflow default configuration. See Basic configuration for further information.

Example
eidosmedia.workflowMap.addMode( 'custommode', {
    // ...
    options: {
        nodeShape:               'roundrectangle',
        nextStatusOnly:          false,
        showAllTransitions:      false,
        showUnreachableStatuses: false,
        showHistoryInMap:        false,
        allNodesEqual:           false
    },
    // ...
};

maps

Inside the maps property, it is possible to specify additional configuration options for each Diagram Workflow. In fact, it is possible to override the "Fast Track" and to specify custom constraints.

Example
eidosmedia.workflowMap.addMode( 'custommode', {
    // ...
    maps: [
       {
           name: 'NewsFlow',
           mainLine: null, // Or array, or function
           connectionId: 'eidos05methdev', // Optional, it allows to define maps with the same name for different connections
           statuses: [
              {
                  name: "For Approval",
                  label: "For Approval",
                  longName: "For Approval for dropdown",
                  constraints: [{
                      condition: function( ctx ) {
                        console.log('Checking editing constraint...');
                        var metadata = ctx.activeObject.getMetadata();
                        // Some check here
                        var isValid = false;
                        return isValid;
                      },
                      message: 'It seems that you did not do the right thing',
                      action: [
                        'metadata',
                        {
                          name: "My custom action",
                          action: function(ctx) {
                              // Do some actions here...
                          }
                      } ]
                  }]
              },
              {
                  name: 'Ready for print',
                  label: 'RFP'
              },
              {
                  name: 'Ready for website',
                  label: 'RFW'
              }
           ],
           transitions: [
             {
                 source: "Editing",
                 target: "For Approval",
                 constraints: [ /* See constraint example above */ ]
             }
           ]
       }
    ],
    // ...
};
Properties

The map configuration is an array of objects, each one representing a workflow map. Each "workflow map" can be customized with the following properties:

Table 2. Map properties
Property Default Value Description

name

{String}

It’s the reference the the workflow map name. It is mandatory.

label

{String}

If specified, the label is shown instead of the name. It is optional, but recommended in case of longer status names.

longName

{String}

If specified, the longName is shown instead of the name in the dropdown on the right. It is optional.

mainLine

{Array of strings or Function}

If specified, it overrides the calculated FastTrack. It should contain only the Statutes to be considered FastTrack. It is optional, and if is omitted the Diagram Workflow will calculate the "Fast Track" by taking the default statuses obtained from the System Attributes configured via Methode EMC. See the example below for an implementation.

connectionId

{String}

Optional. If specified, the configured maps is valid only for that specific connection. Useful to allow different connection with the same Workflow Name to have different configurations.

statuses

{Array of objects}

Inside each status, it is possible to specify a list of custom constraints. See Constraint definition for further information. Please note the each status must have a name property specified.

transitions

{Array of objects}

Inside each transition, it is possible to specify a list of custom constraints. They will appear only if the user is moving from the source status to the target status. See Constraint definition for further information. Please note the each status must have a target and a source property specified.

statusesModifier

{Function}

It allows to specify an array of status modifier, which overrides the normal behaviour. It is possible to set one or more status node as hidden (property: hidden), or override the "used" style (property: used) which is represented when a node has been already visited. It is optional. See example below for implementation

diagramTitle

{Function}

It allows to specify a title for the diagram, defining the text and the style. It is optional. See example below for implementation

Mainline function implementation
mainLine: function(ctx, callback) {
    // Callback MUST be called with the new mainline
    if (ctx.activeObject.getStatusInfo().name === 'FastTrack/Draft') {
        callback([ 'Start', 'PublishingQueue(Next)', 'Moodys_COM', 'PostedOnMDC' ]);
    } else {
        callback([ 'Start', 'Draft', 'ApprovalQueue(Next)', 'AuthorFinalReview', 'PublishingQueue(Next)', 'Moodys_COM', 'PostedOnMDC' ]);
    }
},
Status Modifier function implementation
statusesModifier: function(ctx, callback) {
    // Callback MUST be called with the status modifier array
    ctx.activeObject.getMetadata(function(metadata) {
        var hideApproved = $(metadata).find('hideApproved').text();
        if(hideApproved === 'true')
            callback([{
                name: "Approved",
                hidden: true
            },{
                name: "Editing",
                used: false
            }]);
        else
            callback([]);
        }
    );
}
Diagram title function implementation
diagramTitle: function(ctx, callback){
    if(ctx.activeObject.getInfo().status_info.name.split('/')[1] == 'L1')
        callback({text: 'L1 stage', style: "color: red"})
}
Constraint definition

Each status or transition can be given a series of custom constraints. Each constraint is specified as a Javascript object, with the following properties:

{
    // ....
    constraints: [{
        message: 'Constraint message',
        longMessage: 'another message to show instead of the default one for EOMDB constraints',
        condition: function( ctx ) { },
        action:[]
    }]
}
  • type (optional). If specified and equal to "warning", the constraint is not mandatory and only appears as a warning to the user. If specified and equal to "reminder", the constraint is not mandatory and only appears as a reminder to the user.

  • id (mandatory if type is "reminder"). It identifies the reminder. It must be unique.

  • message message specifies the message to be shown when the constraint is not overcome.

  • longMessage (optional). If specified, it is shown instead of the message. It can be used for EOMDB constraints to show a longer and different message in the Diagram Workflow.

  • condition is a function in which the user can check particular conditions (such as the availability of a particular metadata) and return true if the condition is met. See Diagram Workflow Context object Reference for further information on the ctx param.

  • action is an array of actions: they can be either strings (in case of out-of-the-box available actions) or javascript functions to manipulate the system attributes or the metadata of the document.

The only "out-of-the-box" action available at the moment is "metadata". This will allow the user to open the document metadata inside the Diagram Workflow dialog, without having to open the document.

If a list of actions is specified, they will appear as clickable buttons inside the Workflow Constraint Box.

This method can be used to add custom actions associated with EOMDB constraints. To do so, simply add a constraint with the same exact message (case sensitive) as the EOMDB constraint message. The Workflow Map will automatically associate that with the actions you provide. No condition is required. Example:

// EOMDB Constrain with custom action
{
    // ....
    constraints: [{
        // BE CAREFUL: THE MESSAGE SHOULD BE THE SAME AS THE EOMDB CONSTRAINT
        message: 'Please spell the text first!'
        action:[ 'metadata', 'customaction' ]
    }]
}
Reminders

Reminders are represented by static lists of conditions that can be checked when completed.
This panel can be used to track conditions that are not strictly related to the object.
Each list is associated to one workflow status.
It is configured in diagram workflow plugin (as warnings, type: 'reminder').
Check status is stored in a specific role of the object.

getTitle

If specified, this method sets the title of the Diagram workflow dialog.

getTitle: function( ctx, callback )
ctx

ctx stands for the Context Object. Please refer to Diagram Workflow Context object Reference for further reference.

callback

The callback function must be called to return the control to the Diagram Workflow dialog so that it can proceed with the subsequent operation.

Examples
{
     getTitle: function( ctx, callback) {
        var title = ctx.activeObject.getName() + ' something custom';
        callback(title);
     }
}

onLoad, onBeforeSave, onAfterSave

The onLoad, onBeforeSave and onAfterSave are called, respectively, when the dialog is opened and before and after the workflow is saved.

All methods have the same declaration:

onLoad: function( ctx, callback )
onBeforeSave: function( ctx, callback )
onAfterSave: function( ctx, callback )
ctx

ctx stands for the Context Object. Please refer to Diagram Workflow Context object Reference for further reference.

callback

The callback function must be called to return the control to the Diagram Workflow dialog so that it can proceed with the subsequent operation.

Examples
{
     onBeforeSave: function( ctx, callback) {
         callback();
     },
     onAfterSave: function( ctx, callback) {
         ctx.activeObject.generatePDF('queuename', callback);
     },
     onLoad: function( ctx, callback) {
         console.log("LOAD " + ctx.activeObject.getName());
         callback();
     }
}

[IMPORTANT] If the callback is not called, the dialog stops working.

onEvent

This method is called when an event on the current document is received.

The syntax is the following:

onEvent ( ctx, evt )

ctx

ctx stands for the Context Object. Please refer to Diagram Workflow Context object Reference for further reference.

evt

evt the event object containing the event name and info.

Examples
{
     onEvent: function( ctx, evt ) {
       const eventName = evt.name;
       if (eventName === 'set_attributes') {
           // Add you logic here
       }
    }
}

onShowHistory

The onShowHistory method is called whenever the user opens the history tab.

onShowHistory: function( ctx, params, callback )
ctx

ctx stands for the Context Object. Please refer to Diagram Workflow Context object Reference for further reference.

params

The params object contains useful parameters to build the workflow history.

{
    workflowHistory: [],
    diffHistory: []
}
callback

The callback is a function that must be called with the new History Panel html. See the example below for the standard implementation.

{
    onShowHistory: function(ctx, params, callback) {
            // Obtain the template
            ctx.map.getTemplate( ctx.map.getBaseUrl() + 'workflow-map-history.html', function(err, html) {
                if (err) {
                    // If error, show error and callback with no value (so the default history is shown).
                    ctx.map.showError( err.message || err );
                    return callback('');

                }
                // Underscore: compile template
                var compiledTemplate = _.template(html);
                // Now, process the template with the required parameters-
                // For example, getCorrelations
//                ctx.activeObject.getCorrelations(function(err, correlationList) {
                    // if (err) {
//                        ctx.map.showError( err.message || err );
//                        return callback('');
//                    }
                    var newHTML = compiledTemplate({
                        data: params.data,
                        external: params.external,
                        // add additional info
                        // correlations: correlationList
                    });
//                });

                callback(newHTML);
            });
        },
}

onShowHelp

The onShowHelp method is optional and used to customize the help button. If this method is not implemented, the button will not be shown.

onShowHelp: function(ctx)
ctx

ctx stands for the Context Object. Please refer to Diagram Workflow Context object Reference for further reference.

callback

The callback is a function that must be called with the new History Panel html. See the example below for the standard implementation.

{
    onShowHelp: function(ctx) {
            // Do some operations...
            ctx.map.getTemplate( ctx.map.getBaseUrl() + 'simple-help.html', function( err, html ) {
                if (err) {
                    ctx.map.showError( err.message || err );
                    return;
                }
                var template = _.template( html );
                ctx.map.showPopup({
                    content: template({})
                });
            });
        },
}

onStatusClick, onStatusHover, onTransitionClick, onTransitionHover

The onStatusClick method is called whenever the user click on a status.

The onStatusHover method is called whenever the user hovers on a status.

The onTransitionClick method is called whenever the user click on a transition arrow.

The onTransitionHover method is called whenever the user hovers on a transition arrow.

The onShowHistory method is called whenever the user opens the history tab.

All methods have the same declaration:

onStatusClick: function( ctx, data )
onStatusHover: function( ctx, data )
onTransitionClick: function( ctx, data )
onTransitionHover: function( ctx, data )
ctx

ctx stands for the Context Object. Please refer to Diagram Workflow Context object Reference for further reference.

data

The data object contains useful information regarding the status and the transition clicked.

An example is the following:

{
    "workflowName": "NewsFlow",
    "selectionType": "TRANSITION",
    "selectedStatus": {
        "name": "For Approval",
        "transitions": [
            {
                "name": "Approved",
                "afterCommand": {},
                "beforeCommand": {},
                "errorCommand": {},
                "locker": "",
                "permissions": [],
                "objectInfo": {},
                "systemAttributeXml": ""
            }
            // ...
        ],
        "constraints": [
            {
                "message": "Please spell the text first!",
                "actions": [],
                "type": "STATUS_CONSTRAINT"
            }
            // ...
        ],
        "permissions": [],
        "systemAttributeXml": "...",
        "color": "RGB(255,192,0)",
        "isNext": true,
        "isPast": false,
        "isUsed": false,
        "isFuture": false,
        "isCurrent": false
    },
    "target": "For Approval",
    "workflowHistory": [],
    "panelVisible": true,
    "uniqueId": "U48623423007fBE",
    "source": "Editing",
    "sourceInfo": {
        // See selectedStatus
    },
    "targetInfo": {
        // See selectedStatus
    },
    "transitionInfo": {
        "constraints": [
            // Custom constraint on the transitions
        ]
    },
    "options": {
        "showHistoryInMap": false
    }
}

The properties are the following:

  • workflowName : the name of the currently selected workflowMap

  • selectionType: It can be either 'TRANSITION' (for the onTransitionClick method) or 'STATUS' (for the onStatusClick / onStatusHover method)

  • selectedStatus, sourceInfo, targetInfo: these properties contain detailed information about the statuses involved. In case of the onStatusClick / onStatusHover method, the source property is equal to null and the sourceInfo is null as well. The selectedStatus property is always equal to the targetInfo. Among others, they contain the following properties:

    • transitions: the list of transitions available for that status

    • constraints: the list of constraints (both traditional and custom) available.

    • isNext, isPast, isUsed, isFuture, isCurrent define the Status inside the map

  • panelVisible: a Boolean saying whether the right panel of the dialog is visible or not.

  • workflowHistory: the full workflow History of the document.

  • statusWorkflowHistory: the full workflow History of the status.

  • options: an object containing the current settings (read-only)

Full Example

Full working example is placed in the swing-extensions-samples.zip file, under /plugins/workflowMap/

Diagram Workflow Context object Reference

The Context object inside the Diagram Workflow follows the general Context Object available in many different parts of the application.

Basic structure of the Context Object

The Context object is made of a specific list of properties, and a number of publicly available methods.

{
    application: {
        getId: function()
    },
    area: {
        getType: function(),
        getName: function(),
        getContext: function()
    },
    component: {
        getType: function()
    },
    activeObject: {
        // Methods of the single object.
    },
    activeObjects: [{activeObject}] // An array of activeObject
    selection: [ ] // Array of objects. See below.
}
Table 3. Parameters list
Parameter Value type Description Values

application.getId()

String

Returns the application Id.

"swing", …​

area.getType()

String

Returns the area type.

"main" (for the main views), "editor"

area.getName()

String

Returns the area name.

"explorer", "dashboard", "myarea", "liveblogmanagement" (for "main" areas). "story" (for editors).

area.getContext()

String

Returns the area context.

"story-editor", "report-editor", "dwp-editor", "topic@editor", "topic@search", "topic@binder", "topicplan@editor", "topicplan@search", "topicplan@binder", "topicitem", "upload", "diagram-workflow", "search", "planning-calendar"

component.getType()

String

Returns the component type.

"toolbar", "grid", "objectpanel"…​

activeObject

Object

Returns an object with a set of methods. Refer to : Methods of the single object for the list of methods.

activeObjects

Array

Returns an array of activeObject(s). In bulk selection mode all selected items are returned here as array. In single selection mode array length is 1. Each activeObject is coupled with one selected item. Methods of the single object operate to that item.

selection

Array of Object

Returns an array with the currently selected items. Each item has the same set of methods available. Refer to : Methods of the single object for the list of methods.

Each context has a different value for these properties.

Methods available in the Context Object

Further details on the methods available in the Context Object can be found in the Context Object Methods reference.

Specific methods of the Context Object in the Diagram Workflow

The Diagram Workflow provides additional methods inside the context object. They are all available within

ctx.map.<method name here>
getBaseUrl

Return the base url of configurable custom templates. See getTemplate for further information.

The base URL is inside {SWING}/config/templates/workflowMap.

Syntax
var baseUrl = ctx.map.getBaseUrl()
getTemplate

Loads a template given its url. It is often used in combination with getBaseUrl to load the custom templates for the popups.

Syntax
ctx.map.getTemplate( url, callback );
Params
Table 4. Parameters list
Parameter Values Description

url (required)

String

The path to the file to load.

callback (required)

function

The callback function when the template is loaded. See example below

Example
// "data" is the argument of the onStatusClick method in this case...
var baseUrl = ctx.map.getBaseUrl();
ctx.map.getTemplate( baseUrl + 'my-custom-popup.html', function( err, html ) {
    if (err) {
        ctx.map.showError( err.message || err );
        return;
    }
    var template = _.template( html );
    ctx.map.showPopup({
        content: template({
            data: data

        })
    });
});
showError

Shows a specified error

Syntax
ctx.map.showError( message );
Params
Table 5. Parameters list
Parameter Values Description

message (required)

String

The message to be shown.

Example
ctx.map.showError('My error message');
showHistory

Shows the history of the document in the right panel.

Syntax
ctx.map.showHistory();
Example
ctx.map.showHistory( );
showPopup

Shows a popup with custom content.

Syntax
ctx.map.showPopup( popoverOptions );
Params
Table 6. Parameters list
Parameter Values Description

popoverOptions (required)

Object

The popover options are the same described in Bootstrap 3.3.6 documentation. It is mandatory to specify a content property.

Example

See getTemplate for a sample of usage of the showPopup method.

History Panel

The History Template is placed under

{SWING}/config/templates/workflowMap/workflow-map-history.html

By changing this, it is possible to change the layout of the history panel.

A compact version of the history is available under

{SWING}/config/templates/workflowMap/workflow-map-history-compact.html

to use it, rename the file to

{SWING}/config/templates/workflowMap/workflow-map-history.html