Customizing the XML configuration files

Use this information to customize the mandatory and optional XML elements in the OPCUaEvent.xml and OPCUaDataChange.xml configuration files to accommodate your environment.

Before you begin

Before you customize the OPCUaEvent.xml and OPCUaDataChange.xml configuration files, consider the following guidelines:

  • The Probe for OPC Unified Architecture (UA) delivers with two XML configuration files: OPCUaEvent.xml and OPCUaDataChange.xml. If you want to subscribe to event notification only, customize the OPCUaEvent.xml configuration file. If you want to subscribe to data change notification only, customize the OPCUaDataChange.xml configuration file.
    Note: Although it is possible to subscribe to both event notification and data change notification in the same XML configuration file (that is, either OPCUaEvent.xml or OPCUaDataChange.xml), these instructions explain how to customize the OPCUaEvent.xml and OPCUaDataChange.xml configuration files separately.
  • The XML configuration files reside in the $OMNIHOME/var directory.
  • There must be at least one monitored event or data item request in the OPCUaEvent.xml and OPCUaDataChange.xml configuration files. You specify each of these requests using the <MonitoredItemCreateRequest> </MonitoredItemCreateRequest> element pair. You can add or remove event notification or data change notification requests by adding or removing <MonitoredItemCreateRequest> </MonitoredItemCreateRequest> element pairs.
  • The <ClientHandle></ClientHandle> element specifies a unique client handle (represented by integers, for example, 1, 2, 3, and so forth) for each monitored event notification or data change notification.
  • You must customize the filter for the $OpcUaEventType element. This element identifies the type of OPC UA event that has occurred. The specific value you want to filter on is EventNotificationList.

    For more information on the $OpcUaEventType element (and other elements), see Elements.

  • You must use the MonitoredItemsConfigFile property to specify the full path of the XML configuration file that contains information on the items that the probe is to monitor. The information in this file is used in the OPC UA CreateMonitoredItems service.

    The default value is: $OMNIHOME/var/OpcUaEvent.xml.

Customizing the OPCUaEvent.xml configuration file

To customize the OPCUaEvent.xml configuration file for event notification, do the following:

  1. Go to the directory in which the OPCUaEvent.xml configuration file resides. For example:
    cd $OMNIHOME/var
  2. Copy the OPCUaEvent.xml configuration file to a backup file. For example:
    cp OPCUaEvent.xml OPCUaEvent.xml.save

    This ensures that if you make any mistakes you can access the original OPCUaEvent.xml configuration file.

  3. Using an appropriate editor, open the OPCUaEvent.xml configuration file for editing.
  4. Locate the <NodeId> element's <Identifier> and </Identifier> elements and specify the unique identifiers of the node in the OPC UA server's address space that you want to monitor. The following example shows the values that come with the OPCUaEvent.xml configuration file delivered with the probe:
    <MonitoredItemCreateRequest>
		<ItemToMonitor>
			<NodeId>
.
.
.
			<Identifier>ns=5;s=Well_24412</Identifier>
			</NodeId>
.
.
.
		</ItemToMonitor>
.
.
.
</MonitoredItemCreateRequest>
.
.
.
<MonitoredItemCreateRequest>
		<ItemToMonitor>
			<NodeId>
.
.
.
			<Identifier>ns=5;s=Well_48306</Identifier>
			</NodeId>
.
.
.
		</ItemToMonitor>
.
.
.
</MonitoredItemCreateRequest>
.
.
.
  5. Locate the <AttributeId> and </AttributeId> elements and specify the attribute identifiers for event notification. It is recommended that you specify the value 12 (which represents the String data type) for event notification or check with the OPC UA information model for additional guidance on possible values. The following example shows the values that come with the OPCUaEvent.xml configuration file delivered with the probe:
    <MonitoredItemCreateRequest>
		<ItemToMonitor>
.
.
.
			<AttributeId>12</AttributeId>
.
.
.
		</ItemToMonitor>
