Errata exists for this version of the document.

As illustrated in the figure below, the A&E COM UA Proxy is a COM Server combined with a UA Client. It maps the Alarms and Conditions address space of UA A&C Server into the appropriate COM Alarms and Event Objects.

Subclauses D.3.2 through D.3.9 identify the design guidelines and constraints used to develop the A&E COM UA Proxy provided by the OPC Foundation. In order to maintain a high degree of consistency and interoperability, it is strongly recommended that vendors, who choose to implement their own version of the A&E COM UA Proxy, follow these same guidelines and constraints.

The A&E COM Client simply needs to address how to connect to the UA A&C Server. Connectivity approaches include the one where A&E COM Clients connect to a UA A&C Server with a CLSID just as if the target Server were an A&E COM Server. However, the CLSID can be considered virtual since it is defined to connect to intermediary components that ultimately connect to the UA A&C Server. Using this approach, the A&E COM Client calls co-create instance with a virtual CLSID as described above. This connects to the A&E COM UA Proxy components. The A&E COM UA Proxy then establishes a secure channel and session with the UA A&C Server. As a result, the A&E COM Client gets a COM Event Server interface pointer.

The A&E COM UA Proxy reads the UA A&C Server status from the Server Object Variable Node. Status enumeration values that are returned in ServerStatusDataType structure can be mapped 1 for 1 to the A&E COM Server status values with the exception of UA A&C Server status values Unknown and Communication Fault. These both map to the A&E COM Server status value of Failed.

The VendorInfo string of the A&E COM Server status is mapped from ManufacturerName.

Since all Alarms and Conditions Events belong to a subtype of BaseEventType, the A&E COM UA Proxy maps the subtype as received from the UA A&C Server to one of the three A&E Event types: Simple, Tracking and Condition. Figure D.2 shows the mapping as follows:

• Those A&C Events which are of subtype AuditEventType are marked as A&E Event type Tracking.
• Those A&C Events which are ConditionType are marked as A&E Event type Condition.
• Those A&C Events which are of any subtype except AuditEventType or ConditionType are marked as A&E Event type Simple.

Figure D.2 – Mapping UA Event Types to COM A&E Event Types

Note that the Event type mapping described above also applies to the children of each subtype.

Each A&E Event type (e.g. Simple, Tracking, Condition) has an associated set of Event categories which are intended to define groupings of A&E Events. For example, Level and Deviation are possible Event categories of the Condition Event type for an A&E COM Server. However, since A&C does not explicitly support Event categories, the A&E COM UA Proxy uses A&C Event types to return A&E Event categories to the A&E COM Client. The A&E COM UA Proxy builds the collection of supported categories by traversing the type definitions in the address space of the UA A&C Server. Figure D.3 shows the mapping as follows:

• A&E Tracking categories consist of the set of all Event types defined in the hierarchy of subtypes of AuditEventType and TransitionEventType, including AuditEventType itself and TransitionEventType itself.
• A&E Condition categories consist of the set of all Event types defined in the hierarchy of subtypes of ConditionType, including ConditionType itself.
• A&E Simple categories consist of the set of Event types defined in the hierarchy of subtypes of BaseEventType excluding AuditEventType and ConditionType and their respective subtypes.

Figure D.3 – Example mapping of UA Event Types to COM A&E categories

Category name is derived from the display name Attribute of the Node type as discovered in the type hierarchy of the UA A&C Server.

Category description is derived from the description Attribute of the Node type as discovered in the type hierarchy of the UA A&C Server.

The A&E COM UA Proxy assigns Category IDs.

The collection of Attributes associated with any given A&E Event is encapsulated within the ONEVENTSTRUCT. Therefore, the A&E COM UA Proxy populates the Attribute fields within the ONEVENTSTRUCT using corresponding values from UA Event Notifications either directly (e.g., Source, Time, Severity) or indirectly (e.g., OPC COM Event category determined by way of the UA Event type). Table D.5 lists the Attributes currently defined in the ONEVENTSTRUCT in the leftmost column. The rightmost column of Table D.5 indicates how the A&E COM UA proxy defines that Attribute.

Table D.5 – Event category attribute mapping table

