BEA WebLogic Adapter for MQSeries
User Guide Release 7.1 Document Date: June 2003 Copyright
Copyright © 2003 BEA Systems, Inc. All Rights Reserved. Restricted Rights Legend
This software and documentation is subject to and made available only pursuant to the terms of the BEA Systems License Agreement and may be used or copied only in accordance with the terms of that agreement. It is against the law to copy the software except as specifically allowed in the agreement. This document may not, in whole or in part, be copied, photocopied, reproduced, translated, or reduced to any electronic medium or machine readable form without prior consent, in writing, from BEA Systems, Inc. Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the BEA Systems License Agreement and in subparagraph (c)(1) of the Commercial Computer Software-Restricted Rights Clause at FAR 52.227-19; subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013, subparagraph (d) of the Commercial Computer Software--Licensing clause at NASA FAR supplement 16-52.227-86; or their equivalent. Information in this document is subject to change without notice and does not represent a commitment on the part of BEA Systems. THE SOFTWARE AND DOCUMENTATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. FURTHER, BEA Systems DOES NOT WARRANT, GUARANTEE, OR MAKE ANY REPRESENTATIONS REGARDING THE USE, OR THE RESULTS OF THE USE, OF THE SOFTWARE OR WRITTEN MATERIAL IN TERMS OF CORRECTNESS, ACCURACY, RELIABILITY, OR OTHERWISE. Trademarks or Service Marks
BEA, Jolt, Tuxedo, and WebLogic are registered trademarks of BEA Systems, Inc. BEA Builder, BEA Campaign Manager for WebLogic, BEA eLink, BEA Manager, BEA WebLogic Commerce Server, BEA WebLogic Enterprise, BEA WebLogic Enterprise Platform, BEA WebLogic Express, BEA WebLogic Integration, BEA WebLogic Personalization Server, BEA WebLogic Platform, BEA WebLogic Portal, BEA WebLogic Server, BEA WebLogic Workshop and How Business Becomes E-Business are trademarks of BEA Systems, Inc. All other trademarks are the property of their respective companies. BEA WebLogic Adapter for MQSeries User Guide Part Number
N/A Date
June 2003 Contents
About This Document
What You Need to Know .................................................................................. viii e-docs Web Site................................................................................................. viii Related Information........................................................................................... viii Contact Us! .......................................................................................................... ix Documentation Conventions .................................................................................x 1. Introducing the BEA WebLogic Adapter for MQSeries
About the BEA WebLogic Adapter for MQSeries............................................ 1-1 Supported Integration Capabilities............................................................. 1-2 Key Concepts..................................................................................................... 1-2 Application Views...................................................................................... 1-3 Services ...................................................................................................... 1-3 Events ......................................................................................................... 1-4 Schemas...................................................................................................... 1-5 2. Defining Application Views for the Adapter for MQSeries
Before You Begin.............................................................................................. 2-1 Defining and Deploying an Application View.................................................. 2-2 Step 1. Log On to the Application View Console...................................... 2-2 Step 2. Add a Folder................................................................................... 2-3 Step 3. Define an Application View........................................................... 2-4 Step 4. Establish an MQSeries Connection................................................ 2-5 Step 5. Add Services and Events................................................................ 2-9 Step 6. Deploy the Application View....................................................... 2-16 Step 7. Test Services and Events.............................................................. 2-16 Editing an Application View ........................................................................... 2-30 BEA WebLogic Adapter for MQSeries User Guide iii 3. Using the Adapter for MQSeries
About TCP/IP Connections ............................................................................... 3-1 Implementing User Exits............................................................................ 3-2 Using CCSID in MQ Connection............................................................... 3-3 About Transaction Services............................................................................... 3-4 About Content Filtering in Events..................................................................... 3-5 Sending and Receiving Messages...................................................................... 3-7 Sending a Datagram Message .................................................................... 3-7 Sending a Reply Message........................................................................... 3-8 Sending Messages to Remote Queues........................................................ 3-9 Sending Group Messages ........................................................................... 3-9 Sending Messages with MQRFH2 Header Information .......................... 3-13 About Receiving Group Messages ........................................................... 3-14 Using Data Formats in Services and Events............................................. 3-14 Handling MQ Message Descriptor Values in Services and Events ......... 3-16 Handling Request, Response Documents and MQMD Ids ...................... 3-17 Handling Errors and Exceptions............................................................... 3-17 4. Example of Using Services and Events
Service Example ................................................................................................ 4-2 Transaction Service - Begin ....................................................................... 4-2 SendMessage .............................................................................................. 4-3 SendRequest ............................................................................................... 4-5 GetMessage ................................................................................................ 4-6 Transaction Service - Commit.................................................................... 4-8 Event Example................................................................................................... 4-9 Event Response Document....................................................................... 4-10 A. Schema Formats of Services and Events
Service Schemas ............................................................................................... A-1 Transaction ................................................................................................ A-2 SendMessage ............................................................................................. A-3 SendRequest .............................................................................................. A-5 GetMessage ............................................................................................... A-8 Event Schema ................................................................................................. A-10 iv BEA WebLogic Adapter for MQSeries User Guide B. Logging Messages
About Logging...................................................................................................B-1 Levels of Logging..............................................................................................B-2 Logging and Performance .................................................................................B-2 C. Run-Time Parameter Values D. Error Messages and Troubleshooting
Error Messages ................................................................................................. D-1 Troubleshooting Tips........................................................................................ D-4 Index BEA WebLogic Adapter for MQSeries User Guide v vi BEA WebLogic Adapter for MQSeries User Guide About This Document
This document explains how to use the BEA WebLogic Adapter for MQSeries to integrate IBM MQSeries messages with BEA WebLogic Integration. It is organized as follows: Chapter 1, "Introducing the BEA WebLogic Adapter for MQSeries," introduces the BEA WebLogic Adapter for MQSeries and provides an overview of the adapter's functionality. Chapter 2, "Defining Application Views for the Adapter for MQSeries," describes how to define the application views for the Adapter for MQSeries. Chapter 3, "Using the Adapter for MQSeries," describes in detail the services and events that the Adapter for MQSeries offers. Chapter 4, "Example of Using Services and Events," illustrates examples of using the Adapter for MQSeries. Appendix A, "Schema Formats of Services and Events," presents the formats for service and event schema created by the adapter. Appendix B, "Logging Messages," provides information on logging levels and categories. Appendix C, "Run-Time Parameter Values," details the run-time parameters used for adapter services. Appendix D, "Error Messages and Troubleshooting," provides details on error messages and troubleshooting tips. BEA WebLogic Adapter for MQSeries User Guide vii What You Need to Know
This document is written for system integrators who develop client interfaces between MQSeries and other Web applications. It describes how to use the BEA WebLogic Adapter for MQSeries to develop application environments with a special focus on message integration. It is assumed that you know Web technologies and have a general understanding of MQSeries, Microsoft Windows, and UNIX systems. e-docs Web Site
BEA product documentation is available on the BEA corporate Web site. From the BEA Home page, click on Product Documentation or go directly to the e-docs product documentation page at http://e-docs.bea.com. Related Information
The following WebLogic Integration documents contain information that is relevant to using this product. BEA WebLogic Adapter for MQSeries Installation and Configuration Guide at http://edocs.bea.com/wladapters/mq/docs71/index.html BEA WebLogic Adapter for MQSeries Release Notes at http://edocs.bea.com/wladapters/mq/docs71/index.html WebLogic Server installation and user documentation at http://edocs.bea.com/more_wls.html BEA WebLogic Integration installation and user documentation at http://edocs.bea.com/more_wli.html viii BEA WebLogic Adapter for MQSeries User Guide This document assumes that you have in-depth knowledge of Workflow Design, Workflow Templates, Worklists, and WebLogic Integration Studio. If you do not have the required knowledge of workflows or the WebLogic Integration Studio, see the following documents: Using the WebLogic Integration Studio at http://edocs.bea.com/wli/docs70/studio/index.htm Learning to Use BPM with WebLogic Integration at http://edocs.bea.com/wli/docs70/bpmtutor/index.htm Contact Us!
Your feedback on the BEA WebLogic Adapter for MQSeries documentation is important to us. Send us e-mail at docsupport@bea.com if you have questions or comments. Your comments will be reviewed directly by the BEA professionals who create and update the BEA WebLogic Adapter for MQSeries documentation. In your e-mail message, please indicate that you are using the documentation for the BEA WebLogic Adapter for MQSeries 7.1 release. If you have any questions about this version of BEA WebLogic Adapter for MQSeries, or if you have problems installing and running the product, contact BEA Customer Support through BEA WebSupport at www.bea.com. You can also contact Customer Support by using the contact information provided on the Customer Support Card, which is included in the product package. When contacting Customer Support, be prepared to provide the following information: Your name, e-mail address, phone number, and fax number Your company name and company address Your machine type and authorization codes The name and version of the product you are using A description of the problem and the content of pertinent error messages BEA WebLogic Adapter for MQSeries User Guide ix Documentation Conventions
The following documentation conventions are used throughout this document. Convention
boldface text Ctrl+Tab italics
monospace text Item
Indicates terms defined in the glossary. Indicates that you must press two or more keys simultaneously. Indicates emphasis or book titles. Indicates code samples, commands, and their options, data structures and their members, data types, directories, and filenames and their extensions. Examples: #include void main ( ) the pointer psz chmod u+w * \tux\data\ap
.doc tux.doc BITMAP float monospace boldface text monospace italic text Identifies significant words in code. Example: void commit ( ) Identifies variables in code. Example: String expr Indicates device names, environment variables, and logical operators. Examples: LPT1 SIGNON OR UPPERCASE TEXT x BEA WebLogic Adapter for MQSeries User Guide Convention
{} Item
Indicates a set of choices in a syntax line. The braces themselves should never be typed. Indicates optional items in a syntax line. The brackets themselves should never be typed. Example: buildobjclient [-v] [-o name] [-f file-list]... [-l file-list]... [] | Separates mutually exclusive choices in a syntax line. The symbol itself should never be typed. Indicates one of the following in a command line: That an argument can be repeated several times in a command line That the statement omits additional optional arguments That you can enter additional parameters, values, or other information The ellipsis itself should never be typed. Example: buildobjclient [-v] [-o name] [-f file-list]... [-l file-list]... ... . . . Indicates the omission of items from a code example or from a syntax line. The vertical ellipsis itself should never be typed. BEA WebLogic Adapter for MQSeries User Guide xi xii BEA WebLogic Adapter for MQSeries User Guide CHAPTER 1 Introducing the BEA WebLogic Adapter for MQSeries
This section introduces the BEA WebLogic Adapter for MQSeries and explains the key concepts. It contains the following topics: About the BEA WebLogic Adapter for MQSeries Key Concepts About the BEA WebLogic Adapter for MQSeries
The BEA WebLogic Adapter for MQSeries integrates your IBM MQSeries messages with WebLogic Integration. You can use the adapter to exchange XML, Binary, and TEXT formats between your MQSeries resources and the WebLogic Integration. BEA WebLogic Adapter for MQSeries User Guide 1-1 1 Introducing the BEA WebLogic Adapter for MQSeries Supported Integration Capabilities
MQSeries messaging products support application integration by sending and receiving data as messages that allow business applications to exchange information across platforms. They account for network interfaces, delivery of messages, deal with communication protocols, dynamically distribute workload across available resources, handle recovery after system problems, and help make programs portable. This allows programmers to use their skills to handle key business requirements, instead of wrestling with underlying network complexities. The BEA WebLogic Adapter for MQSeries provides: Asynchronous, bi-directional message interactions between WebLogic Integration and native IBM MQSeries managed queues. Data transfer between a business process running within WebLogic Integration and an MQSeries Queue Manager. Services and events for end-to-end business process management using XML schemas. Key Concepts
This topic describes the following concepts, which you must understand before using the BEA WebLogic Adapter for MQSeries: Application Views Services Events Schemas 1-2 BEA WebLogic Adapter for MQSeries User Guide Key Concepts Application Views
An application view is a business-oriented interface to objects and operations within an EIS. Application views include the information needed to communicate with the EIS, as well as configurations for services and events. Application views define: Communication with the EIS, including connection settings, login credentials, and so on. Service invocations, including the information that the EIS requires for the request, as well as the service request and response schemas associated with the service. Event notifications, including the information that the EIS publishes and the event schemas for inbound messages. An application view is typically configured for a single business purpose and contains only the services or events required for that business purpose. Application views provide a layer of abstraction between applications and the EIS, making it easier for developers and non-programmers to access and maintain the services and events exposed by the adapter. Services
Services are request/response communications with the EIS. Client applications submit service requests to the EIS via the adapter, and the adapter returns the EIS response back to the client. Responses can be either synchronous or asynchronous. When an application receives a request to invoke a business service, the application view invokes the service in the target application and responds with an XML document that describes the results. To define a service, you must define input requirements, output expectations, and an interaction specification containing static secondary metadata about the request. A service receives an XML request document from a client and invokes the associated function in the underlying EIS. Services are consumers of messages. They may or may not provide responses. A service may be invoked in either of two ways: synchronously or asynchronously, in a workflow. When a synchronous service is used, the client waits BEA WebLogic Adapter for MQSeries User Guide 1-3 1 Introducing the BEA WebLogic Adapter for MQSeries
for the response before proceeding with processing. When an asynchronous service is used, the client application issues a service request and then proceeds with processing without waiting for the response. A service performs the following functions: Receive service requests from an external client. Transform an XML request document into the EIS-specific format. The request document conforms to the request XML schema for the service. Invoke the underlying function in the EIS and wait for a response from that function. Transform the response from the EIS-specific data format to an XML format that conforms to the response XML schema for the service. Events
Events are asynchronous, one-way messages received from an EIS. For example, the adapter can receive a message from an MQ system. The adapter routes the EIS message to the appropriate software component. Events are triggers to workflows. When a particular message arrives in a queue, it triggers an event to read the message, and convert it, if necessary, to an XML format that matches the required schema. The event then initiates a workflow. An event is an XML document published by an application view when an occurrence of interest takes place within an EIS. Clients that want to be notified of events, request such notification by registering with an application view. The application view then acts as a broker between the target application and the client. When a client has subscribed to events published by an application view, the application view notifies the client whenever an event of interest occurs in the target application. Upon receiving such notification, the event is passed as an XML document that describes the event. Application views that publish events can also provide clients with the XML schema for publishable events. Events are designed to propagate information from an EIS to WebLogic Server. They can be described as publishers of information. Events running in a WebLogic Integration environment perform the following functions: 1-4 BEA WebLogic Adapter for MQSeries User Guide Key Concepts
Respond to events that occur inside the running EIS by extracting and storing data about the event from the EIS. Transform event data from an EIS-specific format to an XML document that conforms to the XML schema for the event. Propagate each event to an event context obtained from the application view by using the event router. Schemas
At run-time, the EIS and the adapter exchange service requests, service responses, and events via XML documents. The adapter handles the data translation between XML documents and the EIS format, using schemas that have been defined at design-time to map the data between XML and the EIS format: For service requests, the request arrives at the adapter in the form of an XML document. The adapter uses the request schema associated with the service (as defined in the application view) to translate the request to the format that the EIS expects. Similarly, when the adapter receives the response back from the EIS, it uses the response schema associated with the service to translate the response to an XML document that the requesting application handles. For event notifications, the inbound message arrives at the adapter in the format that the EIS uses to publish the event. The adapter uses the event schema associated with the event (as defined in the application view) to translate the response to an XML document that the subscribed application handles. The Adapter for MQSeries creates the schema you need when you define services and events. To view the schemas that the adapter creates, see Appendix A, "Schema Formats of Services and Events." BEA WebLogic Adapter for MQSeries User Guide 1-5 1 Introducing the BEA WebLogic Adapter for MQSeries 1-6 BEA WebLogic Adapter for MQSeries User Guide CHAPTER 2 Defining Application Views for the Adapter for MQSeries
This section explains how to define application views for the Adapter for MQSeries. It contains the following topics: Before You Begin Defining and Deploying an Application View Editing an Application View Before You Begin
When you define an application view, you create an XML-based interface between WebLogic Server and the Adapter for MQSeries. Once you create the application view, a business analyst can use it to create business processes that use the application. You can create as many application views for an adapter, each of which may contain any number of services and events. Note: Before you define an application view, determine which business processes should be supported by the application view that you are configuring. The required business processes determine the types of services and events you include in your application views. Therefore, you must gather information BEA WebLogic Adapter for MQSeries User Guide 2-1 2 Defining Application Views for the Adapter for MQSeries
about the application's business requirements from the business analyst. Once you determine the necessary business processes, you can define and test the appropriate services and events. Defining and Deploying an Application View
This section explains how to define and deploy application views using an Adapter for MQSeries. This procedure consists of the following steps: Step 1. Log On to the Application View Console Step 2. Add a Folder Step 3. Define an Application View Step 4. Establish an MQSeries Connection Step 5. Add Services and Events Step 6. Deploy the Application View Step 7. Test Services and Events Note: Before performing the following steps, ensure that the WebLogic Integration Server is running on your system. Step 1. Log On to the Application View Console
The Application View Console displays all the application views in your WebLogic Integration environment, organized in folders. To log on to the Application View Console: 1. Open a new browser window. 2-2 BEA WebLogic Adapter for MQSeries User Guide Defining and Deploying an Application View
2. Enter the URL for your system's Application View Console. The actual URL you enter depends on your system. It should conform to the following format:
http://localhost:port/wlai Here, localhost represents the IP address machine on which the WebLogic Integration Server is running and port represents the listening port. The Application View Console Logon page appears. 3. Enter your WebLogic Server username and password, and click Login. The Application View Console page appears. Figure 2-1 Application View Console Step 2. Add a Folder
You organize the application views in folders. A single folder may contain both applications views and other subfolders. Once you create a folder, you cannot move it to another folder. Before you can remove a folder, you must first remove all applications views and subfolders. Once you create an application view in a folder, you can remove the application view, but you cannot move it to another folder. You can add application views to existing folders. To add a folder: 1. On the Application View Console page, click the New Folder icon. The Add Folder page appears. 2. Enter a name in the New Folder field. Any valid Java Identifier is allowed to be the name. BEA WebLogic Adapter for MQSeries User Guide 2-3 2 Defining Application Views for the Adapter for MQSeries
3. Click Save. The newly created folder appears on the Application View Console page. Step 3. Define an Application View
You must define an application view and relate it to the adapter you are working with. For more information about defining application views and using them in workflows, see Using Application Integration: For WebLogic Integration 7.0, see
http://edocs.bea.com/wli/docs70/aiuser/2usrdef.htm For WebLogic Integration 2.1, see
http://edocs.bea.com/wlintegration/v2_1sp/aiuser/2usrdef.htm To define an application view: 1. Click the newly created folder. It takes you to the page where you can add application views to this folder. 2. Click Add Application View. Note: Make sure you are working in the appropriate folder before performing this step. Once you define an application view, you cannot move it to another folder. The Define New Application View page appears. 2-4 BEA WebLogic Adapter for MQSeries User Guide Defining and Deploying an Application View
Figure 2-2 Define New Application View Note: A red asterisk (*) indicates that a field is mandatory. 3. Enter a name for the application view. Generally, the name should indicate the functions performed by this application. Each application view must be unique to its Adapter. Example, my_mqseries_appview. 4. Select an adapter. Example, BEA_MQSERIES_7_1. 5. Click OK. The Select the Type of Connection page appears. Step 4. Establish an MQSeries Connection
You can connect to MQSeries either by using a bindings connection or a TCP/IP connection.You can choose the connection type on the Select the Type of Connection page. BEA WebLogic Adapter for MQSeries User Guide 2-5 2 Defining Application Views for the Adapter for MQSeries
Figure 2-3 Select the Type of Connection Page You can choose one of the following types of MQ Connection: Bindings Connection: provides an MQ Connection to the MQ Server running on the system where the Adapter for MQSeries is installed. To learn more, see Step 4A. Connecting Through Bindings Connection Type. TCP/IP Connection: provides the option of connecting to any MQ Server running on the same network where the Adapter for MQSeries is installed. To learn more, see Step 4B. Connecting Through TCP/IP Connection Type. Step 4A. Connecting Through Bindings Connection Type
To establish a connection to MQSeries through bindings, do the following: 1. On the Select Type of Connection page, select Bindings Connection. The Configure Local Bindings Connection page appears. Figure 2-4 Configure Local Bindings Connection Note: A red asterisk (*) indicates that a field is mandatory. 2-6 BEA WebLogic Adapter for MQSeries User Guide Defining and Deploying an Application View
2. Enter the WebLogic User Name and Password. 3. Enter the name of the Queue Manager. 4. Click Connect to EIS. The Application View Administration page appears with the summary of the connection. Figure 2-5 Application View Administration - Local Bindings Connection Summary Step 4B. Connecting Through TCP/IP Connection Type
To learn more about the options available when you select a TCP/IP connection, see "About TCP/IP Connections" on page 3-1. To establish a connection to through TCP/IP: 1. On the Select Type of Connection page, select TCP/IP Connection. The Configure TCP/IP Connection page appears. BEA WebLogic Adapter for MQSeries User Guide 2-7 2 Defining Application Views for the Adapter for MQSeries
Figure 2-6 Configure TCP IP Connection Note: A red asterisk (*) indicates that a field is mandatory. 2. Enter the WebLogic User Name and Password. 3. Select the check box if MQSeries requires an authorization. Note: If you select this, the User Name and Password used here should be valid on both the WebLogic Platform and the MQ Server. 4. Enter the name of the Queue Manager. 5. Enter the name of the host where the MQ Server is installed. Example, localhost. 6. Enter the name of the channel to connect to the Queue Manager. 7. Enter the port number of the Queue Manager. Example, 1414. 8. If you expect to exchange messages using a non-latin character set, enter the character set ID from the CCSID Catalog. CCSID defines the character set of character data in the message. Click the View CCSID Catalog link for a list of character catalogs. To learn more, see "Using CCSID in MQ Connection" on page 3-3. 9. Select the applicable User Exit Type and enter the relevant application name. These are the user exits: 2-8 BEA WebLogic Adapter for MQSeries User Guide Defining and Deploying an Application View
Send Exit: processes the message before sending it to a queue. Receive Exit: processes the message after getting it from a queue. Security Exit: performs a security check on the message. To learn more about user exit types, see "Implementing User Exits" on page 3-2. 10. Click Connect to EIS. The Application View Administration page appears with the summary of the connection. Figure 2-7 Application View Administration - TCP/IP Connection Summary Step 5. Add Services and Events
You can add services and events that support specific business processes. An application view can have multiple services and events. The required business processes determine the types of services and events you include in your application view. Step 5A. Add a Service to an Application View
You must consider the following points before you execute a workflow using Adapter for MQSeries services: BEA WebLogic Adapter for MQSeries User Guide 2-9 2 Defining Application Views for the Adapter for MQSeries
The SendMessage, SendRequest, and GetMessage services must always be a part of an existing transaction scope. Within a transaction scope, the SendMessage, SendRequest, and GetMessage services can be invoked in any order. Transaction boundary services (Begin and Commit/BackOut) are required for sending and receiving messages. To add a service: 1. On the Application View Administration page, click Add in the Services row. The Add Service page appears. Figure 2-8 Add Service 2. Select the Service Type and click Continue. A page for the service type you select appears. The services provided by the Adapter for MQSeries are as follows: Transaction Services: begins and ends a transaction that can contain any number of other services. To learn more about Transaction services, see "About Transaction Services" on page 3-4. SendMessage: sends a message to a specified queue. SendRequest: sends a request message to a specific queue. GetMessage: gets a message from a specified queue. For specific instructions on configuring a GetMessage service, see "About Configuring GetMessage Services" on page 2-13. 3. Enter a unique name for the service. 2-10 BEA WebLogic Adapter for MQSeries User Guide Defining and Deploying an Application View
4. Select the message type from the drop-down list. The options are: Datagram: for your messages where no reply is expected. This message type is used for SendMessage services. For more information, see "Sending a Datagram Message" on page 3-7. Reply: for your reply messages. This message type is used for SendMessage services. For more information, see "Sending a Reply Message" on page 3-8. Request: for your message where a reply is expected. This message type is used for SendRequest services. 5. Enter a valid queue name for the queue manager you are connecting to, for Bindings connection. For a TCP/IP connection enter a valid queue name and sender channel for the queue manager. For details on setting up a sender-receiver channel to the remote queue manager, see "Sending Messages to Remote Queues" on page 3-9. Note: The instructions that follow apply to SendMessage and SendRequest services. For instructions for configuring GetMessage services, see "About Configuring GetMessage Services" on page 2-13. 6. Enter the expiration value for the message. 7. Select the message priority. You can select a number between 0 and 9, or AsQueuedef (as defined in the queue). 8. Select the persistence policy. The available options are Persistent, NotPersistent, and AsQueuedef. 9. If you expect to exchange messages using a non-latin character set, enter the character set ID from the CCSID Catalog. CCSID defines the character set of character data in the message. Click the View CCSID Catalog link for a list of character catalogs. To learn more, see "Using CCSID in MQ Connection" on page 3-3. 10. Enter a message user name that is authorized by the MQSeries Server and a member of the MQ Administrator group. 11. Select a segmentation policy. If you select Allowed, the MQ Manager can segment the message, if required. If you select NotAllowed, the message cannot be segmented. 12. Select the relevant report messaging option: BEA WebLogic Adapter for MQSeries User Guide 2-11 2 Defining Application Views for the Adapter for MQSeries
COA: Confirmation of Arrival, with some data or with full data. COD: Confirmation of Delivery, with some data or with full data. Exception report, with some data or with full data. Expiration report, with some data or with full data. 13. If you select a report messaging option, enter the name of the queue where the report should be sent. The default value is obtained from the queue manager to which the connection is made. Note: The reports go to the specified reply to queue if the user is authorized by MQSeries. Otherwise, they go into the dead letter queue of the queue manager where the message is sent. In any case, the COA report goes into the specified Reply to Queue Name destination. For more information on reports, see your MQSeries documentation. 14. Enter the queue manager to which the report should be sent. The default value is obtained
from the queue manager to which the connection is made. This is an optional field. 15. Select the applicable format for the message. The available options are None, String, and MQRFH2. To view the format of MQRFH2, click View Format link. Note: If you do not specify a value in run-time, the design-time value takes precedence. If you specify both run-time and design-time values, the run-time value takes precedence. 16. Enter the contents of the selected format. This field is mandatory if you select MQRFH2 data format. To create the contents, use the MQRFH2 schema and insert values in it. For more information, see Sending Messages with MQRFH2 Header Information. 17. Select the data format. If you specify the data format as TEXT or Binary during design-time, you cannot specify the data format as XML during run-time. 18. Enter the schema of the XML data content. This is required only when you select XML as the data format. Note: The XML data content schema cannot be provided during run-time. 19. Click Add Service. The service is added to the application view. 2-12 BEA WebLogic Adapter for MQSeries User Guide Defining and Deploying an Application View About Configuring GetMessage Services
When you configure a GetMessage service, you specify the service name, service type, description, and queue name the same as for a SendMessage or SendRequest service. In addition, you specify a message consumption setting and a time out. The Message Consumptions options are: Browse ­ This option is only for Browsing a message. Even after the message is read from the Queue it remains there intact. Delete ­ This option is to fully consume the message as it is read. After the message is read, it is permanently removed from the Queue. Note: It is the MQ Administrator's responsibility to periodically remove outdated and unwanted messages from the Queue whenever the Browse is set as the consumption type. The Time Out is the maximum amount of time for which the application should pause before getting a message. For unlimited waiting period, specify -1. When you configure a GetMessage service for TEXT or Binary Data formats, it will not fetch messages of XML format. The application will throw a Resource Exception on such occurrences. When a GetMessage service is configured for XML Data formats it will not fetch messages of TEXT or Binary formats. The application will throw a Resource Exception on such occurrences. At run-time, one or more or all of the following values can be provided. MessageId: The MessageId of the message that is to be received. CorrelationId: The CorrelationId of the message that is to be received. GroupId: The GroupId of the message that is to be received. For more information, see "Sending Group Messages" on page 3-9. A Message that matches these given IDs is received. If none of the above is provided, the first message in the Queue is received. Messages, also known as In-process replies, may be responses to previously sent requests and/or subsequent messages in a group. For more information on the data formats, see "Using Data Formats in Services and Events" on page 3-14. BEA WebLogic Adapter for MQSeries User Guide 2-13 2 Defining Application Views for the Adapter for MQSeries Step 5B. Add an Event to an Application View
You can use an Adapter for MQSeries event to monitor a queue for messages. Messages can be received only from queues that are local to the queue manager to which the connection is obtained and not from remote queues. To add an event: 1. On the Application View Administration page, click Add in the Events row. The Add Event page appears. Figure 2-9 Add Event Note: A red asterisk (*) indicates that a field is mandatory. 2. Enter a Unique Name for the event. 3. Select the type of connection from the drop-down list. 4. Enter the name of the Queue Manager. 5. Enter the name of the host required to connect to the Queue Manager. Note: The host name should be a valid IP address on a non-Windows platform. Example, 172.19.138.44. On Windows, it can be either an IP address or a valid name. Example, QM_Host 2-14 BEA WebLogic Adapter for MQSeries User Guide Defining and Deploying an Application View
6. Enter the name of the Queue Manager Channel. This entry is required only if the connection type is TCP/IP. 7. Enter the port number of the Queue Manager. This entry is required only when the connection type is TCP/IP. 8. Enter the name of the queue to monitor. 9. If you expect to exchange messages using a non-latin character set, enter the character set ID from the CCSID Catalog. CCSID defines the character set of character data in the message. Click the View CCSID Catalog link for a list of character catalogs. To learn more, see "Using CCSID in MQ Connection" on page 3-3. 10. Select the type of message consumption from the drop-down list. Browse ­ This option is only for Browsing a message. Even after the message is read from the Queue it remains there intact. Delete ­ This option is to fully consume the message as it is read. After the message is read, it is permanently removed from the Queue. Note: It is the MQ Administrator's responsibility to periodically remove outdated and unwanted messages from the Queue whenever the Browse is set as the consumption type. 11. Select the data format of the message from the drop-down list. For details, see "Using Data Formats in Services and Events" on page 3-14 12. Select the Content Filter Required check box if you need content filtering. For details, see "About Content Filtering in Events" on page 3-5. 13. Enter the class of the content filter. You should enter this only if you select the Content Filter Required check box. 14. Click Add. The event is added to the application view. BEA WebLogic Adapter for MQSeries User Guide 2-15 2 Defining Application Views for the Adapter for MQSeries Step 6. Deploy the Application View
After adding the services and events, you must deploy the application view to use its services and events in a workflow. If you want to reconfigure the application view, you have to undeploy it and reconfigure. For details on reconfiguring an application view, see "Editing an Application View" on page 2-30. To deploy the application view, do the following: 1. After you add services and events, on the Application View Administration page, click Continue. The Deploy Application View page appears. Note: Before you deploy the application view, configure the log verbosity level for the application view. For more details, see Appendix B, "Logging Messages." 2. Click Deploy. The application view is deployed. Step 7. Test Services and Events
The purpose of testing an application view service is to evaluate whether or not that service interacts properly with the MQSeries. After deploying an application view, you can test the services and events in one of the following ways: Using the Application View Console Using WebLogic Integration Studio Note: Before you test an application view, ensure that all the required services and events are added to it and it has been deployed. Step 7A. Test Services and Events Using the Application View Console
It's a good idea to test the functionality of an application view before you start using it in workflow. You can do this using the Application View Console. Note: Before you test an application view's services, ensure that the application view contains a Transaction service and other necessary services that form a part of the transaction scope. 2-16 BEA WebLogic Adapter for MQSeries User Guide Defining and Deploying an Application View
To test a service, see "Test Services in Application View Console" on page 2-17. To test an event, see "Test Events in the Application View Console" on page 2-19. Test Services in Application View Console
To confirm that a deployed application view's services are correctly configured, you must test it before using them in the workflow. You can test the SendMessage, SendRequest, and GetMessage services. To test an application view's services, do the following: 1. Open the WebLogic Integration-Application View Console, and select a deployed application view. The Summary for Application View page appears. Figure 2-10 Summary for Application View 2. Click the Test link for one of the application view's services (SendMessage, SendRequest, and GetMessage). The Test Service page for that service appears. BEA WebLogic Adapter for MQSeries User Guide 2-17 2 Defining Application Views for the Adapter for MQSeries
Figure 2-11 Test Service Note: A red asterisk (*) indicates that a field is mandatory. 3. Enter the name of the transaction service (that has been added to the selected application view) in the Transaction Service Name field. 4. Enter a sample request document that matches the request schema for the service to be tested, in the text box. For example,
TEXT hello world 5. Click Test to execute the service. The Test Result page appears. 2-18 BEA WebLogic Adapter for MQSeries User Guide Defining and Deploying an Application View
Figure 2-12 Test Result You have now confirmed that the application view service is correctly configured. Test Events in the Application View Console
To confirm that a deployed application view's events are correctly configured, you must test it before using them in the workflow. You can test an event through a service or manually. Each of these is described in the following steps. To test an event, do the following: 1. Open the WebLogic Integration-Application View Console, and click the application view bearing deployed status.The Summary for Application View page appears. BEA WebLogic Adapter for MQSeries User Guide 2-19 2 Defining Application Views for the Adapter for MQSeries
Figure 2-13 Summary for Application View 2. Click the Test link for one of the application view's events. The Test Event page appears. Figure 2-14 Test Event 3. To test the event through a service, do the following: a. Select Service, and select the service from the drop-down list. The Test Service page appears as shown in the figure "Test Service" on page 2-18. b. Enter the name of the transaction service (that has been added to the selected application view) in the Transaction Service Name field. 2-20 BEA WebLogic Adapter for MQSeries User Guide Defining and Deploying an Application View
c. Enter a sample Request Document that matches the Request Schema for the selected service, in the text area. d. Click Test to test the event using a service. The Test Result page appears. 4. To test the event directly, do the following a. Select Manual and enter the waiting period in the Time (in milliseconds) in the field. b. Click Test to test the event. The Test Result page appears. Note: If the duration of waiting is lesser than the actual time required to pick the message from the Queue, the Result page will display the Timed Out message. In such case, you will have to increase the waiting period specified in the Time field. You have now confirmed that the application view is correctly configured and can receive events. Note: If you wait longer than the specified period and do not receive the event's result, you should assume that there is a problem with the application view event. Examine the WebLogic Server log for information about the event's activity. Step 7B. Test Services and Events Using WebLogic Integration Studio
You can test events and services separately, using the WebLogic Integration Studio. Before you begin testing services and events, you must complete the tasks described in the following steps. Note: The information provided here assumes that you have in-depth knowledge of Workflow Design, Workflow Templates, Worklists, and WebLogic Integration Studio. If you do not have the required knowledge of workflows or the WebLogic Integration Studio, see the following documents: Using the WebLogic Integration Studio at http://edocs.bea.com/wli/docs70/studio/index.htm Learning to Use BPM with WebLogic Integration at http://edocs.bea.com/wli/docs70/bpmtutor/index.htm Before you test an application views's services and events, do the following: BEA WebLogic Adapter for MQSeries User Guide 2-21 2 Defining Application Views for the Adapter for MQSeries
1. Create the necessary Request Documents for the services that you want to test. You can create the Request Documents using the Request Schema available for that service. 2. Log on to the WebLogic Integration Studio, using a valid user name, password, and server URL. The WebLogic Integration Studio appears. Figure 2-15 WebLogic Integration Studio 3. In the left pane of WebLogic Integration Studio, from the Organizaton drop-down list, select the relevant organization. 4. In the left pane, right-click the Templates folder and select Create Template. The Template Properties dialog box appears. Figure 2-16 Template Properties Dialog Box 5. On the General tab, in the Name field, enter a name for the template, and click OK. The new template (MQ Adapter) appears in the Templates folder, on the left pane of the WebLogic Integration Studio. 6. Right-click the newly created template, and select Create Template Definition. The Template Definitio