mqsa 7 0 migr host ad

WebSphere MQ Interface 7.0

For Alliance Access 7.0

Migrating to the MQ Host AdapterThis guide explains how to migrate from the WebSphere MQ Interface for Alliance Access (MQSA) to the MQ HostAdapter (MQHA) in Alliance Access 7.0. It describes the prerequisites of the migration and how to migrate theconfiguration information of MQSA to an equivalent configuration for MQHA in Alliance Access 7.0. This document is foroperators and administrators of Alliance Access, and for users of the back-office applications that communicate withAlliance Access through IBM WebSphere MQ.

19 July 2013

Connectivity

Table of Contents

.Preface .............................................................................................................................................................................3

1 Introduction ....................................................................................................................................................... 4

1.1 Differences Between MQSA and MQHA ............................................................................................... 4

1.2 Impact of the Migration ............................................................................................................................. 5

2 Preparation ...................................................................................................................................................... 10

2.1 Prerequisites ............................................................................................................................................ 10

2.2 Overview of the Migration from MQSA ................................................................................................ 11

3 Migration to MQHA ....................................................................................................................................... 13

3.1 Migration Tasks on Alliance Access ..................................................................................................... 13

3.2 Defining Permissions for Message Partners ....................................................................................... 14

3.3 Migrating an MQ Queue to a Message Partner Profile ..................................................................... 15

3.4 Configuring Routing for Messages ....................................................................................................... 28

3.5 Configuring System Parameters ........................................................................................................... 34

3.6 Enabling a Message Partner Profile ..................................................................................................... 36

4 Post-Migration Tasks .................................................................................................................................. 37

.Appendix A Reference Information ...................................................................................................................38

A.1 WebSphere MQ ....................................................................................................................................... 38

.Legal Notices ...............................................................................................................................................................39

WebSphere MQ Interface 7.0 for Alliance Access 7.0

2 Migrating to the MQ Host Adapter

PrefacePurpose of this guide

Welcome to the guide for the migration to the MQ Host Adapter. This guide explains how tomigrate from the WebSphere MQ interface for Alliance Access (MQSA) to the MQ Host Adapter(MQHA) in Alliance Access 7.0.

It describes the prerequisites of the migration and the instructions for migrating the configurationinformation of MQSA to an equivalent configuration for MQHA in Alliance Access 7.0.

About this guide

This guide is intended for:

• The person responsible for installing Alliance Access software, and configuring the systemfor the MQ Host Adapter.

• Developers and users of the back-office applications that communicate with Alliance Accessthrough IBM WebSphere MQ.

Related documentation

The following documents are referenced:

• Alliance Access Daily Operations Guide

• Alliance Access Installation Guide (Windows systems, AIX, or Solaris)

• Alliance Access Security Guide

• Alliance Access System Management Guide

• WebSphere MQ Interface Installation Guide

• WebSphere MQ Interface User Guide

Preface

19 July 2013 3

1 IntroductionOverview

Alliance Access 7.0 supports two interfaces for exchanging SWIFT messages with back-officeapplications through IBM WebSphere MQ:

• the WebSphere MQ Interface for Alliance Access software application (referred to as MQSAin this document), which is built using functions of the Alliance Developer Kit (ADK).

• the Alliance Access MQ Host Adapter (referred to as MQHA in this document), which isembedded in the Application Interface. It does not require the installation of any ADKsoftware.

This guide explains how to migrate from MQSA to MQHA.

This migration can be performed gradually, per MQ queue. MQSA and MQHA can run inparallel until the migration is complete.

1.1 Differences Between MQSA and MQHAOverview

You can use the following sections to learn about the differences with the configuration ofMQSA and the configuration of MQHA.

Architecture

MQSA is built using the functions of the Alliance Developer Kit (ADK), to access the messagingservices of Alliance Access, which enable the communication between Alliance Access and IBMWebSphere MQ.

MQHA uses the message partner functionality of the Application Interface in Alliance Access. Amessage partner profile with the Connection Method "WebSphere MQ" manages thecommunication sessions between IBM WebSphere MQ and Alliance Access.

Licences

MQSA is an ADK component. It requires the Alliance Access licence package 99:TOOLKITRUN-TIME and a specific MQSA licence.

MQHA is fully integrated into Alliance Access 7.0. It requires the additional licence package13:MQ HOST ADAPTER. MQHA does not require the licence package 99:TOOLKIT RUN-TIME.

Data transport formats

MQSA supports the exchange of messages in the following data formats:

• ASCII or EBCDIC character encoding (MT messages)

• XML version 1 (MX messages only)

• XML version 2 (MX and MT messages)

MQHA supports the exchange of messages in the following data formats:

• MQ-MT (MT messages only)



MQHA supports ASCII character encoding only. The EBCDIC character encoding is notsupported. Therefore, IBM WebSphere MQ must perform the conversion between EBCDICand ASCII, if it is required. In that case, for messages sent from the back-office application,the Format field of the MQ Descriptor must be set to the value MQFMT_STRING. Formessages received by the back-office application, the get message optionMQGMO_CONVERT must be used.

• XML version 2 (MX, MT, and FileAct messages)

For more information about these formats, see the System Management Guide: MessageFormats Used in AI.

Message processing

Compared to MQSA, MQHA processes differently messages exchanged over IBM WebSphereMQ between back-office applications and Alliance Access. This requires changes within theback-office applications and Alliance Access. For details, see "Impact of the Migration" on page5.

Handling Validation Errors

In MQSA, if the message fails validation, then it is routed to an exit point using the routing rulewith function result Validation error of the routing point SMQS_From_MQSeries.

In MQHA, if Alliance Access detects a validation error, then it takes ones of the followingactions:

• if Message Modification allowed is set to Allowed in the MQHA message partner profile,then Alliance Access routes the message to the _MP_mod_text queue.

• if Message Modification allowed is set to Prohibited, then Alliance Access completesthe message.

