19 Integrating Java Message Service Queue (JMSQ)

Customers with access monitoring requirements involving multiple applications and data sources now have the ability to take a proactive security and compliance posture. Using the provided Java Message Service Queue (JMSQ) customers can implement near real-time risk analysis to actively identify suspected fraud or misuse.

This chapter describes how to integrate OAAM and Java Message Service Queue (JMSQ) for asynchronous integration. It contains the following sections:

• JMS Definitions

• Install the Asynchronous Integration Option

• JMS Integration

• JMS Messages

• Database Views for Entities and Transactions

• Python Rule Condition

19.1 JMS Definitions

Table 19-1 lists JMS terms and definitions. For in-depth information about Java Message Service, see Oracle Fusion Middleware Configuring and Managing JMS for Oracle WebLogic Server.

Table 19-1 JMS Definitions

Term	Definition
Messaging	Messaging is a method of communication between software components or applications. A messaging system is a peer-to-peer facility: A messaging client can send messages to, and receive messages from, any other client. Each client connects to a messaging agent that provides facilities for creating, sending, receiving, and reading messages. Messaging enables distributed communication that is loosely coupled. A component sends a message to a destination, and the recipient can retrieve the message from the destination. However, the sender and the receiver do not have to be available at the same time in order to communicate. In fact, the sender does not need to know anything about the receiver; nor does the receiver need to know anything about the sender. The sender and the receiver need to know only what message format and what destination to use. Messaging also differs from electronic mail (email), which is a method of communication between people or between software applications and people. Messaging is used for communication between software applications or software components.
Java Message Service (JMS)	Java Message Service (JMS) is a Java API that allows applications to create, send, receive, and read messages using reliable, asynchronous, loosely coupled communication. The JMS API defines a common set of interfaces and associated semantics that allow programs written in the Java programming language to communicate with other messaging implementations.
JMS Queues	JMS Queues are message queues that allow software or applications to exchange information asynchronously. Each message is addressed to a specific queue, and receiving clients extract messages from the queues established to hold their messages. Queues retain all messages sent to them until the messages are consumed or expire.
JNDI	JNDI is a java naming and directory service. The JMS queue can be accessed using the JNDI names.
JMS Queue Destination	Applications send messages to the queue. Provider stores one copy of each message until OAAM receives the message.
JMS Listener	The JMS listener is configured to listen to JMS queues for messages in XML format. A client can register a message listener with a consumer. A message listener is similar to an event listener. Whenever a message arrives at the destination, the JMS provider delivers the message; then, the contents of the message are acted upon. The XML schema in Section 19.4.2, "XML Schema Example for Message Formats" provides details about the message format.
OAAM JMS Message	OAAM JMS message contents look similar to the Oracle Adaptive Access Manager Web Services API calls. The XML schema in Section 19.4.2, "XML Schema Example for Message Formats" provides details about the message format.

19.2 Install the Asynchronous Integration Option

Table 19-2 lists a summary of the tasks for installing the Asynchronous Integration Option.

Table 19-2 Asynchronous Integration Option Installation

No.	Task	Information
1	Review prerequisites.	For information, refer to Pre-requisites.
2	Install the Asynchronous Integration Option.	For information, refer to Installing the Asynchronous Integration Option.
3	Set Up the JMS Queues.	For information, refer to Setting Up JMS Queues.
4	Update the OAAM Extensions Library.	For information, refer to Updating the OAAM Extensions Library.
5	Update the database.	For information, refer to Updating the OAAM Database.

19.2.1 Pre-requisites

Ensure that Oracle Adaptive Access Manager 11g is installed and configured before proceeding. This section contains the steps required to install the Asynchronous Integration Option.

The Asynchronous Integration Option includes various reports as Oracle Business Intelligence Publisher report templates. Ensure that Oracle Business Intelligence Publisher is installed and configured before proceeding with installation of the Asynchronous Integration Option. For information on installing Oracle Business Intelligence Publisher, see Oracle Fusion Middleware Installation Guide for Oracle Business Intelligence.

19.2.2 Installing the Asynchronous Integration Option

The Asynchronous Integration Option contains the osg_integration_kit.zip file.

To install the Asynchronous Integration Option, proceed as follows:

1. Create a work directory called osg_install on the machine where OAAM is installed. The directory can be created anywhere if it is outside the installation folder.

2. Create an osg_integration_kit directory inside the osg_install directory.

3. Locate osg_integration_kit.zip, which is located in the IAM_Home/oaam/oaam_extensions/generic directory.