.
.
.
</MonitoredItemCreateRequest>
.
.
.
<MonitoredItemCreateRequest>
		<ItemToMonitor>
.
.
.
			<AttributeId>12</AttributeId>
.
.
.
		</ItemToMonitor>
.
.
.
</MonitoredItemCreateRequest>
.
.
.
  6. Locate the <MonitoringMode> and </MonitoringMode> elements and ensure that the values specified are Reporting_2 so that the Probe for OPC UA probe can receive events from the OPC UA server. The following example shows the values that come with the OPCUaEvent.xml configuration file delivered with the probe:
    <MonitoredItemCreateRequest>
		<ItemToMonitor>
.
.
.
		</ItemToMonitor>
.
.
.
<MonitoringMode>Reporting_2</MonitoringMode>
</MonitoredItemCreateRequest>
.
.
.
<MonitoredItemCreateRequest>
		<ItemToMonitor>
.
.
.
		</ItemToMonitor>
.
.
.
<MonitoringMode>Reporting_2</MonitoringMode>
</MonitoredItemCreateRequest>
.
.
.
  7. Locate the <ClientHandle> and </ClientHandle> elements and ensure that you specify a unique client handle (an integer value starting with 1) for each event notification item you want to monitor. The OPCUaEvent.xml configuration file comes with two event item requests (specified with the <MonitoredItemCreateRequest> and </MonitoredItemCreateRequest> elements) and thus defines two client handles as follows:
    <MonitoredItemCreateRequest>
.
.
.
<ClientHandle>1</ClientHandle>
.
.
.
</MonitoredItemCreateRequest>

<MonitoredItemCreateRequest>
.
.
.
<ClientHandle>2</ClientHandle>
.
.
.
</MonitoredItemCreateRequest>
.
.
.
  8. Locate the <SamplingInterval> and </SamplingInterval> elements and specify an appropriate value to instruct the OPC UA server on the frequency with which it publishes events into the queue. The following example shows the values that come with the OPCUaEvent.xml configuration file delivered with the probe:
    <MonitoredItemCreateRequest>
.
.
.
<ClientHandle>1</ClientHandle>

<SamplingInterval>1</SamplingInterval>
.
.
.
</MonitoredItemCreateRequest>
.
.
.
<MonitoredItemCreateRequest>
.
.
.
<ClientHandle>2</ClientHandle>
<SamplingInterval>0.0</SamplingInterval>
.
.
.
</MonitoredItemCreateRequest>
.
.
.
  9. Ensure that the <EventFilter> and </EventFilter> elements are included. These elements contain the <SelectClauses> and </SelectClauses> elements which are also mandatory.

    The <SelectClauses> and </SelectClauses> elements contain the event attributes you want to receive from the OPC UA server. In the OPCUaEvent.xml configuration file delivered with the probe the default event attributes are contained within the <SimpleAttributeOperand> and </SimpleAttributeOperand> elements.

    The <SimpleAttributeOperand> and </SimpleAttributeOperand> elements delivered with the OPCUaEvent.xml configuration file contain the following default event attributes:
    • EventId
    • EventType
    • SourceNode
    • SourceName
    • Time
    • ReceiveTime
    • LocalTime
    • Severity
    • Message
  10. You can modify any of the default event attributes specified within a <SimpleAttributeOperand> </SimpleAttributeOperand> element pair. You can also add event attributes by adding <SimpleAttributeOperand> </SimpleAttributeOperand> element pairs and by adding the following elements within those pairs:
    • <TypeDefinitionId> </TypeDefinitionId>
    • <Identifier> </Identifier>
    • <BrowsePath> </BrowsePath>
    • <QualitifedName> </QualifiedName>
    • <NamespaceIndex> </NamespaceIndex>
    • <Name> </Name>
    • <AttributeId> </AttributeId>

    You can also delete event attributes by deleting one or more <SimpleAttributeOperand> and </SimpleAttributeOperand> element pairs and the associated elements that they contain.

    The following example shows the EventId attribute entry delivered with the OPCUaEvent.xml configuration file:

    
