Concepts

Settings

Setting up APM Outbound Events

When certain APM objects are created, updated, or deleted, events can be produced (serialized) and published to an external system using AWEIS.

Configuring this functionality involves the following steps:

•	Enable outbound events in the site interoperability profile

•	Configure the server\service instance

•	Create an APM Outbound Event service provider

•	Set Interop Event Handler options

Note: The Publish APM Events feature does not support Oracle DBMS without additional steps. If you wish to use this feature with Oracle 12, contact Bentley Support.

When setup tasks are completed, add target and connection components in AWEIS. In the AssetWise Interoperability Setup Guide, see “Setting up APM Outbound Events”.

This topic provides information about events, explains how to set up APM to publish events, and outlines the steps for creating a custom interface package and event handler. It includes:

•	Introduction to Events

•	Types of SyncEvents for APM Events

•	Setting up APM to Publish Events

•	Creating a Custom Interface Package and Classes

•	Creating a Custom Event Handler

Introduction to Events

An event is a log of the actual events that occurred at a service segment or asset over time (it is not work performed by an entity).

Different kinds of events capture operating and failure events, such as Logged Operating Events, Failure “Modes”, Failure “Effects”, Failure “Mechanisms”, Defect Events, Abnormal Situations, Alarm Events, and so on. In MIMOSA CCOM:

•	An Actual Event is an alarm, operational change, or abnormal condition related to a segment or asset at a specific point in time or during a specific interval of time

•	Hypothetical Events are possible failure modes and effects from an engineering study (often FMEA or RCM analysis)

•	A Proposed Event might have occurred in the past, present, or future that explains events and measurement events, including diagnostic/prognostic event outputs

Note: Currently, APM supports outbound events for indicator alarms, asset installation, failures, failure modes, and work document change requests.

In the example workflow below, events that are recorded in APM are published to the service bus, and the Data Hub subscribes to these events so they can be recorded in another system.

Producing Outbound Events – APM Interface Packages

An outbound event can be created when an APM object is created, updated, or deleted. The APM interface class defines the structure that will be serialized to an event. A typical event XML document contains the state of an object. The XML document is generated using the APM IFW API, which uses the interface class.

Each object for which events need to be created must have a root level interface class. All of the interface classes created for the purpose of creating outbound events must be owned by an interface package.

APM provides interface packages such as:

•	InteropEvents is designed to create events when indicator readings are in alarm, acknowledged, or missed. It can also create events when a failure or failure mode is created or updated on an interop asset.

•	InteropEventsSyncAssets is designed to create events when an asset is installed in or removed from a parent asset. For example, when a work order is used to swap component assemblies, outbound XML messages are generated for all removed and installed component assets and sent to the service bus

If you need to create a custom interface class structure, start by copying the existing interface package and then add interface classes to it. See Creating a Custom Interface Package and Classes.

Publishing Events

Publishing an outbound event to an external service is performed by the APM Outbound Event service provider. This service provider polls the APM event table at regular intervals, fetches one event at a time, and delegates it to the registered event handler. The responsibility of an event handler is to process the event. Once the event is successfully processed, the event is deleted and the next event is fetched. If it fails to process an event, the service provider will retry the event and will not move to the next event until it is successfully processed.

Setting up an APM Outbound Event service provider involves configuring the server/service instance to use the event handler, adding the service provider to the server, and restarting the server.

APM provides an event handler for publishing events to the interoperability service bus. You can also create a custom event handler and register it with the outbound event service provider. See Creating a Custom Event Handler.

Types of SyncEvents for APM Events

When an APM event is processed, one or more SyncEvent messages are produced. This section explains the type of messages that are created for each of the supported events.

Asset Installation

APM can product and publish outbound events when an asset is installed in or removed from a parent asset. For example, when a work order is used to swap component assemblies, outbound XML messages are generated for all removed and installed component assets and sent to the service bus.

The APM event can produce a SyncEvent with the event type “SyncAssetSegmentEvents”. This allows a child asset to be added to or removed from the parent segment.

The APM event can produce a SyncEvent with the event type “SyncBreakdownStructureConnection”. This allows a child segment to be added to or removed from the parent segment.