Alliance Access includes both the original message and the reason for which the messagefailed validation in the logical reply that Alliance Access sends to WebSphere MQ.

For more information on how to configure the MQHA message partner, see the SystemManagement Guide: Managing Message Partner Profiles.

1.2 Impact of the MigrationOverview

The migration to MQHA has an impact on back-office applications and on Alliance Access. Thefollowing sections compare MQHA and MQSA behaviour.

1.2.1 Impact on Back-Office Applications

Coded Character Set ID (CSSID)

For MQHA, the CCSID used is 437. For MQSA, it is the one configured as the default at thequeue manager level.

EBCDIC character set not supported

MQHA supports ASCII character encoding only. The EBCDIC character encoding is notsupported. Therefore, IBM WebSphere MQ must perform the conversion between EBCDIC andASCII, if it is required.

Introduction

19 July 2013 5

For messages in MQ-MT format, MQHA exchanges data with WebSphere MQ in ASCII. Itexchanges messages in XML format in UTF-8.

XML version 1 not supported

MQHA does not support XML version 1. With XML version 2 (XMLv2), you can use revision2.0.0, 2.0.1, 2.0.2, or 2.0.3.

For more information about the differences between version 1 and version 2 of XML, see theSystem Management Guide: XML Formats.

Transferring information about Alliance Access (SAAInfo)

MQSA can include information about the Alliance Access instance only in the MQ messagedescriptor.

MQHA can send this information in the MQ message data part or in the MQ messagedescriptor. When this information is included in the message data part, it is transmitted throughadditional tags of the S-block for the MQ-MT format, and through the new SAAInfo element forthe XMLv2 format.

For more information, see the System Management Guide: XML Format 2.

Important If you want to transmit the SAA information in the message data part, then youmust adapt the back-office application to handle the new fields in that part for theSAAInfo element.

Messages on MQ dead letter queue

In MQSA, failures during message processing, such as LAU authentication failures, can lead toa message being put on the MQ dead letter queue.

With MQHA, the only type of message that can be put on the dead letter queue is a Report/Reply message that was not successfully stored on the MQ reply-to queue or the error queue (ifdefined in the MHQA message partner). In case of LAU failures, the message remains on theMQ queue and the MQHA Message Partner is automatically disabled. For all other failures, themessage cannot be routed and is stored as an Internal message within Alliance Access.

Exit routines not supported

MQSA uses Exit Routines because the standard features of IBM WebSphere MQ do notprovide application-to-application security. If Exit Routines are used in MQSA for otherpurposes, then the WebSphere MQ Channel Exit Routines must be used for MQHA. For moreinformation, see the IBM WebSphere MQ documentation.

MQHA offers application-to-application security through the Local Authentication feature.

Logical Terminals are assigned automatically

In MQSA, Logical Terminals (LT) are assigned automatically to the messages before they arestored in Alliance Access. This is done based on a static list of BIC11s (receiver or sender).

MQHA uses the generic load balancing that Alliance Access provides. The assignment of an LTis based only on the BIC8 of the sender specified in the MT message. It is performed when theMT message is sent to SWIFT. For more information about Load Balancing, see the SystemManagement Guide: Automatic Logical Terminal Allocation.



No reconciliation of delivery notification system message

When MQSA processes a delivery notification system message for output, it copies the originalmessage ID from the original MQ message descriptor of the associated input message into thecorrelation ID of the message sent to the back-office application.

MQHA does not support the reconciliation of a delivery notification system message with theoriginal message.

If reconciliation is required, then a back-office application must use the MIR of the originalmessage which is contained within the delivery notification system message. The back-officeapplication can also make use of the Alliance Access traffic reconciliation (TR_REC) and routethe created delivery notification. For more information, see the System Management Guide:XML Format 2 - Message Reconciliation Scenario.

Feedback field not used for ACK or NAK

In MQSA 7.0 or previous releases, you could use the Feedback field in the MQ messagedescriptor to send a network acknowledgement (ACK or NAK), as follows:

• ACK - Feedback had the value 275, for positive acknowledgement

• NAK - Feedback had the value 276, for negative acknowledgement

With MQHA, if you send an ACK or NAK to MQ, then the Feedback field has the value 0 (nostatus). The Feedback field is only used to return a Logical Reply, which is PAN or NAN. Tocheck the status of a message, you must check the content of the ACK or NAK.

S-block always placed at end of transmission notification

MQHA can send SWIFT acknowledgements to back-office applications with or without includingthe complete original message.

The S-block is always placed at the end of the transmission notification, as follows:<ACK><Message><S-Block>The S-block is optional. If the S-block is present, then it appears in the following location:

ACK or NAK MQSA MQHA

with original message <ACK><S-block><MT-Blocks1,2,3,4,5>

<ACK><MT-Blocks 1,2,3,4,5><S-block>

without originalmessage

<ACK><S-block> <ACK><MT-Blocks 1,2,3,5><S-block>In this case, there is no Block 4.

Order of tags in block 5 and S-block

For input messages and transmission notifications, MQSA puts the {REF:} and {RTV:} blockswithin the block 5 of the MT message.

MQHA puts the {REF:} and {RTV:} blocks in the S-block, and builds block 5 as described in theFIN Operations Guide.

Calculation of Common Reference in Field 22 of Block 4

In FIN Messages, the field 22 of Block 4 is composed of two mandatory components:

• a function code, that must be one of AMEND, CANCEL, CLOSEOUT, or NEW

• a Common Reference, that is derived from the Sender and Receiver, and from the content offield 36.

Introduction

19 July 2013 7

MQSA does not calculate the Common Reference in Field 22 of Block 4 automatically.

In Alliance Access, the configuration parameter Common Ref Calculation, determines whetherAlliance Access calculates the Common Reference automatically for the messages that use thedata formats, CAS, RJE, DOS-PCC, and XML version 2. For more information about thisparameter, see the System Management Guide.