A&E ONEVENTSTRUCT “attribute”	A&E COM UA Proxy Mapping
The following items are present for all A&E event types
szSource	UA BaseEventType Property: SourceName
ftTime	UA BaseEventType Property: Time
szMessage	UA BaseEventType Property: Message
dwEventType	See Clause D.3.3
dwEventCategory	See Clause D.3.4
dwSeverity	UA BaseEventType Property: Severity
dwNumEventAttrs	Calculated within A&E COM UA Proxy
pEventAttributes	Constructed within A&E COM UA Proxy
The following items are present only for A&E Condition-Related Events
szConditionName	UA ConditionType Property: ConditionName
szSubConditionName	UA ActiveState Property: EffectiveDisplayName
wChangeMask	Calculated within Alarms and Events COM UA proxy
wNewState: OPC_CONDITION_ACTIVE	A&C AlarmConditionType Property: ActiveState Note that events mapped as non-Condition Events and those that do not derive from AlarmConditionType are set to ACTIVE by default.
wNewState: OPC_CONDITION_ENABLED	A&C ConditionType Property: EnabledState Note, Events mapped as non-Condition Events are set to ENABLED (state bit mask = 0x1) by default.
wNewState: OPC_CONDITION_ACKED	A&C AcknowledgeableConditionType Property: AckedState Note that A&C Events mapped as non-Condition Events or which do not derive from AcknowledgeableConditionType are set to UNACKNOWLEDGED and AckRequired = False by default.
wQuality	A&C ConditionType Property: Quality Note that Events mapped as non-Condition Events are set to OPC_QUALITY_GOOD by default. In general, the Severity field of the StatusCode is used to map COM status codes OPC_QUALITY_BAD, OPC_QUALITY_GOOD and OPC_QUALITY_UNCERTAIN. When possible, specific status' are mapped directly. These include (UA => COM): Bad status codes Bad_ConfigurationError => OPC_QUALITY_CONFIG_ERROR Bad_NotConnected => OPC_QUALITY_NOT_CONNECTED Bad_DeviceFailure => OPC_QUALITY_DEVICE_FAILURE Bad_SensorFailure => OPC_QUALITY_SENSOR_FAILURE Bad_NoCommunication => OPC_QUALITY_COMM_FAILURE Bad_OutOfService => OPC_QUALITY_OUT_OF_SERVICE Uncertain status codes Uncertain_NoCommunicationLastUsableValue => OPC_QUALITY_LAST_USABLE Uncertain_LastUsableValue => OPC_QUALITY_LAST_USABLE Uncertain_SensorNotAccurate => OPC_QUALITY_SENSOR_CAL Uncertain_EngineeringUnitsExceeded => OPC_QUALITY_EGU_EXCEEDED Uncertain_SubNormal => OPC_QUALITY_SUB_NORMAL Good status codes Good_LocalOverride => OPC_QUALITY_LOCAL_OVERRIDE
bAckRequired	If the ACKNOWLEDGED bit (OPC_CONDITION_ACKED) is set then the Ack Required Boolean is set to False, otherwise the Ack Required Boolean is set to True. If the Event is not of type AcknowledgeableConditionType or subtype then the AckRequired Boolean is set to False.
ftActiveTime	If the Event is of type AlarmConditionType or subtype and a transition from ActiveState of False to ActiveState to True is being processed then the TransitionTime Property of ActiveState is used. If the Event is not of type AlarmConditionType or subtype then this field is set to current time. Note: Additional logic applies to exclusive limit alarms, This value should be mapped to the LimitState.TransitionTime.
dwCookie	Generated by the A&E COM UA Proxy. These unique Condition Event cookies are not associated with any related identifier from the address space of the UA A&C Server.
The following is used only for A&E tracking events and for A&E condition-relate events which are acknowledgement notifications
szActorID
Vendor specific Attributes – ALL
ACK Comment
AREAS	All A&E Events are assumed to support the "Areas" Attribute. However, no Attribute or Property of an A&C Event is available which provides this value. Therefore, the A&E COM UA Proxy initializes the value of the Areas Attribute based on the MonitoredItem producing the Event. If the A&E COM Client has applied no area filtering to a Subscription, the corresponding A&C Subscription will contain just one MonitoredItem – that of the UA A&C Server Object. Events forwarded to the A&E COM Client on behalf of this Subscription will carry an Areas Attribute value of empty string. If the A&E COM Client has applied an area filter to a Subscription then the related UA A&C Subscription will contain one or more MonitoredItems for each notifier Node identified by the area string(s). Events forwarded to the A&E COM Client on behalf of such a Subscription will carry an areas Attribute whose value is the relative path to the notifier which produced the Event (i.e., the fully qualified area name).
Vendor specific Attributes – based on category
SubtypeProperty1 SubtypePropertyn	All the UA A&C subtype Properties that are not part of the standard set exposed by BaseEventType or ConditionType

Condition Event instance records are stored locally within the A&E COM UA Proxy. Each record holds ONEVENTSTRUCT data for each EventSource/Condition instance. When the Condition instance transitions to the state INACTIVE|ACKED, where AckRequired = True or simply INACTIVE, where AckRequired = False, the local Condition record is deleted. When a Condition Event is received from the UA A&C Server and a record for this Event (identified by source/Condition pair) already exists in the proxy Condition Event store, the existing record is simply updated to reflect the new state or other change to the Condition, setting the change mask accordingly and producing an OnEvent callback to any subscribing Clients. In the case where the Client application acknowledges an Event which is currently unacknowledged (AckRequired = True), the UA A&C Server Acknowledge Method associated with the Condition is called and the subsequent Event produced by the UA A&C Server indicating the transition to acknowledged will result in an update to the current state of the local Condition record as well as an OnEvent Notification to any subscribing Clients.

