Mayam Tasks BPM Process Guide 3

© Copyright Mayam 2019

BPM Process Guide

Mayam Tasks

Version 3

Technical Reference

© Copyright Mayam 2019 2

Contents Contents ............................................................................................................. 2

Document Information ..................................................................................... 5

1 Abstract...................................................................................................... 6

2 Introduction .............................................................................................. 7

3 Getting Started.......................................................................................... 9

3.1 Installing Activiti ..................................................................................................9 3.1.1 Installing Eclipse ............................................................................................................ 9 3.1.2 Installing the Activiti Plugin ...................................................................................... 9 3.1.3 Installing the Mayam Palette in Activiti .............................................................. 10 3.1.4 Create a Demo Project and Download Sample Processes ........................... 11

3.2 Activiti Explorer................................................................................................. 13 3.2.1 Log In ............................................................................................................................... 13 3.2.2 Deploy Sample Processes ........................................................................................ 14

4 Process Tutorial ....................................................................................... 16

4.1 CreateTaskForNewItem ................................................................................... 16 4.2 CreateTaskForNewEpisodeRules .................................................................... 17 4.3 UpdateTitle ........................................................................................................ 18 4.4 UpdateTitleUnmanaged .................................................................................. 18 4.5 SendMediaForReview ...................................................................................... 19 4.6 SendMediaForReviewErrorHandling ............................................................. 19 4.7 SendMediaForReviewIfNeeded ...................................................................... 20 4.8 MonitorXfer ....................................................................................................... 21

5 Starting Processes and mapping of attributes ..................................... 22

6 Generic BPMN Shapes............................................................................. 24

7 Mayam Custom Palette........................................................................... 26

7.1 Mayam Activiti Utils .......................................................................................... 28 7.1.1 Delete Process Instance History ............................................................................. 28 7.1.2 Javascript ........................................................................................................................ 28 7.1.3 Send Notification ......................................................................................................... 28 7.1.4 Process Rules ................................................................................................................. 29

7.2 Mayam BMS Operations ................................................................................... 30 7.2.1 Close BMS Request ..................................................................................................... 30 7.2.2 Update BMS ................................................................................................................... 30

7.3 Mayam Asset ...................................................................................................... 30 7.3.1 Create Asset ................................................................................................................... 30 7.3.2 Create Logtracks for Asset ....................................................................................... 31 7.3.3 Delete Asset Media ..................................................................................................... 31 7.3.4 Delete Asset ................................................................................................................... 31 7.3.5 Delete Peer Asset ......................................................................................................... 32 7.3.6 Update Full Asset......................................................................................................... 32 7.3.7 Update Full Legacy Asset ......................................................................................... 32 7.3.8 Generate SiteId ............................................................................................................. 33 7.3.9 Get Asset By SiteId ...................................................................................................... 33

Technical Reference


7.3.10 Get Full Asset .............................................................................................................. 33 7.3.11 Get Peer Asset By PeerSiteId ................................................................................. 34 7.3.12 Get Asset Metadata .................................................................................................. 34 7.3.13 Import File ................................................................................................................... 34 7.3.14 Move Media Essence ............................................................................................... 34 7.3.15 Request Conform ...................................................................................................... 35 7.3.16 Request Transcode ................................................................................................... 35 7.3.17 Request Transfer........................................................................................................ 36 7.3.18 Retire Asset .................................................................................................................. 36 7.3.19 Set Asset Metadata ................................................................................................... 36 7.3.20 Update Asset Acl ....................................................................................................... 37 7.3.21 Update Asset............................................................................................................... 37 7.3.22 Update Process Instance From Asset ................................................................ 37

7.4 Mayam File Operations .................................................................................... 38 7.4.1 Get File Info .................................................................................................................... 38 7.4.2 Get Side Car Info .......................................................................................................... 38 7.4.3 Link File ........................................................................................................................... 38 7.4.4 Move File ........................................................................................................................ 39 7.4.5 Remove File ................................................................................................................... 39 7.4.6 Touch file if exists ........................................................................................................ 39

7.5 Mayam Task ....................................................................................................... 40 7.5.1 Add To CommentLog ................................................................................................ 40 7.5.2 Close task ........................................................................................................................ 40 7.5.3 Create task ..................................................................................................................... 40 7.5.4 Find Task for Asset ...................................................................................................... 41 7.5.5 Find Task for Peer Asset ............................................................................................ 41 7.5.6 Find Task ......................................................................................................................... 41 7.5.7 Get Full Task .................................................................................................................. 42 7.5.8 Set Task State ................................................................................................................ 42 7.5.9 Update ProcessInstance from Task ....................................................................... 42 7.5.10 Update QC status ...................................................................................................... 43 7.5.11 Update Task ................................................................................................................ 43 7.5.12 Update TX status ....................................................................................................... 43

8 System Architecture ............................................................................... 45

8.1 Activiti BPM........................................................................................................ 45 8.1.1 Activiti Explorer GUI ................................................................................................... 45 8.1.2 Activiti REST Service ................................................................................................... 46 8.1.3 Mayam Delegates ........................................................................................................ 46

8.2 Mayam Tasks ..................................................................................................... 46 8.2.1 Tasks‐Ws REST API ....................................................................................................... 47 8.2.2 Tasks‐Ws Java SDK ...................................................................................................... 47 8.2.3 Mam‐Adapter ................................................................................................................ 48 8.2.4 Bpms‐Event‐Daemon ................................................................................................. 48

8.3 ActiveMQ Message Queue ............................................................................... 48 8.3.1 Message Routing using Camel ............................................................................... 48

8.4 MAM System ...................................................................................................... 49 8.4.1 MAM System API.......................................................................................................... 49 8.4.2 MAM System Events ................................................................................................... 49

8.5 Active Directory / LDAP .................................................................................... 49 8.6 Other Systems ................................................................................................... 49

9 Data Constructs for Managing Tasks and Assets ................................. 51

Technical Reference


9.1 Top Level Entities and Operations.................................................................. 51 9.1.1 Task ................................................................................................................................... 51 9.1.2 Asset ................................................................................................................................. 51 9.1.3 Static Constructs .......................................................................................................... 52 9.1.4 Attribute ......................................................................................................................... 52 9.1.5 Value Data Types ......................................................................................................... 52 9.1.6 Unmanaged Metadata (New in 2.4) ..................................................................... 52

9.2 Configurable Entities ........................................................................................ 53 9.2.1 Task List Configuration .............................................................................................. 53 9.2.2 Fields ................................................................................................................................ 53 9.2.3 Attribute Mapping ...................................................................................................... 53 9.2.4 Further Reading ........................................................................................................... 53

10 Javascript in processes ........................................................................... 55 10.1 Introduction ..................................................................................................... 55 10.2 The attribute map ........................................................................................... 55 10.3 The UNM_IN object ......................................................................................... 56 10.4 The logger object ............................................................................................ 56 10.5 The util object .................................................................................................. 56 10.6 The execution object ...................................................................................... 57

11 Reference Documentation ..................................................................... 58 11.1 Mayam .............................................................................................................. 58 11.2 Activiti .............................................................................................................. 58 11.3 BPMN ................................................................................................................ 58

Technical Reference


Document Information

Revision History

Rev. Date Author Comment

1.0 Sept 2018 André Cruz

Contact Information

Mayam AB, Svärdvägen 27, 182 32 Danderyd Sweden

Phone: +46 (0)730-808011 E-mail: [email protected]

Technical Reference


