Configuring MQ Connections and Handlers for MQ adapter 6.5 July 2008

Page 2 Logging into MQ adaptor Admin UI EXSAP276, IP: EXSAP277, IP: Log into WM Admin UI: :44300/ :44300/ 2. Under ‘Adapters’ click Webmethods MQ Adapter…

Page 3 Listener and Listener Notification Customers send messages from their MQ queue to Covisint’s MQ queue. Listeners and Notifications are configured to receive messages from MQ queue to Connect tier2. Steps to receive message from Covisint MQ queue: 1. Configure new Transactional connection to Covisint queue through WM MQ adaptor admin UI 2. Configure Listener to the above queue using WM MQ adaptor admin UI. 3. Develop Messaging service (receive) flow using WM Developer 6.5. This flow is used for setting all Connect attributes and for processing data 4. Generate Listener Notification for the above listener using Wm Developer 6.5 and set Messaging flow developed in step 3 to be invoked by this Notification. Note: If non-Transactional connection is associated to any Listener and if there is an exception in Listener Notification, then message is lost.

Page 4 Put handler Put handlers are configured to send messages from Connect Tier2 to Covisint’s MQ queue. Steps to Create Put handler: 1. Configure new connection to Covisint queue through WM MQ adaptor admin UI 2. Configure “put” handler service through WM Developer

Page 5 Package Structure to be used All Webmethods generated flows will be stored in MQConnections and User defined flows will be stored in MQConnector. There will be a folder for Inbound and Outbound under the above packages. For each customer, a folder will be created under Inbound and Outbound folder in MQConnections package. In MQConnector package a folder will be created for each customer only under Inbound folder. Naming Convention Queue: Inbound queue starts with CUIN and outbound queue starts with CUOU e.g.: CUINJCI and CUOUJCI Connection :“connection” Listener :“listener” Listener Notification: “listenerNotif“ Receive Messaging service: “receive” Put handler:“put”

Page 6 e.g.: MQConnections Inbound CUINJCI connection (configured through UI) listener (configured through UI) listenerNotif (config through Developer) listenerNotifReplyDocument listenerNotifRequestDocument ReplyDocument and RequestDocument are auto generated by Webmethods Adpater after listener notification is created. Outbound CUOUJCI connection (configured through UI) put (generated through Developer)

Page 7 e.g.: MQConnector Inbound CUINJCI receive (developed in developer) getConfig (developed in developer) receiveMQ (core flow used by all messaging service) Outbound deliverMQ (core flow used by all put handlers) No customer based folder in MQConnector’s Outbound as there is no user defined flow.

Page 8 Configuring Connection Before configuring connection create a folder named as Queue name in MQConnections.Inbound or MQConnections.Outbound depending on direction of flow. l Select ‘Connections’ from MQ adapter UI l Select ‘Websphere MQ Transactional Connection’ Fill in the following parameters: l Package: MQConnections l FolderName: MQConnections.Inbound. +”queue name”, e.g.: MQConnections.Inbound.CUINJCI l Connection name: connection l Queue Manager Name: QM_COVMSG1 l Host Name: messaging.mq.server l TCP/IP port: 1414 l Server Connection channel: SYSTEM.DEF.SVRCONN l CCSID : CP819 l UserId: MQM l Queue Name: select the queue from drop down l Cache Overridden connections : false l Action before Disconnecting an in-transaction connection: COMMIT l Maximum Pool Size set to 5. Do not modify other default values.

Page 9 Configuring Listener l Select ‘Listeners’ from MQ adapter UI l Select ‘Configure New Listener’ l Select ‘WebSphere MQ Single-Queue Listener Service’ as listener type l Fill in the following parameters: l Package: MQConnections l FolderName: MQConnections.Inbound.” + queue name” e.g.: MQConnections.Inbound.CUINJCI l Listener Name: listener l Connection Name: select the connection created for this queue e.g.: MQConnections.Inbound.CUINJCI:connection l Open Queue in Shared mode?: true l Convert Application data?: false (if true will, messages read using this service will be converted to local character set and encoding) l Dead letter Queue Name: CUIN_DLQ l Dead Letter Queue manager: QM_COVMSG1 l Headers to include in Dead Letter Message: DLH & MQMD

Page 10 Creating Messaging service Before creating listener notification create Messaging service. Messaging services are created in MQConnector.Inbound folder. l Create a folder named as queue name eg: CUINJCI l Copy receive message and getConfig flows from any other queue to the folder created in step 1 e.g.: MQConnector.Inbound.CUINJCIABONORMAL:receive and MQConnector.Inbound.CUINJCIABONORMAL:getConfig copied to MQConnector.Inbound.CUINJCI l In first Map step, change getConfig flow reference. l Set CustomFilteringService in MQChRecord if needed. e.g.: MQConnector.Utilities:filterXMLWrapper is used for data coming from JCI to remove xml header.

Page 11 Generating Listener Notification This has to be done through Developer Before generating Notification, corresponding connection and listener should be enabled. l Create new ‘Adapter Notification’ under MQConnections.Inbound.queue name l Adapter type: Websphere MQ adpater l Template: Websphere MQ Synchronous Listener Notification l Listener Name : select corresponding listener e.g.:Inbound.CUINJCI.listener l Enter a notification name and select folder Notification name – listenerNotif l Folder name - MQConnections.Inbound.CUINJCI l Select Messaging service name to be invoked: e.g.: MQConnector.Inbound.CUINJCI:receiveCUINJCI Select ‘Finish’ to create Listener Notification.