The A&E COM UA Proxy maintains the mapping of Attributes on an Event category basis. An Event category inherits its Attributes from the Properties defined on all supertypes in the UA Event Type hierarchy. New Attributes are added for any Properties defined on the direct UA Event type to A&E category mapping. The A&E COM UA Proxy adds two Attributes to each category: AckComment and Areas. Figure D.4 shows an example of this mapping.

Figure D.4 – Example mapping of UA Event Types to A&E categories with attributes

Events of any subtype of ConditionType are designated COM Condition Events and are subject to additional processing due to the stateful nature of Condition Events. COM Condition Events transition between states composed of the triplet ENABLED|ACTIVE|ACKNOWLEDGED. In UA A&C, Event subtypes of ConditionType only carry a value which can be mapped to ENABLED (DISABLED) and optionally, depending on further sub typing, may carry additional information which can be mapped to ACTIVE (INACTIVE) or ACKNOWLEDGED (UNACKNOWLEGED). Condition Event processing proceeds as described in Table D.5 (see A&E ONEVENTSTRUCT “Attribute” rows: OPC_CONDITION_ACTIVE, OPC_CONDITION_ENABLED and OPC_CONDITION_ACKED).

A&E COM browsing yields a hierarchy of areas and sources. Areas can contain both sources and other areas in tree fashion where areas are the branches and sources are the leaves. The A&E COM UA Proxy relies on the "HasNotifier" Reference to assemble a hierarchy of branches/areas such that each Object Node which contains a HasNotifier Reference and whose EventNotifier Attribute is set to SubscribeToEvents is considered an area. The root for the HasNotifier hierarchy is the Server Object. Starting at the Server Object, HasNotifier References are followed and each HasNotifier target whose EventNotifier Attribute is set to SubscribeToEvents becomes a nested COM area within the hierarchy.

Note that the HasNotifier target can also be a HasNotifier source. Further, any Node which is a HasEventSource source and whose EventNotifier Attribute is set to SubscribeToEvents is also considered a COM Area. The target Node of any HasEventSource Reference is considered an A&E COM “source” or leaf in the A&E COM browse tree.

In general, Nodes which are the source Nodes of the HasEventSource Reference and/or are the source Nodes of the HasNotifier Reference are always A&ECOM Areas. Nodes which are the target Nodes of the HasEventSource Reference are always A&E COM Sources. Note however that targets of HasEventSource which cannot be found by following the HasNotifier References from the Server Object are ignored.

Given the above logic, the A&E COM UA Proxy browsing will have the following limitations: Only those Nodes in the UA A&C Server’s address space which are connected by the HasNotifier Reference (with exception of those contained within the top level Objects folder) are considered for area designation. Only those Nodes in the UA A&C Server’s address space which are connected by the HasEventSource Reference (with exception of those contained within the top level Objects folder) are considered for area or source designation. To be an area, a Node shall contain a HasNotifier Reference and its EventNotifier Attribute shall be set to SubscribeToEvents. To be a source, a Node shall be the target Node of a HasEventSource Reference and shall have been found by following HasNotifier References from the Server Object.

From the root of any sub tree in the address space of the UA A&C Server, the A&E COM Client may request the list of areas and/or sources contained within that level. The resultant list of area names or source names will consist of the set of browse names belonging to those Nodes which meet the criteria for area or source designation as described above. These names are "short" names meaning that they are not fully qualified. The A&E COM Client may request the fully qualified representation of any of the short area or source names. In the case of sources, the fully qualified source name returned to the A&E COM Client will be the string encoded value of the NodeId as defined in OPC 10000-6 (e.g., “ns=10;i=859“). In the case of areas, the fully qualified area name returned to the COM Client will be the relative path to the notifier Node as defined in OPC 10000-4 (e.g., “/6:Boiler1/6:Pipe100X/1:Input/2:Measurement“). Relative path indices refer to the namespace table described below.

UA Server Namespace table indices may vary over time. This represents a problem for those A&E COM Clients which cache and reuse fully qualified area names. One solution to this problem would be to use a qualified name syntax which includes the complete URIs for all referenced table indices. This however would result in fully qualified area names which are unwieldy and impractical for use by A&E COM Clients. As an alternative, the A&E COM UA Proxy will maintain an internal copy of the UA A&C Server's namespace table together with the locally cached endpoint description. The A&E COM UA Proxy will evaluate the UA A&C Server’s namespace table at connect time against the cached copy and automatically handle any re-mapping of indices if required. The A&E COM Client can continue to present cached fully qualified area names for filter purposes and the A&E COM UA Proxy will ensure these names continue to reference the same notifier Node even if the Server's namespace table changes over time.