If you must ensure that archived messages on the customer site must match those messagesthat are sent to SWIFT, then you can set Common Ref Calculation to No. This action meansthat Alliance Access does change the value of field 22 or repair the Common Reference.Therefore, a NAK may be received if field 22 of the message contains incorrect information.

Quit ACK

MQSA sends a transmission notification of an MT05 Quit ACK as an F25 message, followed byan F01.

MQHA sends a Transmission notification of an MT05 Quit ACK as an F25 message, followed byan F05.

RTV trailer

The RTV trailer indicates that the message has been retrieved from the network. MQSAincludes the RTV trailer in Block 5.

MQHA includes the RTV trailer in the S-block.

Interventions in History notifications

In MQSA, a History notification instance contains all interventions for the original message.

For MQHA, a History notification contains a maximum of 10 interventions, which are the 10most recent interventions. For more information about interventions, see the SystemManagement Guide: Structure of the DataPDU - HistoryReport.

1.2.2 Impact on Alliance Access

Routing rule modifications

MQSA allows you to dispose a message to any queue and to route messages.

MQHA uses message partner functionality. Therefore, Alliance Access can handle a receivedmessage in one of the following ways:

• Route the message from a message partner according to the routing rules that are specifiedfor the _AI_from_APPLI queue.

• Dispose the message to one of the following queues:

– Modification

– Verification

– Authorisation

– Ready-to-send

Note New routing rules are required for MQHA to route and dispose messages. Formore information, see "Configuring Routing for Messages" on page 28.



No reconciliation of delivery notification system message

As described in "Impact on Back-Office Applications" on page 5, if the Alliance Access trafficreconciliation (TR_REC) is used, then the created delivery notification must be routed to theback-office application.

Function result in routing point _AI_from_APPLI

As described in "Differences Between MQSA and MQHA" on page 4, the routing point_AI_from_APPLI does not have the function result Validation error.

Introduction

19 July 2013 9

2 PreparationIntroduction

This section lists the prerequisites that must be met before starting the migration. It alsoprovides an overview of the migration process.

High-level approach to migration

The following steps provide a high-level approach to the migration:

• Read this document carefully.

• Understand your MQSA configuration.

• Understand the message partner and routing concepts.

• Understand the system configuration that is required in Alliance Access.

• Migrate from MQSA and customise your new system.

2.1 PrerequisitesOverview

Before you start the migration, the following prerequisites must be met.

Alliance Access

You must have Alliance Access 7.0 installed.

The licence packages, 13: MQ HOST ADAPTER and 99:TOOLKIT RUN-TIME must beinstalled. The latter allows you to use MQSA 7.0.

MQHA is integrated with Alliance Access 7.0. You are not required to install extra software for it.

At the time of migration, there must be no messages present in the Alliance Access queues thatare awaiting delivery to MQSA. To do this, you must get the messages delivered, or manuallycomplete all messages in the Message File application.

The Application Interface has several functions available and some of its functions have afurther level of entitlement, known as permissions. These permissions are included within thedefault profiles of Alliance Access 7.0. Ensure that the operators that have access to thegraphical user interface for MQSA also have access to the Application interface. If you have tocreate additional operator profiles with special permissions for the Application Interface, thenyou can define these before starting the migration. For example, if you have created adedicated MQSA profile already, you can change the permissions in this profile.

In addition, if you have to change the existing security definition profile "R7.0_MsgPartner", thenyou can change it, or create a new profile before the migration.

If you are not familiar with the concepts of message partner profiles, session management, ormessage routing, then SWIFT recommends that you read the following sections:

• Daily Operations Guide: Managing Message Exchange Sessions

• System Management Guide: Managing Message Partner Profiles

• System Management Guide: Message Routing



Back-office applications

Ensure that each back-office application has been adjusted to manage the impact of themigration. If a back-office application expects to receive EBCDIC, then it must use theWebSphere MQ functions to convert from ASCII to EBCDIC.

For more information, see "Impact on Back-Office Applications" on page 5.

MQSA

Ensure that there is no business data waiting to be migrated from MQSA to MQHA. That is, atthe time of migration, MQ queues must not contain messages that are awaiting delivery toAlliance Access or to a back-office application.

Data

Review the configuration data, which will be migrated:

• MQSA queues, for which you must create message partners for MQHA

• routing queues, routing points, routing rules, and routing codes

• operator profiles

• configuration parameters

• mapping of Logical Terminal assignment

2.2 Overview of the Migration from MQSADescription

To migrate from MQSA, you must complete the following tasks:

1. Ensure that the prerequisites are met, as described in "Prerequisites" on page 10.

2. Perform the tasks outlined in "Migration to MQHA" on page 13, to migrate the MQSAconfiguration to an equivalent configuration for MQHA in Alliance Access 7.0. These tasksmust be repeated for each MQ queue.

This migration can be performed gradually. You do not have to migrate all your MQ queuesat once from MQSA to MQHA. MQSA and MQHA can run in parallel: MQ queues that havenot been migrated yet can still be used in MQSA while other MQ queues have already beenmigrated to MQHA.

3. Verify the successful exchange of messages through MQHA to a back-office applicationthrough IBM WebSphere MQ.

If you do not succeed in exchanging a message with a back-office application, then ensurethat the message partners are enabled. Verify the session parameters in the messagepartner profile. Verify that the routing and message partners are defined correctly.

4. Remove MQSA once all MQ queues have been successfully migrated to MQHA, and if youare sure that all back-office applications are processing messages properly. For moreinformation about removing MQSA, see the WebSphere MQ Interface Installation Guide.

5. Down license your ADK packages, unless they are required for other ADK applications. Formore information about down licensing ADK packages, see the Alliance Access InstallationGuide: Down Licensing.

Preparation

19 July 2013 11

Important Do not remove the Alliance Developer Kit (ADK) until after you have verifiedthat the migration was successful.



3 Migration to MQHAOverview

