Enterprise Events

Configuration and usage of Aucerna Execute's real-time event publishing system

This document describes how to use Aucerna Execute’s Enterprise Events functionality.

The Aucerna Execute Enterprise Events functionality enables the asynchronous notification of external systems upon events within the AFE life-cycle.

There are four different transport mechanisms or targets that can be used with Enterprise Events:

Events delivered to a SOAP service, or
Events delivered to a HTTP service via HTTP Post, or
Events that are written to a file in XML format or transformed to another format using XSLT, or
Events delivered to a Microsoft Queue (MSMQ), or
Events can invoke a stored procedure and pass in the AFEID, the USERID and the Event Name.

Aucerna Execute allows configuration of multiple “event handlers”, each of which can publish the event information to a single event sink via SOAP, MSMQ, a stored procedure, or directly to a file.

Types of Events

AFE Events

Aucerna Execute will raise events for many of the actions that take place over an AFE’s lifetime. Aucerna Execute can be configured to notify an external system for some or all of these events. In addition, Aucerna Execute can be configured to suppress events on historical AFEs.

Event	Description
AfterInternalApprovalCompleteEvent	Once the last internal approvers has approved thisAFE(would be raised after the AfterInternalApproval event)
AfterInternalApprovalEvent	When an internal approver approves theAFE
AfterInternalHoldEvent	When an internal approver places theAFEon hold
AfterInternalRejectionEvent	When an internal approver rejects theAFE
AfterInternalUnHoldEvent	When an internal approver removes their hold on anAFE
AfterFullApprovalEvent	When anAFEbecomes fully approved. Follows the PartnerApprovalEvent
AfterPartnerApprovalEvent	When a Partner status is changed to Approved
AfterPartnerRejectionEvent	When a Partner status is changed to Rejected
AfterReleaseEvent	When anAFEis released for approval
AfterReviewCompleteEvent	When anAFEis reviewed by the final reviewer
AfterReviewerAddedEvent	When a new reviewer is added to anAFE
AfterReviewEvent	When anAFEis reviewed by a reviewer
AfterRevisionEvent	When anAFEis revised.
AfterRouteForReviewEvent	When anAFEis routed for review
AfterSaveEvent	When anAFEis saved
AfterSupplementEvent	When anAFEis supplemented
AfterUnreleaseEvent	When anAFEis rolled back to an unreleased state
AfterSystemReviewEvent	When anAFEis reviewed by a system reviewer
AfterAfeClosedEvent	When anAFEis marked as closed
AfterAfeReopenedEvent	When a closedAFEis re-opened
AfterAfeNumberChangedEvent	When anAFENumber is generated or changed.

RTD Events

RTD Navigator will raise events for many of the actions that take place over an RTD’s lifetime. Aucerna Execute can be configured to notify an external system for some or all of these events.

Event	Description
AfterRtdCloseEvent	When anRTDis marked as closed
AfterRtdReopenEvent	When anRTDis re-opened
AfterDisciplineUncompletedEvent	When a discipline on anRTDis uncompletes their discipline
AfterDisciplineCompletedEvent	When a discipline on anRTDis completes their discipline
AfterDisciplinesCompletedEvent	When all disciplines on anRTDhave been completed
AfterRtdApprovalCompleteEvent	When all approvers on anRTDhave approved
AfterRtdApprovalEvent	When an individual approval on anRTDis completed
AfterRtdRejectedEvent	When anRTDis rejected
AfterRtdReleasedEvent	When anRTDis release for approval
AfterRtdHoldEvent	When anRTDis placed on hold
AfterRtdUnholdEvent	When anRTDis taken off hold
AfterRtdLicensedEvent	When anRTDis marked as licensed
AfterRtdClearLicensedEvent	When anRTDis marked as not licensed
AfterRtdChangeOwnerEvent	When anRTD’s owner is changed

Enabling Enterprise Events

Events, whether targeting SOAP, MSMQ, or a file, are configured through a plugin. The “plugins_available\enterprise_events” folder gives you a selection of starting points. Copy one of these files to your “plugins” folder, remove the .sample suffix, and open it in a text editor to customize the configuration (review the XML comments in each configuration file for details).

These configuration files include:

events_file.config.sample: Write information to a file upon an event being fired. An optional XSLT transform can rewrite this data to match what is expected by the target system.
events_http.config.sample: Submit information to a service via HTTP Post.
events_soap_simple.config.sample: Send notification to a SOAP service using Document-Style SOAP.
events_soap_wsdl.config.sample: Send notification to a SOAP service using a WSDL (method with single string parameter consisting of afe payload (afe.xsd)).
events_stored_procedure.config.sample: Call a stored procedure giving it the AFEID and event information
events_msmq.config.sample: Push message into a Microsoft Queue for processing by another system.
rtd_events_file.config.sample: Sample file based events export for RTDs.