.
.
.
<EventFilter>
		<SelectClauses>
				<!-- Attribute: EventId-->
				<SimpleAttributeOperand>
					<TypeDefinitionId>
					<!-- Identifier i=2041 indicates BaseEventType -->
						<Identifier>i=2041</Identifier>
					</TypeDefinitionId>
					<BrowsePath>
						<QualifiedName>
							<NamespaceIndex>0</NamespaceIndex>
							<Name>EventId</Name>
						</QualifiedName>
					</BrowsePath>
				<AttributeId>13</Attribute>
			</SimpleAttributeOperand>
.
.
.
  11. Modify the elements contained within the <WhereClause> and </WhereClause> and <Elements> and </Elements> element pairs to accommodate the needs of your environment. See the OPC UA specification for information about customizing the where clause filter for event filtering.
  12. Modify the <QueueSize> and </QueueSize> and <DiscardOldest> and </DiscardOldest> element pairs to accommodate the needs of your environment. The following example shows the default values that come with the OPCUaEvent.xml configuration file delivered with the probe:
    <MonitoredItemCreateRequest>
.
.
.
<ClientHandle>1</ClientHandle>
.
.
.
<QueueSize>1000</QueueSize>
<DiscardOldest>true</DiscardOldest>
.
.
.
</MonitoredItemCreateRequest>
.
.
.
<MonitoredItemCreateRequest>
.
.
.
<ClientHandle>2</ClientHandle>
.
.
.
<QueueSize>1000</QueueSize>
<DiscardOldest>true</DiscardOldest>
</MonitoredItemCreateRequest>
.
.
.
  13. Save the OPCUaEvent.xml configuration file with the modifications you have made.
  14. Edit the MonitoredItemsConfigFile property to specify the full path of the XML configuration file, in this example OpcUaEvent.xml. For example:
    MonitoredItemsConfigFile: "/opt/tivoli/netcool/omnibus/var/OpcUaEvent.xml"
  15. Start the probe to run and check the probe logs to ensure the monitored event items are created successfully. For example:
    Status code 0 indicate the monitored items are created 
successfully without issues.
2014-07-03T15:33:03: Debug: D-JPR-000-000: 
CreatedMonitoredItems 1 Item Id: 14 , status code:0
2014-07-03T15:33:03: Debug: D-JPR-000-000: 
CreatedMonitoredItems 2 Item Id: 15 , status code:0

Customizing the OPCUaDataChange.xml configuration file

To customize the OPCUaDataChange.xml configuration file for data change notification, do the following:

  1. Go to the directory in which the OPCUaDataChange.xml configuration file resides. For example:
    cd $OMNIHOME/var
  2. Copy the OPCUaDataChange.xml configuration file to a backup file. For example:
    cp OPCUaDataChange.xml OPCUaDataChange.xml.save

    This ensures that if you make any mistakes you can access the original OPCUaDataChange.xml configuration file.

  3. Using an appropriate editor, open the OPCUaEvent.xml configuration file for editing.
  4. Locate the <NodeId> element's <Identifier> and </Identifier> elements and specify the unique identifiers of the node in the OPC UA server's address space that you want to monitor. The following example shows the values that come with the OPCUaDataChange.xml configuration file delivered with the probe:
    <MonitoredItemCreateRequest>
		<ItemToMonitor>
			<NodeId>
.
.
.
			<Identifier>ns=2;s=1:Pipe2001?Online/FalseState</Identifier>
			</NodeId>
.
.
.
		</ItemToMonitor>
.
.
.
</MonitoredItemCreateRequest>
.
.
.
<MonitoredItemCreateRequest>
		<ItemToMonitor>
			<NodeId>
.
.
.
			<Identifier>ns=2;s=1:FC1001?Status/EnumStrings</Identifier>
			</NodeId>
.
.
.
		</ItemToMonitor>
.
.
.
</MonitoredItemCreateRequest>
.
.
.
<MonitoredItemCreateRequest>
		<ItemToMonitor>
			<NodeId>
