Introduction

Vyopta provides alerts via email in either formatted plain text or HTML formats. The use of email as a transport allows alerts to be delivered without complication in most environments but does not easily lend itself to integration with other monitoring systems.

Presented here is the use of an open-source integration framework, OpenESB, to process Vyopta email alerts and forward them to other systems – the example provided will forward alerts to a notional REST based monitoring system, but may be adapted to send to file, database, SOAP or JMS message queues by substituting the final step. The framework requires no additional code to perform these activities.

Disclaimers

Vyopta is providing the information presented herein “as-is” and makes no representations and warranties whatsoever, whether express, implied, or statutory, including, but not limited to any warranty of merchantability or fitness for a particular purpose or any warranty that the contents herein will be error-free with respect to such information or the use of OpenESB. 

In no respect shall Vyopta incur any liability for any damages, including, but not limited to, direct, indirect, special or consequential damages arising out of, resulting from, or in any way connected to the use of the contents herein, whether or not based upon warranty, contract, tort, or otherwise; whether or not injury was sustained by persons or property or otherwise; and whether or not loss was sustained from, or arose out of, the results of, the contents herein, or any services that may be provided by Vyopta.

The contents herein are provided solely for informational and illustration purposes and are not under any circumstances, by implication or otherwise, to be considered as a Vyopta solution, product, or service or any part thereof. 

It should be noted that this document simply describes an approach that may be taken and provides an example. The Vyopta support organisation will not be able to assist you with any questions or issues arising from the information here, or its use.

OpenESB is subject to the license governing its use, and we refer you to OpenESB documentation for that license and use rights. 

Prerequisites

Email Server

The provided example will read Vyopta alert emails via IMAP/IMAPS from a mail server. An account should be provided that only receives the Vyopta alerts in plain text format.

If preferred, POP3/POP3S can be used as the email transport.

Note that STARTTLS is not supported -the transport must be IMAP or POP3, or IMAP/POP3 over TLS. Should TLS be used as the transport then it may be necessary to configure a java truststore and password via the normal Java properties – this may be specified in the JAVA_OPTS environment variable prior to starting any OpenESB process.

OpenESB

The reader should obtain OpenESB from open-esb.net, and consult the documentation found in the getting started section. Once installed and running, the two listed exercises should be completed in order to ensure that the basic concepts are familiar.

The OpenESB project is currently supported by Pymma along with the OpenESB Community – all support should be directed to these support channels. Pymma offers a commercially supported advanced version of OpenESB (OpenESB Enterprise Edition) and training on the platform.

Note that OpenESB requires Java 8.

Vyopta does not provide support for OpenESB – please see “Disclaimers” above.

The Approach

Vyopta can be configured to send alerts via email in a formatted, but not structured text form – an example of the body of such an email would be

Endpoints are down

Status is down for 1 min(s)


Device 1
Status Down for 5 minutes
10.10.10.10
Device 2
Status Down for 5 minutes
10.10.10.11
Device 3
Status Down for 5 minutes
10.10.10.12
Device 4
Status Down for 5 minutes
10.10.10.13                                                            
Device 5
Status Down for 5 minutes
10.10.10.14
Device 6
Status Down for 5 minutes
10.10.10.15

As can be seen, this is a simple format, consisting of a header section (title and message) followed by a list of devices with per-device information. 

In order to be able to process this, it will be converted to structured text (in this case, XML) –