This section describes the tasks that you must perform to migrate from MQSA to MQHA inAlliance Access 7.0.

Terminology

• Input message partner refers to a message partner profile that has the Allowed direction setto "From Message Partner" in the profile definition.

• Output message partner refers to a message partner profile that has the Allowed directionset to "To Message Partner" in the profile definition.

3.1 Migration Tasks on Alliance AccessOverview

This section provides an overview of the migration tasks that you must perform on AllianceAccess.

Before you begin

Before you start the migration, check the software and ensure that the prerequisites have beenmet and that preparation is complete.

Migration Tasks

D05

4013

8

Define security definitionprofile

Create message partnerprofile(s)

Define routing configuration

Configure system-wideparameters

Enable message partnerprofile(s)

Description

1. For input message partners, you can define a security definition profile which controls thecreation and routing of messages from IBM WebSphere MQ within Alliance Access. You

Migration to MQHA

19 July 2013 13

can select this profile when you create an input message partner for a WebSphere MQconnection.

For more information, see "Defining Permissions for Message Partners" on page 14.

2. Create the message partner profiles that manage the flow of messages between AllianceAccess and a back-office application through WebSphere MQ.

For more information, see "Migrating an MQ Queue to a Message Partner Profile" on page15.

Note One MQ queue in MQSA corresponds to one message partner profile inAlliance Access 7.0.

3. Define the routing configuration that Alliance Access will use to route messages to and froma message partner.

For more information, see "Configuring Routing for Messages" on page 28.

4. Configure the system parameters for WebSphere MQ for Alliance Access.

For more information, see "Configuring System Parameters" on page 34.

5. Enable message partners for WebSphere MQ and start any manual communicationsessions. For more information, see "Enabling a Message Partner Profile" on page 36.

3.2 Defining Permissions for Message PartnersPurpose

For input message partners, you can define security definition profiles that control the creationand disposition of incoming messages in Alliance Access.

You can use the existing security definition profile "R7.0_MsgPartner", or define a new profile, ifyou need special permissions for disposing a message.

R7.0_MsgPartner profile

Alliance Access uses the security definition profile "R7.0_MsgPartner" only within theApplication Interface, to grant privileges to an external application, which is defined as amessage partner profile. Those privileges apply only when the external application sendsmessages to Alliance Access. Specifically, this profile controls how Alliance Access handles thecreation and disposition of message instances.

You can change permissions of this profile, or define a new profile from the Security Definitionapplication.



For a description of the default profiles, see the Security Guide.

For more information about entitlements and permissions, see the Security Guide: DefiningOperators.

For information about creating a default profile or changing an existing profile, see the SystemManagement Guide: Managing Alliance Security and System Management Guide: StandardDefault Profiles: Application Interface Application.

Reception tab

The Reception tab of a message partner profile has a parameter, Profile name, defined for asecurity definition profile. In this field, you can select a profile that has the permissions whichyou want to apply to the message partner. You can select the existing profile"R7.0_MsgPartner", or a newly created profile.

For more information about specifying the Profile name parameter for reception messagepartners, see "Creating an Input Message Partner Profile" on page 16.

3.3 Migrating an MQ Queue to a Message PartnerProfile

Overview

In MQSA, an MQ queue is defined to specify information about the connection to WebSphereMQ. This section describes how to create a message partner profile in Alliance Access thataccomplishes the same results as a specific MQ queue in MQSA.

For each MQ queue that you migrate, you must perform the following steps:

• create a message partner profile with the Connection Method "WebSphere MQ"

• specify the direction of message transfer

• configure the profile.

Migration to MQHA

19 July 2013 15

3.3.1 Creating an Input Message Partner Profile

Overview

This section describes how to create a message partner profile that controls the transport ofmessages from a back-office application to Alliance Access.

To create an input message partner profile

1. Open the MQSeries interface window, which displays a list of the MQ queues that aredefined in MQSA. Double-click a queue to view its details.

For more information, see the WebSphere MQ Interface User Guide: MQSeries InterfaceMain Window.

2. Using the procedure described in the System Management Guide: WebSphere MQConnection Method, create a message partner for the MQ queue.

3. In the Connection Method field, select WebSphere MQ, and select a value in the DataFormat field.

4. In the Allowed direction, select "From Message Partner".

5. Complete the remaining fields and tabs in the Message Partner window, using theinformation in "Parameters for an Input Message Partner" on page 17.

You must enable a message partner profile before Alliance Access can use it in acommunication session.

Example of an MQ queue for incoming messages

The following shows the details of a queue, which is defined in MQSA:



3.3.2 Parameters for an Input Message Partner

Overview

This section outlines the parameters and values that you must define when migrating an MQqueue to a message partner with the Allowed direction, "From Message Partner".

3.3.2.1 Profile Tab

Overview

This section describes the Profile tab for a WebSphere MQ message partner. It also explainsthe parameters that you can use to support FileAct over WebSphere MQ.

For more information about the parameters listed in this section, see the System ManagementGuide: Managing Message Partner Profiles.

Parameters

The following table explains how to complete the parameters on the Profile tab, and explainshow to locate their values in MQSA or to provide new values:

MP field MP value Corresponding MQSA queueparameter

Message partner The name of the message partner profile -

Description Value as defined in MQSA Description

Allowed direction "From Message Partner" Message Flow Direction

Connection method "WebSphere MQ" -

Session initiation The options are:

• Manual

• Automatic

-

Queue Manager Name Value as defined in MQSA Queue Manager Name

Queue Name Value as defined in MQSA Queue Name

Error Queue Name Value as defined in the System Configurationparameter for MQSA.

If you leave this field empty, then the default errorqueue is used.

-

Keep session Open If the Session initiation is set to Manual, then selectthis option to ensure that Alliance Accessautomatically recovers a failed communicationsession.

-

Transfer SAAInformation

Value as defined in MQSA.

If selected, the Use MQ Descriptor field becomesavailable.

Transfer SAA info

