Professional Documents
Culture Documents
19 July 2013
Table of Contents
.Preface .............................................................................................................................................................................3
1
Introduction ....................................................................................................................................................... 4
1.1
1.2
Preparation ...................................................................................................................................................... 10
2.1
2.2
Prerequisites ............................................................................................................................................ 10
Overview of the Migration from MQSA ................................................................................................ 11
3.3
3.4
3.5
3.6
WebSphere MQ ....................................................................................................................................... 38
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
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
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
1.2.1
19 July 2013
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.
Introduction
MQSA
MQHA
<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>
19 July 2013
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
New routing rules are required for MQHA to route and dispose messages. For
more information, see "Configuring Routing for Messages" on page 28.
Introduction
19 July 2013
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
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
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.
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
Important
12
Do not remove the Alliance Developer Kit (ADK) until after you have verified
that the migration was successful.
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.
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
Configure system-wide
parameters
D0540138
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
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.
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.
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.
14
Migration to MQHA
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
3.3.1
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.
3.
In the Connection Method field, select WebSphere MQ, and select a value in the Data
Format field.
4.
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
Migration to MQHA
3.3.2
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".
MP value
Message partner
Description
Description
Allowed direction
Connection method
"WebSphere MQ"
Session initiation
Manual
Automatic
19 July 2013
Queue Name
Queue Name
Transfer SAA
Information
Use MQ Descriptor
17
MP field
MP value
Data format
Message Data
Version
"2"
This field is only available when the data format is
XML.
Version (1)
Revision
Options:
MP value
Select from:
Full
Mixed
18
Chunk Size
Input Attachment
Directory
Migration to MQHA
Example
MP value
19 July 2013
MP value
Value as defined in MQSA
19
MP field
Profile name
MP value
Unit to be assigned
UUMID included in
Original Message
Disposition
Disposition
Transfer UUMID
- (1)
Original Message
- (1)
- (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
Migration to MQHA
Example
3.3.3
Reason
Priority
Message to Read
Reply-to-Queue Format
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
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.
4.
In the Connection Method field, select WebSphere MQ, and select a value in the Data
Format field.
5.
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
Migration to MQHA
3.3.4
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".
19 July 2013
MP value
Message partner
Description
Description
Allowed direction
Connection method
"WebSphere MQ"
23
MP field
MP value
Session initiation
Manual
Automatic
Queue Manager Name
Queue Name
Queue Name
Transfer SAA
Information
Use MQ Descriptor
Data format
Message Data
Version
"2"
This field is only available for XML data format.
Version(1)
Revision
Options:
24
Migration to MQHA
MP value
Select from:
Full
Mixed
Chunk Size
Example
19 July 2013
25
MP value
26
MP value
Exit Points
Routing code
transmitted
Message emission
format
Message Text
Format of original
message
Transfer UUMID
Include UMID
Migration to MQHA
MP field
MP value
Include TRN
Remove S-Block
Strip S-Block
Example
19 July 2013
Reason
Each MQ message partner, through the assigned exit point, is
mapped to an MQ queue.
27
3.4
3.4.1
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.
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
Recovery
Reject
(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
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
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
3.4.2
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.
32
Migration to MQHA
19 July 2013
33
3.5
34
The parameters are available only if the package 13:MQ HOST ADAPTER is
licensed.
Migrating to the MQ Host Adapter
Migration to MQHA
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
19 July 2013
Initial Time
35
SMA configuration
parameter
MQSA parameter
Description
recover a communication session with
WebSphere MQ.
Increment Time
Maximum Time
For more information about the configuration parameters for MQHA, see "WebSphere MQ"
on page 38.
4.
3.6
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
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
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
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.
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.
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