4. Extract the contents of osg_integration_kit.zip to the osg_install/osg_integration_kit directory.

19.2.3 Updating the OAAM Extensions Library

The asynchronous execution functionality is implemented as an Oracle Adaptive Access Manager extension. Follow the subsequent steps to replace the default extension library:

1. Shut down all Oracle Adaptive Access Manager servers. For example, oaam_server_server1 and oaam_admin_server1.

2. Start the WebLogic Server where Oracle Adaptive Access Manager is deployed and log in to the Oracle WebLogic Administration Console.

3. Click Lock & Edit.

4. Select oracle.oaam.extensions and click Delete.

5. Navigate to Domain Environment > Deployments and lock the console.

6. Click the Install button.

7. Browse to the location of the osg_oaam_extensions.war file and select it by clicking the option next to the WAR file and clicking Next.

8. Ensure Install this deployment as a library is selected and click Next.

9. Select all OAAM servers as deployment targets. For example, oaam_admin_server1 and oaam_server_server1.

10. Click Next again to accept the defaults in this next page and then click Finish.

11. Click the Save button and then Activate Changes.

12. Start all necessary Oracle Adaptive Access Manager servers.

19.2.4 Setting Up JMS Queues

OAAM uses JMS (Java Message Service) queues as one of the integration mechanisms. OAAM listens on one or more JMS queues for XML messages. For example, an electronic patient medical records (EMR) will need a message queue to transmit transaction details that will be used by the OAAM server. For information on the XML schema and listener configuration, see Section 19.3, "JMS Integration."

With the default configuration included in osg_oaam_extension.war, OAAM listens for messages in a JMS queue with JNDI name jms/oaamDefaultQueue at t3://localhost:7001. Review this configuration and update as necessary for your deployment, per the details given in Section 19.3, "JMS Integration."

Ensure that the JMS queues specified in the listeners configuration exists and are active. If any do not exist, create them in the appropriate WebLogic Server. For information on setting up a JMS Queue on a WebLogic Server, see Oracle Fusion Middleware Configuring and Managing JMS for Oracle WebLogic Server.

19.2.5 Updating the OAAM Database

Database views for the entities and transactions can be created for use in rule conditions and reports. For information on these database views, see Section 19.5, "Database Views for Entities and Transactions." Database privileges of the OAAM database user must be updated for view creation and other database operations.

To grant the necessary privileges, log in to Oracle database with administrator credentials and run the following SQL statement, replacing dev_oaam with the OAAM database schema:

grant create view to dev_oaam.

19.3 JMS Integration

With the JMS listener implementation in an asynchronous deployment, you can configure Oracle Adaptive Access Manager to listen to JMS queues (or topics) for messages in XML format. The XML schema shown in Section 19.4.2, "XML Schema Example for Message Formats" provides details on the message format. For details on the parameters, you can refer to Oracle Fusion Middleware Java API Reference for Oracle Adaptive Access Manager. JMS message contents is similar to OAAM Web Services API calls.

19.3.1 Web Services API

The following is a subset of Web Services APIs available through JMS:

• VCryptTracker.updateLog

• VCryptTracker.updateEntity

• VCryptTracker.createTransaction

• VCryptRulesEngine.processRules

19.3.2 JMS Integration Diagram

The subsequent diagram provides an overview of the JMS integration with OAAM.

Figure 19-1 JMS integration with OAAM

Description of "Figure 19-1 JMS integration with OAAM"

The flow of interaction is as follows:

1. The application (JMS Sender) sends a message to the JMS Queue. It identifies the queue destination by the JNDI namespace.

2. The queuing system receives the message from the JMS Sender and routes the message to the destination.

3. OAAM Server listens for the message with the configured JMS Listener.

4. The message is processed by the Message Processor.

5. Information is loaded into the database as transaction or login data.

6. Rules are then run on the login and transaction data offline.

19.3.3 Registering the JMS Listener

You can configure various aspects of JMS integration using Oracle Adaptive Access Manager properties and user-defined enums. For information on user-defined enums, see Section 7.2, "Customizing or Extending OAAM By Editing Enums."

Table 19-3 shows the list of JMS configuration properties. For each queue (or topic) to be monitored, one listener must be configured by adding an enum element in the user-defined enum oracle.oaam.jms.listeners.enum. Any changes to the listener list or properties require the OAAM Server where the listeners run to be restarted.

Table 19-3 JMS Configuration Properties