Use MQ Descriptor Specify whether to transfer the SAA information inthe MQ Descriptor. Before you can use the MQDescriptor to transfer the SAA information, you setthe SETID privilege in IBM WebSphere MQ.

If not selected, then the SAA information is sent inthe MQ Message Data part.

-

Migration to MQHA

19 July 2013 17


Data format If ASCII or EBCDIC is used in MQSA, then select"MQ-MT"

If XML is used in MQSA, then select "XML" andselect the Revision.

Message Data

Version "2"

This field is only available when the data format isXML.

Version (1)

Revision Options:

• "Original", if the XML revision 2.0.1, 2.0.2, or 2.0.3is not being used

• "1", for revision 2.0.1



-

(1) If MQSA was using XML version 1, then you must migrate to XML version 2. For more information, see the System

Management Guide: Migration Path from Version 1 to Version 2.

Parameters to support FileAct

The following table explains how to complete the parameters on the Profile tab that support thesending of FileAct messages over WebSphere MQ. you must select at least revision 2 of XMLversion 2:


FileAct mode Select from:

• Full

• Mixed

-

Chunk Size If you selected Full FileAct mode, then specify themaximum size of a WebSphere MQ message (inbytes) that Alliance Access can send a back-officeapplication.

-

Don't Use Segmentation If you selected Full FileAct mode, and the payload ofthe file is greater than the Chunk Size, then clearthis option to ensure that the payload file issegmented before it is sent to the back-officeapplication.

-

Input AttachmentDirectory

If you selected Mixed FileAct mode, then specify thepath to a directory on the server where the payloadfile is stored

The exact payload file name will be extracted fromthe content of the XMLv2 message.

-



Example

3.3.2.2 Authentication Tab

Overview

This section explains how to complete the parameters on the Authentication tab.

If a Local Authentication failure occurs, the MQHA Message Partner is automatically disabled.

Parameters


Local authenticationrequired


Select this option if "Yes" is selected in MQSA.

If selected, more fields appear. To complete them,see the System Management Guide: Specifying LocalAuthentication.

LAU Required

3.3.2.3 Reception Tab

Overview

This section describes the Reception tab for a WebSphere MQ message partner. For moredetails about this tab, see the System Management Guide: Specifying the ReceptionParameters.

Parameters

The following table explains how to complete the parameters on the Reception tab, andexplains how to locate their values in MQSA or to provide new values:


Validation level Value as defined in MQSA Validation Level(2)

Migration to MQHA

19 July 2013 19


Profile name A security definition profile, for example,R7.0_Msg_Partner

For more information, see the System ManagementGuide: Selecting a Permission Profile for theMessage Partner.

-

Message modificationallowed

Specify whether the text of a message received froma message partner can be modified in AllianceAccess.

For more information, see the System ManagementGuide: Specifying Message Modification.

-(2)

Unit to be assigned Specify a unit to which an incoming message from amessage partner is assigned.

For more information, see the System ManagementGuide: Assigning a Unit.

-

UUMID included inOriginal Message

Specify whether the original message to be sentincludes a UUMID.

This option is available only for the data format, MQ-MT.

-

Disposition Value as defined in MQSA.

For more information, see the System ManagementGuide: Message Disposition.

Disposition

Transfer UUMID Transfers the UUMID with the message.


- (1)

Original Message Appends the original message request to anotification.


- (1)

Validation Error Code Includes an error code in a response message if anerror occurred during processing.


- (1)

(1) This value is set in MQSA using the Feedback field of the MQ descriptor in the original message. For more details,

see the WebSphere MQ Interface User Guide: Report Message Options.

(2) If the configuration parameter Common Ref Calculation is set to No, then Alliance Access does not calculate the

Common Reference in field 22. In this case, Validation level and Message modification allowed are ignored and

a NAK may be received if field 22 of the message contains incorrect information.



Example

3.3.2.4 Unused MQ Parameters

The following table lists the parameters in an MQ queue definition that have no equivalent in aninput message partner profile.

Parameters

Unused MQ queue parameter Reason

Use Exit Routine Exit routines are not supported in MQHA.

Priority Not required, because Alliance Access reads the queuesconcurrently.

Message to Read Not required, because Alliance Access reads the queuesconcurrently.

Reply-to-Queue Format The message partner supports only ASCII encoding for messages inMQ-MT format. EBCDIC is not supported.

3.3.3 Creating an Output Message Partner Profile

Overview

This section describes how to create a message partner profile that controls the transport ofmessages from Alliance Access to a back-office application.

Migration to MQHA

19 July 2013 21

To create an output message partner profile:

1. Open the MQSeries interface window, which displays a list of the MQ queues that aredefined in MQSA. Double-click a queue to view its details.

For more information, see the WebSphere MQ Interface User Guide: MQSeries InterfaceMain Window.

2. Using the procedure described in the System Management Guide: Managing Exit PointProfiles, create an exit point that you must assign later to the output message partnerprofile. An exit point is a special routing point which is assigned to a message partnerprofile, such as a WebSphere MQ message partner. The exit point controls the delivery ofmessages to a back-office application.

Example of an exit point assigned to a message partner

3. Using the procedure described in the System Management Guide: WebSphere MQConnection Method, create a message partner for the MQ queue.

4. In the Connection Method field, select WebSphere MQ, and select a value in the DataFormat field.

5. In the Allowed direction field, select "To Message Partner".

6. Complete the remaining fields and tabs in the Message Partner window, using theinformation in "Parameters for an Output Message Partner" on page 23.

You must enable a message partner profile before Alliance Access can use it in acommunication session.



Example of an MQ queue for outgoing messages

The following shows the details of a queue, which is defined in MQSA:

3.3.4 Parameters for an Output Message Partner

Overview

This section outlines the parameters and values that you must define when migrating an MQqueue to a message partner with the Allowed direction, "To Message Partner".

3.3.4.1 Profile Tab

Overview

