You are on page 1of 39

Connectivity

WebSphere MQ Interface 7.0


For Alliance Access 7.0

Migrating to the MQ Host Adapter


This guide explains how to migrate 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 how to migrate the
configuration information of MQSA to an equivalent configuration for MQHA in Alliance Access 7.0. This document is for
operators and administrators of Alliance Access, and for users of the back-office applications that communicate with
Alliance Access through IBM WebSphere MQ.

19 July 2013

WebSphere MQ Interface 7.0 for Alliance Access 7.0

Table of Contents
.Preface .............................................................................................................................................................................3
1

Introduction ....................................................................................................................................................... 4
1.1
1.2

Preparation ...................................................................................................................................................... 10
2.1
2.2

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


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

Prerequisites ............................................................................................................................................ 10
Overview of the Migration from MQSA ................................................................................................ 11

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


3.1
3.2

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


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

3.3
3.4
3.5
3.6

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


Configuring Routing for Messages ....................................................................................................... 28
Configuring System Parameters ........................................................................................................... 34
Enabling a Message Partner Profile ..................................................................................................... 36

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

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


A.1

WebSphere MQ ....................................................................................................................................... 38

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

Migrating to the MQ Host Adapter

Preface

Preface
Purpose of this guide
Welcome to the guide for the migration to the MQ Host Adapter. This guide explains how to
migrate 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 configuration
information 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 system
for the MQ Host Adapter.
Developers and users of the back-office applications that communicate with Alliance Access
through 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

19 July 2013

WebSphere MQ Interface 7.0 for Alliance Access 7.0

Introduction
Overview
Alliance Access 7.0 supports two interfaces for exchanging SWIFT messages with back-office
applications through IBM WebSphere MQ:
the WebSphere MQ Interface for Alliance Access software application (referred to as MQSA
in 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 is
embedded in the Application Interface. It does not require the installation of any ADK
software.
This guide explains how to migrate from MQSA to MQHA.
This migration can be performed gradually, per MQ queue. MQSA and MQHA can run in
parallel until the migration is complete.

1.1

Differences Between MQSA and MQHA


Overview
You can use the following sections to learn about the differences with the configuration of
MQSA and the configuration of MQHA.
Architecture
MQSA is built using the functions of the Alliance Developer Kit (ADK), to access the messaging
services of Alliance Access, which enable the communication between Alliance Access and IBM
WebSphere MQ.
MQHA uses the message partner functionality of the Application Interface in Alliance Access. A
message partner profile with the Connection Method "WebSphere MQ" manages the
communication sessions between IBM WebSphere MQ and Alliance Access.
Licences
MQSA is an ADK component. It requires the Alliance Access licence package 99:TOOLKIT
RUN-TIME and a specific MQSA licence.
MQHA is fully integrated into Alliance Access 7.0. It requires the additional licence package
13:MQ HOST ADAPTER. MQHA does not require the licence package 99:TOOLKIT RUNTIME.
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)

Migrating to the MQ Host Adapter

Introduction

MQHA supports ASCII character encoding only. The EBCDIC character encoding is not
supported. Therefore, IBM WebSphere MQ must perform the conversion between EBCDIC
and 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. For
messages received by the back-office application, the get message option
MQGMO_CONVERT must be used.
XML version 2 (MX, MT, and FileAct messages)
For more information about these formats, see the System Management Guide: Message
Formats Used in AI.
Message processing
Compared to MQSA, MQHA processes differently messages exchanged over IBM WebSphere
MQ between back-office applications and Alliance Access. This requires changes within the
back-office applications and Alliance Access. For details, see "Impact of the Migration" on page
5.
Handling Validation Errors
In MQSA, if the message fails validation, then it is routed to an exit point using the routing rule
with 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 following
actions:
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 completes
the message.
Alliance Access includes both the original message and the reason for which the message
failed 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 System
Management Guide: Managing Message Partner Profiles.

1.2

Impact of the Migration


