Working with Advanced Queue Manager (WWMQ)

Advanced queuing allows you to send messages between Oracle Retail Order Management System and other applications using database-integrated message queuing.

Advanced queuing is made up of the following components:

Queuing Database	The Oracle database used for queue processing.
Queue Manager	Receives messages and puts them into the appropriate queue. The Work with Advanced Queue Manager (WWMQ) menu option defines the connection information to the queuing database.
Queues	An area where messages are stored so that they can be processed in sequential order (first in, first out). Each queue is maintained by the queue manager, which puts messages it receives into the appropriate queue.
Queue Table	Queues are stored in queue tables in the database.
Message	The actual data, such as an XML message, that is inserted into and retrieved from a queue. The message contains: • control information (metadata) to define message properties used to manage the message. • payload, or the actual data, in the message
Message log	The Message log tracks XML and transactional messages generated or received by Oracle Retail Order Management System.

In this chapter:

• Advanced Queuing Process

- Outbound Process Flow

- Inbound Process Flow

• Advanced Queuing Setup

- JMS RESTful Web Service

- Basic Authentication

- Viewing Messages on a Queue in the Database

• Work with Advanced Queue Manager Screen

• Create Advanced Queue Manager Screen

For more information: See:

• Generic Web Services for more information on the web services available for Oracle Retail Order Management System.

• Working with Web Service Authentication (WWSA) for more information on how to define which Oracle Retail Order Management System web service endpoints require authentication and the valid web service authentication users for each web service

• Logs for more information on the Oracle Retail Order Management System application logs.

• Working with Integration Layer Processes (IJCT) for more information on the processes that transmit data between Oracle Retail Order Management System and and external system.

Advanced Queuing Process

Outbound Process Flow

1. A user or a process in Oracle Retail Order Management System calls an outbound integration layer process to send information to an external system.

2. If the Communication type setting for the outbound integration layer process is set to Message Queue and the status of the integration layer process is active, the process looks at the queue defined for the process. For an outbound process, the queue indicates:

- the queue manager name on the Work with Advanced Queue Manager Screen that defines the connection settings to connect to the database used for queue processing.

- the name of the outbound queue to which the integration layer process sends the message for transmission to the external system; this must be a valid queue in the database used for queue processing.

- the name of the XML message generated and sent to the external system.

3. The system sends the message to the outbound queue defined for the integration layer process.

4. An external system use the JMS RESTful Web Service to retrieve the message from the queue in order to process the message.

Inbound Process Flow

1. An external system uses a Oracle Retail Order Management System web service to send a message to a queue in the database used for queue processing. Note: The target in the message must match the Inbound job name defined on the Integration Layer Process Queue screen in Work with Integration Layer Processes (IJCT). See Generic Web Services for more information on the web services available for Oracle Retail Order Management System.

2. If the Communication type setting for an inbound integration layer process is set to Message Queue and the status of the integration layer process is active, the process monitors the queue defined for the process for new messages. For an inbound process, the queue indicates:

- the queue manager name on the Work with Advanced Queue Manager Screen that defines the connection settings to connect to the database used for queue processing.

- the name of the inbound queue that the integration layer process monitors for new messages to process from an external system; this must be a valid queue in the database used for queue processing.

- the name of the job that processes the message from the inbound queue.

3. If the integration layer process finds a new message to process in the queue, the process picks up the message and processes it using existing functionality.

For more information: See Integration Layer Processes and Web Services for more information on the integration layer processes that use a message queue.

Advanced Queuing Setup

Before you can begin using advanced queuing, you must complete the necessary setup.