Indicator Alarms

APM can produce and publish outbound events when a non-normal indicator reading is created or updated, when an indicator alarm is acknowledged, or when an unacknowledged alarm is marked as “missed”. The indicator readings, which must be on interop assets, produce SyncEvents with the event type “MeasurementLocationTriggeredRegion”.

Failures and Failure Modes

APM can produce and publish outbound events when failures and failure modes are created and updated. Failures and failure modes must be created on interop assets for the outbound events to work.

Failure modes created or updated on MTA2 and RCM2 analyses are mapped to the MIMOSA noun hypothetical events. They produce SyncEvents with the event type “HypotheticalEvent”.

Failures with partial or total severities are mapped to SyncEvents with the event type “ActualEvent”. If a failure is created in the process of acknowledging an indicator alarm, the source indicator reading is included in a separate SyncEvent with the event type “MeasurementLocationTriggeringRegion”.

Failures with null or potential severities are mapped to SyncEvents with the event type “ProposedEvents”. When a failure references a failure mode on an interop asset, the SyncEvent includes the “ProposedEventForHypotheticalEvent” element.

Work Document Change Requests

APM can produce and publish outbound events when a work order change request or work request change request is marked as “Ready to send”. They produce SyncEvents with the event type “ChangeWorkOrders” or “ChangeWorkRequests”.

Setting up APM to Publish Events

This section explains how:

•	To Enable Outbound Events in the Site Interoperability Profile

•	To Configure the Server Instance

•	To Set up the Outbound Event Service Provider

•	To Set Interop Event Handler Options

To Enable Outbound Events in the Site Interoperability Profile

1.	In the Enterprise window, select the Integrations view, AssetWise Interoperability tab.

2.	Select the Interoperability Profiles tab and either open an existing profile or click New to create one.

For more information about creating profiles, see Setting up Site Interoperability Profiles for AWEIS.

3.	In the Site Interoperability Profile dialog, select the Events tab and select Interop events enabled. For example:

4.	Select one or more interop interface packages.

5.	Click OK to save the profile and close the dialog.

6.	In the appropriate sites, activate interoperability and select the site interoperability profile.

For more information, see Activating AssetWise Enterprise Interoperability in APM.

7.	Restart the APM client. At this point, APM will start creating events for classes that have “root level” interface classes in the interface package you created.

To Configure the Server Instance

1.	Launch APM Configuration. For example, on the Start menu, click Bentley, and then Configure APM. The APM Configuration window appears.

2.	In the Type list, select Server/Service.

3.	Select or create the instance that you want to use to publish events.

Tip: Take note of the name of the instance. You will use it when setting up the service provider.

4.	Click the Configuration list and then Full Settings. The Settings Editor appears.

5.	In the File menu, click Show Advanced Settings.

6.	Under the Server node, click Service Providers. Scroll down to the Outbound Event section.

7.	In the Event Handler Assembly Name box, browse to the event handler provided by Bentley in the install directory, bin\Service Providers folder. For example:

C:\Program Files\Bentley\AssetWise Performance Management\bin\Service Providers\Bentley.APM.Interop.EventHandler.dll

If you wish to use a custom event handler that you created, click the browse icon, navigate to the bin\Service Providers folder, and select the dll file.

8.	The event publisher interval is set to 10 seconds by default. You can change this value if required. For example:

9.	Save and close the Settings Editor.

To Set up the Outbound Event Service Provider

1.	From the Enterprise window, select the Services view and the Servers tab. This example shows the tab before a server machine has been set up:

2.	Click New to create a server machine. The Server Machine Properties dialog appears. For example:

3.	Enter the computer name of the server machine that will publish events.

4.	Click New to add a server. The Server dialog appears.

5.	Enter the name of the server/service instance. This name must match the name given to the instance when it was created.

6.	Click Browse to add a service provider. The Browse Service Provider Plugins dialog appears:

7.	Select APM Outbound Event Service Provider and click OK. The service provider is added to the table.

8.	Click OK in the server Properties dialog to close it.

9.	Click OK in the server machine Properties dialog to close it.