<?xml version="1.0" encoding="UTF-8"?>
<AlertMsg xmlns="http://xml.netbeans.org/schema/AlertMessage" xsi:schemaLocation="http://xml.netbeans.org/schema/AlertMessage /Users/j.random.user/NetBeansProjects/VyoptaAlertIntegration/src/AlertMail.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <Header>
          <Title>Endpoints are down</Title>
          <Message>Status is down for 1 min(s)</Message>
     </Header>
     <Device>
          <Name>Device 1</Name>
          <Status>Status Down for 5 minutes</Status>
          <Host>10.10.10.10</Host>
     </Device>
     <Device>
          <Name>Device 2</Name>
          <Status>Status Down for 5 minutes</Status>
          <Host>10.10.10.11</Host>
     </Device>
     <Device>
          <Name>Device 3</Name>
          <Status>Status Down for 5 minutes</Status>
          <Host>10.10.10.12</Host>
     </Device>
     <Device>
          <Name>Device 4</Name>
          <Status>Status Down for 5 minutes</Status>
          <Host>10.10.10.13</Host>
     </Device>
     <Device>
          <Name>Device 5</Name>
          <Status>Status Down for 5 minutes</Status>
          <Host>10.10.10.14</Host>
     </Device>
     <Device>
          <Name>Device 6</Name>
          <Status>Status Down for 5 minutes</Status>
          <Host>10.10.10.15</Host>
     </Device>
</AlertMsg>

Using this message, we can iterate over the <Device>...</Device> items and send alerts on a per-device basis. 

OpenESB Configuration 

The Server

OpenESB should have the following components loaded and started before proceeding:

• The BPEL Service Engine (bpelse-installer.jar)
• The Email Binding Component (emailbc-installer.jar)
• The REST Binding Component (restbc-installer.jar) 

Additionally, the following shared libraries are required to be loaded into the OpenESB server instance :

• The WSDL Extensions Shared Library (wsdlextsl-installer.jar)
• The Encoder Shared Library (encodersl.jar)

These shared libraries are dependencies of the above binding components. 

Some of these items will have been installed in order to complete the pre-requisite exercises – additional components and libraries that are installed will not interfere with those required for this activity.

Please also note the prior information regarding the use of TLS as a transport and the possible need to configure a custom trust store.

OpenESB Studio

Example Projects

There are two projects provided that should be opened in OpenESB Studio:

VyoptaAlertIntegration – this is, in OpenESB parlance, a BPEL project. It contains the definitions and BPEL process that perform the operations. A BPEL process is not deployable.

VyoptaAlertIntegrationCA – this is the deployable part of the example – the Composite Application. A Composite Application may contain one or more processes.

Example Files

VyoptaAlertIntegration

OpenESB transfers all information internally as XML files – it is therefore necessary to specify an XML schema to describe all content, whether or not this content is XML – for instance, the content of a JSON payload must be specified as a XML schema – this will be seen in the following example

Schemas

The following schemas are defined for the example project, in order of first use:

• AlertMail.xsd – this file contains the description of the email body containing the alert message, and also contains information that is used by the encoder library in order to parse the input into XML. In this instance, the parsing is simplified by being line-oriented with the required SMTP line-end of CR-LF being used as a delimiter. Further information on the custom file encoder used can be found here.

The design view of this schema is

• RESTMsg.xsd - This is the schema for the REST message to be sent on to the notional monitoring system. The payload specified here will be a JSON payload even though it is specified in an XML schema.

• RESTReply.xsd – this contains the schema for the JSON return of the monitoring system.

The Workflow

The OpenESB platform contains, as has been noted, the facility to embed an XLST transformation into the its workflow. This facility will be used to convert the formatted text of the email into its structured (XML) representation by providing the message body as a parameter to a XSL style sheet.

One converted, messages will be sent with the information contained within the list of devices. 

OpenESB specifies the configuration of each instance of a Binding Component in a WSDL file. For more advanced users, the use of an ‘Abstract WSDL’ that is refined when building the Composite Application is recommended, but this usage pattern is confusing for those new to the platform. For this reason, this example is presented using the ‘Concrete WSDL’ approach that is more intuitive. 

The Email Reader

The first WSDL that must be configured to support the workflow is that required to communicate with the email server – an example showing IMAP communication is provided, but this may be defined as follows if POP3 is required:- 

• Add a process file of type WSDL
• Select a WSDL type of Concrete WSDL Document
• Choose a name for the WSDL (in this case POP3Reader)
• Select a Binding of EMAIL
• Select your chosen email activity