This section describes the Profile tab for a WebSphere MQ message partner. It also explainsthe parameters that you can use to support FileAct over WebSphere MQ.

For more information about the parameters listed in this section, see the System ManagementGuide: Managing Message Partner Profiles.

Parameters

The following table explains how to complete the parameters on the Profile tab, and explainshow to locate their values in MQSA or to provide new values:


Message partner The name of the profile -

Description Value as defined in MQSA Description

Allowed direction "To Message Partner" Message Flow Direction

Connection method "WebSphere MQ" -

Migration to MQHA

19 July 2013 23


Transfer PKI Signatures Value as defined in MQSA.

This field is only available for the MQ-MT dataformat.

Transfer PKI signature

Always transfer MAC/PAC

Value as defined in MQSA Always Transfer MAC/PAC

Session initiation The options are:

• Manual

• Automatic

-

Queue Manager Name Value as defined in MQSA Queue Manager Name

Queue Name Value as defined in MQSA Queue Name

Error Queue Name Value as defined in the System Configurationparameter for MQSA.

If you leave this field empty, then the default errorqueue is used.

-

Keep Session Open Select this option to ensure that Alliance Accessautomatically recovers a failed communicationsession.

-

Transfer SAAInformation


If selected, the Use MQ Descriptor field becomesavailable.

Transfer SAA info

Use MQ Descriptor Specify whether to transfer the SAA information inthe MQ Descriptor.

Before you can use the MQ Descriptor to transfer theSAA information, you set the SETID privilege in IBMWebSphere MQ.

-

Data format If ASCII or EBCDIC in MQSA, then select "MQ-MT".

If XML in MQSA, then select "XML" and select theRevision.

Message Data

Version "2"

This field is only available for XML data format.

Version(1)

Revision Options:

• "Original", if the XML revision 2.0.1 or 2.0.2 is notbeing used



For more information, see the System ManagementGuide: XML Formats.

-

Run output session This section appears when you select Automatic inthe Session initiation field.

For more information, see the System ManagementGuide: WebSphere MQ Connection Method.

-

(1) If MQSA was using XML version 1, then you must migrate to XML version 2. For more information, see the System

Management Guide: Migration Path from Version 1 to Version 2.



Parameters to support FileAct

The following table explains how to complete the parameters on the Profile tab that support thesending of FileAct messages over WebSphere MQ. you must select at least revision 2 of XMLversion 2:


FileAct mode Select from:

• Full

• Mixed

-

Chunk Size If you selected Full FileAct mode, then specify themaximum size of a WebSphere MQ message (inbytes) that Alliance Access can send a back-officeapplication.

-

Don't Use Segmentation If you selected Full FileAct mode, and the payload ofthe file is greater than the Chunk Size, take one ofthe following actions:

• select this option to chunk the file based on theMessage Grouping only

• clear this option to chunk the file based on thevalue of Chunk Size

-

Output AttachmentDirectory

If you selected Mixed FileAct mode, then specify thepath to a directory on the server where the payloadfile is stored

The exact payload file name will be extracted fromthe content of the XMLv2 message.

-

Example

Migration to MQHA

19 July 2013 25

3.3.4.2 Authentication Tab

Overview

This section explains how to complete the parameters on the Authentication tab.

Parameters


Local authenticationrequired


Select this option if "Yes" is selected in MQSA.

If selected, more fields appear. To complete them,see the System Management Guide: Specifying LocalAuthentication.

LAU Required

3.3.4.3 Emission Tab

Overview

This section describes the Emission tab for a WebSphere MQ message partner. For moredetails about this tab, see the System Management Guide: Specifying the EmissionParameters.

Parameters

The following table explains how to complete the parameters on the Emission tab, and explainshow to locate their values in MQSA or to provide new values:


Exit Points The exit point where messages are queued beforesending to the message partner.

If an exit point exists, then you can assign it to themessage partner here. If not, you can assign it later.

See the System Management Guide: Emission Taband System Management Guide: Managing ExitPoint Profiles.

-

Routing codetransmitted

Select this option to transmit the application routingcode (defined in MQSA as "APPL-ROUTINGCODE")to the message partner.

See step 2 on page 32, and the SystemManagement Guide: Emission Tab.

-

Message emissionformat

Value as defined in MQSA Message Text

Send original message Value as defined in MQSA.

See the System Management Guide: Specifying theNotification Content.

Notification Emission: SendOriginal Message

Format of originalmessage

Specify how much content of the original message isincluded in the notification.

See the System Management Guide: Specifying theNotification Content.

-

Transfer UUMID Value as defined in MQSA.

This is only available for the MQ-MT format.

Include UMID




Include TRN Select this option to send the transaction referencenumber of the original message to the messagepartner.


-

Remove S-Block Select this option to remove the S-Block from the MQMessage Data part of the message (and the originalmessage, if it is transferred).


Strip S-Block

Example

3.3.4.4 Unused MQ Parameters

Overview

The following table lists the parameters in an MQ queue definition that have no equivalent in anoutput message partner profile.

Parameters

Unused MQ queue parameter Reason

Routing code Each MQ message partner, through the assigned exit point, ismapped to an MQ queue.

Migration to MQHA

19 July 2013 27

3.4 Configuring Routing for MessagesOverview

This section describes how to configure Alliance Access to route or to dispose messagescoming from and going to a message partner.

In Alliance Access, the Routing application processes a message at a routing point according toits associated routing rules.

A routing schema is used to group routing rules to allow activation within the system. Eachrouting rule can belong to one or more routing schemas. However, only routing rules assignedto the active schema are used for processing the messages that arrive at a routing point.

For more information about routing, see the System Management Guide.

Routing points for MQSA

MQSA includes three pre-defined routing points:

• SMQS_From_MQSeries, which handles messages coming from WebSphere MQ

• SMQS_To_MQSeries, which handles messages being sent to WebSphere MQ