Page 12 WM developer generates two documents associated to this notification 1.Request Document 2. Reply Document e.g.:Inbound.CUINJCI:listenerNotifReplyDocument Inbound.CUINJCI:listenerNotifRequestDocument l After Notification is generated, add all rows under MQMD attributes. If any attribute is set with constant value then it will be used as a filter. l Open request document associated to the notification and check whether all following parameters are there. 1. msgBodyByteArray 2. queueManagerName 3. queueName 4. msgBody 5. msgHeader If no MQMD attrubute is added, then generated Request Document won’t have msgHeader attribute.

Page 13 Modifying Messaging Service ( if copied from messaging service which has listenerNotifRequestDocument ) l In the Input/Output parameter of messaging service change the Document Reference of listenerNotifRequestDocument e.g.: MQConnector.Inbound.CUINJCIABONORMAL:receive copied from MQConnector.Inbound.CUINJCI:receive. Then listenerNotifRequestDocument will be reference of MQConnections.Inbound.CUINJCI.listenerNotifRequestDocument Modify that to refer to MQConnections.Inbound.CUINJCIABONORMAL.listenerNotifRequestDocument.

Page 14 Configuring Put handler l Create a folder named as queue name in MQConnections.Outbound using WM Developer. e.g.: CUOUJCI l Configure a connection. l Put service is generated through WM developer l Select New ‘Adapter Service’ under new folder (CUOUJCI) created. l Select Adapter type as ‘WebSphere MQ Adapter’ l Select corresponding Adapter Connection Alias. l Select ‘Put Service’ as template. l Enter name of Put service (“put”) and select the folder. l Select “Finish” to generate put service. l Open Put service and specify Dead Letter queue name information under ‘Put Service’ tab. Dead letter Queue Name: CUOU_DLQ Dead Letter Queue Manager name : QM_COVMSG1 Headers to include in DLQ : DLH_&_MQMD

Page 15 Values for MQMD header attributes can be set in 2 ways. For both options first the attribute has to be added to MQMD header. This can be done thro webmethods Developer. Go to Put service and add the attributes in ‘MQMD Header’ tab. Option 1 : Dynamic values for MQMD header attributes  Set value in core flow (deliverMQ) and pass it on to put Handler. Particular attribute has to be mapped with pipeline value. e.g.: In ‘deliverMQ’ flow, pipeline object msgHeader’s attribute ApplIndentityData is mapped to put handler’s input parameter ‘putInput.msgHeader.ApplIndentityData’. Option 2 : Constant values for MQMD header attributes  Set Value in ‘MQMD header’ tab in put Handler. e.g.: Format set to “MQSTR”. But if value is set through both options then the value passed as input will be sent along with the message. e.g.: In ‘deliverMQ’ CodedCharSetId is set as ‘CP819’ and mapped to put handler’s input parameter. Also same attribute value is set as ‘CP1208’ in ‘MQMD Header’ tab in put handler using Developer. Then CP819 is the value that will be sent to customers. For all put handlers, Coded Char set Id is added as input field and set to CP819

Page 16 Put Handler’s Output parameters : MQMD attributes are returned by put handler. The attributes needed to be tracked are added as output parameters. In our application, following attributes are stored in message audit for most of the put handlers. 1.Application Identity Data 2. Coded Char Set ID 3. Format Add the above attributes for all put handlers in ‘Output Filed name’ under ‘MQMD Header’ tab. In ‘deliverMQ’ all these attributes are tracked. Note: Adapter services inherently depend on connections, so adapter connection for adapter service cannot be changed after configuration. If connection has to be modified for a put service then after modifying the connection and a new put service have to created.

Page 17 Configure DLQ Processor Though rare, some of the inbound MQ messages may go to the custom dead letter queue (DLQ) that we configure for all inbound queues – CUIN_DLQ. The message that goes to DLQ has a so called DLH header that contains the information about the original source queue of the messages. The DLQ processor parses this header, identifies the source queue and submits the message to the messaging hub as if it was coming from the original queue. The DLQ processor is a webMethods scheduled service (MQConnector.Tasks: sch_processDLQ) that calls a pre-configured CUIN_DLQ “get” service to poll for DLQ messages. In order to submit the message with the correct inbound channel id, the DLQ processor should know which “receive” service to call on the basis of known queue name. We maintain this configuration inside the MQConnector package in “config” directory as XML file named “MQConnectorConfig.xml”. In the source control tool (like ClearCase) three files are stored for configuration in “mqConnector\src\config\config\” directory. The current active configuration file has the original name of “MQConnectorConfig”. The file with “_prep” suffix in the name stores a reference pre-prod configuration, “_prod” suffix is for production configuration. Please maintain all three files accordingly. We typically keep production configuration as current so “MQConnectorConfig.xml” and “MQConnectorConfig_prod.xml” should be identical.

Page 18 Steps to configure DLQ processor: 1. Set the correct DLQ “get” service name in the element, e.g.: MQConnections.Inbound.CUIN_DLQ:get 2. Add a necessary with and, e.g.: CUINVSP_MSG MQConnector.Inbound.CUINVSP_MSG:receive 3. Add as many extra elements as needed. 4. Validate the XML file in a browser to make sure the syntax is correct. 5. Update the files in source control tool (e.g. ClearCase) accordingly.