.
.
.
			<Identifier>ns=2;s=1:Pipe2001?Measurement/EURange</Identifier>
			</NodeId>
.
.
.
		</ItemToMonitor>
.
.
.
</MonitoredItemCreateRequest>
.
.
.
  5. Locate the <AttributeId> and </AttributeId> elements and specify the attribute identifiers for event notification. It is recommended that you specify the value 12 (which represents the String data type) for event notification or check with the OPC UA information model for additional guidance on possible values. The following example shows the values that come with the OPCUaDataChange.xml configuration file delivered with the probe:
    <MonitoredItemCreateRequest>
		<ItemToMonitor>
.
.
.
			<AttributeId>13</AttributeId>
.
.
.
		</ItemToMonitor>
.
.
.
</MonitoredItemCreateRequest>
.
.
.
<MonitoredItemCreateRequest>
		<ItemToMonitor>
.
.
.
			<AttributeId>13</AttributeId>
.
.
.
		</ItemToMonitor>
.
.
.
</MonitoredItemCreateRequest>
.
.
.

<MonitoredItemCreateRequest>
		<ItemToMonitor>
.
.
.
			<AttributeId>13</AttributeId>
.
.
.
		</ItemToMonitor>
.
.
.
</MonitoredItemCreateRequest>
.
.
.
  6. Locate the <MonitoringMode> and </MonitoringMode> elements and ensure that the values specified are Reporting_2 so that the Probe for OPC UA probe can receive events from the OPC UA server. The following example shows the values that come with the OPCUaDataChange.xml configuration file delivered with the probe:
    <MonitoredItemCreateRequest>
		<ItemToMonitor>
.
.
.
		</ItemToMonitor>
.
.
.
<MonitoringMode>Reporting_2</MonitoringMode>
</MonitoredItemCreateRequest>
.
.
.
<MonitoredItemCreateRequest>
		<ItemToMonitor>
.
.
.
		</ItemToMonitor>
.
.
.
<MonitoringMode>Reporting_2</MonitoringMode>
</MonitoredItemCreateRequest>
.
.
.
<MonitoredItemCreateRequest>
		<ItemToMonitor>
.
.
.
		</ItemToMonitor>
.
.
.
<MonitoringMode>Reporting_2</MonitoringMode>
</MonitoredItemCreateRequest>
.
.
.
  7. Locate the <ClientHandle> and </ClientHandle> elements and ensure that you specify a unique client handle (an integer value starting with 1) for each data change notification item you want to monitor. The OPCUaDataChange.xml configuration file comes with three data change item requests (specified with the <MonitoredItemCreateRequest> and </MonitoredItemCreateRequest> elements) and thus defines three client handles as follows:
    <MonitoredItemCreateRequest>
.
.
.
<ClientHandle>1</ClientHandle>
.
.
.
</MonitoredItemCreateRequest>

<MonitoredItemCreateRequest>
.
.
.
<ClientHandle>2</ClientHandle>
.
.
.
</MonitoredItemCreateRequest>
.
.
.
<MonitoredItemCreateRequest>
.
.
.
<ClientHandle>3</ClientHandle>
.
.
.
  8. Locate the <SamplingInterval> and </SamplingInterval> elements and specify an appropriate value to instruct the OPC UA server on the frequency with which it publishes events into the queue. The following example shows the values that come with the OPCUaDataChange.xml configuration file delivered with the probe:
    <MonitoredItemCreateRequest>
.
.
.
<ClientHandle>1</ClientHandle>

