Configuring Serena Business Manager to Receive E-Mail Events

Setting Up a POP3 E-mail Account

The SBM Event Manager can support receiving events only from a POP3-compliant e-mail server. To use the e-mail event feature, you must set up a dedicated e-mail account on the POP3 server, establishing the e-mail address that you want to use to accept the e-mail event requests. To configure SBM, you need to know the POP3 server host name, the port used by your POP3 server, the e-mail account name, and the e-mail account password.

Options Provided by SBM Configurator

On-premise only

The SBM Configurator provides the following fields to collect the values necessary to configure the SBM Event Manager to receive e-mail events. If these values are configured correctly during configuration, the e-mail event feature will be enabled.

Host: The network name of the POP3 e-mail server you want to use to provide the e-mail inbox for the e-mailed events. The installer presents the network name of the server on which SBM is being installed as a default. However, it is quite likely that your e-mail server resides on a different machine.

Port: The port used by the POP3 e-mail server. POP3 typically uses port 110.

User name: The e-mail account name for the inbox that your POP3 server provides.

Password: The password to the e-mail account.

Adjusting the Configuration

If you want to adjust the configuration settings for e-mailed events after you have completed the initial mail server set up, you can change the settings in SBM Configurator at any time.

E-mail Event Messages

To send an event by e-mail, you must construct an XML SOAP document in the correct format and send it to the event-enabled e-mail account.

Here is an example e-mail event message document:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:ns="http://www.eclipse.org/alf/schema/EventBase/1"
  xmlns:exam="http://www.eclipse.org/ALF/ExampleVocabulary"
  xmlns:myev="http://www.example.org/MyEventExtensions"
  xmlns:wsa="http://www.w3.org/2005/08/addressing"
  xmlns:mym="http://www.example.org/MyEventDefinitionEventExtensions">
  <soapenv:Header>
    <wsa:To>mailto yourEmailUser@yourEmailHost?X-Service-Path=/eventmanager/
→services/ALFEventManagerOneWayDocLit</wsa:To>
    <wsa:MessageID>urn:uuid:421A2EE66BA3A42A8C1203350641340</wsa:MessageID>
    <wsa:Action>urn:EventNotice</wsa:Action>
  </soapenv:Header>
  <soapenv:Body>
    <ns:ALFEventNoticeDoc version="1.0">
      <ns:Base>
        <ns:EventId>421A2EE66BA3A42A8C1203350641340</ns:EventId>
        <ns:Timestamp>2008-10-17T09:59:51.328-08:00</ns:Timestamp>
        <ns:EventType>MyEventDefinitionEvent</ns:EventType>
        <ns:ObjectType>MyEventDefinitionObject</ns:ObjectType>
        <ns:ObjectId>123</ns:ObjectId>
        <ns:Source>
          <ns:Product>MyEventDefinition</ns:Product>
          <ns:ProductVersion>1.0</ns:ProductVersion>
          <ns:ProductInstance>MyEventDefinitionInstance</ns:ProductInstance>
        </ns:Source>
        <ns:User>
          <ns:ALFSecurity>
            <ns:UsernameToken>
              <ns:Username>sbmUser</ns:Username>
              <ns:Password>sbmUserPassword</ns:Password>
            </ns:UsernameToken>
          </ns:ALFSecurity>
        </ns:User>
      </ns:Base>
      <ns:Extension>
        <mym:MyEventDefinitionData>Example Tool Data</mym:MyEventDefinitionData>
      </ns:Extension>
    </ns:ALFEventNoticeDoc>
  </soapenv:Body>
</soapenv:Envelope>

Header Values

The most important different between an e-mail event and an event sent through HTTP is that a Web service addressing header must be used:

<soapenv:Header>
  <wsa:To>mailto yourEmailUser@yourEmailHost?X-Service-Path=/eventmanager/
→services/ALFEventManagerOneWayDocLit</wsa:To>
  <wsa:MessageID>urn:uuid:421A2EE66BA3A42A8C1203350641340</wsa:MessageID>
  <wsa:Action>urn:EventNotice</wsa:Action>
</soapenv:Header>

The value of element wsa:To must be in the following format:

e-mailAddress?X-Service-Path=/eventmanager/services/eventmanagerService

where e-mailAddress is the dedicated POP3 e-mail account set up to receive events, and eventmanagerService is the Event Manager service that you want to receive the event.

The Event Manager service should be either ALFEventManagerOneWayDocLit or ALFEventManagerDocLit. ALFEventManagerOneWayDocLit is generally preferred, because it does not send an e-mail response message.

Event Instance Values

The value of wsa:MessageID should typically be a newly allocated UUID in the format shown. It may be useful to set the value of the message EventId to the same UUID value, because that will enable you to correlate the e-mail instance with the event.

You do not have to provide a value for ObjectId, although it can be useful to do so. Generally, it should contain a unique identifier for the object instance that is responsible for generating the event.

You must provide a value for Timestamp or set it to nil. The expected Timestamp value uses the subset of ISO 8601 used by XML Schema as specified for the XML Schema type datetime. To set Timestamp to nil, you must reference the following namespace:

xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance

and set the nil attribute instead of defining a value:

<ns:Timestamp xsi:nil="true"/>

Event Match Values

As with any SBM external event, the values of EventType, ObjectType, Product, ProductVersion, and ProductInstance must be set correctly to match a deployed event mapping. E-mail events are essentially external events, so it is generally necessary to create a custom event definition WSDL and import it into a process app before you can usefully process an e-mail event.

Authentication

As with any SBM external event, the event will not be accepted unless valid credentials are provided in the event request. Currently, the only practical way to do this is to provide a completed ALFSecurity element. You must fill in the values for Username and Password. At this time, only plain-text passwords are accepted. Because the credentials are passed in plain-text, it is recommended that the client send the message over HTTPS.

Extension Data

If your event definition specifies extension data, you can provide the appropriate XML structure and values inside the Extension element in the message.

Event Definitions and Message Style

Event definitions are used to define service flows that use the RPC literal message style, whereas the document literal message style is generally preferred for event communication. The example given above follows the document literal format and the document-literal event is contained within the root document element:

<ns:ALFEventNoticeDoc xmlns:ns="http://www.eclipse.org/alf/schema/EventBase/1">
  …Event Base and Extension elements go here…
</ns:ALFEventNoticeDoc>

Your message should validate against the WSDL/schema for the ALFEventManagerDocLit or ALFEventManagerOneWayDocLit services:

http://localhost:8085/eventmanager/services/ALFEventManagerDocLit?wsdl

http://localhost:8085/eventmanager/services/ALFEventManagerOneWayDocLit?wsdl

If you generate an XML document from an RPC literal service definition, the event content is contained within the parameter element <EventNotice xmlns="">, which in turn is contained within the operation element <ns:EventNotice xmlns:ns="http://www.eclipse.org/alf/schema/EventBase/1">:

<ns:EventNotice xmlns:ns="http://www.eclipse.org/alf/schema/EventBase/1">
  <EventNotice xmlns="">
    …Event Base and Extension elements go here…
  </EventNotice>
</ns:EventNotice>

To create the correct message for the e-mail event, you must replace the operation and parameter EventNotice elements with the document root element, ALFEventNoticeDoc.

Related Topics

Raising an External Event through E-mail