Overview
The migration to MQHA has an impact on back-office applications and on Alliance Access. The
following 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 the
queue manager level.
EBCDIC character set not supported
MQHA supports ASCII character encoding only. The EBCDIC character encoding is not
supported. Therefore, IBM WebSphere MQ must perform the conversion between EBCDIC and
ASCII, if it is required.

19 July 2013

WebSphere MQ Interface 7.0 for Alliance Access 7.0

For messages in MQ-MT format, MQHA exchanges data with WebSphere MQ in ASCII. It
exchanges 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 revision
2.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 the
System Management Guide: XML Formats.
Transferring information about Alliance Access (SAAInfo)
MQSA can include information about the Alliance Access instance only in the MQ message
descriptor.
MQHA can send this information in the MQ message data part or in the MQ message
descriptor. When this information is included in the message data part, it is transmitted through
additional tags of the S-block for the MQ-MT format, and through the new SAAInfo element for
the 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 you
must adapt the back-office application to handle the new fields in that part for the
SAAInfo element.

Messages on MQ dead letter queue


In MQSA, failures during message processing, such as LAU authentication failures, can lead to
a 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 (if
defined in the MHQA message partner). In case of LAU failures, the message remains on the
MQ queue and the MQHA Message Partner is automatically disabled. For all other failures, the
message 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 not
provide application-to-application security. If Exit Routines are used in MQSA for other
purposes, then the WebSphere MQ Channel Exit Routines must be used for MQHA. For more
information, 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 are
stored 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 LT
is based only on the BIC8 of the sender specified in the MT message. It is performed when the
MT message is sent to SWIFT. For more information about Load Balancing, see the System
Management Guide: Automatic Logical Terminal Allocation.

Migrating to the MQ Host Adapter

Introduction

No reconciliation of delivery notification system message


When MQSA processes a delivery notification system message for output, it copies the original
message ID from the original MQ message descriptor of the associated input message into the
correlation ID of the message sent to the back-office application.
MQHA does not support the reconciliation of a delivery notification system message with the
original message.
If reconciliation is required, then a back-office application must use the MIR of the original
message which is contained within the delivery notification system message. The back-office
application can also make use of the Alliance Access traffic reconciliation (TR_REC) and route
the 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 message
descriptor 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 (no
status). The Feedback field is only used to return a Logical Reply, which is PAN or NAN. To
check 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 including
the 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-Blocks
1,2,3,4,5>

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

without original
message

<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:} blocks
within 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 the
FIN 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 of
field 36.

19 July 2013

WebSphere MQ Interface 7.0 for Alliance Access 7.0

MQSA does not calculate the Common Reference in Field 22 of Block 4 automatically.
In Alliance Access, the configuration parameter Common Ref Calculation, determines whether
Alliance Access calculates the Common Reference automatically for the messages that use the
data formats, CAS, RJE, DOS-PCC, and XML version 2. For more information about this
parameter, see the System Management Guide.
If you must ensure that archived messages on the customer site must match those messages
that are sent to SWIFT, then you can set Common Ref Calculation to No. This action means
that 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 by
an F01.
MQHA sends a Transmission notification of an MT05 Quit ACK as an F25 message, followed by
an F05.
RTV trailer
The RTV trailer indicates that the message has been retrieved from the network. MQSA
includes 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 10
most recent interventions. For more information about interventions, see the System
Management 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 received
message in one of the following ways:
Route the message from a message partner according to the routing rules that are specified
for 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. For
more information, see "Configuring Routing for Messages" on page 28.

Migrating to the MQ Host Adapter

Introduction

No reconciliation of delivery notification system message


As described in "Impact on Back-Office Applications" on page 5, if the Alliance Access traffic
reconciliation (TR_REC) is used, then the created delivery notification must be routed to the
back-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.

19 July 2013

WebSphere MQ Interface 7.0 for Alliance Access 7.0

Preparation
Introduction
This section lists the prerequisites that must be met before starting the migration. It also
provides 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