Property Name	Description
jms.message.processor.default.user	When the loginId field is not specified, in the VCryptTracker.updateLog message, the value in this property will be used. Default value: JmsDefaultUser
jms.message.processor.default.usergroup	When the groupId field is not specified in the VCryptTracker.updateLog message, the value in this property will be used. Default value: default
jms.message.processor.default.ip	When the remoteIPAddr field is not specified in the VCryptTracker.updateLog message, the value in this property will be used. Default value: 127.0.0.1
jms.message.processor.default.clientver	When the clientVersion field is not specified in the VCryptTracker.updateLog message, the value in this property will be used. Default value: 1.0
jms.message.processor.default.authtype	When the clientType field is not specified in the VCryptTracker.updateLog message, the value in this property will be used. Default value: normal
jms.message.processor.default.sessionid	When the requestId field is not specified in the VCryptTracker.updateLog message, the value in this property will be used. If no value is specified, a value generated using the remoteIPAddr field value will be used. In the case of multiple message being sent in a MessageList, when the requestId field is not specified for createTransaction/updateEntity/processRules messages, the requestId used in the earlier updateLog message, if available, will be used.
jms.message.processor.default.browser.fingerprint	When the fingerPrint field is not specified in the VCryptTracker.updateLog message, the value in this property will be used.
jms.message.processor.default.flash.fingerprint	When the fingerPrint2 field is not specified in the VCryptTracker.updateLog message, the value in this property will be used.
oracle.oaam.jms.listeners.default.initial.cont ext.factory	Name of the Java class that implements the initial context factory. This value will be used to initialize the Java Naming context. Default value: weblogic.jndi.WLInitialContextFactory
oracle.oaam.jms.listeners.default.connection.factory	JNDI name of the JMS connection factory used to create queue/topic connections. Default value: weblogic.jms.ConnectionFactory
oracle.oaam.jms.listeners.enum.lsnr_1	Defines a new listener named lsnr_1. Various attributes for this listener can be specified using the properties listed. Valid Value: an integer which is not assigned to any other element in this enum
oracle.oaam.jms.listeners.enum. lsnr_1.type	Specify whether the listener will be connecting to a JMS queue or a JMS topic. Valid values: queue or topic
oracle.oaam.jms.listeners.enum. lsnr_1.url	JNDI provider URL to resolve the queue (or topic) names.
oracle.oaam.jms.listeners.enum.lsnr_1.jndiname	JNDI name of the queue or topic
oracle.oaam.jms.listeners.enum.lsnr_1.initial.context.factory	Name of the Java class that implements the initial context factory. This value will be used to initialize Java Naming context. Default value: value of property oracle.oaam.jms.listeners.default.initial.context.factory
oracle.oaam.jms.listeners.enum.lsnr_1.connection.factory	JNDI name of the JMS connection factory used to create queue/topic connections. Default value: value of property oracle.oaam.jms.listeners.default.connection.factory
oracle.oaam.jms.listeners.enum.lsnr_1.processor	Name of the Java class that implements the message processor interface. An instance of this class will be created to process messages received by this listener. Default value: oracle.oaam.jms.JmsDefaultMessageProcessor
oracle.oaam.jms.listeners.enum.lsnr_1.instancecount	Number of listeners to create to process messages from the specified queue/topic. Default value: 1

19.3.4 Configuring Message Processor

Configure Message Processor properties using Oracle Adaptive Access Manager properties and user-defined enums. For information on user-defined enums, see Section 7.2, "Customizing or Extending OAAM By Editing Enums."

The OAAM default JMS message processor processes only the messages of type javax.jms.TextMessage. Other types of messages are ignored by the JMS message processor.

To process other type of messages, you must implement a custom processor by extending either oracle.oaam.jms.JmsAbstractMessageProcessor or oracle.oaam.jms.JmsDefaultMessageProcessor and associating the processor with a JmsListener.

In addition, the default JMS message processor processes only if the contexts of the TextMessage is a XML string that conforms to the XML schema as shown in Section 19.4.2, "XML Schema Example for Message Formats."

19.4 JMS Messages

This section includes the following topics:

• JMS Message Examples

• XML Schema Example for Message Formats

• Sending a Message to a JMS Queue

19.4.1 JMS Message Examples

This section provides JMS message examples. It includes the following topics:

• VCryptTracker.updateLog

• VCryptTracker.updateEntity

• VCryptTracker.createTransaction

• VCryptRulesEngine.processRules

• MessageList

These message examples may not include all data elements supported for the messages. For a complete list of supported data elements, see Section 19.4.2, "XML Schema Example for Message Formats."