• SMQS_Msg_Wait, which handles messages that MQSA has put on hold.

This last routing point is for internal use only and is not visible from the Routing application.

The configuration of routing for MQHA requires that you create new routing rules and routingpoints for messages that MQHA will process.

3.4.1 Migrating the Routing for Incoming Messages

Overview

When a back-office application sends messages to Alliance Access, the SMQS component inMQSA creates messages in the SMQS_From_MQSeries routing point.

For MQHA, the _AI_From_APPLI queue replaces the SMQS_From_MQSeries routing point,which MQSA uses.

_AI_From_APPLI Queue

Alliance Access places all the messages received from a back-office application, includingMQHA, in the _AI_From_APPLI queue. This is done regardless of the connection method andthe message format that are used. From there, the Message Processing Function (MPF) routesthem according to the active routing schema and according to the message partner profile thatis associated with the application.

For more information about the processing of messages in this queue, see the SystemManagement Guide: List of System Queues.

To migrate routing for incoming messages:

1. Take a backup of your routing information. Print out all your routing so that you can refer toit when required.

2. In the System Management application, select the Queue view. Then, select the_AI_From_APPLI queue and view its details. In the Routing tab, select the optionsDisplay Rules Allowed and Modify Rules Allowed.



3. Open the Routing application, and review the rules defined for the SMQS_From_MQSeriesrouting point. Determine which rules are still valid.

For more information, see the System Management Guide: Defining Routing Rules.

4. For each valid routing rule for the SMQS_From_MQSeries routing point, add a new routingrule with the same conditions and actions to the _AI_From_APPLI routing point.

The mapping of the function results is provided in the following table:

MQSA - SMQS_From_MQSeries MQHA - _AI_from_APPLI

Accept Success

Validation Error Failure

MQ error Failure

Nacked Not applicable for MQHA (1)

Recovery Not applicable for MQHA (1)

Reject Not applicable for MQHA (1)

(1) This MQSA function result is not applicable for MQHA. It was used internally by MQSA recovery.

5. Verify that the order of the routing rules in the _AI_From_APPLI routing point is correct.

6. From the printouts of your routing point details, search for all the routing rules that includeSMQS_From_MQSeries in the criteria for routing. The criteria are defined in the Conditiontab of a routing rule.

If a routing rule contains the criteria, (Creating_mpfn = 'SMQS_From_MQSeries'),then change it to (Src_entity = <WebSphere MQ MP name1>) or (Src_entity =<WebSphere MQ MP name2>) or (Src_entity = <WebSphere MQ MP name3>).This depends on the number of input queues that you originally had. The example heretakes three 'From MQ' WebSphere MQ queues, for each of which three new 'FromMessage Partner' message partners with Connection method 'WebSphere MQ' have beencreated, and where <WebSphere MQ MP nameN> is the name of the input messagepartner as defined in "Creating an Input Message Partner Profile" on page 16.

If other routing rules contain the criteria (Src_entity = <WebSphere MQ queuename>), then change these to (Src_entity = <WebSphere MQ MP name>).<WebSphere MQ MP nameN> is the name of the input message partner associated to the<WebSphere MQ queue name>, as defined in "Creating an Input Message PartnerProfile" on page 16.

Migration to MQHA

19 July 2013 29

MQHA example

The _AI_From_APPLI queue has the following targets assigned to it:

The following shows an example of the routing rules defined for the routing pointAI_From_APPLI:



The following shows an example of the conditions of the routing rule, "Send message toaddressee". If the message is processed successfully, then the action of this routing rule isapplied to the message:

The following shows an example of the actions that are applied if the conditions of the routingrule, "Send message to addressee" are met:

The routing code is applicable for routing points that control outgoing messages. For example, arouting point that is assigned to an exit point.

Migration to MQHA

19 July 2013 31

3.4.2 Migrating the Routing for Outgoing Messages

Overview

All the messages that are queued at an exit point are transmitted to a specific WebSphere MQqueue. In the MQSA application, you can define the code MQSA-ROUTINGCODE that MQSAuses to identify the WebSphere MQ queues. This code is also included in the Free FormattedIntervention field in a routing rule for a specific routing point. The code enables MQSA to routea message which is queued at that routing point to the correct WebSphere MQ queue.

In MQHA, MQSA-ROUTINGCODE and APPL-ROUTINGCODE are not used as such. Toreplace the MQSA-ROUTINGCODE and APPL-ROUTINGCODE codes, you must configurerouting rules and message partners, as detailed in this section.

To migrate routing for outgoing messages:

For each MQSA queue that was used to send messages to the WebSphere MQ, you mustdefine one exit point, as follows:

1. For each MQSA queue that controls outgoing messages, define an exit point. For moreinformation, see the System Management Guide: Defining an Exit Point.

Assign each exit point to an output message partner for a WebSphere MQ connectionmethod.

After you create an exit point, Alliance Access assigns the message processing function_AI_To_APPLI_ to it and creates a routing point of the same name.

2. You can configure the Routing application to transmit automatically an application routingcode to a message partner. This application routing code replaces the code APPL-ROUTINGCODE that was contained in Free text intervention fields of the routing ruleswhere SMQS_to_MQSeries is a target.

To configure the application routing code transmission, do the following:

a. Look for the MQSA routing rules that contain the code APPL-ROUTINGCODE.

b. Create a new routing rule for the routing point that corresponds to the exit point.Specify the application routing code in the Routing code field present in the Actiontab of the routing rule.

c. In the corresponding message partner profile, ensure that the option Routing codetransmitted is selected in the Emission tab.

3. To replace the MQSA-ROUTINGCODE code used in MQSA, you must find the rules in theother routing points that send messages to SMQS_To_MQSeries. Then you must changeor recreate those rules to send the messages to exit points. For more information, see theSystem Management Guide: Classes of Configuration Parameters - WebSphere MQ.

4. Restart Alliance Access in operational mode.

Examples of a routing rule in MQSA and MQHA

