Workflow in Action - Kaleo email notifications

In one of my previous blogs I wrote about how to setup email settings and configure Web Content notifications triggered by workflow.

Liferay portal 6.1 relays to external workflow engine Kaleo which also has ability to send notifications. As our intention is to centralize workflow related code in  Kaleo and users workflow definitions, eventually we will remove legacy workflow notifications (such those in web content managment). So to prepare you for things that are comming check this blog.

Kaleo

To constrain your business process with some rules, you need:

  1. rules
  2. language to describe those rules to mchine
  3. workflow engine
  4. assets and resources aware of workflow engine
  5. people who want to play by the rules

Kaleo and Liferay give us 1*, 2, 3, 4*. Once you have idea what are yours company rules, you will ask somebody to write definition in an xml like language. Than you will run those rules in portal and apply it to you asset and resources.

1* kaleos default rules are very generic and may be good as starting point. Depending to your company business you will probably need your own rules writen as definition.
4* by default those assets are workflow aware: Blogs Entries, Web Content, Comments, Message Boards Messages, Wiki Pages and Page Revisions (when you do staging). Your and any other assets you want in game must implement workflow interfaces.

What is interesting you will probably want some actions performed to asset to trigger messages to get users attention. You want to notify user there is job to do, he done great job or there is awful escalation that needs immediate intervention. As part of workflow definition you will be able to create some actions eather real scripted actions or notifications. Notifications can be emails, instant messages or private messages. In the rest of blog I will focus on email notifications.

Kaleo email notifications

As kind of action we form notifications as part of process state or tasks. Triggering of notification is done in a three ways:

  • on assignment - when task is assigned to user
  • on entry - when asset enters some state or is ready for an task within state
  • on exit - when asset leaves the state or all job required by the task is done by particular user

At the end we must choose do we need some simple messages in our email or we want to build more specific messages aware of business and workflow context. Kaleo definitions will allow you to write messages as plain text but in most cases that wouldn't be enough. also for advanced users there is possibility to do that in freemarker or velocity.

Write your own notifications

For example I'll existing default single-approver-definition.xml notification defined for review task. New notification will use new email subject and will include some data related to asset that is being workflowed. My new notification related to review task is following:

<notification>
<name>Review Notification</name>
<description>New Submission Is Ready For Review</description>
<template>
   <![CDATA[
      <#assign comments    = taskComments!"">
      <!-- email body -->
      <p>
   Please review the ${entryType} waiting for you in your workflow tasks.
   <#if comments != "" >
     <br />Assignment comment says: <strong>${comments}</strong>
   </#if>
   </p>
       <!-- signature -->
   <p>Sincerely,<br /><strong>Liferay Portal Workflow</strong></p>
   ]]>
</template>
<template-language>freemarker</template-language>
<notification-type>email</notification-type>
<execution-type>onAssignment</execution-type>
</notification>

Now, lets go step by step:

node name - it will just define notification identification name

node description - it serves as description, but kaleo will populate an email subject field with its value so be as more creative when you setting this value

node template-language - tells kaleo to use freemarker engine to merge template and data

template - there are two things to note. First it is assignment of variable comment:

<#assign comments    = taskComments!"">

expression taskComments!"" will take value from freemarker context variable taskComments and if it is null en ampty string will be returned. We have to do that because when initaly enters review task, it is done by engine so there won't be available taskComments. In moment when manager assigns task to user he will be prompted to set comment so we will be able to display comment inside email message.

Second thing is use of freemarker context variable entryType. Expression ${entryType} will be evaluated as asset type like Web Content, Comment or Wiki.

This is how received email looks now:

For next time I will display how to make more advanced templates.

Blogs
Are you sure if this is really working? I've tried it with EE-trial and it doesn't work, it is not accepted.
hi Akos,
example was done for 6.1.0 CE and it worked emoticon honestly, I planed some more advanced examples but at the end there is always something more important. Also I had similar problem, developer has to be very careful when uploading new definitions. To be sure your new definition is engaged all pending processes over assets that using previous definition version must be finished. This one made a lot of pain and waste of my time.
Hi Igor,

Most likely my problem was caused by the designer. I tried it again and once it worked.
I guess in your test you had to upload the whole definition as an xml (since no gui-based designer exists in ce). Could you please publish the whole xml here?

Thanks,
Akos
But under which file or folder we can change or write this code for work flow email noticfications?
In workflow definition xml
More details would be appropriate I think.

In Liferay 6.1, they are located under:
$your_liferay_root/tomcat/webapps/kaleo-web/WEB-INF/src/META-INF/definitions

But I suggest you be very careful manipulating these, I tried and created a mess. At least I was on a development platform, but I had to scrap it after my tests and now I think I will use only single-approver-definition.xml until Liferay publishes a more complete documentation about Kaleo.
are you familiar with Liferay workflow definition? I want to assign a task by user email ID, so I can do it like the following, but XXX@XXX.com should be an input on UI page and then pass it to the workflow, how can I use a variable instead of XXX@XXX.com.

<task>
<name>Manager Approval</name>
<assignments>
<user>
<email-address>XXX@XXX.com</email-address>
</user>
</assignments>
<transitions>
<transition>
<name>Reject</name>
<target>update</target>
<default>true</default>
</transition>
</transitions>
</task>
i would do this in the task (an e-mail sender task) itself, there you have access to workflow instance attributes (recipient address).
can you plz why worlflow send email notification on user rejection?
Hi Imran, workflow sends email notifications on user rejection because it is written in definition. If you want different behavior you adopt definition to fit your business process.
I tried to display email notification using kaleo workflow , i am able to perform the same but the notification mail i receive does not have user name.

"Your Submission was rejected by ${userName}, Please Modify and Re-Submit."

i don't know what is the issue but i am unable to show user name in email.
Hi Dharmendra, I haven't tackle Kaleo for a while, but I think ${userName} is not available. In the moment I was writing this post available set of variables is described http://www.liferay.com/web/igor.beslic/blog/-/blogs/workflow-in-action-kaleo-workflow-context-variables?_33_redirect=http%3A%2F%2Fwww.liferay.com%2Fweb%2Figor.beslic%2Fblog%3Fp_p_id%3D33%26p_p_lifecycle%3D0%26p_p_state%3Dnormal%26p_p_mode%3Dview%26p_p_col_id%3Dcolumn-2%26p_p_col_count%3D1. (You can use userId to grab reviewer's name)
hello Friends,
i m trying to create two approval workflow but i m getting following error

Unable to find target node for transition resubmit
Hello,
Please can you tell me how change "Liferay Portal Workflow Notifications” and “no-reply@liferay.com”? i made changes in kaleo-spring.xml but not works. Emails still arrive from no-reply@liferay.com .
Please help!
thank you