19.4.1.1 VCryptTracker.updateLog

The VCryptTracker.updateLog message is used to create or update a user-session (login) in Oracle Adaptive Access Manager. If no value is specified for the requestId data element, a unique value will be generated and used.

A VCryptTracker.updateLog message example is shown as follows:

<?xml version="1.0"?>
<OaamJmsMessage>
  <VCryptTracker.updateLog>
    <UpdateAuthResultRequest>
      <requestId>20110721_00_9004_terminal_1</requestId>
      <requestTime>07/21/2011 00:21:01</requestTime>
      <userId>9004</userId>
      <loginId>jjames</loginId>
      <isSecure>false</isSecure>
      <groupId>HealthcareUsers</groupId>
      <result>0</result>
      <clientType>10</clientType>
      <clientVersion>1.0</clientVersion>
      <remoteIPAddr>192.168.0.0</remoteIPAddr>
      <remoteHost>server.domain.com</remoteHost>
    </UpdateAuthResultRequest>
  </VCryptTracker.updateLog>
<OaamJmsMessage>

This message is the JMS equivalent of the OAAM API VCryptTracker.updateLog(). For information on the data elements (parameters), see Oracle Fusion Middleware Java API Reference for Oracle Adaptive Access Manager.

19.4.1.2 VCryptTracker.updateEntity

The VCryptTracker.updateEntity message is used to create or update a user-defined entity instance in Oracle Adaptive Access Manager.

This is a VCryptTracker.updateEntity message example:

<?xml version="1.0"?>
<OaamJmsMessage>
  <VCryptTracker.updateEntity>
    <updateEntity>
      <entityDefKey>Patient</entityDefKey>
      <contexts>
        <context>
          <name>Patient_ID</name>
          <value>21600481</value>
        </context>
        <context>
          <name>MR_Number</name>
          <value>21600481</value>
        </context>
        <context>
          <name>Short_Name</name>
          <value>Jane</value>
        </context>
        <context>
          <name>Last_Name</name>
          <value>Celebrity</value>
        </context>
        <context>
          <name>First_Name</name>
          <value>Jane</value>
        </context>
        <context>
          <name>Phone_Number</name>
          <value>603.555.0100</value>
        </context>
        <context>
          <name>Email_Address</name>
          <value>[e-mail]</value>
        </context>
        <context>
          <name>Date_Of_Birth</name>
          <value>1979-05-12 00:00:00 -0800</value>
        </context>
        <context>
          <name>Confidential_Indicator</name>
          <value>true</value>
        </context>
        <context>
          <name>homeAddr.Line1</name>
          <value>6819 Park Blvd</value>
        </context>
        <context>
          <name>homeAddr.City</name>
          <value>Los Angeles</value>
        </context>
        <context>
          <name>homeAddr.State</name>
          <value>California</value>
        </context>
        <context>
          <name>homeAddr.Zip</name>
          <value>90001</value>
        </context>
        <context>
    </updateEntity>
  </VCryptTracker.updateEntity>
</OaamJmsMessage>

This message is the JMS equivalent for the OAAM API VCryptTracker.updateEntity(). For information on the data elements (parameters), see Oracle Fusion Middleware Java API Reference for Oracle Adaptive Access Manager.

19.4.1.3 VCryptTracker.createTransaction

The VCryptTracker.createTransaction message is used to create a transaction in Oracle Adaptive Access Manager.

This is a VCryptTracker.createTransaction message example:

<?xml version="1.0"?>
<OaamJmsMessage>
  <VCryptTracker.createTransaction>
    <createTransaction>
      <requestId>20110721_00_9004_terminal_1</requestId>
      <requestTime>07/21/2011 00:21:01</requestTime>
      <transactionDefKey>pat_rec_acc</transactionDefKey>
      <status>0</status>
      <contexts>
        <context>
          <name>Person_ID</name>
          <value>9004</value>
        </context>
        <context>
          <name>Patient_ID</name>
          <value>21600481</value>
        </context>
        <context>
          <name>Action</name>
          <value>View_Records</value>
        </context>
        <context>
          <name>Application_ID</name>
          <value>Healthcare_App</value>
        </context>
        <context>
          <name>Terminal_ID</name>
          <value>terminal_1</value>
        </context>
        <context>
          <name>Item_Key</name>
          <value>image-x-20110720-156</value>
        </context>
        <context>
          <name>Is_Restricted_Item</name>
          <value>false</value>
        </context>
        <contexts>
    </createTransaction>
  </VCryptTracker.createTransaction>
