| Oracle® Business Activity Monitoring Architect User's Guide 10g (10.1.3.1.0) Part Number B28992-01 |
|
|
View PDF |
| Oracle® Business Activity Monitoring Architect User's Guide 10g (10.1.3.1.0) Part Number B28992-01 |
|
|
View PDF |
This chapter contain the information needed to create and manage Enterprise Message Sources.
This chapter contains the following topics:
Enterprise message sources are providers of the real-time information flowing through the enterprise to the Active Data Cache. Each enterprise message source connects to a specific message queue and the information is delivered into a data object in the Active Data Cache. Data objects are used in reports and the data is viewed by users.
After an enterprise message source is defined, it can be included in a Plan for loading the information to a data object in the Active Data Cache.
To view the existing enterprise message sources:
Select Enterprise Message Sources from the Architect function list.
This section contains the following topics:
When you define an enterprise message source, you specify all fields in the messages to be received. Some messaging systems have a variable number of user-defined fields, while systems have a fixed number of fields.
For any string type field, you can apply formatting to that field to break apart the contents of the field into separate, individual fields to be sent through the Data Flow of the Plan. This is useful for messaging systems where you cannot create user-defined fields and the entire message body is received as one large field. The formatting specifications allow you to specify the path to a location in the XML tree, and then extract the attributes or tags as fields.
Before defining an enterprise message source, you must be familiar with the third party application providing the messages so that you can specify the message source connection details in Architect.
To define an enterprise message source:
Select Enterprise Message Sources from the Architect function list.
Click Create.
Select the type of enterprise message source from the list in the right frame and click Select.
Enter a name for the enterprise message source.
See one of the following sections for information about settings:
For all types, you specify the dataflow name, data type, maximum size, and formatting included. Formatting can be set to XML with column values contained in tags, or in attributes, or no formatting. For advanced formatting using XSL transformations, see "Using Advanced Formatting".
Settings for Oracle (AS JMS and OJMS) include:
Initial Context Factory.
For 10.1.3: oracle.j2ee.rmi.RMIInitialContextFactory
For 10.1.2: com.evermind.server.rmi.RMIInitialContextFactory
JNDI Service Provider URL. For standalone use oc4j: ormi://machine_name/ where machine_name is the OC4J installed host, and for production use Application Server: opmn:ormi://<machine_name>:<opmn request port>:home where machine_name is the application server installed host, opmn request port could be found from looking at opmn.xml in <App server install location>/opmn/conf
TopicConnectionFactory Name. java:comp/resource/BAMTTT/TopicConnectionFactories/bam_ttq_tab
Topic Name. java:comp/resource/BAMTTT/Topics/bam_ttq
JMS Message Type. TextMessage.
Durable Subscriber Name. BAMFilteredSubscription
Message Selector. Message selector, for example, BAMFilter='true'
Client ID. ClientID
Settings for BEA WebLogic Server include:
Initial Context Factory. Context factory to use, for example, weblogic.jndi.WLInitialContextFactory
JNDI Service Provider URL. File path or URL, for example, t3://localhost:6733
TopicConnectionFactory Name. Connection factory of the topic, for example, JMSConnectionFactory
Topic Name. Topic name, for example, JMSTopic
JMS Message Type. Select the message type such as BytesMessage, MapMessage, ObjectMessage, StreamMessage, TextMessage.
Durable Subscriber Name. Name of the subscriber, for example, BAMFilteredSubscription.
Message Selector. Message selector, for example, BAMFilter='true'
Client ID. Client ID, for example, BAMFilteredClientID
Settings for IBM WebSphere MQ include:
Initial Context Factory. Context factory to use, for example, com.sun.jndi.fscontext.RefFSContextFactory
JNDI Service Provider URL. File path or URL, for example, file:/C:/JNDI-Directory
TopicConnectionFactory Name. Connection factory of the topic, for example, ivtTCF
Topic Name. Topic name, for example, ivtT
JMS Message Type. Select the message type such as BytesMessage, MapMessage, ObjectMessage, StreamMessage, TextMessage.
Durable Subscriber Name. Name of the subscriber, for example, BAMFilteredSubscription.
Message Selector. Message selector, for example, BAMFilter='true'
Client ID. Client ID, for example, BAMFilteredClientID
Settings for Microsoft MSMQ include:
Queue name. Type the MSMQ queue name, for example, horus\retail_queue.
Message body character encoding. Select Unicode UTF-8, UTF-16, UTF-7, or ASCII.
Look for byte order marks at start of message body. Select Yes or No.
The field names are already defined as ID, Arrival Time, Label, and Data. If you select a type of formatting, you must provide a path such as row, the tag or attribute name for each item, the name in the data flow, and maximum size.
You can use database triggers and a web service to send data to the ADC using Microsoft MSMQ. For more information, refer to:
http://<host>:<http_port>/oraclebam/Services/EnterpriseLink/EnterpriseLink.asmx
When using a trigger, the directory containing the service requires anonymous access or basic authentication to be set in IIS.
The following example includes a portion of an Oracle database trigger using this service:
utl_http.request(http://host/oraclebam/services/enterpriselink/ enterpriselink.asmx/SendToMSMQ?strQueueName=private$\OracleTriggerTest&strData= '<?xmlversion="1.0"?><row><fname>'||fname||'</fname><lname>' ||lname||'</lname><title>'||title||'</title><location>'||location|| '</location></row>'&strLabel='' HTTP/1.1); End;
Internet Explorer has a maximum URL length of 2,048 characters which also applies to POST and GET request URLs. If you use the GET method, the limit includes the number of characters in the actual path. POST is not limited by the URL size when submitting name-value pairs since they are transferred in the header and not the URL.
Settings for See Beyond JMS Intelligent Queue include:
Initial Context Factory. Context factory to use, for example, com.sun.jndi.fscontext.RefFSContextFactory
JNDI Service Provider URL. File path or URL, for example, file:/C:/JNDI-Directory
TopicConnectionFactory Name. Connection factory of the topic, for example, ivtTCF
Topic Name. Topic name, for example, ivtT
JMS Message Type. Select the message type such as BytesMessage, MapMessage, ObjectMessage, StreamMessage, TextMessage.
Durable Subscriber Name. Name of the subscriber, for example, BAMFilteredSubscription.
Message Selector. Message selector, for example, BAMFilter='true'
Client ID. Client ID, for example, BAMFilteredClientID
Settings for Sonic MQ include:
Initial Context Factory. Context factory to use, for example, com.sun.jndi.fscontext.RefFSContextFactory
JNDI Service Provider URL. File path or URL, for example, file:/C:/JNDI-Directory_SonicMQ
TopicConnectionFactory Name. Connection factory of the topic, for example, sonicTCF
Topic Name. Topic name, for example, sonicT
JMS Message Type. Select the message type such as BytesMessage, MapMessage, ObjectMessage, StreamMessage, TextMessage.
Durable Subscriber Name. Name of the subscriber, for example, BAMFilteredSubscription.
Message Selector. Message selector, for example, BAMFilter='true'
Client ID. Client ID, for example, BAMFilteredClientID
Settings for Tibco Rendezvous include:
Initial Context Factory. Context factory to use, for example, com.tibco.tibjms.naming.TibjmsInitialContextFactory
JNDI Service Provider URL. File path or URL, for example, tibjmsnaming://localhost:7222
TopicConnectionFactory Name. Connection factory of the topic, for example, TopicCF
Topic Name. Topic name, for example, Topic
JMS Message Type. Select the message type such as BytesMessage, MapMessage, ObjectMessage, StreamMessage, TextMessage.
Durable Subscriber Name. Name of the subscriber, for example, BAMFilteredSubscription.
Message Selector. Message selector, for example, BAMFilter='true'
Client ID. Client ID, for example, BAMFilteredClientID
Settings for WebMethods include:
Initial Context Factory. Context factory to use, for example, com.sun.jndi.fscontext.RefFSContextFactory
JNDI Service Provider URL. File path or URL, for example, file:/C:/JNDI-Directory
TopicConnectionFactory Name. Connection factory of the topic, for example, ivtTCF
Topic Name. Topic name, for example, ivtT
JMS Message Type. Select the message type such as BytesMessage, MapMessage, ObjectMessage, StreamMessage, TextMessage.
Durable Subscriber Name. Name of the subscriber, for example, BAMFilteredSubscription.
Message Selector. Message selector, for example, BAMFilter='true'
Client ID. Client ID, for example, BAMFilteredClientID
The Advanced formatting options allow an enterprise message source to contain a user-supplied XSL Transformation (XSLT) for each formatted field in the message.
Uses for XSL transformations include:
Handling of hierarchical data. The Data Flow does not handle hierarchical data. The XSL transformation can flatten the received XML into a single record with repeating fields.
Handling of message queues that contain messages of more than one type in a single queue. The Data Flow requires that all records from the Message Receiver be of the same schema. The enterprise message source output can be defined as a combined superset of the message schemas that will be received, and the XSL transformation can identify each message type and map it to the superset schema as appropriate.
Handling of XML that, while not expressing hierarchical data, does contain needed data at more than one level in the XML. EMS formatting can only read from one level with the XML. The XSL transformation can identify the data needed at various levels in the input XML and output it all in new XML that contains all of the data combined at one level.
Handling changes to message formats without affecting Plans. If a complex message-processing Plan exists and the format of the messages, or the data in them, is changed slightly, the XSL transformation could compensate for this change so that changes to the Plan are not required.
To specify an XSL transformation:
In an enterprise message source that you are defining or editing, select one of the XML formatting options in the Formatting column.
Click Advanced formatting options.
The Advanced Formatting dialog displays.
Type or paste the XSL code for the transformation for the XML in this field. You might want to write the XSL in another editing tool and then copy and paste the code into this dialog.
In the Sample XML to transform field, type sample XML to test the transformation against. The sample XML is not saved in this dialog and will not be displayed if you close and open this dialog.
Click Verify transformation syntax to check the XSL syntax.
Click Test transformation on sample XML to test your transformation.
The results are displayed in the field underneath the links. If any errors are found in the XSL syntax, the sample XML syntax, or during the transformation, the error text is shown in this field.
The Enterprise Message Receiver Transform receives messages from the queue, and converts them to a traditional row and column format to send into the Data Flow.
The records in the Data Flow must be flat records because hierarchical data is not supported. The Message Receiver can generate multiple Data Flow records for each received message, but all records must have the same schema.
In the Enterprise Message Source definition, a formatting specification can be provided for any fields in the message of type String to parse XML inside the string field. Typically for MSMQ, the Body field of the message contains the XML for the message.
The formatting specification indicates how the received XML is to be converted into one or more records. It assumes that the fields of data are contained within a particular single node-type within the XML, either as attributes of that node or as tags directly contained in that node. Although this formatting can handle multiple instances of the node, it cannot handle multiple node types, nor can it handle hierarchies in the XML.
The following example shows how a simple message might look:
<order>
<item>
<description>Fuel pump</description>
<price>128.95</price>
<quantity>1</quantity>
</item>
<item>
<description>Fuel filter</description>
<price>12.95</price>
<quantity>1</quantity>
</item>
</order>
The generated records for the preceding message might look like the following:
| Description | Price | Quantity |
|---|---|---|
| Fuel pump | 128.95 | 1 |
| Fuel filter | 12.95 | 1 |
To handle complex XML, or do formatting or parsing not supported by the Enterprise Message Receiver, the Enterprise Message Source can contain an XSL-T specification to "preprocess" the received XML before it is passed to the Message Receiver formatting. This transformation can be complex, and can contain any code supported by the Microsoft .NET XSL-T Processor, including scripting. Any field in the received message of type String can have an XSL-T preprocessor. In the case of MSMQ, this is almost always the Body field of the message.
The XSL-T code can be used for any purpose required. For this example, it is used to translate hierarchical message XML into simpler XML that can be handled by the formatting. Typically, this would mean flattening of the hierarchical message into multiple records, where the higher-level field values repeat.
Phoenix Debt Order Messages
The XML in these messages expresses a hierarchy. Each message contains a root PhoenixDebtOrder tag, which contains one or more PhoenixDebtOrderProduct tags, which each contain one or more PhoenixDebtOrderIOI tags:
<PhoenixDebtOrder attr1 attr2>
<PhoenixDebtOrderProduct attr3 attr4>
<PhoenixDebtOrderIOI attr5 attr6>
The values at each level are contained in attributes on the tags.
The purpose of the XSL transformation is to convert the preceding hierarchy into a flat structure containing a node for each PhoenixDebtOrderIOI node, with the values for the parent tags repeated in each instance:
<PhoenixDebtOrder> <Flat attr1 attr2 attr3 attr4 attr5 attr6>
The XSL assumes that the attribute names are different at each level, or if they are not different, that they represent the same information and do not need to be repeated.
The XSL does a generic copy of all of the attributes at each level, and no specific attribute names are referenced. If attributes are added or removed at any level, it is not necessary to change the XSL code, although in such cases, it is necessary to change the formatting in the Enterprise Message Source.
The following text shows a sample Phoenix Debt Order message:
<PhoenixDebtOrder ord_id="1847494630" rgn_id="0" last_modified_dt="2003-06-23T16:56:35.900" ae_up_id="0" deleted_ind="0" iss_id="1847492081" brk_id="1877504017" inst_inv_id="0" swap_ind="0" identity_nm=""> <PhoenixDebtOrderProduct ord_id="1847494630" prd_id="1847494611" price_basis="spread" ioi_ccy_id="1847483827" canceled_ind="0" inst_alloc_qty="" ret_alloc_qty=""> <PhoenixDebtOrderIOI ord_ioi_id="1847558620" ord_id="1847494630" ioi_prd_id="1847494611" ioi_size="4770000000" ioi_px="14.123512"/> <PhoenixDebtOrderIOI ord_ioi_id="1847558621" ord_id="1847494630" ioi_prd_id="1847494611" ioi_size="5540000000" ioi_px="15.252500"/> <PhoenixDebtOrderIOI ord_ioi_id="1847558619" ord_id="1847494630" ioi_prd_id="1847494611" ioi_size="3330000000" ioi_px="12.500000"/> </PhoenixDebtOrderProduct> <PhoenixDebtOrderProduct ord_id="1847494630" prd_id="1847494612" price_basis="spread" ioi_ccy_id="1847483827" canceled_ind="0" inst_alloc_qty="" ret_alloc_qty=""> <PhoenixDebtOrderIOI ord_ioi_id="1847558620" ord_id="1847494630" ioi_prd_id="1847494612" ioi_size="5880000000" ioi_px="14.124512"/> <PhoenixDebtOrderIOI ord_ioi_id="1847558621" ord_id="1847494630" ioi_prd_id="1847494612" ioi_size="4430000000" ioi_px="12.252500"/> </PhoenixDebtOrderProduct> </PhoenixDebtOrder>
The following text shows the transformed XML produced for the previous example:
<PhoenixDebtOrder> <Flat ord_id="1847494630" rgn_id="0" last_modified_dt="2003-06-23T16:56:35.900" ae_up_id="0" deleted_ind="0" iss_id="1847492081" brk_id="1877504017" inst_inv_id="0" swap_ind="0" identity_nm="" prd_id="1847494611" price_basis="spread" ioi_ccy_id="1847483827" canceled_ind="0" inst_alloc_qty="" ret_alloc_qty="" ord_ioi_id="1847558620" ioi_prd_id="1847494611" ioi_size="4770000000" ioi_px="14.123512"/> <Flat ord_id="1847494630" rgn_id="0" last_modified_dt="2003-06-23T16:56:35.900" ae_up_id="0" deleted_ind="0" iss_id="1847492081" brk_id="1877504017" inst_inv_id="0" swap_ind="0" identity_nm="" prd_id="1847494611" price_basis="spread" ioi_ccy_id="1847483827" canceled_ind="0" inst_alloc_qty="" ret_alloc_qty="" ord_ioi_id="1847558621" ioi_prd_id="1847494611" ioi_size="5540000000" ioi_px="15.252500"/> <Flat ord_id="1847494630" rgn_id="0" last_modified_dt="2003-06-23T16:56:35.900" ae_up_id="0" deleted_ind="0" iss_id="1847492081" brk_id="1877504017" inst_inv_id="0" swap_ind="0" identity_nm="" prd_id="1847494611" price_basis="spread" ioi_ccy_id="1847483827" canceled_ind="0" inst_alloc_qty="" ret_alloc_qty="" ord_ioi_id="1847558619" ioi_prd_id="1847494611" ioi_size="3330000000" ioi_px="12.500000"/> <Flat ord_id="1847494630" rgn_id="0" last_modified_dt="2003-06-23T16:56:35.900" ae_up_id="0" deleted_ind="0" iss_id="1847492081" brk_id="1877504017" inst_inv_id="0" swap_ind="0" identity_nm="" prd_id="1847494612" price_basis="spread" ioi_ccy_id="1847483827" canceled_ind="0" inst_alloc_qty="" ret_alloc_qty="" ord_ioi_id="1847558620" ioi_prd_id="1847494612" ioi_size="5880000000" ioi_px="14.124512"/> <Flat ord_id="1847494630" rgn_id="0" last_modified_dt="2003-06-23T16:56:35.900" ae_up_id="0" deleted_ind="0" iss_id="1847492081" brk_id="1877504017" inst_inv_id="0" swap_ind="0" identity_nm="" prd_id="1847494611" price_basis="spread" ioi_ccy_id="1847483827" canceled_ind="0" inst_alloc_qty="" ret_alloc_qty="" ord_ioi_id="1847558621" ioi_prd_id="1847494612" ioi_size="4430000000" ioi_px="12.252500"/> </PhoenixDebtOrder>
A single parameter is passed to the XSL transformation from the Message Receiver Transform, called "SequenceNumber". This is an integer that starts at one and increments for each message received. This number can be used to identify the set of records generated for a single original message, or for any other purpose desired by the XSL code.
In this case, the XSL code does use this number to identify the set of records that are generated for a single message, but with a twist.
The goal is for an iterating SubPlan within the Data Flow to iterate once for each set of records produced by a single message, using the Iterate each time a key field changes value option for the SubPlan. The XSL passes the sequence number in the Data Flow records as a field named "seq_no", and this is the key field used for SubPlan iteration.
The SubPlan does not actually iterate until the key value changes. If a gap in time exists between messages, completion of processing for the prior message is delayed until the next message is received since changes are not committed until the SubPlan iterates through using the "Group Transaction" feature. To solve this problem, the XSL always generates an extra "dummy" record, or tag, at the end of the set of records for each message. Since the sequence numbers are incremented by one, the XSL can know what the next sequence number will be, unlike with an MSMQ message ID. It can use the sequence number that the next message will use. The Data Flow contains logic to recognize and ignore the dummy records, which are denoted by an "ord_id" attribute value of "dummy".
Example 3-1 shows the XSLT code contained within the Enterprise Message Source.
Example 3-1 Enterprise Message Source XSLT
<?xml version="1.0"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:param name="SequenceNumber"/>
<xsl:output method="xml" omit-xml-declaration="yes"/>
<xsl:template match="/">
<PhoenixDebtOrder>
<xsl:choose>
<xsl:when test="PhoenixDebtOrder">
<xsl:apply-templates select="PhoenixDebtOrder"/>
</xsl:when>
<xsl:otherwise>
<!-- There is no root PhoenixDebtOrder tag -->
<!-- Generate a tag with no attribute values -->
<Flat>
<xsl:attribute name="seq_no">
<xsl:value-of select="$SequenceNumber"/></xsl:attribute>
</Flat>
</xsl:otherwise>
</xsl:choose>
<!-- Dummy row, always generated at the end, with the sequence number
that the next set of rows will have. Used to cause the SubPlan
to iterate immediately after the receipt of all rows for this order-->
<Flat ord_id="Dummy">
<xsl:attribute name="seq_no">
<xsl:value-of select="$SequenceNumber + 1"/></xsl:attribute>
</Flat>
</PhoenixDebtOrder>
</xsl:template>
<xsl:template match="PhoenixDebtOrder">
<xsl:choose>
<xsl:when test="PhoenixDebtOrderProduct">
<xsl:apply-templates select="PhoenixDebtOrderProduct"/>
</xsl:when>
<xsl:otherwise>
<!-- There are no products -->
<!-- Generate a tag with only the attributes from the root
PhoenixDebtOrder tag -->
<Flat>
<xsl:for-each select="@*">
<xsl:copy-of select="."/>
</xsl:for-each>
<xsl:attribute name="seq_no">
<xsl:value-of select="$SequenceNumber"/></xsl:attribute>
</Flat>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<xsl:template match="PhoenixDebtOrderProduct">
<xsl:choose>
<xsl:when test="PhoenixDebtOrderIOI">
<xsl:apply-templates select="PhoenixDebtOrderIOI"/>
</xsl:when>
<xsl:otherwise>
<!-- This product has no IOIs -->
<!-- Generate a tag with only the attributes from the root
PhoenixDebtOrder tag and the parent PhoenixDebtOrderProductTag -->
<Flat>
<xsl:for-each select="../@*">
<xsl:copy-of select="."/>
</xsl:for-each>
<xsl:for-each select="@*">
<xsl:copy-of select="."/>
</xsl:for-each>
<xsl:attribute name="seq_no">
<xsl:value-of select="$SequenceNumber"/></xsl:attribute>
</Flat>
<!-- Add a linebreak to the output XML, just for appearance -->
<xsl:text disable-output-escaping="yes"> </xsl:text>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<xsl:template match="PhoenixDebtOrderIOI">
<Flat>
<!-- Root PhoenixDebtOrder attributes -->
<xsl:for-each select="../../@*">
<xsl:copy-of select="."/>
</xsl:for-each>
<!-- PhoenixDebtOrderProduct attributes -->
<xsl:for-each select="../@*">
<xsl:copy-of select="."/>
</xsl:for-each>
<!-- PhoenixDebtOrderIOI attributes -->
<xsl:for-each select="@*">
<xsl:copy-of select="."/>
</xsl:for-each>
<xsl:attribute name="seq_no">
<xsl:value-of select="$SequenceNumber"/></xsl:attribute>
</Flat>
<!-- Add a linebreak to the output XML, just for appearance -->
<xsl:text disable-output-escaping="yes"> </xsl:text>
</xsl:template>
</xsl:stylesheet>
To edit an enterprise message source:
Select Enterprise Message Sources from the Architect function list.
Click the name of the enterprise message source.
The message source properties display.
Click Edit.
Make the changes and click Save.
To copy an enterprise message source:
Select Enterprise Message Sources from the Architect function list.
Click the name of the enterprise message source to copy.
The message source properties display.
Click Copy.
Type a new name for the copy of the enterprise message source and click Copy.
The new message source is created and added to the list.
To delete an enterprise message source:
Select Enterprise Message Sources from the Architect function list.
Click the name of the enterprise message source to delete.
The message source properties display.
Click Delete.
Click OK to confirm that you want to delete the message source.
The message source is deleted.