<SamplingInterval>1</SamplingInterval>
.
.
.
</MonitoredItemCreateRequest>
.
.
.
<MonitoredItemCreateRequest>
.
.
.
<ClientHandle>2</ClientHandle>
<SamplingInterval>0</SamplingInterval>
.
.
.
</MonitoredItemCreateRequest>
.
.
.
<MonitoredItemCreateRequest>
.
.
.
<ClientHandle>3</ClientHandle>
<SamplingInterval>0</SamplingInterval>
.
.
.
</MonitoredItemCreateRequest>
  9. Customize the data change filter (specified by the <Filter> and </Filter> elements) or the aggregate filter for data change notification according to the needs of your environment. For more information on customizing the data change filter and the aggregate filter, see the OPC UA specification.

    The following example shows the data change filter elements that the <Filter> </Filter> elements contain. The example also shows placeholders for adding your data change filters. These come with the OPCUaDataChange.xml configuration file delivered with the probe:

    <MonitoredItemCreateRequest>
.
.
.
		<ClientHandle>1</ClientHandle>
.
.
.
		<!-- DataChange Filter format starts here  -->
		<!-- [Optional] Remove or leave blank if filter is not required -->
		<Filter>
			<TypeId>
			<!-- Identifier i=723 indicates DataChangeFilter type -->
				<Identifier>i=723</Identifier>
			</TypeId>
			<Body>     
				<!-- TODO: Customize your data change filter here if required>
				<DataChangeFilter>
				<!-- Trigger: Status_0, StatusValue_1, StatusValueTimestamp_2 -->
					<Trigger>StatusValue_1</Trigger>
					<!-- Dead band type:  0 (None), 1 (Absolute), 2 (Percent) -->
					<DeadbandType>0</DeadbandType>
					<!-- Dead band value: n (any double value)  -->
					<DeadbandValue>0</DeadbandValue>
				</DataChangeFilter>
			</Body>
		</Filter>   
		<!-- DataChange Filter format ends here  -->
.
.
.
</MonitoredItemCreateRequest>
.
.
.
<MonitoredItemCreateRequest>
.
.
.
<ClientHandle>2</ClientHandle>
.
.
.
<!-- Empty filter, change it if required -->
		<Filter />
.
.
.
</MonitoredItemCreateRequest>
.
.
.
<MonitoredItemCreateRequest>
.
.
.
<ClientHandle>3</ClientHandle>
.
.
.
<!-- Empty filter, change it if required -->
		<Filter />
.
.
.
</MonitoredItemCreateRequest>
.
.
.
  10. Modify the <QueueSize> and </QueueSize> and <DiscardOldest> and </DiscardOldest> elements to accommodate the needs of your environment. The following example shows the default values that come with the OPCUaDataChange.xml configuration file delivered with the probe:
    <MonitoredItemCreateRequest>
.
.
.
<ClientHandle>1</ClientHandle>
.
.
.
<QueueSize>1000</QueueSize>
<DiscardOldest>true</DiscardOldest>
.
.
.
</MonitoredItemCreateRequest>
.
.
.
<MonitoredItemCreateRequest>
.
.
.
<ClientHandle>2</ClientHandle>
.
.
.
<QueueSize>10</QueueSize>
<DiscardOldest>true</DiscardOldest>
.
.
.
</MonitoredItemCreateRequest>
.
.
.
<MonitoredItemCreateRequest>
.
.
.
<ClientHandle>3</ClientHandle>
.
.
.
<QueueSize>10</QueueSize>
<DiscardOldest>true</DiscardOldest>
.
.
.
</MonitoredItemCreateRequest>
.
.
.
  11. Save the OPCUaDataChange.xml configuration file with the modifications you have made.
  12. Edit the MonitoredItemsConfigFile property to specify the full path of the XML configuration file, in this example OpcUaDataChange.xml. For example:
    MonitoredItemsConfigFile: "/opt/tivoli/netcool/omnibus/var/OpcUaDataChange.xml"
  13. Start the probe to run and check the probe logs to ensure the monitored data change items are created successfully. For example:
    Status code 0 indicate the monitored items are created 
successfully without issues.
2014-07-03T15:33:03: Debug: D-JPR-000-000: 
CreatedMonitoredItems 1 Item Id: 14 , status code:0
2014-07-03T15:33:03: Debug: D-JPR-000-000: 
CreatedMonitoredItems 2 Item Id: 15 , status code:0