</OaamJmsMessage>

This message is the JMS equivalent for the OAAM API VCryptTracker.createTransaction(). For information on the data elements (parameters), see Oracle Fusion Middleware Java API Reference for Oracle Adaptive Access Manager.

19.4.1.4 VCryptRulesEngine.processRules

The VCryptRulesEngine.processRules message is used to run OAAM rules.

This is a VCryptRulesEngine.processRules message example:

<?xml version="1.0"?>
<OaamJmsMessage>
  <VCryptRulesEngine.processRules>
    <ProcessRulesRequest>
      <requestId>20110721_00_9004_terminal_1</requestId>
      <requestTime>07/21/2011 00:21:01</requestTime>
      <profileTypeList>
        <profileType>800</profileType>
      </profileTypeList>
      <contexts></contexts>
    </ProcessRulesRequest>
  </VCryptRulesEngine.processRules>
</OaamJmsMessage>

This message is the JMS equivalent for the OAAM API VCryptRulesEngine.processRules(). For information on the data elements (parameters), see Oracle Fusion Middleware Java API Reference for Oracle Adaptive Access Manager.

19.4.1.5 MessageList

The MessageList message is used to send one or more messages in one JMS message.

This is a MessageList message example:

<?xml version="1.0"?>
<OaamJmsMessage>
  <MessageList>
    <VCryptTracker.updateLog>
    </VCryptTracker.updateLog>

    <VCryptTracker.updateEntity>
    </VCryptTracker.updateEntity>

    <VCryptTracker.updateEntity>
    </VCryptTracker.updateEntity>

    <VCryptTracker.createTransaction>
    </VCryptTracker.createTransaction>

    <VCryptRulesEngine.processRules>
    </VCryptRulesEngine.processRules>
  </MessageList>
</OaamJmsMessage>

This message is the JMS equivalent of calling multiple OAAM API calls in a batch.

In addition to batching the messages, the MessageList message also provides useful default values for requestId and transactionLogId data elements.

• When transactionLogId is not explicitly specified in the processRules message, the value returned from the earlier createTranasction message, if available, is used.

• When requestId is not explicitly specified in the createTransaction, processRules or updateEntity message, the value of the requestId data element from the previous message (within this MessageList) is used

19.4.2 XML Schema Example for Message Formats

The following XML schema example shows the details on the message format.