To implement the relative path, the A&E COM UA Proxy maintains a stack of INode interfaces of all the Nodes browsed leading to the current level. When the A&E COM Client calls GetQualifiedAreaName, the A&E COM UA Proxy first validates that the area name provided is a valid area at the current level. Then looping through the stack, the A&E COM UA Proxy builds the relative path. Using the browse name of each Node, the A&E COM UA Proxy constructs the translated name as follows:

QualifiedName translatedName = new QualifiedName(Name,(ushort) ServerMappingTable[NamespaceIndex]) where

Name – the unqualified browse name of the Node

NamespaceIndex – the Server index

the ServerMappingTable provides the Client namespace index that corresponds to the Server index.

A ‘/’ is appended to the translated name and the A&E COM UA Proxy continues to loop through the stack until the relative path is fully constructed.

The A&E COM UA Proxy supports all of the defined A&E COM filter criteria.

These filter types are implemented using simple numeric comparisons. For Event filters, the received Event shall match the Event type(s) specified by the filter. For Category filters, the received Event’s category (as mapped from UA Event type) shall match the category or categories specified by the filter. For severity filters, the received Event severity shall be within the range specified by the Subscription filter.

In the case of source filters, the UA A&C Server is free to provide any appropriate, Server-specific value for SourceName. There is no expectation that source Nodes discovered via browsing can be matched to the SourceName Property of the Event returned by the UA A&C Server using string comparisons. Further, the A&E COM Client may receive Events from sources which are not discoverable by following only HasNotifier and/or HasEventSource References. Thus, source filters will only apply if the source string can be matched to the SourceName Property of an Event as received from the target UA A & C Server. Source filter logic will use the pattern matching rules documented in the A&E COM specification, including the use of wildcard characters.

The A&E COM UA Proxy implements Area filtering by adjusting the set of MonitoredItems associated with a Subscription. In the simple case where the Client selects no area filter, the A&E COM UA Proxy will create a UA Subscription which contains just one MonitoredItem, the Server Object. In doing so, the A&E COM UA Proxy will receive Events from the entire Server address space – that is, all Areas. The A&E COM Client will discover the areas associated with the UA Server address space by browsing. The A&E COM Client will use GetQualifiedAreaName as usual in order to obtain area strings which can be used as filters. When the A&E COM Client applies one or more of these area strings to the COM Subscription filter, the A&E COM UA Proxy will create MonitoredItems for each notifier Node identified by the area string(s). Recall that the fully qualified area name is in fact the namespace qualified relative path to the associated notifier Node.

The A&E COM UA Proxy calls the TranslateBrowsePathsToNodeIds Service to get the Node ids of the fully qualified area names in the filter. The Node ids are then added as MonitoredItems to the UA Subscription maintained by the A&E COM UA Proxy. The A&E COM UA Proxy also maintains a reference count for each of the areas added, to handle the case of multiple A&E COM Subscription applying the same area filter. When the A&E COM Subscriptions are removed or when the area name is removed from the filter, the ref count on the MonitoredItem corresponding to the area name is decremented. When the ref count goes to zero, the MonitoredItem is removed from the UA Subscription.

As with source filter strings, area filter strings can contain wildcard characters. Area filter strings which contain wildcard characters require more processing by the A&E COM UA Proxy. When the A&E COM Client specifies an area filter string containing wildcard characters, the A&E COM UA Proxy will scan the relative path for path elements that are completely specified. The partial path containing just those segments which are fully specified represents the root of the notifier sub tree of interest. From this sub tree root Node, the A&E COM UA Proxy will collect the list of notifier Nodes below this point. The relative path associated with each of the collected notifier Nodes in the sub tree will be matched against the Client supplied relative path containing the wildcard character. A MonitoredItem is created for each notifier Node in the sub tree whose relative path matches that of the supplied relative path using established pattern matching rules. An area filter string which contains wildcard characters may result in multiple MonitoredItems added to the UA Subscription. By contrast, an area filter string made up of fully specified path segments and no wildcard characters will result in one MonitoredItem added to the UA Subscription. So, the steps involved are:

1. Check if the filter string contains any of these wild card characters, '*', '?', '#', '[', ']', '!', '-'.
2. Scan the string for path elements that are completely specified by retrieving the substring up to the last occurrence of the ‘/’ character.
3. Obtain the Node Id for this path using TranslateBrowsePathsToNodeIds
4. Browse the Node for all notifiers below it.
5. Using the ComUtils.Match() function match the browse names of these notifiers against the Client supplied string containing the wild card character.
6. Add the Node ids of the notifiers that match as MonitoredItems to the UA Subscription.