Notification E-mail Customization Sample

WSO2 Governance Registry generates notifications for events triggered by various operations performed on resources and collections stored in the repository. Notifications can be consumed in a variety of formats including E-mail. Read more about Notifications and also the API-Level Access provided for subscription operations. The contents of notification e-mails can be customized by using an Axis2 Handler. WSO2 Governance Registry contains an Apache Axis2 based runtime as a part of the WSO2 Carbon Framework. We will be reusing the code of the Handler Sample in this example. This sample requires Apache Maven. See Installing Apache Maven for Governance Registry on Windows or Installing Apache Maven for Governance Registry on Linux.

Instructions

1. Navigate to GREG_HOME/samples/handler/src to find the source code of the Handler Sample.

2. Add a new Java Class named EmailTransformHandler at 

GREG_HOME/samples/handler/src/src/main/java/org/wso2/carbon/registry/samples/notifications/EmailTransformHandler.java with the following source:

package org.wso2.carbon.registry.samples.notifications;
 
import org.apache.axiom.om.OMElement;
import org.apache.axiom.om.xpath.AXIOMXPath;
import org.apache.axiom.soap.SOAPEnvelope;
import org.apache.axis2.AxisFault;
import org.apache.axis2.context.MessageContext;
import org.apache.axis2.engine.Handler;
import org.apache.axis2.handlers.AbstractHandler;
import org.jaxen.JaxenException;
 
import java.util.ArrayList;
 
public class EmailTransformHandler extends AbstractHandler implements Handler {
    private String name;
 
    public String getName() {
        return name;
    }
 
    public InvocationResponse invoke(MessageContext msgContext) throws AxisFault {
        if (msgContext.getTo() != null && msgContext.getTo().getAddress().startsWith("mailto:")) {
            try {
                SOAPEnvelope envelope = msgContext.getEnvelope();
                AXIOMXPath xPath = new AXIOMXPath("//ns:text");
                xPath.addNamespace("ns", "http://ws.apache.org/commons/ns/payload");
                OMElement element = (OMElement) ((ArrayList) xPath.evaluate(envelope)).get(0);
                element.setText(element.getText().replace("--", "This message was intercepted by " +
                        "EmailTransformHandler\n--"));
            } catch (JaxenException e) {
                e.printStackTrace();
            }
        }
        return InvocationResponse.CONTINUE;
    }
 
    public void revoke(MessageContext msgContext) {
    }
 
    public void setName(String name) {
        this.name = name;
    }
}

3. Compile the source code by running the following command inside GREG_HOME/samples/handler/src:

mvn clean install

A successful run of Apache Maven will generate a report similar to the following:

4. Copy the GREG_HOME/samples/handler/src/target/org.wso2.carbon.registry.samples.handler-4.5.0.jar into GREG_HOME/repository/components/dropins.

5. Add the EmailTransformHandler to the MessageOut phase in the OutFlow in GREG_HOME/repository/conf/axis2/axis2.xml:

<phaseOrder type="OutFlow">
    <phase name="UEPPhase" />
    <phase name="RMPhase"/>
    <phase name="OpPhase"/>
    <phase name="OperationOutPhase"/>
    <phase name="PolicyDetermination"/>
    <!-- The E-mail Transform Handler is added to the MessageOut phase -->
    <phase name="MessageOut">
        <handler name="EmailTransformHandler"
                 class="org.wso2.carbon.registry.samples.notifications.EmailTransformHandler"/>
    </phase>
    <phase name="Security"/>
    <phase name="MsgOutObservation"/>
</phaseOrder>

<handler name="EmailTransformHandler"
         class="org.wso2.carbon.registry.samples.notifications.EmailTransformHandler"/>

6. Configure Governance Registry to send E-mails in GREG_HOME/repository/conf/axis2/axis2.xml.

7. Start the server and observe the command prompt. See Starting Governance Registry Management Console on Windows or Starting Governance Registry Management Console on Linux.

8. Navigate to the / collection of the Resource Browser and add an E-mail subscription for Update events.

Click the "Subscribe" button to create the subscription. Read about Managing the Resources and Managing Breadcrumb to learn how to navigate to the / collection. And read more about Managing Subscriptions.

9. Click on the E-mail Address verification link that you will receive via E-mail.

10. Make some update to the Root collection like adding a new property. Read Managing Properties to learn how to add a new property.

11. You should now receive a Notification E-mail which contains the following text:

This message was intercepted by EmailTransformHandler

See also Notifications and Managing Subscriptions.

An Axis2 Handler must implement the org.apache.axis2.engine.Handler interface and can optionally extend the org.apache.axis2.handlers.AbstractHandler class. Read more about Axis2 Handlers to get a better understanding of their uses.