<?xml version="1.0" encoding="utf-8"?>
<xs:schema id="OaamJmsMessage"
           xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="OaamJmsMessage" type="MessageList"/>

    <xs:complexType name="MessageList">
      <xs:sequence>
          <xs:element name="MessageList" type="MessageList"
                    minOccurs="0" maxOccurs="unbounded"/>
          <xs:element name="VCryptTracker.updateLog"
                    type="updateLog"
                    minOccurs="0" maxOccurs="unbounded"/>
          <xs:element name="VCryptTracker.createTransaction"
                    type="createTransaction"
                    minOccurs="0" maxOccurs="unbounded"/>
          <xs:element name="VCryptRulesEngine.processRules"
                    type="processRules"
                    minOccurs="0" maxOccurs="unbounded"/>
          <xs:element name="VCryptTracker.updateEntity"
                    type="updateEntity"
                    minOccurs="0" maxOccurs="unbounded"/>
      </xs:sequence>
  </xs:complexType>

  <xs:complexType name="updateLog">
    <xs:sequence>
    <xs:element name="UpdateAuthResultRequest">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="requestId" type="xs:string"
                      minOccurs="0" maxOccurs="1"/>
          <xs:element name="requestTime" type="xs:string"
                      minOccurs="1" maxOccurs="1"/>
          <xs:element name="userId" type="xs:string"
                      minOccurs="0" maxOccurs="1"/>
          <xs:element name="loginId" type="xs:string"
                      minOccurs="0" maxOccurs="1"/>
          <xs:element name="isSecure" type="xs:boolean"
                      minOccurs="0" maxOccurs="1"/>
          <xs:element name="groupId" type="xs:string"
                      minOccurs="0" maxOccurs="1"/>
          <xs:element name="result" type="xs:integer"
                      minOccurs="0" maxOccurs="1"/>
          <xs:element name="secureCookie" type="xs:string"
                      minOccurs="0" maxOccurs="1"/>
          <xs:element name="digitalCookie" type="xs:string"
                      minOccurs="0" maxOccurs="1"/>
          <xs:element name="clientType" type="xs:integer"
                      minOccurs="0" maxOccurs="1"/>
          <xs:element name="clientVersion" type="xs:string"
                      minOccurs="0" maxOccurs="1"/>
          <xs:element name="remoteIPAddr" type="xs:string"
                      minOccurs="0" maxOccurs="1"/>
          <xs:element name="remoteHost" type="xs:string"
                      minOccurs="0" maxOccurs="1"/>
          <xs:element name="fingerPrintType" type="xs:integer"
                      minOccurs="0" maxOccurs="1"/>
          <xs:element name="fingerPrint" type="xs:string"
                      minOccurs="0" maxOccurs="1"/>
          <xs:element name="fingerPrintType2" type="xs:integer"
                      minOccurs="0" maxOccurs="1"/>
          <xs:element name="fingerPrint2" type="xs:string"
                      minOccurs="0" maxOccurs="1"/>
        </xs:sequence>
      </xs:complexType>
    </xs:element>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="createTransaction">
    <xs:sequence>
    <xs:element name="createTransaction">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="requestId" type="xs:string"
                      minOccurs="0" maxOccurs="1"/>
          <xs:element name="requestTime" type="xs:string"
                      minOccurs="0" maxOccurs="1"/>
          <xs:element name="transactionDefKey" type="xs:string"
                      minOccurs="1" maxOccurs="1"/>
          <xs:element name="status" type="xs:integer"
                      minOccurs="0" maxOccurs="1"/>
          <xs:element name="contexts"
                      minOccurs="0" maxOccurs="1">
            <xs:complexType>
              <xs:sequence>
                <xs:element name="context"
                            minOccurs="0" maxOccurs="unbounded">
                  <xs:complexType>
                    <xs:sequence>
                      <xs:element name="name" type="xs:string"
                            minOccurs="1" maxOccurs="1"/>
                      <xs:element name="value" type="xs:string"
                            minOccurs="1" maxOccurs="1"/>
                    </xs:sequence>
                  </xs:complexType>
                </xs:element>
              </xs:sequence>
            </xs:complexType>
          </xs:element>
        </xs:sequence>
      </xs:complexType>
    </xs:element>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="updateEntity">
    <xs:sequence>
     <xs:element name="updateEntity">
       <xs:complexType>
        <xs:sequence>
          <xs:element name="requestId" type="xs:string"
                      minOccurs="0" maxOccurs="1"/>
          <xs:element name="entityDefKey" type="xs:string"
                      minOccurs="1" maxOccurs="1"/>
          <xs:element name="status" type="xs:integer"
                      minOccurs="0" maxOccurs="1"/>
          <xs:element name="isReplace" type="xs:boolean"
                      minOccurs="0" maxOccurs="1"/>
          <xs:element name="createTime" type="xs:string"
                      minOccurs="0" maxOccurs="1"/>
          <xs:element name="updateTime" type="xs:string"
                      minOccurs="0" maxOccurs="1"/>
          <xs:element name="unlinkEntities"
                      minOccurs="0" maxOccurs="1">
              <xs:complexType>
                <xs:sequence>
                  <xs:element name="entityRelation"
                              type="xs:string"
                              minOccurs="0"
                              maxOccurs="unbounded"/>
                </xs:sequence>
              </xs:complexType>
            </xs:element>
            <xs:element name="contexts"
                      minOccurs="1" maxOccurs="1">
              <xs:complexType>
              <xs:sequence>
                  <xs:element name="context"
                              minOccurs="0 maxOccurs="unbounded">
                    <xs:complexType>
                      <xs:sequence>
                        <xs:element name="name" type="xs:string"
                                    minOccurs="1" maxOccurs="1"/>
                        <xs:element name="value" type="xs:string"
                                    minOccurs="1" maxOccurs="1"/>
                      </xs:sequence>
                    </xs:complexType>
                  </xs:element>
                </xs:sequence>
              </xs:complexType>
            </xs:element>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="processRules">
    <xs:sequence>
    <xs:element name="ProcessRulesRequest">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="requestId" type="xs:string"
                      minOccurs="0" maxOccurs="1"/>
          <xs:element name="requestTime" type="xs:string"
                      minOccurs="0" maxOccurs="1"/>
          <xs:element name="transactionLogId" type="xs:integer"
                      minOccurs="0" maxOccurs="1"/>
          <xs:element name="extTransactionId" type="xs:string"
                      minOccurs="0" maxOccurs="1"/>
          <xs:element name="profileTypeList"
                      minOccurs="1" maxOccurs="1">
            <xs:complexType>
              <xs:sequence>
              <xs:element name="profileType" type="xs:integer"
                          minOccurs="1" maxOccurs="unbounded"/>
              </xs:sequence>
            </xs:complexType>
          </xs:element>
        </xs:sequence>
      </xs:complexType>
    </xs:element>
    </xs:sequence>
  </xs:complexType>