1.	Define a separate Oracle database with open access to use for queue processing.
2.	For each queue you wish to create in the database: • Use the following SQL command to create a queue table: EXEC DBMS_AQADM.CREATE_QUEUE_TABLE (queue_table => 'process_table', queue_payload_type => 'SYS.AQ$_JMS_TEXT_MESSAGE'); where process_table is the name of the queue table you wish to create. • Use the following SQL command to create a queue: EXEC DBMS_AQADM.CREATE_QUEUE (queue_name => 'process', queue_table => 'process_table'); where process is the name of the queue you wish to create and process_table is the name of the corresponding queue table. Note: the queue name is case-sensitive. • Use the following SQL command to start the queue: EXEC DBMS_AQADM.START_QUEUE (queue_name => 'process'); where process is the name of the queue you wish to start. The queue must be started in order to enable the queue for processing. Recommended queue naming convention: To easily identify the purpose of a queue, use the following naming convention when creating a queue: PROCESS_DIRECTION where: • PROCESS = the name of the Oracle Retail Order Management System process that sends or receives the message. • DIRECTION = the direction of the message. - IN = the message is inbound to Oracle Retail Order Management System. - OUT = the message is outbound from Oracle Retail Order Management System. Example: • CUST_SRCH_OUT = The queue receives messages from the CUST_SRCH process in Work with Integration Layer Processes (IJCT) in Oracle Retail Order Management System. • CUST_SRCH_IN = The queue sends messages to the CUST_SRCH process in Work with Integration Layer Processes (IJCT) in Oracle Retail Order Management System.
3.	Use the Work with Advanced Queue Manager Screen to define the connection information to the database used for queue processing.
4.	Define queue information for the associated Oracle Retail Order Management System process. In Working with Integration Layer Processes (IJCT): • On the Integration Layer Process screen, select Message Queue for the Communication type. • Use the Work with Integration Layer Process Queues screen to define the queues that run for the process. When defining the integration layer process queue: - the Inbound queue manager and/or Outbound queue manager is the queue manager name defined on the Work with Advanced Queue Manager Screen. - the Inbound queue and/or Outbound queue is the name of the associated queue in the database used for queue processing.
5.	Open the jmsrest.properties file located on the application server at /usr/local/tomcat01/conf, where /usr/local/tomcat01 is the installed location of Oracle Retail Order Management System, and update the url setting to the URL of the database used for queuing.

JMS RESTful Web Service

Advanced queuing uses the Java Messaging Service (JMS) as its method to transmit information from the queuing database to an external system. The JMS RESTful web service is used to read from a queue in the queuing database.

The individual URLs for the web service use the following format: http(s)://server:port/JMS-REST/jms/jmsREST/getFromQueue, where server:port identifies the server where the JMS RESTful web service is located.

In the payload, or message data, include the name of the queue to be read as a JSON string; for example: {"queueName":"process"}, where process is the name of the queue.

Basic Authentication

For security, the RESTful web service endpoint requires basic authentication. In the basic authentication header, you must pass the user ID and password defined in the database that has access to the queue.

• If the message passes basic authentication, the message will be returned as a JSON string: {"status": "OK", "message": "data"}, where data is the message data.

• If there are no more messages to read from the queue, a status of EOF (End Of File) will be returned: {"status": "EOF"}.

• If there is a failure, the status will return the error condition; for example: {"status": "JMS-232: An invalid user/password was specified for the JMS connection"}.

Viewing Messages on a Queue in the Database

Because messages are placed in normal rows in a database table, if you have access to the queuing database, you can query the table using standard SQL.

Use the following SQL command to view existing messages on a queue:

select msgid, enq_time, enq_uid, qt.user_data.text_vc || qt.user_data.text_lob from process_table qt where q_name = 'process'

where process_table is the name of the queue table and process is the name of the queue. Note: the queue name is case-sensitive.

Work with Advanced Queue Manager Screen

Use this screen to define connection information to the database used for queue processing.

How to display this screen: Enter WWMQ in the Fast path field at the top of a menu or select Work with Advanced Queue Manager from a menu.

When you first advance to the screen, queue manager names display in ascending alphanumeric sequence.

Field	Description
Queue Manager Name	The name of the connection, identifying the database used for queue processing. Enter a full or partial queue manager name to display queue managers that begin with your entry. Alphanumeric, 75 positions; optional.

Screen Option	Procedure
Create a queue connection	Select Create to advance to the Create Advanced Queue Manager Screen.
Change a queue connection	Select Change for a queue manager to advance to the Change Advanced Queue Manager screen. You can change all fields except the Queue Manager Name; see Create Advanced Queue Manager Screen for field descriptions.
Delete a queue connection	Select Delete for a queue manager to delete it.

Create Advanced Queue Manager Screen

Use this screen to define connection information to the database used for queue processing.

How to display this screen: Select Create at the Work with Advanced Queue Manager Screen.

Field	Description
Queue Manager Name	The name of the connection, identifying the database used for queue processing. Alphanumeric, 75 positions. Create screen: required. Change screen: display-only.
Database URL	The connection string used to connect to the database used for queue processing. Note: In order to connect without errors, the database URL should directly correspond to the database connection information on the Oracle database server that contains the message queues. For example: jdbc:oracle:thin:@//hostname:port/servicename, where: • hostname = the Hostname defined for the database server. • port = the Port defined for the database server. • servicename = the Service name defined for the database server. Alphanumeric, 115 positions; required.
User Name	The user name used to connect to the database used for queue processing. Alphanumeric, 75 positions; required.
Password	The password used to connect to the database used for queue processing. When you define or update the password, the system immediately encrypts it and does not display any password information on the screen. Alphanumeric 75 positions; required.