« Back

Workflow in Action - Kaleo email notifications

Company Blogs February 7, 2012 By Igor Beslic Staff

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.

Threaded Replies Author Date
Great post. Keep those Kaleo tips coming :) Szymon Gołębiewski February 10, 2012 1:14 AM
Please I want to see more advanced templates!... Sébastien Nadeau March 8, 2012 1:06 PM
Can you suggest some examples for Private... Preeti Deshpande April 6, 2012 5:13 AM
Thank you for this example -- would love to see... Jeff Smith April 11, 2012 12:21 PM
Are you sure if this is really working? I've... Ákos Gábriel May 29, 2012 11:45 AM
hi Akos, example was done for 6.1.0 CE and it... Igor Beslic May 30, 2012 2:07 PM
Hi Igor, Most likely my problem was caused by... Ákos Gábriel May 31, 2012 1:50 AM
But under which file or folder we can change or... omer 345621 June 12, 2012 5:38 AM
In workflow definition xml Igor Beslic June 12, 2012 5:40 AM
More details would be appropriate I think. In... Sébastien Nadeau June 12, 2012 5:46 AM
are you familiar with Liferay workflow... kevin wu August 2, 2012 3:03 AM
i would do this in the task (an e-mail sender... Ákos Gábriel August 2, 2012 4:45 AM
can you plz why worlflow send email... Imran Khalil November 22, 2012 9:50 PM
Hi Imran, workflow sends email notifications on... Igor Beslic November 23, 2012 12:52 AM
I tried to display email notification using... Dharmendra Dubey June 20, 2013 4:22 AM
Hi Dharmendra, I haven't tackle Kaleo for a... Igor Beslic June 21, 2013 1:19 AM
hello Friends, i m trying to create two... ranjit reval November 26, 2013 4:23 AM
hello Friends, i m trying to create two... ranjit reval November 26, 2013 4:23 AM
Hi Ranjit, if you want to notify to two... Daniel Martínez Cisneros July 31, 2014 4:05 AM
Hello, Please can you tell me how change... gnp present February 11, 2015 6:27 AM

Great post. Keep those Kaleo tips coming emoticon
Posted on 2/10/12 1:14 AM.
Please I want to see more advanced templates! Especially, I,d like to know what template variables (e.g. ${entryType}) are available in the workflow context. Thanks!
Posted on 3/8/12 1:06 PM in reply to Szymon Gołębiewski.
Can you suggest some examples for Private mesage and IM type notification?
Posted on 4/6/12 5:13 AM.
Thank you for this example -- would love to see more (and more advanced) examples! :-)
Posted on 4/11/12 12:21 PM in reply to Preeti Deshpande.
Are you sure if this is really working? I've tried it with EE-trial and it doesn't work, it is not accepted.
Posted on 5/29/12 11:45 AM.
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.
Posted on 5/30/12 2:07 PM in reply to Ákos Gábriel.
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
Posted on 5/31/12 1:50 AM.
But under which file or folder we can change or write this code for work flow email noticfications?
Posted on 6/12/12 5:38 AM.
In workflow definition xml
Posted on 6/12/12 5:40 AM in reply to omer 345621.
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/definitio­ns

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.
Posted on 6/12/12 5:46 AM in reply to Igor Beslic.
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>
Posted on 8/2/12 3:03 AM.
i would do this in the task (an e-mail sender task) itself, there you have access to workflow instance attributes (recipient address).
Posted on 8/2/12 4:45 AM in reply to kevin wu.
can you plz why worlflow send email notification on user rejection?
Posted on 11/22/12 9:50 PM in reply to Ákos Gábriel.
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.
Posted on 11/23/12 12:52 AM in reply to Imran Khalil.
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.
Posted on 6/20/13 4:22 AM in reply to Igor Beslic.
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-wor­kflow-context-variables?_33_redirect=http%3A%2F%2Fwww.liferay.com%2Fweb%2Figor.b­eslic%2Fblog%3Fp_p_id%3D33%26p_p_lifecycle%3D0%26p_p_state%3Dnormal%26p_p_mode%3­Dview%26p_p_col_id%3Dcolumn-2%26p_p_col_count%3D1. (You can use userId to grab reviewer's name)
Posted on 6/21/13 1:19 AM in reply to Dharmendra Dubey.
hello Friends,
i m trying to create two approval workflow but i m getting following error

Unable to find target node for transition resubmit
Posted on 11/26/13 4:23 AM.
hello Friends,
i m trying to create two approval workflow but i m getting following error

Unable to find target node for transition resubmit
Posted on 11/26/13 4:23 AM.
Hi Ranjit, if you want to notify to two differents users you could do it assigning it to a role or creating two task.
Posted on 7/31/14 4:05 AM in reply to ranjit reval.
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
Posted on 2/11/15 6:27 AM.