</xs:schema>

19.4.3 Sending a Message to a JMS Queue

The following java code is an example of how to write a message to send to the JMS queue.

/* XML Message */ 
String xmlString = ; 
 
/* get reference to queue from its JNDI name */ 
javax.jms.Queue queue = ; 
 
/* get a queue connection from connection factory */ 
QueueConnection queueConn = ; 
 
QueueSession queueSess   = conn.createQueueSession(...); 
QueueSender  queueSender = queueSess.createSender(queue); 
 
TextMessage msg = queueSess.createTextMessage(xmlString); 
 
queueSender.send(msg); 

19.5 Database Views for Entities and Transactions

Users can define entities and transactions in Oracle Adaptive Access Manager with any number of data fields. In addition, transactions can also be defined to reference entities. Oracle Adaptive Access Manager persists the entity and transaction data in the database. The OAAM database schema is designed to store any type of entity and transaction data. However this generic schema makes it challenging to write SQL queries to work with the entity and transaction data.

Oracle Adaptive Access Manager provides a command line tool to generate the SQL script file which contains SQL queries to create views for entities and transactions in Oracle Adaptive Access Manager. These database views makes is easier to query the transaction and entity data and create reports using Oracle Business Intelligence Publisher.

19.5.1 Generating SQL Script File

To generate the SQL script:

1. Set up the OAAM CLI environment.

   For instructions on setting up the OAAM command line environment, see "Setting Up the CLI Environment" in Oracle Fusion Middleware Administrator's Guide for Oracle Adaptive Access Manager.

2. Generate the SQL script file.

   To generate the SQL script, run the following command from the OAAM CLI working folder:

   $ sh generateTrxEntityViewsSQL.sh
   

   The default file name is createTrxEntityViews.sql. Optionally, the administrator can change the default filename by adding property with the name oaam.trxentityview.filename with required filename as the value.

3. Create the database views for entities and transactions.

   Follow these steps to create the database views for entities and transactions stored in the OAAM database:

   1. Ensure that the OAAM database schema has privileges to create views.

   2. Connect to database using the OAAM database schema user.

      For example:

      sqlplus DEV_OAAM/PASSWORD
      

   3. Run the createTrxEntityViews.sql script:

      SQL>@ createTrxEntityViews.sql
      

      This script creates database views for each transaction and entity defined in the OAAM database.

19.5.2 Entity View Details

For each entity defined in Oracle Adaptive Access Manager, one view will be created with the name oaam_ent_entity_key. entity_key will be replaced by the key of the entity as defined in Oracle Adaptive Access Manager.

The created view will contain one column for each data defined in the entity. For the naming convention of the data columns and the view name, see Section 19.5.4, "Identifiers."

In addition to the data columns, the created view will contain the following columns:

• entity_id: unique identifier for the entity instance

• create_time: time the entity was created

• update_time: time of last update to the entity

19.5.3 Transaction View Details

For each transaction defined in Oracle Adaptive Access Manager, one view will be created with the name oaam_trx_transaction_key. transaction_key will be replaced by the name of the transaction as defined in Oracle Adaptive Access Manager.

The created view will contain one column for each data defined in the transaction. For the naming convention of the data columns and the view name, seeSection 19.5.4, "Identifiers."

The created view will contain one column for each entity referenced in the transaction to store the entity_id of the referenced entity, that is, the entity_id column in the oaam_ent_entity_key view. Spaces in the instance names will be replaced with an underscore in the column name.

In addition to the data columns, the created view will contain the following columns:

• log_id: unique identifier for the transaction

• user_id: user who performed this transaction

• request_id: session in which this transaction was performed

• ext_trx_id: external ID of this transaction

• status: status of the transaction

• create_time: time the entity was created

• update_time: time of last update to the entity

• created_hour: create time truncated to nearest hour

• created_day: create time truncated to nearest day

• created_week: create time truncated to nearest week

• created_month: create time truncated to nearest month

• created_year: create time truncated to nearest year

19.5.4 Identifiers

The Oracle database limits the length of identifiers (table, view, and column names) to 30 characters. To ensure that the views created by this script comply with this requirement, you should limit the length of entity, transaction, and data field names to the following:

• entity: 21 (view names will be oaam_ent_ + entity_key)