Prerequisites
Overview
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 be
installed. 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 that
are awaiting delivery to MQSA. To do this, you must get the messages delivered, or manually
complete all messages in the Message File application.
The Application Interface has several functions available and some of its functions have a
further level of entitlement, known as permissions. These permissions are included within the
default profiles of Alliance Access 7.0. Ensure that the operators that have access to the
graphical user interface for MQSA also have access to the Application interface. If you have to
create additional operator profiles with special permissions for the Application Interface, then
you can define these before starting the migration. For example, if you have created a
dedicated 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", then
you 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, or
message 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

10

Migrating to the MQ Host Adapter

Preparation

Back-office applications
Ensure that each back-office application has been adjusted to manage the impact of the
migration. If a back-office application expects to receive EBCDIC, then it must use the
WebSphere 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, at
the time of migration, MQ queues must not contain messages that are awaiting delivery to
Alliance 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 MQSA


Description
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 MQSA
configuration to an equivalent configuration for MQHA in Alliance Access 7.0. These tasks
must be repeated for each MQ queue.
This migration can be performed gradually. You do not have to migrate all your MQ queues
at once from MQSA to MQHA. MQSA and MQHA can run in parallel: MQ queues that have
not been migrated yet can still be used in MQSA while other MQ queues have already been
migrated to MQHA.

3.

Verify the successful exchange of messages through MQHA to a back-office application


through IBM WebSphere MQ.
If you do not succeed in exchanging a message with a back-office application, then ensure
that the message partners are enabled. Verify the session parameters in the message
partner profile. Verify that the routing and message partners are defined correctly.

19 July 2013

4.

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

5.

Down license your ADK packages, unless they are required for other ADK applications. For
more information about down licensing ADK packages, see the Alliance Access Installation
Guide: Down Licensing.

11

WebSphere MQ Interface 7.0 for Alliance Access 7.0

Important

12

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

Migrating to the MQ Host Adapter

Migration to MQHA

Migration to MQHA
Overview
This section describes the tasks that you must perform to migrate from MQSA to MQHA in
Alliance Access 7.0.
Terminology
Input message partner refers to a message partner profile that has the Allowed direction set
to "From Message Partner" in the profile definition.
Output message partner refers to a message partner profile that has the Allowed direction
set to "To Message Partner" in the profile definition.

Migration Tasks on Alliance Access

3.1

Overview
This section provides an overview of the migration tasks that you must perform on Alliance
Access.
Before you begin
Before you start the migration, check the software and ensure that the prerequisites have been
met and that preparation is complete.
Migration Tasks

Define security definition


profile

Create message partner


profile(s)

Define routing configuration

Configure system-wide
parameters

D0540138

Enable message partner


profile(s)

Description
1.

19 July 2013

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

13

WebSphere MQ Interface 7.0 for Alliance Access 7.0

can select this profile when you create an input message partner for a WebSphere MQ
connection.
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 Alliance
Access and a back-office application through WebSphere MQ.
For more information, see "Migrating an MQ Queue to a Message Partner Profile" on page
15.
Note

3.

One MQ queue in MQSA corresponds to one message partner profile in


Alliance Access 7.0.

Define the routing configuration that Alliance Access will use to route messages to and from
a 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.

3.2

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

Defining Permissions for Message Partners


Purpose
For input message partners, you can define security definition profiles that control the creation
and disposition of incoming messages in Alliance Access.
You can use the existing security definition profile "R7.0_MsgPartner", or define a new profile, if
you need special permissions for disposing a message.
R7.0_MsgPartner profile
Alliance Access uses the security definition profile "R7.0_MsgPartner" only within the
Application Interface, to grant privileges to an external application, which is defined as a
message partner profile. Those privileges apply only when the external application sends
messages to Alliance Access. Specifically, this profile controls how Alliance Access handles the
creation and disposition of message instances.
You can change permissions of this profile, or define a new profile from the Security Definition
application.

14

Migrating to the MQ Host Adapter

Migration to MQHA

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