The above configuration files are samples and the system supports:

Controlling which events are captured (and whether to process event on historical AFEs)
XSL Transforms on AFE data to match requirements of recipient system.
E-mail notifications upon failures

<castle>

  <components>

    <component id="externalEventChannel_{##UNIQUE##}" service="Eni.AfeNavigatorServer.Framework.Channels.IChannel, Eni.AfeNavigatorServer.Framework"
        type="Eni.AfeNavigatorServer.Framework.Channels.FileChannel, Eni.AfeNavigatorServer.Framework"  lifestyle="singleton">
      <parameters>

        <!-- Enter root path for XML file output -->
        <path>c:\afenav\events</path>

        <!-- Start of Filename -->
        <filename>afe</filename>

        <!-- Padding Zeros in sequence -->
        <paddingZeros>6</paddingZeros>

        <!-- Extension -->
        <extension>xml</extension>

        <!-- Text Encoding: common values are "utf-8" or "Windows-1252"
             see complete list at https://msdn.microsoft.com/en-us/library/system.text.encoding(v=vs.110).aspx -->
        <encoding>utf-8</encoding>

      </parameters>
    </component>

    <component id="externalEventTransformer_{##UNIQUE##}" service="Eni.AfeNavigatorServer.Components.Events.IEventTransformer, Eni.AfeNavigatorServer.Components" type="Eni.AfeNavigatorServer.Components.Events.DocumentEventTransformer, Eni.AfeNavigatorServer.Components"  lifestyle="transient">
      <parameters>
        <!-- Optional XSLT file to tranform data on output -->
        <!-- <xsltPathname>c:\afenav\sample.xslt</xsltPathname> -->
      </parameters>
    </component>

    <component id="historicalAfeEventFilter_{##UNIQUE##}" service="Eni.AfeNavigatorServer.Framework.Events.IEventFilter, Eni.AfeNavigatorServer.Framework" type="Eni.AfeNavigatorServer.Framework.Events.HistoricalAfeEventFilter, Eni.AfeNavigatorServer.Framework"  lifestyle="transient">
      <parameters>
        <suppressEventsOnHistoricalAFEs>false</suppressEventsOnHistoricalAFEs>
      </parameters>
    </component>

    <component id="eventFilter_{##UNIQUE##}" service="Eni.AfeNavigatorServer.Framework.Events.IEventFilter, Eni.AfeNavigatorServer.Framework" type="Eni.AfeNavigatorServer.Framework.Events.AggregatingEventFilter, Eni.AfeNavigatorServer.Framework"  lifestyle="transient">
      <parameters>
        <eventFilters>
          <array>
            <item>${historicalAfeEventFilter_{##UNIQUE##}}</item>
            <item>${eventTypeFilter_{##UNIQUE##}}</item>
          </array>
        </eventFilters>
      </parameters>
    </component>

    <component id="eventTypeFilter_{##UNIQUE##}" service="Eni.AfeNavigatorServer.Framework.Events.IEventFilter, Eni.AfeNavigatorServer.Framework" type="Eni.AfeNavigatorServer.Framework.Events.EventTypeFilter, Eni.AfeNavigatorServer.Framework"  lifestyle="transient">
      <parameters>
        <eventTypes>
          <array>
            <item>Eni.AfeNavigatorServer.Framework.Events.AfeEvents.AfterAfeNumberChangedEvent</item>
            <item>Eni.AfeNavigatorServer.Framework.Events.AfeEvents.AfterInternalApprovalCompleteEvent</item>
            <item>Eni.AfeNavigatorServer.Framework.Events.AfeEvents.AfterInternalApprovalEvent</item>
            <item>Eni.AfeNavigatorServer.Framework.Events.AfeEvents.AfterInternalHoldEvent</item>
            <item>Eni.AfeNavigatorServer.Framework.Events.AfeEvents.AfterInternalRejectionEvent</item>
            <item>Eni.AfeNavigatorServer.Framework.Events.AfeEvents.AfterInternalUnHoldEvent</item>
            <item>Eni.AfeNavigatorServer.Framework.Events.AfeEvents.AfterFullApprovalEvent</item>
            <item>Eni.AfeNavigatorServer.Framework.Events.AfeEvents.AfterPartnerApprovalEvent</item>
            <item>Eni.AfeNavigatorServer.Framework.Events.AfeEvents.AfterPartnerRejectionEvent</item>
            <item>Eni.AfeNavigatorServer.Framework.Events.AfeEvents.AfterReleaseEvent</item>
            <item>Eni.AfeNavigatorServer.Framework.Events.AfeEvents.AfterReviewCompleteEvent</item>
            <item>Eni.AfeNavigatorServer.Framework.Events.AfeEvents.AfterReviewEvent</item>
            <item>Eni.AfeNavigatorServer.Framework.Events.AfeEvents.AfterSystemReviewEvent</item>
            <item>Eni.AfeNavigatorServer.Framework.Events.AfeEvents.AfterRevisionEvent</item>
            <item>Eni.AfeNavigatorServer.Framework.Events.AfeEvents.AfterRouteForReviewEvent</item>
            <!-- <item>Eni.AfeNavigatorServer.Framework.Events.AfeEvents.AfterSaveEvent</item> -->
            <item>Eni.AfeNavigatorServer.Framework.Events.AfeEvents.AfterSupplementEvent</item>
            <item>Eni.AfeNavigatorServer.Framework.Events.AfeEvents.AfterReviewerRemovedEvent</item>
            <item>Eni.AfeNavigatorServer.Framework.Events.AfeEvents.AfterReviewerAddedEvent</item>
            <item>Eni.AfeNavigatorServer.Framework.Events.AfeEvents.AfterAfeClosedEvent</item>
            <item>Eni.AfeNavigatorServer.Framework.Events.AfeEvents.AfterAfeReopenedEvent</item>
            <item>Eni.AfeNavigatorServer.Framework.Events.AfeEvents.AfterForceApprovalEvent</item>
            <item>Eni.AfeNavigatorServer.Framework.Events.AfeEvents.AfterUnreleaseEvent</item>
          </array>
        </eventTypes>
      </parameters>
    </component>

    <component id="externalEventHandler1_{##UNIQUE##}" service="Eni.AfeNavigatorServer.Framework.Events.IEventHandler, Eni.AfeNavigatorServer.Framework" type="Eni.AfeNavigatorServer.Components.Events.StandardEventHandler, Eni.AfeNavigatorServer.Components"  lifestyle="transient">
      <parameters>
        <channel>${externalEventChannel_{##UNIQUE##}}</channel>
        <eventFilter>${eventFilter_{##UNIQUE##}}</eventFilter>
        <eventTransformer>${externalEventTransformer_{##UNIQUE##}}</eventTransformer>
        <notifier>${smtpNotifier}</notifier>
        <emailAddresses>
          <array>
            <!-- List of email addresses to notify upon failures handling an event -->
            <!-- <item>user@example.com</item> -->
          </array>
        </emailAddresses>
      </parameters>
    </component>

  </components>
</castle>

All events are processed asynchronously and will not affect performance of Aucerna Execute.

The Event Message

The message sent to the receiving system when an event is raised is defined by the document-event.xsd in the documentation index.

The Event message consists of details on the user who caused the event, the event name itself (from the above table), and the document payload data at the time the event was raised.

The following is some a simplified output for an AFE’s After Release Event.

<DocumentEvent xmlns="http://energynavigator.com/xml/document/event/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Timestamp>2016-05-17T15:36:25</Timestamp>
  <Event>Eni.AfeNavigatorServer.Framework.Events.AfeEvents.AfterReleaseEvent</Event>
  <User>
    <ACTIVE>true</ACTIVE>
    <CUSTOM/>
    <DOCUMENT_ID>744d1b49-48b9-495c-ad2b-773f22f730ad</DOCUMENT_ID>
    <NAME>System Admin</NAME>
    <USERDESCRIPTION>2f3e5c8a-0a9b-4cbc-8071-5925731d645b</USERDESCRIPTION>
    <USERID>1</USERID>
  </User>
  <Document>
    <CREATION_DATE>2013-12-21T01:42:10Z</CREATION_DATE>
    <CUSTOM>
      <AFE_TYPE DOCUMENT_TYPE="LUT_AFE_TYPE">
        <ACTIVE>true</ACTIVE>
        <CODE_NUM>12</CODE_NUM>
        <DOCUMENT_ID>abc4e380-459e-42d5-8e60-9eff32062ebc</DOCUMENT_ID>
        <OTHER_VALUE1>W</OTHER_VALUE1>
        <OTHER_VALUE2>WORK</OTHER_VALUE2>
        <VALUE>WORKOVER</VALUE>
      </AFE_TYPE>
    </CUSTOM>
    <DESCRIPTION>RECOMPLETION please</DESCRIPTION>
    <DOCUMENT_ID>b8c55aae-cc44-4a83-95ac-8513aec9326b</DOCUMENT_ID>
  </Document>
</DocumentEvent>

Errors & Logging

At times, Aucerna Execute may be unable to send an event to a remote system (i.e. communication failure). When an error occurs, an entry will be logged to the system event log in Windows (below). The user who invoked the action will not be notified and their action will not be interrupted. Any other event handlers for that event will be unaffected.

In addition, entries will be logged to the System Notifications log (Tools > System Notifications) table in Aucerna Execute so that Administrators are aware of the failure and can take whatever actions are necessary to recover from the failure.

If e-mail notification of event failures was configured (above), an e-mail containing the event details will be sent to each configured e-mail address.