Email Customization
Prev Chapter 3. KEW Next

Email Customization

KEW provides default email template for Action List notification messages that are sent. However, it is also possible to customize this either globally or on a Document Type by Document Type basis.

There are two ways to customize Action List emails:

  1. Configure a CustomEmailAttribute

  2. Creating a custom XSLT Stylesheet

To accomplish this, you must write a CustomEmailAttribute and configure it on the appropriate DocumentType.

Configure a CustomEmailAttribute

The CustomEmailAttribute interface provides two methods for adding custom content to both the subject and the body.

public String getCustomEmailSubject();

public String getCustomEmailBody();

Note that each of these values is appended to the end of either the subject or the body of the email. The rest of the email still uses the standard email content.

Also, when implementing one of these components, the document is made available to you as a RouteHeaderDTO and the action request related to the notification is made available as an ActionRequestDTO.

Once you have implemented the CustomEmailAttribute, you need to make it available to the KEW engine (either deployed in a plugin or available on the classpath when running embedded KEW).

Document Type Configuration

Once you make the email attribute component available to KEW, you need to configure it on the Document Type.

First, define the attribute:

<data xmlns="ns:workflow" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="ns:workflow resource:WorkflowData">
    <ruleAttributes xmlns="ns:workflow/RuleAttribute" xsi:schemaLocation="ns:workflow/RuleAttribute resource:RuleAttribute">
        <ruleAttribute>
            <name>MyCustomEmailAttribute</name>
            <className>my.package.MyCustomEmailAttribute</className>
            <label>MyCustomEmailAttribute</label>
            <description>My Custom Email Attribute</description>
            <type>EmailAttribute</type>
        </ruleAttribute>
    </ruleAttributes>
</data>

Next, update the Document Type definition to include the attribute:

<data xmlns="ns:workflow" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="ns:workflow resource:WorkflowData">
    <documentTypes xmlns="ns:workflow/DocumentType" xsi:schemaLocation="ns:workflow/DocumentType resource:DocumentType">
        <documentType>
            <name>MyDocType</name>
            <label>My Document Type</label>
            <postProcessorName>...</postProcessorName>
            <attributes>
                <attribute>
                    <name>MyCustomEmailAttribute</name>
                </attribute>
            </attributes>
            <routePaths>
                ...
            </routePaths>
            <routeNodes>
                ...
            </routeNodes>
        </documentType>
    </documentTypes>
</data>

These should be ingested using the XML Ingester. See Importing Files to KEW for more information on using the XML Ingester.

Create a Custom XSLT Style Sheet

Global Email Customization

A more convenient way to customize email content declaratively is to replace the global email XSLT style sheet in Rice. Do this by ingesting an XSLT style sheet with the name kew.email.style. This style sheet should take input of this format for reminder emails:

<!-- root element sent depends on email content requested by the system -->
<immediateReminder|dailyReminder|weeklyReminder actionListUrl="url to ActionList" preferencesUrl="url to Preferences" 
applicationEmailAddress="configured KEW email address" env="KEW environment string (dev/test/prd)">
  
    <user> <!-- the principal who received the request -->
        <name>...</name>
        <principalName>...</principalName>
        <principalId>...</principalId>
        <firstName>...</firstName>
        <lastName>...</lastName>
        <emailAddress>...</emailAddress>
        ...
    </user>
    <actionItem>
        <!-- one top-level actionItem element sent for each ActionItem; for immediate email reminders, there will only ever be one; for daily and weekly reminders, there may be several -->
           
        <!-- custom subject content produced by the CustomEmailAttribute associated with the DocumentType of this ActionItem, if any -->
        <customSubject>...</customSubject>
 
        <!-- custom body content produced by the CustomEmailAttribute associated with the DocumentType of this ActionItem, if any -->
        <customBody>...</customBody>
    
        <actionItem> <!-- the actual ActionItem -->
            <principalId>...</principalId>
            <groupId>...</groupId>
            <routeHeaderId>...</routeHeaderId>
            <actionRequestId>...</actionRequestId>
            <docTitle>...</docTitle>
            <actionItemId>...</actionItemId>
            <roleName>...</roleName>
            <dateAssigned>...</dateAssigned>
            <actionRequestCd>...</actionRequestCd>
            <docHandlerURL>...</docHandlerURL>
            <recipientTypeCode>...</recipientTypeCode>
            <actionRequestLabel>...</actionRequestLabel>
            <delegationType>...</delegationType>
            <docName>...</docName>
            <docLabel>...</docLabel>
        </actionItem>
        <actionItemPerson> <!-- see "user" element at the top, simliar content -->
        ...
        </actionItemPerson>
        <actionItemPrincipalId>...</actionItemPrincipalId>
        <actionItemPrincipalName>...</actionItemPrincipalName>

        <doc> <!-- the RouteHeader associated with this ActionItem -->
            <routeHeaderId>...</routeHeaderId>
            <docTitle>...</docTitle>
            <docContent>...</docContent>
            <initiatorWorkflowId>...</initiatorWorkflowId>
            <documentTypeId>...</documentTypeId>
            <docRouteStatusLabel>...</docRouteStatusLabel>
            <docRouteStatus>...</docRouteStatus>
            <createDate>...</createDate>
            ...
        </doc>
        <docInitiator>
            <principalName>...</principalName>
            <principalId>...</principalId>
            <entityId>...</entityId>
        </docInitiator>
        <documentType> <!-- DocumentType -->
            <name>...</name>
            <label>...</label>
            <description>...</description>
            <serviceNamespace>...</serviceNamespace>
            <notificationFromAddress>...</notificationFromAddress>
            <docHandlerUrl>...</docHandlerUrl>
            <documentTypeId>...</documentTypeId>
            ...
    </actionItem>

</immediateReminder|dailyReminder|weeklyReminder>

This format is used for feedback emails:

<!-- feedback form -->
<feedback actionListUrl="url to ActionList" preferencesUrl="url to Preferences" applicationEmailAddress="configured KEW email address" env="KEW environment string (dev/test/prd)">
    <networkId>...</networkId>
    <lastName>...</lastName>
    <routeHeaderId>...</routeHeaderId>
    <documentType>...</documentType>
    <userEmail>...</userEmail>
    <phone>...</phone>
    <timeDate>...</timeDate>
    <edenCategory>...</edenCategory>
    <comments>
        ...
    </comments>
    <pageUrl>...</pageUrl>
    <firstName>...</firstName>
    <exception>...</exception>
    <userName>...</userName>
</feedback>

In both cases, the output generated by the style sheet must be like this:

<email>
    <subject>... subject here ...</subject>
    <body>... body here ...</body>
</email>

You must then upload the custom style sheet into the style service using the standard KEW XML ingestion mechanism:

<?xml version="1.0" encoding="UTF-8"?>
<data xmlns="ns:workflow" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="ns:workflow resource:WorkflowData">
<styles xmlns="ns:workflow/Style" xsi:schemaLocation="ns:workflow/Style resource:Style">
    <style name="kew.email.style">
 <!-- A custom global email reminder stylesheet -->
        <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
            <xsl:strip-space elements="*"/>
            <xsl:template match="immediateReminder">               
                ...
            </xsl:template>
            <xsl:template match="dailyReminder">
                ...
            </xsl:template>
            <xsl:template match="weeklyReminder">
                ...
            </xsl:template>
            <xsl:template match="feedback">
                ...
            </xsl:template>
        </xsl:stylesheet>
    </style>
</styles>

The global style sheet should handle all email content requests. You can use the standard include syntax to import an existing style sheet that may implement defaults.

DocumentType-Specific Email Customization

You can also customize immediate reminder email content on a per-DocumentType basis. To do so, define a custom email style sheet name on the DocumentType definition:

...
    <documentType>
        <name>SomeDoc</name>
        <description>a document with customized reminder email</description>
            ...
        <emailStylesheet>somedoc.custom.email.style</emailStylesheet>
            ...
    </documentType>
...

Then, upload a corresponding style sheet with a matching name, as above.

Prev Up Next
Action List Configuration Guide Home Document Link