Configuring Serena Business Manager to Receive E-Mail Events

The Web service–based event mechanism exposed by SBM can accept events either through HTTP or via e-mail. Events through HTTP are enabled by default and require no additional configuration beyond the basic installation of SBM. Events through e-mail require that SBM be configured to access an e-mail mailbox provided by an external e-mail server. SBM Configurator provides options to configure this feature.

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.

Important: A single-part message that contains only plain text is treated as a SOAP message and accepted as an ALF e-mail event. If SBM receives a single-part message that only contains HTML, SBM cannot process it and the event is ignored. Multi-part messages are accepted, but they must contain the ALF event in plain text in order for the Event Manager to process the event.

For more information about POP3 mail service behavior, refer to solution S141688.

Options Provided by SBM Configurator

On-premise only

On the Mail Services tab in SBM Configurator, you can enable mail settings for Application Repository and the Event Manager. Use the following fields to configure the Event Manager to receive e-mail events.

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.

Port: The port used by the POP3 e-mail server. POP3 typically uses port 110. If you want to use a secure connection to the POP3 mailbox, select the Use SSL option. The default SSL port is 995.

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.

Important: If you apply changes while the SBM Configurator runs in utility mode, browser users may not be able to access the system immediately while the services are restarting. Therefore, consider applying configuration changes at a time when users are not actively using the system.

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.