10.	Restart the server.

The service provider will be activated when the server instance is restarted.

To Set Interop Event Handler Options

1.	Launch APM Configuration. For example, on the Start menu, click Bentley, and then Configure APM. The APM Configuration window appears.

2.	In the Type list, select Server/Service.

3.	Select the instance used to publish events.

4.	Click the Configuration list and then Full Settings. The Settings Editor appears.

5.	In the File menu, click Show Advanced Settings.

6.	Under the Interop Outbound Event Handler node, click Runtime Settings. Scroll down to the Event section. For example:

7.	Set these options, as required:

•	Retry count – The number of times that the Interop event handler will try to publish the event before giving up

•	Interop ServiceBus Endpoint – The Rest endpoint of Bentley’s interoperability service bus api. For example:

https://dtlinteropqa.bentley.com/interoperability/api/v1/servicebus/syncevents

where syncevents is the exchange name in RabbitMQ or the topic name in Azure Service Bus

•	Sas Token – Shared Access Signature token required to authenticate the request sent to the Interoperability service bus. The Bentley Service Bus API Token is required for outbound events.

8.	In the File menu, click Save and then Exit.

Creating a Custom Interface Package and Classes

You can use the interface packages provided with APM. If they do not meet your organization’s needs, use the following steps to create a custom package and classes.

To Create a Custom Interface Package and Classes

1.	From the Site window, click on the tool bar. The Enterprise window appears.

2.	Select the Customization Center view.

3.	Select the Interfaces tab and then the Packages tab. In the Configurations list, select “All Interface packages”.

4.	Right-click the InteropEvents or InteropEventsSyncAssets package and click Copy. The Interface Package window appears, for example:

5.	Give the package a unique name.

The package type must be “Interop events”. The system can be any of the available values.

6.	Select the Classes tab to create the interface classes for this package.

7.	For each class that you wish to add, click New. The Interface Class window appears.

8.	Provide a unique name for the class.

9.	In the Class list, select the class on which to base this one.

10.	In the Interface level list, select either “Root level” or “Sub level”. The interface class associated with an object that triggers the generation of an event must have the interface level “Root level”. Here is an example of the indicator reading interface class, which triggers an event:

Note: The interface level is very important in this context because it is one of the criteria used to determine whether an event is created. The interface level must be set to “Root” if an event needs to be created for the class referenced by the interface class.

11.	On each root level interface class, select the Events tab and select the actions that will trigger interop events.

In this example, events will be created when objects are created or updated but not when they are deleted.

12.	Create the interface classes used for their relational properties to the root level interface class, and be sure to mark them as “Sub level”. For example, IndicatorToRead has the sub level interface level:

13.	Add properties to the interface classes, using the interface packages provided by APM as models.

Once the interface class structure is ready, you can enable outbound events in the site interoperability profile.

Creating a Custom Event Handler

You can use the event handler provided with APM. If it does not meet your organization’s needs, use the following steps to create a custom event handler.

Note: To create a custom event handler, use .Net Framework 4.7.1 or higher.

To Create a Custom Event Handler

1.	Create a class that implements the IOutboundEventHandler interface (Bentley.APM.ServiceProvider.OutboundEvent.dll).

2.	Write event publishing logic in the ProcessEvent method.

3.

Have the ProcessEvent method return EventProcessStatus. It indicates whether events were successfully processed or failed. If the event was successfully processed, the event will be removed from the system. If it failed, the event will not be removed from the system and the same event will be retried next time.

4.	If you want to provide settings in the custom event handler and see those settings in the APM Settings Editor, the setting class in the custom event handler must be derived from IvaraSettingsBase class (Bentley.APM.Settings.dll). For example:

5.	Build the custom event handler with the Release configuration and place the binaries in the bin\Service Providers folder.

6.	Follow the steps in the APM Outbound Event Service provider Settings section to register the custom event handler.

7.	Close the Settings Editor and open it again. Select Advanced Settings to see the Custom event handler settings in the editor.

8.	Once the settings are correctly configured, start the service. At this point, it will start publishing the outbound events using the registered custom event handler.