The following examples illustrate a routing rule which sends ACKs back to the back-officeapplication.



Routing at _SI_to_SWIFT: ACK from MQSA to back-office application

Migration to MQHA

19 July 2013 33

Routing at _SI_to_SWIFT: ACK from MQHA to back-office application

3.5 Configuring System ParametersOverview

This section describes how to migrate the configuration parameters of MQSA to Alliance Access7.0.

Note The parameters are available only if the package 13:MQ HOST ADAPTER islicensed.



To configure the system parameters:

1. Open the MQSA graphical user interface. From the File menu, select Configuration.

2. Open the System Management application. From the View menu, select Configuration, ifit is not already selected.

3. Set the parameters for the WebSphere MQ class to match the parameters in MQSA.

The following table provides a mapping of the parameters between MQSA and the SystemManagement application (SMA):

SMA configurationparameter MQSA parameter Description

Connection Mode None

Check the SMQS Details tabin your MQSeries InterfaceSystem Configuration, whichidentifies the client or serversetup. For more information,see the WebSphere MQInterface User Guide:WebSphere MQ Client andWebSphere MQ ServerComponents.

Specifies the mode (Client or Server)that the MQ interface of AllianceAccess uses to connect to a QueueManager.

Before you change this parameter, youmust disable all the message partnerprofiles for MQ.

For this change to take effect, you mustrestart the Alliance Access servers.

Input Message RateLimit

Enable Throttling -Messages/Second

Limits the number of messages thatAlliance Access reads per second fromall the WebSphere MQ queues that areconfigured in Alliance Access.

Before you change this parameter, youmust disable all the message partnerprofiles for MQ.

Recovery Time - Initial Initial Time Specifies the number of seconds afterwhich Alliance Access first attempts to

Migration to MQHA

19 July 2013 35

SMA configurationparameter MQSA parameter Description

recover a communication session withWebSphere MQ.

Recovery Time -Increment

Increment Time Specifies the number of seconds bywhich Alliance Access increases theinterval between consecutive attemptsto recover a WebSphere MQ session.

Recovery Time - Max Maximum Time Specifies the maximum interval, inseconds, after which Alliance Accessattempts to recover a WebSphere MQsession.

For more information about the configuration parameters for MQHA, see "WebSphere MQ"on page 38.

4. Save the changes to the parameters.

3.6 Enabling a Message Partner ProfileOverview

After adding or modifying a message partner profile, you must enable the profile before it canparticipate in a communication session.

To enable a message partner profile:

1. Select the required profile from the Message Partner view.

2. Select Enable from the Message Partner menu. The Status attribute displayed in theMessage Partner view changes to Enabled.

For more information about running and managing a communication session with a messagepartner, see "Managing Message Exchange Sessions" in the Daily Operations Guide.



4 Post-Migration TasksOverview

This section describes optional post-migration tasks.

Process

1. If you no longer require MQSA, then remove the MQSA component. For more information,see the WebSphere MQ Interface Installation Guide.

2. If you no longer require the Alliance Developer Kit (ADK) for Alliance Access, then you candown license it.

As MQSA is an ADK component, the ADK RUN TIME licence was required (package99:TOOLKIT RUN-TIME). If this was the only ADK application running and it is removed,then you can down license the ADK.

Post-Migration Tasks

19 July 2013 37

Appendix A

Reference Information

A.1 WebSphere MQList of WebSphere MQ parameters

If the licence package 13:MQ HOST ADAPTER is installed, then the following parameters areavailable in the System Management application:

Parameter Description

Connection Mode Specifies the mode that the Web Sphere MQ interface of Alliance Access uses toconnect to a Queue Manager. The options are:

• Client - The WebSphere MQ interface can connect to multiple QueueManagers which are located on the same host or on a different host as the MQAdapter.

Note See the WebSphere MQ Interface User Guide for informationabout setting the environment variables for "MQSERVER" and"MQ channel table".

• Server - The WebSphere MQ interface can connect to Queue Managerslocated on the same host as Alliance Access.

Default value: Server.

You must restart the Application Interface Services (MXS) component, to apply thechanges to this parameter.

Input MessageRate Limit

Limits the number of messages that Alliance Access reads per second from all theWebSphere MQ queues that are configured in Alliance Access.

The default value is 0, which means that the incoming WebSphere MQ traffic is notlimited. Mininum: 0. Maximum: 999.

Before you change this parameter, you must disable all the Websphere MQmessage partners.

Recovery Time -Initial

The time interval, in seconds, after which the first attempt to reopen thecommunication session with WebSphere MQ is made in case of a brokenconnection. Default value: 60.

Recovery Time -Increment

The increase of the time interval, in seconds, between consecutive attempts toreopen a WebSphere MQ session. Default value: 30.

Recovery Time -Max

The maximum time interval, in seconds, between consecutive attempts to reopen aWebSphere MQ session. Default value: 600.



Legal Notices

Copyright

SWIFT © 2013. All rights reserved.

Restricted Distribution

Do not distribute this publication outside your organisation unless your subscription or order expressly grantsyou that right, in which case ensure you comply with any other applicable conditions.

Disclaimer

The information in this publication may change from time to time. You must always refer to the latestavailable version.

Translations

The English version of SWIFT documentation is the only official and binding version.

Trademarks

SWIFT is the trade name of S.W.I.F.T. SCRL. The following are registered trademarks of SWIFT: the SWIFTlogo, SWIFT, SWIFTNet, SWIFTReady, Accord, Sibos, 3SKey, Innotribe, the Standards Forum logo,MyStandards, and SWIFT Institute. Other product, service, or company names in this publication are tradenames, trademarks, or registered trademarks of their respective owners.

Legal Notices

19 July 2013 39

mqsa 7 0 migr host ad

Documents

alliance access mqsa

websphere mq interface

withalliance access

mq queue

mq hostadapter mqha

ibm websphere mq

migration tasks

mq host adapterthis