1 Abstract The Mayam task management system, Mayam Tasks, extends a workflow and/or MAM environment with advanced task management capabilities and APIs specifically designed for use with BPM systems. What to expect from this document This document introduces the product by providing an overview of the tasklist GUI, the BPM interface and other support applications such as the reporing engine. A description of the system architecture is also provided. What You Should Know Before Reading This Manual This manual describes how to manage the Mayam Tasks and MAM environment. The reader is assumed to have detailed conceptual knowledge and high-level technical knowledge about these systems. For Mayam Tasks, please refer to the document Mayam Tasks Overview (found at: http://your-hostname-here:8084/tasksdoc/tasks_overview.pdf). Also, refer to MAM system product documentation to familiarize yourself with the MAM system concepts, data model and security. A moderate understanding of how to draw BPMN diagrams including the most commonly used BPMN shapes is a also a prerequisite. A suitable entry point is available under “Quick Guide” at http://www.bpmn.org/. It is also useful to have a reference to Activiti documentation at hand. Use http://activiti.org/ as a starting point.

Technical Reference


2 Introduction The Mayam Tasks application extends the Media Asset Management (MAM) environment with advanced task management, business process and integration capabilities. With the Mayam approach to workflow implementation, workflows in a MAM environment are provided through the use of a dedicated task and process modelling and execution subsystem, relying on Mayam Tasks for GUI functions and MAM-independent APIs.

Figure 1. Mayam Tasks GUI.

This manual aims to provide the reader with an understanding of the business process modeling (BPM) parts of the system. The business processes are modelled in the BPMN 2.0 notation. A sample Business Process Diagram (BPD) is shown below.

Figure 2. Sample Business Process Diagram using BPMN 2.0 and Mayam Palette.

Technical Reference


Using the information in this manual, the reader will be equipped with information on how to:

• Receive MAM and task list user events and start processes

• Create, update and close user tasks and send notifications.

• Perform MAM record and metadata CRUD operations

• Manage media - transfer, transcode, move between placeholders etc.

Technical Reference


3 Getting Started This chapter describes how to set up the workflow and BPM environment, Activiti Designer. You will also learn how to deploy process into the Activiti server. Once your Designer environment is up and running, we recommend to proceed to the process design tutorial in the next chapter.

3.1 Installing Activiti

The Activiti Designer environment consists of three different downloadable components:

• The Eclipse framework, which Activiti is using

• The Activiti Designer application, which is downloaded as an Eclipse plugin

• The Mayam palette, which adds the task and MAM action shapes to Activiti

3.1.1 Installing Eclipse

Start by downloading and installing Eclipse. Note that for Mayam Tasks 2.4 and Activiti 5.18, the latest release is supported by Activiti, so see version details below. The download starting point is:

• http://www.eclipse.org/downloads/

• Use the Luna release

• Choose the package “Eclipse IDE for Java EE Developers”

• When the download is complete, follow the installation instructions at:

o http://wiki.eclipse.org/Eclipse/Installation

This task is finished when you have installed and started Eclipse.

3.1.2 Installing the Activiti Plugin

The Activiti application is downloaded and installed using the Eclipse “Add Software” function:

• In the eclipse menu bar, click Help > Install New Software

• Click Add... (the button in the top right corner)

• The Add Repository dialog is displayed

• Enter “Activiti Designer” in the field name

• In the location field, enter http://activiti.org/designer/update/ ○ Ok

• The Available Software window will display “Activiti BPMN Designer”. Select it

Technical Reference


• Important: Ensure that the offered version is 5.18. If not, untick the option “Show only the latest versions of available software” and select version 5.18

• Click Next and Ok as required to complete the installation

• Restart Eclipse

You know that the installation was successful if the restarted Eclipse now has a new so called perspective - Activiti. Try using the Eclipse menu action Window -> Open Perspective -> Other...

The Activiti perspective should be present in the list of perspectives.

3.1.3 Installing the Mayam Palette in Activiti

The final install step adds the Mayam task- and MAM action shapes to Activiti. Do the following:

• Go to the Mayam SDK resource page at http://<your server name>:8084/tasks-ws/

• Click on the download link “Mayam Activiti Palette” in the section BPM / Activiti

• Resources

o This action will download the file mayam-activiti-palette-2.4.0.jar

• Create a personal library directory such as ~/lib or %HOME%/lib

• Copy mayam-activiti-palette-2.4.0.jar to the newly created directory

• In Eclipse, open preferences (Eclipse -> Preferences)

Technical Reference


• Locate the setting Java -> Build Path -> User Libraries

• The list of user libraries should contain “Activiti Designer Extensions”. Select it

• Click “Add External JARs...

o Browse to your personal library directory and select mayam-activiti-palette-2.4.0.jar

o Click Open / Ok The final result should look like shown in the following screenshot.

Finally, click Ok to close the Preferences dialog. The installation is now complete.

3.1.4 Create a Demo Project and Download Sample Processes

The next step is to create a demo project and download a set of sample processes.

• In Eclipse, create a new Activiti project:

o In the Activiti Explorer window, right click New -> Project

o In the list that shows up, select Activiti / Activiti Project

o Click Next and name the project (for example, to activiti-demo)

o Click Finish to create the project

Technical Reference


• Go to the Mayam SDK resource page at http://<your server name>:8084/tasks-ws/

• Click on the download link “Sample Processes” (in the section BPM / Activiti Resources)

o This action will download the file mayam-sample-processes.zip

• In the sample project browse to the folder src/main/resources/diagrams

• Select the folder (click on it), then right click and choose Import...

• Select the import source General / Archive File

• Click Next

• Locate and select the file mayam-sample-processes.zip you just downloaded

Technical Reference


• Double check that the import will happen into the folder <project name>/src/main/resources/diagrams

• Click Finish to import the files.

• Click on a process (.bpmn) file to open it in Activiti Designer

The process should now be displayed as in the figure above. After verifying that we can deploy processes to the server, we are getting ready to learn how to draw new workflow processes.

3.2 Activiti Explorer The Activiti administration console, where, for example new processes are uploaded, is called Activiti Explorer. While Activiti Explorer can be used to perform a wide range of functions, this section will focus on how to deploy processes. Additional documentation pointers are available in Section 9, Reference Documentation.

3.2.1 Log In

Activiti Explorer is a web-based application that can be reached at

• http://your-hostname-here:8084/activiti-explorer

Log in as user mayam (the configured password should vary, but the default is mayam). Alternatively, the blank system default is kermit/kermit. Once logged in, the overview screen will be shown.

Technical Reference


Figure. Activiti Explorer welcome screen.

3.2.2 Deploy Sample Processes

BPMN process diagrams are deployed into Activiti using a web upload function in Activiti Explorer. We recommend to deploy processes as a complete package (zip file) instead of one by one.

Figure. The Activiti Explorer upload dialog for deployment file upload.

Technical Reference


In order to deploy the set of sample processes, do the following:

• In Activiti Explorer, click Manage -> Deployments -> Upload New

• Drag the recently downloaded file into the dropzone in the upload dialog

• Wait for Activiti to deploy the BPMN processes

• Done!

The system is now ready to create and execute the deployed processes. In the next chapter, Process Tutorial, the contents of the processes and the actions performed will be described.

Technical Reference


4 Process Tutorial

This chapter describes a number of sample workflows that can be downloaded from the tasks-ws documentation endpoint.

4.1 CreateTaskForNewItem

This workflow starts automatically whenever an item is created in the mam system. This is because it’s a MessageStartEvent with ASSET_ITEM_CREATE as Message ref. This requires camel rules to be setup correctly.

If content type is “rawm” (raw material), a task is created. Any attribute included in the item, can be used in the gateway expression.

Technical Reference


4.2 CreateTaskForNewEpisodeRules

This workflow is very similar to the previous one. The main differences are that it's started whenever an Episode is created in the MAM, and that the attribute map given in the ASSET_EPISODE_CREATE message gets sent through the process rules activity. This should set the boolean OP_FLAG attribute for all items that should have a task created.

Please note that the gateway expression is “${execution.getVariable("OP_FLAG”)}”. This expression is the same as “${OP_FLAG}” with the difference that if the variable is undefined, the first expression will cause a null value (which is considered false), but the other will cause an error.

Also note that only one process that starts with a message (such as ASSET_ITEM_CREATE) is allowed to be deployed at the same time in Activiti.

Technical Reference


4.3 UpdateTitle

This process simply prefixes the title of the asset with “Raw Material: “ or “Normal Material: ” based on the content type of the asset. This is done with the following javascript followed by an update of ASSET_TITLE

if (s.CONT_MAT_TYPE == 'rawm')

s.ASSET_TITLE = 'Raw Material: ' + s.ASSET_TITLE

else

s.ASSET_TITLE = 'Normal Material: ' + s.ASSET_TITLE

4.4 UpdateTitleUnmanaged

This process is identical to the previous except that it is using the unmanaged api to do the update. This means that it is possible to update any metadata value in the asset without having to map them to Mayam attributes.

The process starts with getting all metadata from the asset. This is now accessible from any javascript shape as a hash named “UNM_IN”. It then updates the asset metadata using the “Set Asset Metadata” node. This is a javascript shape and any value stored in the hash “UNM_OUT" will be updated in the asset. The following javascript is used in this example

if (s.CONT_MAT_TYPE =='rawm')

UNM_OUT = {'asset.title': 'Raw Material:' + UNM_IN['asset.title']}

else

UNM_OUT = {'asset.title': 'Normal Material:' + UNM_IN['asset.title']}

Technical Reference


4.5 SendMediaForReview

This workflow is an example of a workflow that could be started from a button press or using the API. This updates the current task with the process instance id, then requests a transferandupdatesthetasktostateXFER. Itthenwaitsforajobdoneofjobfailedevent and sets the task state accordingly. It also adds some comments to the task.

4.6 SendMediaForReviewErrorHandling

Technical Reference


This workflow is identical to the previous one with the exception that it also handles error. In the previous example, if the request transfer fails, the workflow will cause an error at that point. In this example, there is a sub process that is automatically started when any error occurs and sets the task state to ERROR. This is because it is started with a ErrorStartEvent.

If the previous process is started from a user clicking a button it will give an error to the user, but this process will not.

4.7 SendMediaForReviewIfNeeded

This is an example that is using process rules to see if review is needed, it then calls the process “SendMediaForReview” as given above. This process also shows how to use a ErrorBoundaryEvent to catch any error in the “SendMediaForReview” process. Please note that any variable/attribute needed must be included in the Call activity.

Technical Reference


4.8 MonitorXfer

This is A more complete example of a transfer monitoring. This process requires TASK_ID and XFER_IDSTR to be set when the process is started. The process waits for one of the following things to happen:

• Transfer to be done

• Transfer to fail

• Transfer to be aborted

• Transfer to not be finished for 24 hours.

• User to click reject in the task ui

Technical Reference


5 Starting Processes and mapping of attributes

There are multiple ways to start an Activiti Process in Mayam Tasks.

• User clicking a button in the UI

• Starting based on a MQ message from the MAM or a task

• Starting using the ReST API

In the configuration of the task lists, a named process can be configured for a button.

When a user clicks that button, a process is started and it will receive all attribute values in the tasks as variables in the process. Looking at it in Activiti Explorer it looks something like this:

These variables in the process could then be modified, updated on tasks or assets (or both), used as decision points, etc. Attributes that are of the types Integer, Long, Short, Double, Boolean, String or Date, are stored as that type in Activiti. Attributes of other types are stored as Strings in Activiti.

Technical Reference


Another way is by starting based on an event from the MAM.

The start point is of type MessageStartEvent and the message reference is ASSET_ITEM_CREATE

Every time the MAM sends out a message that a new item has been created, our message forwarder takes that, converts it into a attribute map with a message ref, checks in activiti if there is any process that would start based on a that message ref, and if there is, it starts the process with the attribute map as variables in the process

Technical Reference


6 Generic BPMN Shapes The activiti designer tool uses BPMN 2.0 notations to represent the various elements (shapes / nodes) that are used to design a business process. Some of the commonly used shapes based on past implementations are described in the table below.

Activity Description Parameters

Empty start event, triggers the start of the process. This is used when the process is triggered by a user action button click on tasks screen or from site specific customisation.

Id - Unique Id String Name - String

Message start event. A specific defined message triggers the start of the process.

Id - Unique Id String Name - String Message ref - String

Error start event. Triggers the start of a sub process on an error that occurs on the containing parent process.

Id - Unique Id String Name - String Error code - String

Empty end event. Signals the end of the process. Id - Unique Id String Name - String

Call activity. Used to invoke another process from current execution.

Id - Unique Id String Name - String Called element - processname, String Input Parameters - Refer Activiti user guide. Output Parameters - Refer Activiti user guide.

Event sub-process. A sub-process that is triggered by a non-emtpy start event. eg common error handling for an entire process.


Sub-process. A group of tasks/activities that can be grouped under a common business logic.


Parallel gateway. This represents parallel/concurrent tasks in the process. There are no conditions for this gateway.


Exclusive gateway. These are used to control how the process flows based on conditions. The paths are mutually exclusive. The conditions for each flow is defined in sequence flow (see below).

Id - Unique Id String Name - String Default flow - Refer to the Activiti user guide.

Technical Reference


Activity Description Parameters

Inclusive gateway. This represents parallel/concurrent tasks in the process based on flow conditions. The conditions for each flow is defined in sequence flow (see below).

Id - Unique Id String Name - String Default flow - Refer Activiti user guide.

Event gateway. Similar to a exclusive gateway because both involve only one path in the flow, however the flow is triggered based on listening events rather than conditions.


Timer boundary event. Timer events to trigger timeouts for a sub-process, event task or call activity.

Id - Unique Id String Name - String Cancel activity - Boolean Time duration - ISO 8601 format Time date - ISO 8601

Refer Activiti user guide.

Error boundary event. An intermediate catching error on the boundary of an activity, or boundary error event for short, catches errors that are thrown within the scope of the activity on which it is defined.


Timer intermediate catching event. A timer intermediate event pauses the task in the process flow until the defined timer duration is complete.

Id - Unique Id String Name - String Time duration - ISO 8601 format Time date - ISO 8601 Refer Activiti user guide.

Message intermediate catching event. Puts the task execution on hold until the configured message event is received.

Id - Unique Id String Name - String Message ref - String

Sequence flow/Message flow. Connects the activities in the process. It is responsible for the direction/sequential order of process flow. Can evaluate an option condition to control the flow.

Id - Unique Id String Name - String Condition - Refer Activiti user guide.

Technical Reference


7 Mayam Custom Palette Mayam palette are customised shapes that are created to do Mayam Tasks specific and media related activities. These activities are summarized in the Table below and a detailed description of each shape is provided in the following Sections.

Activity Description Reference

Mayam Activiti Utils

Deletes the current process instance’s history. Sec 7.1.1

Runs javascript with access to process data. Sec 7.1.2

Sends a notification. Sec 7.1.3.

Executes excel based rules and assigns output to configured parameters in the process.

Sec 7.1.4.

Mayam BPM Operations

Site specific shape. This sends a close signal to the traffic system as a MQ message.

Sec 7.2.1.

Site specific shape. Updates the traffic system with task data.

Sec 7.2.2.

Mayam Asset

Creates an asset in the MAM. Sec 7.3.1.

Creates logtracks for an Asset in the MAM. Sec 7.3.2.

Deletes the media in the asset placeholder. Sec 7.3.3.

Marks the asset for deletion in the MAM. Sec 7.3.4.

Marks the peer asset for deletion in the MAM. Sec 7.3.5.

Updates all Attributes of the task in the tasklist with the process variables.

Sec 7.3.6.

Site specific shape. This updates a secondary legacy MAM system.

Sec 7.3.7.

Generates a unique site id. Sec 7.3.8.

Fetches the asset id by site id. Sec 7.3.9.

Fetches and updates the task with the asset details from MAM

Sec 7.3.10.

Gets asset by ASSET_PEER_SITE_ID. Sec 7.3.11.

Technical Reference


Gets the asset metadata. Sec 7.3.12.

Imports a file to the MAM. Sec 7.3.13.

Moves media between asset and the peer asset. Sec 7.3.14.

Conform request to MAM Sec 7.3.15.

Request a simple transcode based on pre-defined profiles. Sec 7.3.16.

Requests a transfer for asset. Sec 7.3.17.

Retire Asset in MAM Sec 7.3.18.

Sets the asset metadata. Sec 7.3.19.

Updates the Acl for an asset. Sec 7.3.20.

Updates the asset metadata in MAM. Sec 7.3.21.

Update Process Instance from asset Sec 7.3.22.

Mayam File Operations

Gets the file information for a file. Sec 7.4.1.

Gets sidecar file info. Sec 7.4.2.

Hard-link a non-MAM managed file Sec 7.4.3.

Move a non-MAM managed file Sec 7.4.4.

Remove a non-MAM managed file. Sec 7.4.5.

Touch a non-MAM managed file. Sec 7.4.6.

Mayam Task

Add a comment to the task comment log. Sec 7.5.1.

Closes a task Sec 7.5.2.

Creates a task. Sec 7.5.3.

Find task for an asset. Sec 7.5.5.

Find task for a peer asset. Sec 7.5.6.

Finds active task. Sec 7.5.7.

Get the full task, using TASK_ID. Sec 7.5.8.

Sets the task state. Sec 7.5.9.

Update Process Instance from task. Sec 7.5.11.

Update QC status Sec 7.5.12.

Update task with values from process variables. Sec 7.5.13.

Updates TX status for the task. Sec 7.5.14.

Technical Reference


7.1 Mayam Activiti Utils Mayam palette group that contains shapes that are a part of utilities and not pertaining to any task or asset related actions.

7.1.1 Delete Process Instance History

Deletes the process instance history data. This is used to delete history for unwanted instances and keep the database size under check. See sample 8.1.

• Input Parameters

o None.

• Input Variables

o None.

• Output Variables

o DELETE_PROCESS_INSTANCE_HISTORY: true

7.1.2 Javascript

This is a service task that can run a JavaScript and has access to all process/execution variables/data. This shapeis typically used to compute and set values to variables that are later used in other parts of the process. For eg. To use “Create asset” shape the variable METADATA_FORM should contain the metadata form model that is defined in the MAM. This can be populated by the Javascript shape based on business case. See sample 8.3.


o Source: javascript. This is a mandatory parameter. The script here can access process attributes by using the subject “s”. For more information see Javascript in processes

o Sample: if (s.FILE_NAME != null) { var nameArr = s.FILE_NAME

s.ASSET_TITLE = s.ASSET_TITLE + "_C";

}

• Input Variables

o All task attributes are available to use in the javascript.


o Variables that are set in the source as per the business case.

7.1.3 Send Notification

Sends a message to the NOTIFICATION queue. This could trigger an email or a task in a custom notification tasklist based on the business needs.


o Notification Event Id: String. Mandatory. This is type of event for the notification. eg.

• Input Variables

Technical Reference


o All attribute variables that are set in the process instance. This depends on what is required for the business scenario.


o None.

7.1.4 Process Rules

Process Rules executes excel based rules and assigns output to configured parameters in the process. See sample 8.2.

Screenshot of the excel configuration is shown below:

The values under the column “Rule Name” represent the defined rules.

The columns under “Compare” have the variables as column names. As the column heading suggests the variables from the task are compared with the values under the rule.

Sample: Rule Name - able_stl Compare - FOLDER_NAME = “able_stl”, FILE_EXTENSION = “stl”

The comparison is always with AND operator. If OR needs to be computed it can be entered as new rule. If there more complex evaluation to be done then the user can use the column “expression”

Sample: s.ASSET_DURATION != null && s.ASSET_DURATION > 1000 && contains(s.FILE_NAME, 'POLICE')

The columns under “Assign” sets the values of the variables mentioned in the column heading if the compare evaluates to true.

Sample: Assign - Sets XFER_PRIORITY = 100, QC_REQUIRED = “FALSE”


o File path: path to the excel file that has the rules

• Input Variables

o All attribute variables in the process.


Technical Reference


o Configured in the excel sheet.

7.2 Mayam BMS Operations This group constitutes shapes that interface with Broadcast Management Systems. Note that the palette shapes don’t interact with the BMS directly. Instead, messages are sent to an adapter typically running a site specific interface to the BMS.

7.2.1 Close BMS Request

This shape sends a close signal to the traffic system as a MQ message. This can be used as an integration with any traffic system.


o None.

• Input Variables

o All attributes defined in the process are sent by default as a part of the MQ message.


o None.

7.2.2 Update BMS

Updates the traffic system with task data.


o None.

• Input Variables

o All attributes relating to the task are sent by default as a part of the MQ message.


o None.

7.3 Mayam Asset This group constitutes shapes that interface with MAM system and does asset related actions.

7.3.1 Create Asset

Creates an asset in the MAM-system. See sample


o Asset Type: Mandatory. dropdown with different asset types in the MAM.

Technical Reference


o Model: Optional. String containing the metadata model. This can be given as a fixed input or is looked up from the Attribute METADATA_FORM.

• Input Variables

o METADATA_FORM: Optional. Value in the attribute is used to create the asset if the input parameter Model is empty.

o All other attributes defined in the process are being included in the create asset call.


o ASSET_ID: The task attribute ASSET_ID is set to the item id of the created item. ASSET_SITE_ID: The task attribute ASSET_SITE_ID is set to the “Id” of the asset created. ASSET_TYPE: The task attribute ASSET_TYPE is set to Asset Type input parameter.

7.3.2 Create Logtracks for Asset

Creates logtracks for an Asset in MAM.


o Asset Sub Type: Optional. If this parameter is empty, the value from the Attribute ASSET_SUBTYPE is used. The valid options are defined as a part of a MAM dictionary. Eg. marker, scenedesc, qcremark, qcerror, etc.

o Only if no logtracks exists: checkbox. If checked the create operation checks if logtracks exists for the asset before creating one.

• Input Variables

o ASSET_ID: Asset Id. ASSET_TYPE: “ltr” (LOG_TRACK) set as default. ASSET_SUBTYPE: refer Asset Sub Type input parameter.


o None.

7.3.3 Delete Asset Media

Deletes the media in the asset placeholder.


o None.

• Input Variables

o ASSET_ID: Asset Id.

o ASSET_TYPE: Asset Type.


o None.

7.3.4 Delete Asset

Technical Reference


Marks the asset for deletion in the MAM with a specific grace period.


o Grace Period: Optional. Period of time after which the asset is deleted. Until then the asset remains in the delete queue. If empty the asset is deleted immediately.

• Input Variables

o ASSET_ID: Asset Id. ASSET_TYPE: Asset Type.


o None.

7.3.5 Delete Peer Asset

Marks the asset that is specified in the Attribute ASSET_PEER_ID for deletion in the MAM with a specific grace period.


o Grace Period: Optional. Period of time after which the asset is deleted. Until then the asset remains in the delete queue. If empty the asset is deleted immediately.

• Input Variables

o ASSET_PEER_ID: Asset Id.

o ASSET_PEER_TYPE: Peer Asset Type. If empty, value from ASSET_TYPE is used.

o ASSET_TYPE: Asset Type.


o None.

7.3.6 Update Full Asset

Updates all Attributes of the asset with the process variables. The process variables might not be in sync with actual task data. This should be done with a lot of care.


o None.

• Input Variables

o All process variables. The following are required ASSET_ID: Asset Id ASSET_TYPE: Asset Type


o None.

7.3.7 Update Full Legacy Asset

This the same as Update full asset but the update is done on a secondary legacy MAM system.


Technical Reference


o None.

• Input Variables

o All process variables. The following are required ASSET_ID: Asset Id ASSET_TYPE: Asset Type


o None.

7.3.8 Generate SiteId

Generates a unique siteId.


o Prefix: Mandatory. This is used as a prefix to the generated Id which together constitutes a siteId.

• Input Variables

o ASSET_TITLE: Title string.


o ASSET_SITE_ID: <prefix>-<generatedid>-<mangled asset_title truncated to 12 characters>

7.3.9 Get Asset By SiteId

Fetches the asset id for a specified site Id.


o None.

• Input Variables

o ASSET_TYPE: Asset type. ASSET_SITE_ID: Site Id.


o ASSET_ID: Asset Id. Is null if not found.

7.3.10 Get Full Asset

Get asset and sets all attributes of the task with values returned from MAM.


o None.

• Input Variables

o ASSET_TYPE: Asset type.

o ASSET_ID: Asset Id. If unset uses ASSET_SITE_ID to fetch the asset details from MAM.

o ASSET_SITE_ID: Site Id.


o Resets all task attributes to values fetched from MAM.

Technical Reference


7.3.11 Get Peer Asset By PeerSiteId

Same as get asset by siteid but uses the ASSET_PEER_SITE_ID and ASSET_PEER_TYPE and sets ASSET_PEER_ID variable. If ASSET_PEER_ID is already set then the object fails with error - “process already has a peer asset “


o None.

• Input Variables

o ASSET_PEER_TYPE: Peer Asset type.

o ASSET_TYPE: Asset type. If ASSET_PEER_TYPE is empty.

o ASSET_PEER_SITE_ID: Peer Asset Site Id.


o ASSET_PEER_ID: Asset Id.

o ASSET_PEER_TYPE: Peer Asset type.

7.3.12 Get Asset Metadata

Gets the asset metadata from MAM. See sample 8.4.


o None.

• Input Variables

o ASSET_TYPE: Asset type. ASSET_ID: Asset Id.


o UNM_IN: String. Serialized metadata of the asset from MAM.

7.3.13 Import File

Imports a file to the MAM.


o Storage: Mandatory. estination storage or service for the import.

• Input Variables

o FILE_PATH: Path to the file to be imported. ASSET_TYPE: Asset type. ASSET_ID: Asset Id.


o XFER_IDSTR: Import job id returned by MAM.

7.3.14 Move Media Essence

Moves media between asset and the peer asset.


o Direction: picklist

Technical Reference


§ "From ASSET_ID to ASSET_PEER_ID" ASSET_ID,

§ "From ASSET_PEER_ID to ASSET_ID" ASSET_PEER_ID

• Input Variables

o ASSET_TYPE: Asset type for both main asset and peer asset.


o ASSET_PEER_ID: Peer Asset Id.

o ASSET_PEER_SITE_ID: Peer Asset Site Id. Used if Peer Asset Id is empty.


o None.

7.3.15 Request Conform

Conform request to MAM.


o Destination: Mandatory. Destination name.

o Destination Type: Mandatory. eg. playout-server.

• Input Variables

o ASSET_PACKAGE_ID: Asset Package Id.

o XFER_DEST_ASSET_TYPE: Currently only AssetType.ITEM is supported.

o XFER_DEST_ASSET_ID: Asset Id to which the conform should happen. If empty the conform creates an asset.


o XFER_IDSTR: Xfer Job Id returned by the conform request.

7.3.16 Request Transcode


o Profile: Transcode profile. If empty the value is fetched from XFER_PROFILE.

• Input Variables

o ASSET_TYPE: Asset type.


o XFER_PROFILE: Uses this “Profile” input parameter is empty.

o XFER_FILENAME: Destination filename.

o XFER_PRIORITY: 1-10000


o XFER_IDSTR: Xfer Job Id returned by the transcode request.

Technical Reference


7.3.17 Request Transfer

Requests a transfer of media file owned by asset. See sample 8.6. While this operation typically concerns the primary media file, MAM system transfer destinations can be configured to process alternate files such as the proxy.


o Destination: The destination for the transfer.

o Destination Type: The destination type for the transfer.

o Language: Optional. Language qualifier; typically, only used with subtitle transfers.

o At least one of Destination or Destination Type must be specified.

• Input Variables



o XFER_IDSTR: Xfer Job Id returned by the transfer request.

7.3.18 Retire Asset

Retire Asset in the MAM (by creating a new asset and moving media essence to it).


o None.

• Input Variables



o None.

7.3.19 Set Asset Metadata

Sets asset metadata. See sample 8.4.


o Source: Javascript to set value for hash UNM_OUT.

o Sample:

§ UNM_OUT = UNM_IN

• Or

§ UNM_OUT = {'mediaId': s.ASSET_SITE_ID}

• Or

§ UNM_OUT[‘mediaId’] = s.ASSET_SITE_ID

• Input Variables



Technical Reference


o None.

7.3.20 Update Asset Acl

Updates the Acl for an asset using acld.


o Status: Acl Status.

• Input Variables



o None. Sends a MQ Msg to updateACL queue.

7.3.21 Update Asset

Update Asset from process instance attribute.


o Attribute 1: Mandatory. Picklist containing attribute to update in asset.

o Attribute 2: Optional. same as above.



• Input Variables



o None.

7.3.22 Update Process Instance From Asset

Update Process Instance variables by fetching the details of the asset from MAM.


o AssetType: Mandatory. Picklist containing all supported Item Types.

o Attribute 1: Mandatory. Picklist containing attribute to update in the process instance.




• Input Variables



o Sets the selected task Attributes with values from asset.

Technical Reference


7.4 Mayam File Operations This group constitutes shapes that does external file related activities. These requires the optional Mayam module "fileop" to be setup, configured and running. These operations do not communicate with any MAM system.

7.4.1 Get File Info

Gets the file information for a file.


o None.

• Input Variables

o FILE_PATH: Path.

o OP_HOSTNAME: Hostname. If empty the hostname is fetched from activiti-delegates.properties file.

o ASSET_TYPE: has to be set to FILE.


o File Info eg. FILE_EXTENSION, FILE_SIZE etc.

7.4.2 Get Side Car Info

This is a site specific palette. Gets sidecar info.


o Attribute: attribute (Optional)

o Any Attribute that is of string type can be chosen. The file information is stored in this attribute in the task given by TASK_ID.

• Input Variables

o FILE_PATH: Path.



o UNM_IN: String. Serialized metadata of the unmanaged metadata. Any attribute returned by the side car converter.

7.4.3 Link File

Hard-link a non-MAM managed file.


o Destination Path: Mandatory. Path to the destination file to be hardlinked.

o Lower case ext: Checkbox. To force the file extension to lowercase.

• Input Variables

Technical Reference


o FILE_PATH: Mandatory. Path.

o FILE_NAME: Optional. Name of the destination file.



o None. This action will link from FILE_PATH (full path to file) to destination/FILE_NAME if FILE_NAME is set. If FILE_NAME is not set, will use the same filename as used in FILE_PATH

7.4.4 Move File

Move a non-MAM managed file.


o Destination Path: Mandatory. Path to the destination.

• Input Variables

o FILE_PATH: Path.




o None.

7.4.5 Remove File

Remove a non-MAM managed file.


o None.

• Input Variables

o FILE_PATH: Path.




o None.

7.4.6 Touch file if exists

Touch a non-MAM managed file. This is used to trigger a file changed event on a monitored directory/file.


o None.

• Input Variables

Technical Reference


o FILE_PATH: Path.




o None.

7.5 Mayam Task

This group constitutes shapes that are used to manage tasks in the system. Actions broadly cover create, fetch and updates.

7.5.1 Add To CommentLog

Add a comment to the task comment log. Appends the new comments to the existing task comments log. See sample 8.5.


o comment: Mandatory. Comment to add. To include an attribute variable in the message use {attrname}. For example, "Job is {XFER_IDSTR}"

• Input Variables

o TASK_ID: Id of the task to which the comment needs to be added.


o None.

7.5.2 Close task

Closes task in the tasklist. Choose a final task state from the list of options.


o Task State: Mandatory. Picklist contain all end states defined for the tasklist.

• Input Variables

o TASK_ID: Task Id.


o None.

7.5.3 Create task

Creates task in the tasklist. See sample 8.1.


Technical Reference


o Task State: The state of the task to be created. Picklist with all available task states.

o Tasklist Id: Tasklist Id where the task needs to be created.

• Input Variables

o All attributes from that are set from the process variables.


o TASK_ID: Id of the created task.

7.5.4 Find Task for Asset

Find task for an asset, using ASSET_TYPE and (ASSET_ID or ASSET_SITE_ID) variables. Sets TASK_ID and TASK_STATE.


o Task List: Mandatory. Tasklist Id.

• Input Variables

o ASSET_TYPE: Mandatory. Type of the asset

o ASSET_ID: Optional. The Id of the asset. If empty ASSET_SITE_ID is used for the search.

o ASSET_SITE_ID: Optional. The site id of the asset. This is used of ASSET_ID is empty.


o TASK_ID: Task Id. TASK_STATE: Task State.

7.5.5 Find Task for Peer Asset

Find task for a peer asset, using ASSET_TYPE and (ASSET_PEER_ID or ASSET_PEER_SITE_ID) variables. Sets TASK_ID and TASK_STATE.



• Input Variables

o ASSET_TYPE: Mandatory. Type of the asset

o ASSET_PEER_ID: Optional. The Id of the peer asset. If empty ASSET_PEER_SITE_ID is used for the search.

o ASSET_PEER_SITE_ID: Optional. The site id of the peer asset. This is used of ASSET_PEER_ID is empty.


o TASK_ID: Task Id. TASK_STATE: Task State.

7.5.6 Find Task

Find active task by Attribute(s) for a given Tasklist Id and sets TASK_ID and TASK_STATE.


Technical Reference



§ Attribute 1: Mandatory. Picklist containing attributes to use in search.

§ Attribute 2: Optional. same as above.



• Input Variables

o Any attribute variable given by the attributes selected as input parameters.


o TASK_ID: Task Id.

o TASK_STATE: Task State.

7.5.7 Get Full Task

Get the full task, using TASK_ID. Overwrites local process variables with the values from the task attributes.


o None.

• Input Variables

o TASK_ID: Task Id.


o Sets all process variables with values from task attributes.

7.5.8 Set Task State

Set task state in the tasklist from state provided as argument or, if no argument is set, from TASK_STATE. See sample 8.5.


o State: Optional. Picklist containing all relevant task states. If this parameter is not set then the value to be set is picked from the process variable TASK_STATE.

• Input Variables

o TASK_STATE: Optional. Task state.

o TASK_ID: Task Id.


o TASK_STATE.

7.5.9 Update ProcessInstance from Task

Updates Process Instance variables, based on process task (requires TASK_ID). See sample 8.8.

Technical Reference



o Attribute 1: Mandatory. Picklist containing attributes.




• Input Variables

o TASK_ID: Task Id.


o Any attribute selected as input parameter.

7.5.10 Update QC status

Updates QC status for the task.


o QC Status: Mandatory. Picklist with the following values - QC fail, QC pass, Manually passed, QC status not yet known.

• Input Variables

o TASK_ID: Task Id.


o QC_STATUS: set to value from the input parameter QC Status.

7.5.11 Update Task

Updates the task in the tasklist based on values in the process variables. See sample 8.6.


o Attribute 1: Mandatory. Picklist containing attributes.




• Input Variables

o TASK_ID: Task Id.


o None.

7.5.12 Update TX status

Updates TX status for the task.


o TX Status: Mandatory. Picklist with the following values - COMPLETE, NEVER, NOT_READY, READY, TBD.

Technical Reference


• Input Variables

o TASK_ID: task id of the task for which the tx status needs to be updated.


o TX_STATUS: set to the value from the input parameter TX Status.

Technical Reference


8 System Architecture This chapter describes the different major components constituting the workflow engine environment and how they interact. Full knowledge about the inner workings of the MAM and workflow environment are not required for basic workflow modelling, so reader can skip this chapter and return here on an as needed basis.

Figure. System overview diagram.

8.1 Activiti BPM The Activiti BPM platform provides two major services:

• The Activiti Explorer GUI

• The Activiti REST API service

Both services run the Activiti BPM engine - either for interactive process execution in the Explorer GUI, or for interaction with other systems via the REST service.

8.1.1 Activiti Explorer GUI

The Activiti Explorer GUI service brings management console functions for process deployment, monitoring and management. In addition, there are functions user management, tasks and messaging that are not used in the Mayam Tasks environment.

Technical Reference


Figure. The Activiti Explorer GUI.

The key functions in this context are the capabilities to deploy and version manage BPM process diagrams authored with Activiti Designer.

8.1.2 Activiti REST Service

The REST service provides functionality to spawn new process instances and pass messages to them. Mayam Tasks forwards MAM and Mayam task event to the REST services via dedicated adapter daemon (bpms-daemon, described below).

The API is documented at http://www.activiti.org/userguide/#_rest_api

8.1.3 Mayam Delegates

Activities performing actions on MAM assets and Mayam tasks are provided as a set of custom delegates. These delegates are used with the custom shapes available through the plugin to Activiti Designer. Example actions: create task (create a Mayam task), request transcode (request transcoding of a media asset by passing the request to the MAM), notify (send an email using formatting and data in Mayam Tasks) and update BMS (send an update message to the broadcast management system).

The delegates are built on top of the Mayam Java SDK for access to task and MAM functions.

8.2 Mayam Tasks Mayam Tasks is the name of a task management and API platform that provides the following services:

Technical Reference


• High function job/tasklist for use inside MAM systems

• Admin GUI for configuration of tasklists, fields and forms

• Framework for building site-plugins to the tasklist. Functions include custom form validation and coded custom actions

• REST API plus a Java SDK on top

• MAM system abstraction layer. The specifics of the underlying MAM APIs are hidden behind a generic high-level interface suitable for tasklist and BPM process use. Operations that are common across MAMs (create asset, request transfer, ...) are performed in a way that is portable between MAM systems

• Notification engine - mostly used for email notifications

• BPM platform interface - format asset, media and task events to the BPM platform

• Framework for implementing custom event responses and periodic actions and micro-services

• Framework for implementing a BMS (broadcast management system) adapter as a service talking a BXF-like protocol internally

• Framework for implementing BMS interface logic (create/update placeholders and schedules, return asset information, ...) based on BXF-like messages.

An overview of the tasklist functions in Mayam Tasks is available at:

http://<your-server>:8084/tasksdoc/tasks_overview.pdf

8.2.1 Tasks-Ws REST API

The Tasks-Ws API provides access to a large set of MAM asset and task management functions via REST. In addition, functions for handling tasklist configurations, users and reports are also available.

An overview of the REST API in Mayam Tasks is available at:

http://<your-server>:8084/tasks-ws

8.2.2 Tasks-Ws Java SDK

The Tasks-Ws Java SDK extends the REST API with high level programming constructs, including classes defining complex data such as segmentation and access control lists. When a BPM process invokes a Mayam delegate to perform a task or media asset action, this Java SDK is used to perform the underlying function (by calling the REST API). In addition, the Java SDK also includes functionality to subscribe to events (JMS by talking to a message broker such as ActiveMQ).

An overview of the Java SDK in Mayam Tasks is available at:

http://<your-server>:8084/tasks-ws

Technical Reference


8.2.3 Mam-Adapter

The Mam-Adapter receives events in a MAM specific format, formats the data as Mayam Tasks AttributeMap format messages and forwards the events to relevant topics such as mayam.asset.create or mayam.job.update.

Note that the name Mam-Adapter is symbolic. The name of the mam-adapter depends on the MAM system in the particular implementation. This emphasizes the key point that the BPM process author and SDK user don’t need to work with MAM specific API calls and data formats.

8.2.4 Bpms-Event-Daemon

This bpms-event-daemon propagates Mayam events to the BPM platform. In the case of Activiti, this means consuming JMS events from a queue and using the Activiti REST API to identify relevant process instances and/or spawn new process instances. For example: A user creates a new placeholder in the MAM, which in turn emits an “asset created” event. This event is received by the mam-adapter (see above) that converts it into the Mayam format and forwards it. The bpms-event-daemon receives the Mayam format event, searches Activiti for process starting with a message event of type “asset create”. A new process instance is spawned for each matching process, passing asset details including the asset id.

8.3 ActiveMQ Message Queue All message passing is done using a message broker capable of persisting queued messages - Apache ActiveMQ. A simplified explanation reads: messages are sent to either named queues (intended for a single type of reader) or to topics where multiple readers can subscribe to the same message. In addition, message routing functions (see Camel below) are available to read from topics and forward messages to queues.

More information about ActiveMQ can be found here: http://activemq.apache.org/

Note: while this system diagram states ActiveMQ, other JMS and message routing capable message queues can be used as well through a small porting effort.

8.3.1 Message Routing using Camel

The Camel message router can perform a range of message routing and transformation functions. Here we focus on the ability to subscribe to a topic and forward messages to a number of queues within the same message transaction (no risk of losing messages).

Several Camel message routing rules are used to propagate events to relevant readers.

For example: A user creates a new placeholder in the MAM, which in turn emits an “asset created” event. This event is sent to a topic - mam.asset.create. A Camel rule is defined to forward all MAM events to a queue dedicated for the Mayam mam-adapter. The mam-adapter converts it into a Mayam format sends it to the topic mayam.asset.create.

Technical Reference


Another Camel rule is defined to listen on mayam.asset.create and forward the messages to the queue mayam.bpms.events. The bpms-event-daemon listens to this queue and interacts with the BPM system.

So, what is the point with all these levels abstraction? The main benefits are:

• Maximum amount of functions that work with a common data format (as opposed to having different implementations for different MAMs)

• Flexibility - adding another subscriber to Mayam or MAM level messaging is done without changes to application logic

• Persistence - the use of dedicated per service queues means that messages are kept until the reader is ready and that the different services can come and go independently without data loss.

8.4 MAM System The MAM system in the diagram refers to the Media Asset Management (MAM) system being driven by the workflow engine.

8.4.1 MAM System API

MAM systems supported by Mayam Tasks have a Web Services or REST API, each using a distinct set of functions and data formats. Mayam Tasks interacts with this API via an abstraction layer internally known as “Mambrella”.

8.4.2 MAM System Events

Information about asset and media processing events such as file transfers is emitted by the MAM to what is typically a set of topics in the message broker. The format of these events is specific to the MAM.

8.5 Active Directory / LDAP Most production implementations use a directory accessible via LDAP (typically Active Directory) to store information about users, groups and organisations. While tasklist and task security is typically slaved to the MAM system security, the Mayam environment also interacts directly with the LDAP directory to retrieve additional user information such as email addresses for notifications, organisation hierarchy details for advanced workflows etc.

8.6 Other Systems The system diagram is a deliberate simplification aiming to provide a view of the interaction between the MAM, Mayam and the BPM platform. In a typical implementation, the Mayam tasks environment is typically connected to a number of additional systems such as an email server, a broadcast management system (BMS) plus other site specific business systems.

Technical Reference


Likewise, the MAM is normally connected to a large number of media systems such as editing platforms, transcoders, storage services etc.

Technical Reference


9 Data Constructs for Managing Tasks and Assets First, Activiti variables are used to store and manipulate processing data, inside a particular process as well as between processes. When a BPM process is started, a number of variables are passed to the process such as the MAM asset and/or task the process is related to.

Using standard Activiti functions, data in variables can be manipulated and new variables can be created. Mayam data is passed as complex variables / objects called AttributeMaps. These are described in this Section.

The primary purpose of the Mayam BPMN shapes is to provide unified high level access to workflow data including tasks MAM assets. While the shapes can be used to manage workflow tasks and MAM assets with a minimum of operations, understanding of the high level data constructs is needed to utilize advanced functions.

There are two primary high level entities:

• Task

• Asset

Depending on type type of entity being managed, different variables are used. For example, a task id is not the same as an asset id. In addition, it is quite common that a single so called AttributeMap is used to represent a MAM asset plus a task referencing the asset.

9.1 Top Level Entities and Operations Mayam Tasks chiefly manages Mayam tasks (referred to as Task entities), MAM assets, and BPM process instances and this is also reflected in our interfaces.

9.1.1 Task

The workflow tasks are understandably the main focus, given the name of our product. A task is a unit of work to be performed by human and/or machine. Unique numeric identifier and state are the two required attributes, but the full set is available for use by tasks. Simply put, the data shown when clicking on a row in the Mayam Tasks GUI is represented by the Task entity. In addition, a Task entity refers to zero or more Tasks and Assets via key ID attributes.

The Mayam shapes provides Task management functions ranging from basic CRUD functions to advanced search and filter lookup and sub-field level data manipulation (like adding a comment to a comment log). A number of additional operations like notifications can also be performed.

It is possible to build BPMN processes listen to task events, for example a user approving or rejecting a request. It is also possible to spawn new processes based on for example task create events.

9.1.2 Asset

Technical Reference


The term Asset refers to an Asset managed by Media Asset Management (MAM) system. Using a type qualifier, most MAM entities such as Series, Programmes, Versions/Items, Packages and Folders can be represented using an Asset entity. In addition, files not managed by a MAM can also be described. To assure uniqueness, both asset type and asset identifier is required.

A key property of the Asset and Task processing is that Assets can be connected to tasks, causing select data to be synchronized between the two. For example, if a Task title attribute is mapped to the corresponding MAM field, bi-directional data synchronization will occur. The effect of this mapping scheme is that the BPMN designer can focus on the high level data management and leave underlying data synchronization between Tasks and Assets to the underlying system.

Beyond Asset CRUD operations, the Mayam shapes also exposes a number of MAM media functions such as media file transfers, transcoding, etc.

9.1.3 Static Constructs

A driving design principle of Mayam Tasks is to reduce run-time errors by strict data typing and a predefined set of variables (referred to as Attributes below). Another key principle is that differences between MAM systems should be kept to a minimum. Both these principles are supported by representing all top level entities using a fixed set of types attributes.

9.1.4 Attribute

In order to robustly pass both technical data and metadata from one system to another, while also allow for meaningful presentation within our web application, we have compiled a list of mappable attributes. Each attribute has a defined purpose (as annotated with @Purpose), a value class, and a set of constraints.

The subjects of create, read, and update operations are in most cases represented as maps from attribute to value class associated with the respective attribute. While this is not easily enforced at compile time, the AttributeMap class comes with an AttributeValidator companion which does this checking at runtime well before any network traffic is involved..

9.1.5 Value Data Types

For many of our attributes, a set of acceptable values have been collected. In the BPMN shapes, these are listed in enums. Only a subset of each is expected to be used per installation, but the values themselves are documented and generic logic may apply - display rendering or otherwise.

9.1.6 Unmanaged Metadata (New in 2.4)

From version 2.4, there is a special Unmanaged Metadata attribute. This attribute provides access to the underlying MAM field metadata in a key/value map.

Technical Reference


9.2 Configurable Entities Building upon the foundation of the static constructs, Mayam Tasks is highly configurable. The dynamic parts are mainly concerned with the presentation of data within our web application, but a number of the configuration options also have an effect visible for third party developers.

9.2.1 Task List Configuration

Each customer installation comes with a factory default that is maintained by Mayam using a Java DSL. The Task Administration web application can then be used by customer and integrators to make adjustments.

The full configuration is available through the SDK, with write support exposed through the REST interface; the latter should really only be used to transfer configuration between systems (such as staging to production).

9.2.2 Fields

As stated above, attributes have statically been assigned purpose, type, and constraints. Further constraints, along with rendering hints, can be configured using fields. One common example is the association of a CVL which is either entered directly into the configuration, or as a reference to a MAM dictionary. It should be noted that these constraints do not have any effect on operations performed using the SDK or via REST directly.

More than one field may be associated with a particular attribute. This is typically done to allow mandatory access or use alternative labels in some situations but not others.

External use of fields has historically been limited to label and type use within reporting plugins.

9.2.3 Attribute Mapping

Attributes can be mapped to metadata fields or, for some MAMs, directly to database columns. This causes changes made to assets to be propagated through message queues and daemons to any tasks associated with said asset. Changes to mapped attributes in tasks that are associated with assets will conversely cause those changes to be propagated to the MAM.

For a mapping to be valid, constraints must align. Notably, data types need to be compatible.

9.2.4 Further Reading

While the configuration of task lists and of mappings between task and MAM data can seem straightforward at first, the complexity in real world implementation typically lies in the scope and extent of the configuration. It is not uncommon with 10+ task lists, 100+ fields and 50+ forms plus mappings to MAM data at 4 levels plus the shared use MAM dictionaries for configurable drop downs. To be fully effective working with these configurable entities, a thorough understanding is of the Tasks data model and the Field /

Technical Reference


Attribute constructs is required. Beyond reading the Mayam Tasks Technical Reference document, a good idea is to explore the Task Administration application for some hands-on experience working with Fields and Attributes.

Technical Reference


10 Javascript in processes This chapter describes how to use javascript in the mayam javascript shape.

10.1 Introduction Javascript can be used in the different javascript shapes in BPMN diagrams as well as in other site specific code outside of the scope of this document. A number of Mayam specific object and functions are available.

10.2 The attribute map The attribute map used in the process is available with the name “s” (for subject) and any attribute can be accessed using “s.ATTRNAME”.

For example, the following gets and sets the title. var title = s.ASSET_TITLE

s.ASSET_TITLE = 'my new title'

Attribute which are of a number, boolean or date type can be used as numbers, booleans and dates in javascript s.EPISODE_NUMBER = 12

s.QC_REQUIRED = true

s.LICENSE_START = new Date()

if (s.QC_REQUIRED) {...

Attributes that are limited by a java enum, can be seen as a string with a fixed set of values.

For example, QC_STATUS can only be set to “FAIL”, “PASS”, “TBD” or “PASS_MANUAL”. Any other value will cause an error.

The following functions are available:

createAttributeMap:

Creates a new empty attribute map var p = createAttributeMap()

p.ASSET_TITLE = "this is a new map"

serialize:

Serializes a attribute map to a string var str = serialize(s)

Technical Reference


deserialize:

Deserializes a string to a map var p = deserialize(str)

clear:

Clears the attribute map. This is a way to remove all attribute variables from the process. s.clear()

copy returns a new attribute map that is a copy of the given one var p = s.copy()

importFrom Import and overwrites values in one attribute map with values from another s.importFrom(p) // Values from p go into s

10.3 The UNM_IN object A hash map including all metadata of an asset if the “get asset metadata” shape has been used previous in the process. var title = UNM_IN['asset.title'];

10.4 The logger object A Java logger that can be used for debug purposes. Output from this goes to activiti-rest.log or actitivi-explorer.log. logger.info("title is {}", s.ASSET_TITLE)

Please see org.slf4j.Logger for more information

10.5 The util object

A utility object to get and set process variables that are not attributes.

util.setVariable("myVariable", "value")

var myvar = util.getVariable("myVariable")

Technical Reference


10.6 The execution object The Activiti Delegate execution object. Please see the Activiti documentation and org.activiti.engine.delegate.DelegateExecution for more information.

While this can be used for getting and setting variables in the process, it does not consider of very large values (such as long strings). Use of the util object is therefore recommended. execution.setVariable("myVariable", "value")

var myvar = execution.getVariable("myVariable")

execution.removeVariable("myVariable")

Technical Reference


11 Reference Documentation This chapter contains a consolidated list of reference documentation pointers.

11.1 Mayam

The following Mayam Tasks documents are available.

Title Description URL

Mayam Tasks Overview An introduction to Mayam Tasks http://your-hostname-here:8084/ tasksdoc/tasks_overview.pdf

Mayam Tasks Technical Reference

Technical reference information on architecture, installation and configuration

http://your-hostname-here:8084/ tasksdoc/tasks_technical_referen ce.pdf

Mayam Tasks Programming Guide

A guide introducing the Mayam APIs and the Java SDK

http://your-hostname-here:8084/ tasksdoc/tasks_programming_gui de.pdf

BPM Process Guide This document http://your-hostname-here:8084/ tasksdoc/bpm_process_guide.pdf

TaskAdmin Guide How to configure tasklists and task actions

http://your-hostname-here:8084/ tasksdoc/taskadmin_guide.pdf

Table. List of Mayam Tasks documents.

11.2 Activiti Please visit http://activiti.org/ for access to product documentation, a technical Activiti tutorial and a pointer to the book “Activiti in Action”.

11.3 BPMN BPMN (V2) is a widely used standard for process notation. Beyond the information supplied with Activiti, the following references provide more generic information about BPMN:

• http://www.bpmn.org/ - An introduction to BPMN is available under “Quick Guide”

• http://www.omg.org/bpmn/index.htm - standards documentation entry point

Mayam Tasks BPM Process Guide 3

Documents

Transcript of Mayam Tasks BPM Process Guide 3