For more information about entitlements and permissions, see the Security Guide: Defining
Operators.
For information about creating a default profile or changing an existing profile, see the System
Management Guide: Managing Alliance Security and System Management Guide: Standard
Default Profiles: Application Interface Application.
Reception tab
The Reception tab of a message partner profile has a parameter, Profile name, defined for a
security definition profile. In this field, you can select a profile that has the permissions which
you 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 message
partners, see "Creating an Input Message Partner Profile" on page 16.

Migrating an MQ Queue to a Message Partner


Profile

3.3

Overview
In MQSA, an MQ queue is defined to specify information about the connection to WebSphere
MQ. This section describes how to create a message partner profile in Alliance Access that
accomplishes 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.

19 July 2013

15

WebSphere MQ Interface 7.0 for Alliance Access 7.0

3.3.1

Creating an Input Message Partner Profile

Overview
This section describes how to create a message partner profile that controls the transport of
messages 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 are
defined in MQSA. Double-click a queue to view its details.
For more information, see the WebSphere MQ Interface User Guide: MQSeries Interface
Main Window.

2.

Using the procedure described in the System Management Guide: WebSphere MQ


Connection Method, create a message partner for the MQ queue.

3.

In the Connection Method field, select WebSphere MQ, and select a value in the Data
Format field.

4.

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

5.

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

You must enable a message partner profile before Alliance Access can use it in a
communication session.
Example of an MQ queue for incoming messages
The following shows the details of a queue, which is defined in MQSA:

16

Migrating to the MQ Host Adapter

Migration to MQHA

3.3.2

Parameters for an Input Message Partner

Overview
This section outlines the parameters and values that you must define when migrating an MQ
queue 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 explains
the parameters that you can use to support FileAct over WebSphere MQ.
For more information about the parameters listed in this section, see the System Management
Guide: Managing Message Partner Profiles.
Parameters
The following table explains how to complete the parameters on the Profile tab, and explains
how to locate their values in MQSA or to provide new values:
MP field

MP value

Corresponding MQSA queue


parameter

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

19 July 2013

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 Configuration


parameter for MQSA.
If you leave this field empty, then the default error
queue is used.

Keep session Open

If the Session initiation is set to Manual, then select


this option to ensure that Alliance Access
automatically recovers a failed communication
session.

Transfer SAA
Information

Value as defined in MQSA.

Transfer SAA info

Use MQ Descriptor

Specify whether to transfer the SAA information in


the MQ Descriptor. Before you can use the MQ
Descriptor to transfer the SAA information, you set
the SETID privilege in IBM WebSphere MQ.
If not selected, then the SAA information is sent in
the MQ Message Data part.

If selected, the Use MQ Descriptor field becomes


available.
-

17

WebSphere MQ Interface 7.0 for Alliance Access 7.0

MP field

MP value

Corresponding MQSA queue


parameter

Data format

If ASCII or EBCDIC is used in MQSA, then select


"MQ-MT"
If XML is used in MQSA, then select "XML" and
select the Revision.

Message Data

Version

"2"
This field is only available when the data format is
XML.

Version (1)

Revision

Options:

"Original", if the XML revision 2.0.1, 2.0.2, or 2.0.3