Click Next

In the form that appears, configure your server and user credentials, and configure the BC to capture one message at a time

You may also choose to delete the messages once read by setting the Message Ack Operation to Delete if desired.

Clicking Finish will create the WSDL

It is also possible to edit the IMAP WSDL provided in the example (and, in a similar way, the POP3 WSDL created above) - in OpenESB studio, open ReadEmail.wsdl and select the WSDL view. The properties can now be edited on the right-hand side once the service has been selected:

The REST POST

The final WSDL that must be defined is that of the REST POST used to send per-device notifications. The REST step is unusual in that it must be specified in as a concrete WSDL – the WSDL creation wizard will allow the creation of any number of REST actions within a single WSDL. Beware that any alterations to the REST service once defined must be made by editing a CDATA section of the WSDL. Both the creation and alteration of the WSDL will be covered 

The WSDL in the example was created as follows:-

• Add a WSDL process file
• Specify a file name
• Specify a concrete REST WSDL
• Specify a type of REST – Outbound

Click Next, and, on the form that follows, select POST and click Add Operation

A new form will now be presented for initial service definition. Provide a operation name of RESTAlert and browse to the request and reply message definitions created earlier

Now follow the on-screen prompt to edit the operation, and specify the URL, any additional headers (such as authorization) and note the settings for response-root-required and request-root-removed

ClIck OK in this pane, and Finish on the Operation Details Pane.

Even though the WSDL has been defined using the wizard, there is one alteration that must be made in the CDATA definition for the service. From this point on, or is using the supplied example, all changes must be made in the CDATA. 

Open the RestSender WSDL in OpenESB Studio, and select the Source view

It is here that the REST service is defined in detail. At the end of this section, there is a property response-root-name the provided example expects this to be set to AlertReply.

As might be expected, the Partner view of this WSDL shows RESTMsg and RESTReply as the input and output messages of this action.

All of the actions have now been defined.

The BPEL Process

The actions defined in the WSDL files previously are controlled by logic in a BPEL file – in the example this is titled VyoptaAlertIntegration.bpel. Opening this file and selecting the design view will show

This shows the flow of the incoming mail message being accepted and transformed into XML. There is then a loop that processes the per-device information and sends the alert to the defined REST service. In the event that the REST service returns an error, the result is logged by a fault handler.

For detailed information of the working of BPEL within OpenESB, please see this document.

Compiling and Deploying the Service

Within the Project view of OpenESB, right click on the VyoptaAlertIntegration project, and select Clean and Build. If the output window is not visible, Select Window – Output on the NetBeans menu bar. Note the message BUILD SUCCESSFUL at the end of the output.

Again, from the project view, right-click and select Clean and Build for the VyoptaAlertIntegrationCA project. If this project does not build, create a new project and drop VyoptaAlertIntegration into the CASA editor, as was done in the getting started examples. No further configuration is necessary, and the project may be built in the CASA by using the hammer icon.

Select Clean and Build, as above, to create the service assembly 

Once built, simply deploy (right click project, select Deploy) to the server. The service assembly will start immediately and scan for emails. 

Trouble Shooting

The server logs will contain details of any errors encountered – the level of logging can be adjusted using the OpenESB web console. Logs are output to stdout by default.

The BPEL execution can be debugged by setting breakpoints (right click where a breakpoint is required and select Toggle Breakpoint) Debugging is enabled when a process is deployed using the Debug (BPEL) option instead of Deploy.

You may wish to target a REST mocking server (such as WireMock, MockServer, Mockoon, SOAPUI, Postman etc) to verify that your requests are correct.

Obtaining Support

The contents contained in this document are for informational purposes only and are not supported by Vyopta.  Vyopta does not provide OpenESB support, nor will the Vyopta Support Team be able to offer support for anything other than the Vyopta platform.

Should support be required, we suggest using the community or commercial channels detailed earlier in this document.