• transaction: 21 (view names will be oaam_trx_ + transaction_key)

• data-field: 28 (column name will be d_ + data_element_name)

• entity-ref: 20 (column name will be relationship_name + _entity_id)

If the script finds any names longer than these limits, the script will trim the identifier. Look for such trimmed column and view names while writing SQL queries on the created views.

Space, dash ("-") and period (".") characters in the names will be replaced with an underscore.

19.6 Python Rule Condition

You can use the Python rule condition to evaluate the python expression using OAAM objects.

19.6.1 Python Expression

The Asynchronous Integration Option includes an OAAM condition to execute a Python expression. You must import the condition from the osg_install/osg_integration_kit/osg_rule_conditions.zip file. Python expressions enable the writing of sophisticated conditions without having to write custom Java code. Expressions used in this condition can contain any Python construct, including function calls, SQL queries, multiple statements, and so on. The only requirement is that the expression must return the condition result (a boolean value) in a variable named oaamResult. Expressions have access to OAAM APIs and objects like session, user, device, location, transaction, logger, and so on as listed in Section 19.6.2, "Objects Available in Python."

19.6.2 Objects Available in Python

Table 19-4 lists the objects (variables) accessible from Python expressions. For information on available methods, see the corresponding Java interface of each variable in Oracle Fusion Middleware Java API Reference for Oracle Adaptive Access Manager.

Table 19-4 Objects Available in Python

Python Variable	Java Interface	Description
oaamAuth	VCryptAuth	OAAM Java API
oaamTracker	VCryptTracker	OAAM Java API
oaamRulesEngine	VCryptRulesEngine	OAAM Java API
oaamCommon	VCryptCommon	OAAM Java API
oaamCC	VCryptCC	OAAM Java API
oaamSession	VCryptTrackerSession	Current session
oaamUser	VCryptTrackerUser	Current session user
oaamDevice	VCryptTrackerDevice	Current session device
oaamLocation	VCryptTrackerLocation	Current session location
oaamTrx	OaamTrxHelper	Current transaction
oaamDb	OaamDbHelper	OAAM DB query interface
oaamLogger	Logger	Logger object for debugging

19.6.3 Examples

Table 19-5 lists a few expressions you can use in the Python Expression condition.

Table 19-5 Python Expressions

Description	Python Expression
Is this the first time the user used this device?	oaamResult = oaamDevice.isUserFirstTime(oaamUser.userId);
Did the current location have more than 5 devices in the past 24 hours?	deviceCount = 5; durationUnit = 24; durationUnitType = 4; # hours authStatus = 0; # success oaamResult = oaamLocation.checkDeviceCountMorethan( deviceCount, authStatus, durationUnit, durationUnitType);
Did the current device have more than 5 users in the past 1 hour?	users = oaamDevice.getAllUsersForDevice(3600); oaamResult = (len(users) > 5);
Does the AccessType attribute of the current transaction contain the value Prescription?	oaamResult = (oaamTrx.AccessType == "Prescription");
Do the patient and provider entities in the current transaction have the same last name?	oaamResult = (oaamTrx.provider.LastName == oaamTrx.patient.LastName);
When the Single-sign-on login-type is COOKIE_LOGIN, i,e., authClientType=1, check if this is the first time the user used this device	oaamResult = ((oaamSession.authClientType == 11) and oaamDevice.isUserFirstTime(oaamUser.userId));
Did the provider in the current transaction have an appointment with the patient in a given duration?	from jarray import array; from java.lang import String; from java.lang import Object; apptCount = oaamDb.executeSqlSelectSingleValue( "select count(*)from oaam_ent_appointmentinfo appt where appt.PatientId=:patientId and appt.ProviderId=:providerId and appt.StartTime between (:trxTime - (:withinHours / 24.0)) and (:trxTime)'", array(['patientId', 'providerId', 'trxTime', 'withinHours'], String), array([oaamTrx.patient.PatientId, oaamTrx.provider.ProviderId, oaamTrx.createTime, 1], Object)); oaamResult = (apptCount.intValue() > 0);
Execute user-defined SQL function to determine whether the patient and provider are co-workers	from jarray import array; from java.lang import String; from java.lang import Object; isCoworker = oaamDb.executeSqlSelectSingleValue( "select IsSameWorkLocation(:patientID, :providerID) from dual", array(['patientID', 'providerID'], String), array([oaamTrx.patient.PatientID, oaamTrx.provider.ProviderID], Object)); oaamResult = (isCoworker.intValue() > 0);