is not being used
"1", for revision 2.0.1
"2", for revision 2.0.2
"3", for revision 2.0.3
(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 the
sending of FileAct messages over WebSphere MQ. you must select at least revision 2 of XML
version 2:
MP field
FileAct mode

MP value

Corresponding MQSA queue


parameter
-

Select from:
Full
Mixed

18

Chunk Size

If you selected Full FileAct mode, then specify the


maximum size of a WebSphere MQ message (in
bytes) that Alliance Access can send a back-office
application.

Don't Use Segmentation

If you selected Full FileAct mode, and the payload of


the file is greater than the Chunk Size, then clear
this option to ensure that the payload file is
segmented before it is sent to the back-office
application.

Input Attachment
Directory

If you selected Mixed FileAct mode, then specify the


path to a directory on the server where the payload
file is stored
The exact payload file name will be extracted from
the content of the XMLv2 message.

Migrating to the MQ Host Adapter

Migration to MQHA

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
MP field
Local authentication
required

MP value

Corresponding MQSA queue


parameter

Value as defined in MQSA.


LAU Required
Select this option if "Yes" is selected in MQSA.
If selected, more fields appear. To complete them,
see the System Management Guide: Specifying Local
Authentication.

3.3.2.3 Reception Tab


Overview
This section describes the Reception tab for a WebSphere MQ message partner. For more
details about this tab, see the System Management Guide: Specifying the Reception
Parameters.
Parameters
The following table explains how to complete the parameters on the Reception tab, and
explains how to locate their values in MQSA or to provide new values:
MP field
Validation level

19 July 2013

MP value
Value as defined in MQSA

Corresponding MQSA queue


parameter
Validation Level(2)

19

WebSphere MQ Interface 7.0 for Alliance Access 7.0

MP field
Profile name

MP value

Corresponding MQSA queue


parameter

A security definition profile, for example,


R7.0_Msg_Partner

For more information, see the System Management


Guide: Selecting a Permission Profile for the
Message Partner.
Message modification
allowed

Specify whether the text of a message received from


a message partner can be modified in Alliance
Access.
For more information, see the System Management
Guide: Specifying Message Modification.

Unit to be assigned

Specify a unit to which an incoming message from a


message partner is assigned.
For more information, see the System Management
Guide: Assigning a Unit.

UUMID included in
Original Message

Specify whether the original message to be sent


includes a UUMID.
This option is available only for the data format, MQMT.

Disposition

Value as defined in MQSA.


For more information, see the System Management
Guide: Message Disposition.

Disposition

Transfer UUMID

Transfers the UUMID with the message.


This option is available only for the data format, MQMT.

- (1)

Original Message

Appends the original message request to a


notification.
This option is available only for the data format, MQMT.

- (1)

Validation Error Code

Includes an error code in a response message if an


error occurred during processing.
This option is available only for the data format, MQMT.

- (1)

(2)

(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.

20

Migrating to the MQ Host Adapter

Migration to MQHA

Example

3.3.2.4 Unused MQ Parameters


The following table lists the parameters in an MQ queue definition that have no equivalent in an
input message partner profile.
Parameters
Unused MQ queue parameter

3.3.3

Reason

Use Exit Routine

Exit routines are not supported in MQHA.

Priority

Not required, because Alliance Access reads the queues


concurrently.

Message to Read

Not required, because Alliance Access reads the queues


concurrently.

Reply-to-Queue Format

The message partner supports only ASCII encoding for messages in


MQ-MT format. EBCDIC is not supported.

Creating an Output Message Partner Profile

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

19 July 2013

21

WebSphere MQ Interface 7.0 for Alliance Access 7.0

To create an output message partner profile:


1.

Open the MQSeries interface window, which displays a list of the MQ queues that are
defined in MQSA. Double-click a queue to view its details.
For more information, see the WebSphere MQ Interface User Guide: MQSeries Interface
Main Window.

2.

Using the procedure described in the System Management Guide: Managing Exit Point
Profiles, create an exit point that you must assign later to the output message partner
profile. An exit point is a special routing point which is assigned to a message partner
profile, such as a WebSphere MQ message partner. The exit point controls the delivery of
messages 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 MQ


Connection Method, create a message partner for the MQ queue.

4.

In the Connection Method field, select WebSphere MQ, and select a value in the Data
Format field.

5.

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

6.

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

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

22

Migrating to the MQ Host Adapter

Migration to MQHA

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 MQ
queue 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 explains
the parameters that you can use to support FileAct over WebSphere MQ.
For more information about the parameters listed in this section, see the System Management
Guide: Managing Message Partner Profiles.
Parameters
The following table explains how to complete the parameters on the Profile tab, and explains
how to locate their values in MQSA or to provide new values:
MP field

19 July 2013

MP value

Corresponding MQSA queue


parameter

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"

23

WebSphere MQ Interface 7.0 for Alliance Access 7.0

MP field

MP value

Corresponding MQSA queue


parameter

Transfer PKI Signatures

Value as defined in MQSA.


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

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 Configuration


parameter for MQSA.
If you leave this field empty, then the default error
queue is used.

Keep Session Open

Select this option to ensure that Alliance Access


automatically recovers a failed communication
session.

Transfer SAA
Information

Value as defined in MQSA.

Transfer SAA info

Use MQ Descriptor

Specify whether to transfer the SAA information in


the MQ Descriptor.
Before you can use the MQ Descriptor to transfer the
SAA information, you set the SETID privilege in IBM
WebSphere MQ.

Data format

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


If XML in MQSA, then select "XML" and select the
Revision.

Message Data

Version

"2"
This field is only available for XML data format.

Version(1)

Revision

Options:

If selected, the Use MQ Descriptor field becomes


available.

"Original", if the XML revision 2.0.1 or 2.0.2 is not


being used
"1", for revision 2.0.1
"2", for revision 2.0.2
For more information, see the System Management
Guide: XML Formats.
Run output session

This section appears when you select Automatic in


the Session initiation field.

For more information, see the System Management


Guide: 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.

24

Migrating to the MQ Host Adapter

Migration to MQHA

Parameters to support FileAct


The following table explains how to complete the parameters on the Profile tab that support the
sending of FileAct messages over WebSphere MQ. you must select at least revision 2 of XML
version 2:
MP field
FileAct mode

MP value
Select from:

Corresponding MQSA queue


parameter
-

Full
Mixed
Chunk Size

If you selected Full FileAct mode, then specify the


maximum size of a WebSphere MQ message (in
bytes) that Alliance Access can send a back-office
application.

Don't Use Segmentation

If you selected Full FileAct mode, and the payload of


the file is greater than the Chunk Size, take one of
the following actions:

select this option to chunk the file based on the


Message Grouping only
clear this option to chunk the file based on the
value of Chunk Size
Output Attachment
Directory

If you selected Mixed FileAct mode, then specify the


path to a directory on the server where the payload
file is stored
The exact payload file name will be extracted from
the content of the XMLv2 message.

Example

19 July 2013

25

WebSphere MQ Interface 7.0 for Alliance Access 7.0

3.3.4.2 Authentication Tab


Overview
This section explains how to complete the parameters on the Authentication tab.
Parameters
MP field
Local authentication
required

MP value

Corresponding MQSA queue


parameter

Value as defined in MQSA.


LAU Required
Select this option if "Yes" is selected in MQSA.
If selected, more fields appear. To complete them,
see the System Management Guide: Specifying Local
Authentication.

3.3.4.3 Emission Tab


Overview
This section describes the Emission tab for a WebSphere MQ message partner. For more
details about this tab, see the System Management Guide: Specifying the Emission
Parameters.
Parameters
The following table explains how to complete the parameters on the Emission tab, and explains
how to locate their values in MQSA or to provide new values:
MP field

26

MP value

Corresponding MQSA queue


parameter

Exit Points

The exit point where messages are queued before


sending to the message partner.
If an exit point exists, then you can assign it to the
message partner here. If not, you can assign it later.
See the System Management Guide: Emission Tab
and System Management Guide: Managing Exit
Point Profiles.

Routing code
transmitted

Select this option to transmit the application routing


code (defined in MQSA as "APPL-ROUTINGCODE")
to the message partner.
See step 2 on page 32, and the System
Management Guide: Emission Tab.

Message emission
format

Value as defined in MQSA

Message Text

Send original message

Value as defined in MQSA.


See the System Management Guide: Specifying the
Notification Content.

Notification Emission: Send


Original Message

Format of original
message

Specify how much content of the original message is


included in the notification.
See the System Management Guide: Specifying the
Notification Content.

Transfer UUMID

Value as defined in MQSA.


This is only available for the MQ-MT format.

Include UMID

Migrating to the MQ Host Adapter

Migration to MQHA

MP field

MP value

Corresponding MQSA queue


parameter

Include TRN

Select this option to send the transaction reference


number of the original message to the message
partner.
This is only available for the MQ-MT format.

Remove S-Block

Select this option to remove the S-Block from the MQ


Message Data part of the message (and the original
message, if it is transferred).
This is only available for the MQ-MT format.

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 an
output message partner profile.
Parameters
Unused MQ queue parameter
Routing code

19 July 2013

Reason
Each MQ message partner, through the assigned exit point, is
mapped to an MQ queue.

27

WebSphere MQ Interface 7.0 for Alliance Access 7.0

3.4

Configuring Routing for Messages


Overview
This section describes how to configure Alliance Access to route or to dispose messages
coming from and going to a message partner.
In Alliance Access, the Routing application processes a message at a routing point according to
its associated routing rules.
A routing schema is used to group routing rules to allow activation within the system. Each
routing rule can belong to one or more routing schemas. However, only routing rules assigned
to 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 routing
points 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 in
MQSA 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, including
MQHA, in the _AI_From_APPLI queue. This is done regardless of the connection method and
the message format that are used. From there, the Message Processing Function (MPF) routes
them according to the active routing schema and according to the message partner profile that
is associated with the application.
For more information about the processing of messages in this queue, see the System
Management Guide: List of System Queues.
To migrate routing for incoming messages:

28

1.

Take a backup of your routing information. Print out all your routing so that you can refer to
it 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 options
Display Rules Allowed and Modify Rules Allowed.

Migrating to the MQ Host Adapter

Migration to MQHA

3.

Open the Routing application, and review the rules defined for the SMQS_From_MQSeries
routing 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 routing
rule 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 include
SMQS_From_MQSeries in the criteria for routing. The criteria are defined in the Condition
tab 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 here
takes three 'From MQ' WebSphere MQ queues, for each of which three new 'From
Message Partner' message partners with Connection method 'WebSphere MQ' have been
created, and where <WebSphere MQ MP nameN> is the name of the input message
partner as defined in "Creating an Input Message Partner Profile" on page 16.
If other routing rules contain the criteria (Src_entity = <WebSphere MQ queue
name>), 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 Partner
Profile" on page 16.

19 July 2013

29

WebSphere MQ Interface 7.0 for Alliance Access 7.0

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 point
AI_From_APPLI:

30

Migrating to the MQ Host Adapter

Migration to MQHA

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

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

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

19 July 2013

31

WebSphere MQ Interface 7.0 for Alliance Access 7.0

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 MQ
queue. In the MQSA application, you can define the code MQSA-ROUTINGCODE that MQSA
uses to identify the WebSphere MQ queues. This code is also included in the Free Formatted
Intervention field in a routing rule for a specific routing point. The code enables MQSA to route
a 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. To
replace the MQSA-ROUTINGCODE and APPL-ROUTINGCODE codes, you must configure
routing 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 must
define one exit point, as follows:
1.

For each MQSA queue that controls outgoing messages, define an exit point. For more
information, see the System Management Guide: Defining an Exit Point.
Assign each exit point to an output message partner for a WebSphere MQ connection
method.
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 routing
code to a message partner. This application routing code replaces the code APPLROUTINGCODE that was contained in Free text intervention fields of the routing rules
where 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 Action
tab of the routing rule.
c. In the corresponding message partner profile, ensure that the option Routing code
transmitted is selected in the Emission tab.

3.

To replace the MQSA-ROUTINGCODE code used in MQSA, you must find the rules in the
other routing points that send messages to SMQS_To_MQSeries. Then you must change
or recreate those rules to send the messages to exit points. For more information, see the
System 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-office
application.

32

Migrating to the MQ Host Adapter

Migration to MQHA

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

19 July 2013

33

WebSphere MQ Interface 7.0 for Alliance Access 7.0

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

3.5

Configuring System Parameters


Overview
This section describes how to migrate the configuration parameters of MQSA to Alliance Access
7.0.
Note

34

The parameters are available only if the package 13:MQ HOST ADAPTER is
licensed.
Migrating to the MQ Host Adapter

Migration to MQHA

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, if
it 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 System
Management application (SMA):
SMA configuration
parameter

MQSA parameter

Description

Connection Mode

None

Specifies the mode (Client or Server)


that the MQ interface of Alliance
Access uses to connect to a Queue
Manager.
Before you change this parameter, you
must disable all the message partner
profiles for MQ.
For this change to take effect, you must
restart the Alliance Access servers.

Check the SMQS Details tab


in your MQSeries Interface
System Configuration, which
identifies the client or server
setup. For more information,
see the WebSphere MQ
Interface User Guide:
WebSphere MQ Client and
WebSphere MQ Server
Components.

19 July 2013

Input Message Rate


Limit

Enable Throttling Messages/Second

Limits the number of messages that


Alliance Access reads per second from
all the WebSphere MQ queues that are
configured in Alliance Access.
Before you change this parameter, you
must disable all the message partner
profiles for MQ.

Recovery Time - Initial

Initial Time

Specifies the number of seconds after


which Alliance Access first attempts to

35

WebSphere MQ Interface 7.0 for Alliance Access 7.0

SMA configuration
parameter

MQSA parameter

Description
recover a communication session with
WebSphere MQ.

Recovery Time Increment

Increment Time

Specifies the number of seconds by


which Alliance Access increases the
interval between consecutive attempts
to recover a WebSphere MQ session.

Recovery Time - Max

Maximum Time

Specifies the maximum interval, in


seconds, after which Alliance Access
attempts to recover a WebSphere MQ
session.

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

3.6

Save the changes to the parameters.

Enabling a Message Partner Profile


Overview
After adding or modifying a message partner profile, you must enable the profile before it can
participate 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 the
Message Partner view changes to Enabled.

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

36

Migrating to the MQ Host Adapter

Post-Migration Tasks

Post-Migration Tasks
Overview
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 can
down license it.
As MQSA is an ADK component, the ADK RUN TIME licence was required (package
99:TOOLKIT RUN-TIME). If this was the only ADK application running and it is removed,
then you can down license the ADK.

19 July 2013

37

WebSphere MQ Interface 7.0 for Alliance Access 7.0

Appendix A

Reference Information
A.1

WebSphere MQ
List of WebSphere MQ parameters
If the licence package 13:MQ HOST ADAPTER is installed, then the following parameters are
available in the System Management application:
Parameter

Description

Connection Mode

Specifies the mode that the Web Sphere MQ interface of Alliance Access uses to
connect to a Queue Manager. The options are:
Client - The WebSphere MQ interface can connect to multiple Queue
Managers which are located on the same host or on a different host as the MQ
Adapter.
Note

See the WebSphere MQ Interface User Guide for information


about setting the environment variables for "MQSERVER" and
"MQ channel table".

Server - The WebSphere MQ interface can connect to Queue Managers


located on the same host as Alliance Access.
Default value: Server.
You must restart the Application Interface Services (MXS) component, to apply the
changes to this parameter.

38

Input Message
Rate Limit

Limits the number of messages that Alliance Access reads per second from all the
WebSphere MQ queues that are configured in Alliance Access.
The default value is 0, which means that the incoming WebSphere MQ traffic is not
limited. Mininum: 0. Maximum: 999.
Before you change this parameter, you must disable all the Websphere MQ
message partners.

Recovery Time Initial

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

Recovery Time Increment

The increase of the time interval, in seconds, between consecutive attempts to


reopen a WebSphere MQ session. Default value: 30.

Recovery Time Max

The maximum time interval, in seconds, between consecutive attempts to reopen a


WebSphere MQ session. Default value: 600.

Migrating to the MQ Host Adapter

Legal Notices

Legal Notices
Copyright
SWIFT 2013. All rights reserved.
Restricted Distribution
Do not distribute this publication outside your organisation unless your subscription or order expressly grants
you 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 latest
available 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 SWIFT
logo, 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 trade
names, trademarks, or registered trademarks of their respective owners.

19 July 2013

39