IBM Adapter for SWIFT User Guide

IBM WebSphere Business Integration Ad apters

AdapterforSWIFTUserGuide

Ve r si o n 1.6. x



IBM WebSphere Business Integration Ad apters

AdapterforSWIFTUserGuide

Ve r si o n 1.6. x



Note!

Before using this information and the product it supports, read the information in Appendix E, “Notices”, on page 181.

18April2003

This edition of this document applies to IBM WebSphere InterChange Server, version 4.2,WebSphere Business Integration Adapters, version 2.2.0, and to all subsequent releases and modification until otherwise indicated in new editions.

To send us your comments about this document, email doc-comments@us.ibm.com. We look forward to hearing from you.

When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you.

US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Integration broker compatibility

Supported on IBM WebSphere Business Integration Adapter Framework version

2.2.0, IBM CrossWorlds Infrastructure version 4.1.1 and 4.2 (if the environment uses ISO Latin-1 data only), WebSphere MQ Integrator version 2.1.0, and WebSphere MQ Integrator Broker, version 2.1.0. See Release Notes for any exceptions.

iv Adapter for SWIFT User Guide

Integration broker compatibility .........................iii

About this document .............................vii

Audience ....................................vii

Prerequisites for this document.............................vii

Related documents .................................vii

Typographic conventions ..............................viii

New in this release ...............................ix

New in release 1.6.x.................................ix

New in release 1.5.x.................................ix

New in release 1.4.x .................................x

New in release 1.3.x .................................x

New in release 1.2.x .................................x

New in release 1.1.x.................................xi

Chapter 1. Overview ..............................1

Connector architecture ................................2

Application-connector communication method ........................4

Event handling ..................................6

Guaranteed event delivery...............................9

Business object requests ...............................10

Business object mapping ...............................10

Message processing.................................10

Error handling ..................................14

Tracing .....................................15

Chapter 2. Configuring the connector ......................17

Prerequisites ...................................17

Installing the connector ...............................18

Connector configuration ...............................19

Enabling guaranteed event delivery ...........................24

Queue Uniform Resource Identifiers (URI) .........................28

Meta-object attributes configuration ...........................29

Startup file configuration ...............................42

Startup .....................................42

Chapter 3. Business objects ..........................43

Connector business object requirements ..........................43

Overview of SWIFT message structure ..........................47

Overview of business objects for SWIFT ..........................48

SWIFT message and business object data mapping ......................49

Chapter 4. ISO 7775 to ISO 15022 mapping ....................81

Production instruction meta-objects (PIMOs) ........................81

Creating PIMOs ..................................88

Modifying PIMOs: Map summary ............................96

Chapter 5. SWIFT Data Handler.........................123

Configuring the SWIFT Data Handler ..........................123

Business Object Requirements .............................124

Converting Business Objects to SWIFT Messages ......................124

Converting SWIFT Messages to Business Objects ......................125

Chapter 6. Troubleshooting ..........................127

Startup problems .................................127

Event processing .................................127

Appendix A. Standard configuration properties for connectors ...........129

New and deleted properties .............................129

Configuring standard connector properties for WebSphere InterChange Server ............130

Configuring standard connector properties for WebSphere MQ Integrator ..............142

Appendix B. Connector Configurator ......................151

Using Connector Configurator in an internationalized environment ................151

Starting Connector Configurator ............................152

Choosing your broker ...............................153

Using a connector-specific property template ........................154

Using Connector Configurator with ICS as the broker .....................157

Setting the configuration file properties (ICS) ........................159

Setting the configuration file properties (WebSphere MQ Integrator Broker) .............164

Using standard and connector-specific properties with Connector Configurator ............167

Completing the configuration .............................168

Appendix C. Connector feature list .......................169

Business object request handling features .........................169

Event notification features ..............................169

General features .................................170

Appendix D. SWIFT message structure .....................173

SWIFT message types ...............................173

SWIFT field structure................................173

SWIFT message block structure ............................175

Appendix E. Notices .............................181

Programming interface information ...........................182

Trademarks and service marks ............................182

vi Adapter for SWIFT User Guide

About this document

IBM(R) WebSphere(R) Business Integration Adapters supply integration connectivity for leading e-business technologies and enterprise applications.

This document describes the installation, configuration, and business object development for the adapter for SWIFT.

Audience

This document is for consultants, developers, and system administrators who support and manage the WebSphere business integration system at customer sites.

Prerequisites for this document

Users of this document should be familiar with

v the WebSphere business integration system (if you are using InterChange Server

as your integration broker)

v the WebSphere MQ Integrator Broker (if you are using WebSphere MQ

Integrator Broker as your integration broker)

v business object development

v the WebSphere MQ application

v the SWIFT product suite and protocol

Typographic conventions

This document uses the following conventions:

courier font Indicates a literal value, such as a command name, filename,

bold Indicates a new term the first time that it appears.

italic, italic Indicates a variable name or a cross-reference. blue text Blue text, which is visible only when you view the manual

ProductDir Product family is WBIA: Represents the directory where the

{ } In a syntax line, curly braces surround a set of options from

[] In a syntax line, square brackets surround an optional

... In a syntax line, ellipses indicate a repetition of the previous

<> In a naming convention, angle brackets surround individual

/, \ In this document, backslashes (\) are used as the convention

%text% and $text Text within percent (%) signs indicates the value of the

information that you type, or information that the system prints on the screen.

online, indicates a cross-reference hyperlink. Click any blue text to jump to the object of the reference.

IBM WebSphere Business Integration Adapters product is installed. The CROSSWORLDS environment variable contains the ProductDir directory path, which is IBM\WebSphereAdapters by default.

which you must choose one and only one.

parameter.

parameter. For example, option[,...] means that you can enter multiple, comma-separated options.

elements of a name to distinguish them from each other, as in <server_name><connector_name>tmp.log.

for directory paths. For UNIX installations, substitute slashes (/) for backslashes. All product pathnames are relative to the directory where the product is installed on your system.

Windows text system variable or user variable. The equivalent notation in a UNIX environment is $text, indicating the value of the text UNIX environment variable.

viii Adapter for SWIFT User Guide

New in this release

New in release 1.6.x

Updated in March, 2003. The ″CrossWorlds″ name is no longer used to describe an entire system or to modify the names of components or tools, which are otherwise mostly the same as before. For example ″CrossWorlds System Manager″ is now ″System Manager,″ and ″CrossWorlds InterChange Server″ is now ″WebSphere InterChange Server.″

The guaranteed event delivery feature has been enhanced. For further information, see “Enabling guaranteed event delivery” on page 24.

You can now associate a data handler with an input queue. For further information, see “Mapping data handlers to InputQueues” on page 31.

The connector supports SWIFTAlliance Access 5.0, but only if you deploy MQSA version 2.2 on WebSphere MQ 5.2 on and run the connector on one of the following operating systems:

v AIX 5.1

v SunOS 5.8 or Solaris 8

v Windows 2000 SP2

New in release 1.5.x

This release extends support for subfield parsing on the following message types:

v Category 1MT100, MT101, MT102, MT103, MT104, MT105, MT106, MT107,

MT110, MT111, MT112, MT190, MT191, MT198, MT199

v Category 2MT200, MT201, MT202, MT203, MT204, MT205, MT206, MT207,

MT210, MT256, MT290, MT291, MT293, MT298, MT299

v Category 3MT300, MT303, MT304, MT305, MT306, MT320, MT330, MT340,

MT341, MT350, MT360, MT361, MT362, MT364, MT365, MT390, MT391, MT398, MT399

v Category 4MT400, MT405, MT410, MT412, MT416, MT420, MT422, MT430,

MT450, MT455, MT456, MT490, MT491, MT498, MT499

v Category 5MT502, MT503, MT504, MT505, MT506, MT507, MT508, MT509,

MT512, MT513, MT514, MT515, MT516, MT517, MT518, MT520, MT521, MT522, MT523, MT524, MT526, MT527, MT528, MT529, MT530, MT531, MT532, MT533, MT534, MT535, MT536, MT537, MT538, MT539, MT540, MT541, MT542, MT543, MT544, MT545, MT546, MT547, MT548, MT549, MT550, MT551, MT552, MT553, MT554, MT555, MT556, MT557, MT558, MT559, MT560, MT561, MT562, MT563, MT564, MT565, MT566, MT567, MT568, MT569, MT570, MT571, MT572, MT573, MT575, MT576, MT577, MT578, MT579, MT580, MT581, MT582, MT583, MT584, MT586, MT587, MT588, MT589, MT590, MT591, MT598, MT599

v Category 6MT600, MT601, MT604, MT605, MT606, MT607, MT608, MT609,

MT643, MT644, MT645, MT646, MT649, MT690, MT691, MT698, MT699

v Category 7MT700, MT701, MT705, MT707, MT710, MT711, MT720, MT721,

MT730, MT732, MT734, MT740, MT742, MT747, MT750, MT752, MT754, MT756, MT760, MT767, MT768, MT769, MT790, MT791, MT798, MT799

v Category 8MT800, MT801, MT802, MT810, MT812, MT813, MT820, MT821,

MT822, MT823, MT824, MT890, MT891, MT898, MT899

v Category 9MT900, MT910, MT920, MT935, MT940, MT941, MT942, MT950,

MT960, MT961, MT962, MT963, MT964, MT965, MT966, MT967, MT970, MT971, MT972, MT973, MT985, MT986, MT990, MT991, MT998, MT999

The InProgress queue is no longer required and may be disabled. For more information, see “InProgressQueue” on page 23.

The connector supports interoperability with applications via MQSeries 5.1, 5.2, and 5.3. For more information, see “Prerequisites” on page 17

The connector now has a UseDefaults property for business object processing. For more information, see “UseDefaults” on page 24.

The connector can now apply a default verb when the data handler does not explicitly assign one to a business object. For more information, see “DefaultVerb”

on page 21.

The ReplyToQueue can now be dictated via the dynamic child meta-object rather than by the ReplyToQueue connector property. For more information see “JMS headers, SWIFT message properties, and dynamic child meta-object attributes” on page 37.

You can use a message selector to identify, filter and otherwise control how the adapter identifies the response message for a given request. This JMS capability applies to synchronous request processing only. For more information, see “Synchronous acknowledgment” on page 11.

New in release 1.4.x

If you are using the guaranteed event delivery feature and ICS as your integration broker, you must install release 4.1.1.2 of ICS.

New in release 1.3.x

The IBM WebSphere Business Adapter for SWIFT can dynamically transform a business object representing an ISO 7775 SWIFT message into a business object representing the corresponding ISO 15022 SWIFT message and vice versa. The adapter supports business object ISO 7775-15022 mapping for SWIFT Category 5, Securities Markets, but only with the expanded business object definitions available with this release and described in this document, and only on the Solaris platform.

New in release 1.2.x

The IBM WebSphere Business Integration Adapter for SWIFT includes the connector for SWIFT. This adapter operates with both the InterChange Server (ICS) and WebSphere MQ Integrator integration brokers. An integration broker, which is an application that performs integration of heterogeneous sets of applications, provides services that include data routing. The adapter includes:

x Adapter for SWIFT User Guide

v An application component specific to SWIFT

v Sample business objects

v IBM WebSphere Adapter Framework, which consists of:

– Connector Framework

– Development tools (including Business Object Designer and Connector

Configurator))

– APIs (including CDK)

This manual provides information about using this adapter with both integration brokers: ICS and WebSphere MQ Integrator.

Important: Because the connector has not been internationalized, do not run it

New in release 1.1.x

The following new features are described in this guide:

v The connector for SWIFT is now enabled for AIX 4.3.3 Patch Level 9

against ICS version 4.1.1 if you cannot guarantee that only ISO Latin-1 data will be processed.

Newinthisrelease xi

xii Adapter for SWIFT User Guide

Chapter 1. Overview

v “Connector architecture” on page 2

v “Application-connector communication method” on page 4

v “Event handling” on page 6

v “Guaranteed event delivery” on page 9

v “Business object requests” on page 10

v “Business object mapping” on page 10

v “Message processing” on page 10

v “Error handling” on page 14

v “Tracing” on page 15

The connector for SWIFT is a runtime component of the WebSphere Business Integration Adapter for SWIFT. The connector allows the WebSphere integration broker to exchange business objects with SWIFT-enabled business processes.

Note: Throughout this document, SWIFT messages denote SWIFT FIN messages

unless otherwise explicitly noted.

Connectors consist of an application-specific component and the connector framework. The application-specific component contains code tailored to a particular application. The connector framework, whose code is common to all connectors, acts as an intermediary between the integration broker and the application-specific component. The connector framework provides the following services between the integration broker and the application-specific component:

v Receives and sends business objects

v Manages the exchange of startup and administrative messages

This document contains information about the application-specific component and connector framework. It refers to both of these components as the connector.

For more information about the relationship of the integration broker to the connector, see the IBM WebSphere InterChange Server System Administration Guide,or the IBM WebSphere Business Integration Adapters Implementation Guide for WebSphere MQ Integrator Broker.

All WebSphere business integration adapters operate with an integration broker. The connector for SWIFT operates with both the WebSphere InterChange Server (ICS) and WebSphere MQ Integrator Broker integration brokers.

The connector for SWIFT allows the ICS or WebSphere MQ Integrator Broker to exchange business objects with applications that send or receive data in the form of SWIFT messages.

Important: The connector supports SWIFT message transformation from ISO 7775

to corresponding ISO 15022 formats and vice versa, but only with the expanded business object definitions and ISO mapping described in this document. For further information, see Chapter 3, “Business objects”, on page 43, and Chapter 4, “ISO 7775 to ISO 15022 mapping”,

on page 81.

Connector architecture

The connector allows WebSphere business processes to asynchronously exchange business objects with applications that issue or receive SWIFT messages when changes to data occur. (The connector also supports synchronous acknowledgment.)

SWIFT stands for Society for Worldwide Interbank Financial Telecommunications. It is a United Nations-sanctioned International Standards Organization (ISO) for the creation and maintenance of financial messaging standards.

As shown in Figure 1, the connector interacts with several components (WebSphere components are shown in bold) whose collective purpose is to bridge the world of WebSphere business objects with that of SWIFT messages.

SWIFT

data handler

IBM WebSphere

Integrator Broker

(Processes)

Connector

for SWIFT

outgoing

Mapping

engine

MQSeries output queue

Figure 1. Connector for SWIFT architecture

messages

SWIFT alliance access gateway

The SWIFT environment is made up of various components that are described below.

Connector for SWIFT

The connector for SWIFT is meta-data-driven. Message routing and format conversion are initiated by an event polling technique. The connector retrieves WebSphere MQ messages from queues, calls the SWIFT data handler to convert messages to their corresponding business objects, and then delivers the objects to

incoming

messages

MQSeries input queue

MQSA

2 Adapter for SWIFT User Guide

the corresponding business processes. In the opposite direction, the connector receives business objects from the integration broker, converts them into SWIFT messages using the same data handler, and then delivers the messages to an WebSphere MQ queue.

The type of business object and verb used in processing a message are based on the meta-data in the Format field of the WebSphere MQ message header. You construct a meta-object to store the business object name and verb to associate with the WebSphere MQ message header Format field text.

You can optionally construct a dynamic meta-object that is added as a child to the business object passed to the connector. The child meta-object values override those specified in the static meta-object that is specified for the connector as a whole. If the child meta-object is not defined or does not define a required conversion property, the connector, by default, examines the static meta-object for the value. You can specify one or more dynamic child meta-objects instead of, or to supplement, a single static connector meta-object.

The connector can poll multiple input queues, polling each in a round-robin manner and retrieving a configurable number of messages from each queue. For each message retrieved during polling, the connector adds a dynamic child meta-object (if specified in the business object). The child meta-object values can direct the connector to populate attributes with the format of the message as well as with the name of the input queue from which the message was retrieved.

When a message is retrieved from the input queue, the connector looks up the business object name associated with the FORMAT text field. The message, along with the business object name, is then passed to the data handler. If a business object is successfully populated with message content, the connector checks to see if it a collaboration subscribes to it, and then delivers it to the integration broker using the gotApplEvents() method.

SWIFT data handler and mapping engine

The connector calls the SWIFT data handler to convert business objects into SWIFT messages and vice versa. The data handler is coupled with a mapping engine, which uses a map to perform transformations between business objects representing ISO 7775 and ISO 15022 SWIFT message formats. For more on the SWIFT data handler, see Chapter 5, “SWIFT Data Handler”, on page 123. For more on mapping, see Chapter 4, “ISO 7775 to ISO 15022 mapping”, on page 81.

WebSphere MQ

The connector for SWIFT uses an MQ implementation of the JavaTM Message Service (JMS), an API for accessing enterprise-messaging systems. This makes possible interaction with incoming and outgoing WebSphere MQ event queues.

MQSA

The WebSphere MQ event queues exchange messages with the WebSphere MQ Interface for SWIFTAlliance (MQSA). The MQSA software integrates WebSphere MQ messaging capabilities with SWIFT message types, performing delivery, acknowledgement, queue management, timestamping, and other functions.

SWIFTAlliance Access

The SWIFTAlliance Access gateway is a window through which SWIFT messages flow to and from remote financial applications over IP or WebSphere MQ. The

Chapter 1. Overview 3

connector supports SWIFTAlliance Access 5.0, but only if you deploy MQSA version 2.2 on WebSphere MQ 5.2 on and run the connector on one of the following operating systems:

v AIX 5.1

v SunOS 5.8 or Solaris 8

v Windows 2000 SP2

Application-connector communication method

The connector makes use of IBM’s WebSphere MQ implementation of the Java Message Service (JMS). The JMS is an open-standard API for accessing enterprise-messaging systems. It is designed to allow business applications to asynchronously send and receive business data and events.

Message request

Figure 2 illustrates a message request communication.

1. The connector framework receives a business object representing an ISO 7775

SWIFT message from an integration broker.

2. The connector passes the business object to the data handler.

3. If specified in the map subscription meta-object, the data handler passes the

ISO 7775 object to the mapping engine.

4. Using a production instruction meta-object (PIMO), the mapping engine

transforms the ISO 7775 object into an ISO 15022 business object and passes it to the data handler.

5. The data handler converts the ISO 15022 business object into an ISO

15022-compliant SWIFT message.

6. The connector dispatches the ISO 15022 SWIFT message to the WebSphere MQ

output queue.

7. The JMS layer makes the appropriate calls to open a queue session and routes

the message to the MQSA, which issues the message to the SWIFT Alliance Gateway.

4 Adapter for SWIFT User Guide

Integration

broker

Gray box indicates

non-WebSphere

components

Figure 2. Application-connector communication method: Message request

ISO 7775

business

object

Connector

SWIFT message

SWIFT

data handler

Mapping

engine

ISO 15022

MQSeries output

queue

MQSA

SWIFT alliance access gateway

Event delivery

Figure 3 illustrates the message return communication.

1. The polling method retrieves the next applicable ISO 15022 SWIFT message

from the WebSphere MQ input queue.

2. The message is staged in the in-progress queue, where it remains until

processing is complete.

3. The data handler converts the message into an ISO 15022 business object.

4. Using the map subscription meta-object, the connector determines whether the

message type is supported and, if supported, requires transformation into an ISO 7775 business object. If so, the data handler passes the ISO 15022 business object to the mapping engine.

5. Using a PIMO, the mapping engine processes the sub-fields of business object

data, creating an ISO 7775-compliant business object, which is passed to the data handler.

6. The SWIFT data handler receives the ISO 7775 business object and sets the verb

in it to the default verb specified in the data handler-specific meta-object.

7. The connector then determines whether the business object is subscribed to by

the integration broker. If so, the connector framework delivers the business object to the integration broker, and the message is removed from the in-progress queue.

Chapter 1. Overview 5

Integration

roker

ISO 7775

business

object

Connector

SWIFT data

handler

In-progress

queue

ISO 15022

SWIFT message

SWIFT alliance access gateway

MQSeries input

queue

MQSA

Gray box Indicates

non-WebSphere

components

Figure 3. Application-connector communication method: Event delivery

Mapping

engine

Event handling

For event notification, the connector detects an event written to a queue by an application rather than by a database trigger. An event occurs when SWIFTAlliance generates SWIFT messages and stores them on the WebSphere MQ queue.

Retrieval

The connector uses a polling method to poll the WebSphere MQ input queue at regular intervals for messages. When the connector finds a message, it retrieves it from the WebSphere MQ input queue and examines it to determine its format. If the format has been defined in the connector’s static or child meta-objects, the connector uses the data handler to generate an appropriate business object with a verb.

In-progress queue

The connector processes messages by first opening a transactional session to the WebSphere MQ queue. This transactional approach allows for a small chance that a business object could be delivered to a business process twice due to the connector successfully submitting the business object but failing to commit the transaction in the queue. To avoid this problem, the connector moves all messages to an in-progress queue. There, the message is held until processing is complete. If the connector shuts down unexpectedly during processing, the message remains in the in-progress queue instead of being reinstated to the original WebSphere MQ queue.

Note: Transactional sessions with a JMS service provider require that every

6 Adapter for SWIFT User Guide

requested action on a queue be performed and committed before events are removed from the queue. Accordingly, when the connector retrieves a message from the queue, it does not commit to the retrieval until: 1) The

message has been converted to a business object; 2) the business object is delivered to the integration broker, and 3) a return value is received.

Synchronous acknowledgment

To support applications that require feedback on the requests they issue, the connector for SWIFT can issue report messages to the applications detailing the outcome of their requests once they have been processed.

To achieve this, the connector posts the business data for such requests synchronously to the integration broker. If the business object is successfully processed, the connector sends a report back to the requesting application including the return code from the integration broker and any business object changes. If the connector or the integration broker fails to process the business object, the connector sends a report containing the appropriate error code and error message.

In either case, an application that sends a request to the connector for SWIFT is notified of its outcome.

If the connector for SWIFT receives any messages requesting positive or negative acknowledgment reports (PAN or NAN), it posts the content of the message synchronously to the integration broker and then incorporates the return code and modified business data in to a report message that is sent back to the requesting application.

Table 1 shows the required structure of messages sent to the connector to be processed synchronously.

Table 1. Required structure of synchronous WebSphere MQ messages

MQMD Field (message descriptor)

MessageType Message type DATAGRAM Report Options for report

ReplyToQueue Name of reply

ReplyToQueueManager Name of queue

Description Supported values (multiple values should be

OR’d)

You can specify one or both of the following:

message requested

queue

manager

v MQRO_PAN The connector sends a report

message if the business object can be successfully processed.

v MQRO_NANThe connector sends a report

message if an error occurred while processing the business object.

You can specify one of the following to control how the correlation ID of the report message is to be set:

v MQRO_COPY_MSG_ID_TO_CORREL_IDThe connector

copies the message ID of the request message to the correlation ID of the report. This is the default action.

v MQRO_PASS_CORREL_IDThe connector copies the

correlation ID of the request message to the correlation ID of the report.

The name of the queue to which the report message should be sent.

The name of the queue manager to which the report message should be sent.

Chapter 1. Overview 7

Table 1. Required structure of synchronous WebSphere MQ messages (continued)

MQMD Field (message descriptor)

Message Body A serialized business object in a format

Description Supported values (multiple values should be

OR’d)

compatible with the data handler configured for the connector.

Upon receipt of a message as described in Table 1, the connector:

1. Reconstructs the business object in the message body using the configured data

handler.

2. Looks up the business process specified for the business object and verb in the

static meta-data object.

3. Posts the business object synchronously to the specified process.

4. Generates a report encapsulating the result of the processing and any business

object changes or error messages.

5. Sends the report to the queue specified in the replyToQueue and

replyToQueueManager fields of the request.

Table 2 shows the structure of the report that is sent to the requesting application from the connector.

Table 2. Structure of the report returned to the requesting application

MQMD field Description Supported values (multiple values should

be OR’d)

MessageType Message type REPORT feedback Type of report One of the following:

v MQRO_PAN If the business object is

successfully processed.

v MQRO_NANIf the connector or the

integration broker encountered an error while processing the request.

Message Body If the business object is successfully

processed, the connector populates the message body with the business object returned by the integration broker. This default behavior can be overridden by setting the DoNotReportBusObj property to true in the static meta-data object.

Recovery

Upon initialization, the connector checks the in-progress queue for messages that have not been completely processed, presumably due to a connector shutdown. The connector configuration property InDoubtEvents allows you to specify one of four options for handling recovery of such messages: fail on startup, reprocess, ignore, or log error.

8 Adapter for SWIFT User Guide

If the request could not be processed, the connector populates the message body with the error message generated by the connector or the integration broker.

Fail on startup

With the fail on startup option, if the connector finds messages in the in-progress queue during initialization, it logs an error and immediately shuts down. It is the responsibility of the user or system administrator to examine the message and take appropriate action, either to delete these messages entirely or move them to a different queue.

Reprocess

With the reprocessing option, if the connector finds any messages in the in-progress queue during initialization, it processes these messages first during subsequent polls. When all messages in the in-progress queue have been processed, the connector begins processing messages from the input queue.

Ignore

With the ignore option, if the connector finds any messages in the in-progress queue during initialization, the connector ignores them but does not shut down.

Log error

With the log error option, if the connector finds any messages in the in-progress queue during initialization, it logs an error but does not shut down.

Archiving

If the connector property ArchiveQueue is specified and identifies a valid queue, the connector places copies of all successfully processed messages in the archive queue. If ArchiveQueue is undefined, messages are discarded after processing.

Guaranteed event delivery

The guaranteed-event-delivery feature enables the connector framework to ensure that events are never lost and never sent twice between the connector’s event store, the JMS event store, and the destination’s JMS queue. To become JMS-enabled, you must configure the connectorDeliveryTransport standard property to JMS. Thus configured, the connector uses the JMS transport and all subsequent communication between the connector and the integration broker occurs through this transport. The JMS transport ensures that the messages are eventually delivered to their destination. Its role is to ensure that once a transactional queue session starts, the messages are cached there until a commit is issued; if a failure occurs or a rollback is issued, the messages are discarded.

Note: Without use of the guaranteed-event-delivery feature, a small window of

possible failure exists between the time that the connector publishes an event (when the connector calls the gotApplEvent() method within its pollForEvents() method) and the time it updates the event store by deleting the event record (or perhaps updating it with an “event posted” status). If a failure occurs in this window, the event has been sent but its event record remains in the event store with an “in progress” status. When the connector restarts, it finds this event record still in the event store and sends it, resulting in the event being sent twice.

You can configure the guaranteed-event-delivery feature for a JMS-enabled connector with, or without, a JMS event store. To configure the connector for guaranteed event delivery, see “Enabling guaranteed event delivery” on page 24.

If connector framework cannot deliver the business object to the ICS integration broker, then the object is placed on a FaultQueue (instead of UnsubscribedQueue

Chapter 1. Overview 9

and ErrorQueue) and generates a status indicator and a description of the problem. FaultQueue messages are written in MQRFH2 format.

Business object requests

Business object requests are processed when the integration broker issues a business object. Using the SWIFT data handler and mapping engine, and depending on the requirements specified in the subscription meta-object, the connector can transform an ISO 7775 object to an ISO 15022 object before converting the business object to a SWIFT message and issuing it.

Business object mapping

The map subscription meta-object determines whether mapping between ISO 7775 and ISO 15022 business objects occurs. For example, a child map subscription meta-object (MO_Swift_MapSubscriptions_In) with an attribute Map_Swift_MT523_to_MT543 indicates that the business object definition corresponding to SWIFT message type 523 must be mapped to a business object definition representing SWIFT message type 543. For more information on the map subscription meta-object, see “Production instruction meta-objects (PIMOs)” on page 81.

The transformation of business object definitions from those representing ISO 7775 messages to those representing ISO 15022 and vice versa takes place in the mapping engine. There, a production instruction meta-object (PIMO) governs the mapping process. The PIMO is a meta-object, but one designed to handle mapping only. Each PIMO specifies attribute-by-attribute processing instructions for a specific transformation, for example, from SWIFT message type 523 to message type 543. You can modify PIMOs using Business Object Designer. For more information on mapping and PIMOs, see Chapter 4, “ISO 7775 to ISO 15022 mapping”, on page 81.

Message processing

The connector processes business objects passed to it by an integration broker based on the verb for each business object. The connector uses business object handlers to process the business objects that the connector supports.The business object handlers contain methods that interact with an application and that transform business object requests into application operations.

The connector supports the following business object verbs:

v Create

v Retrieve

Create

Processing of business objects with create depends on whether the objects are issued asynchronously or synchronously.

Asynchronous delivery

This is the default delivery mode for business objects with Create verbs. A message is created from the business object using a data handler and then written to the output queue. If the message is delivered, the connector returns BON_SUCCESS, else BON_FAIL.

10 Adapter for SWIFT User Guide

Note: The connector has no way of verifying whether the message is received or if

action has been taken.

Synchronous acknowledgment

If a replyToQueue has been defined in the connector properties and a responseTimeout exists in the conversion properties for the business object, the

connector issues a request in synchronous mode. The connector then waits for a response to verify that appropriate action was taken by the receiving application.

For WebSphere MQ, the connector initially issues a message with a header as shown in Table 3.

Table 3. Request Message Descriptor Header (MQMD)

Field Description Value

Format Format name Output format as defined in the conversion properties and

truncated to 8 characters to meet IBM requirements (example: MQSTR).

MessageType Message type MQMT_DATAGRAM Report Options for report message

requested.

When a response message is expected, this field is populated as follows:

MQRO_PAN

processing is successful.

MQRO_NAN

processing fails.

MQRO_COPY_MSG_ID_TO_CORREL_ID

ID of the report generated should equal the message ID of the request originally issued.

ReplyToQueue Name of reply queue When a response message is expected, this field is populated

with the value of connector property ReplyToQueue. Persistence Message persistence MQPER_PERSISTENT Expiry Message lifetime MQEI_UNLIMITED

Indicates constant defined by IBM.

to indicate that a positive-action report is required if

to indicate that a negative-action report is required if

to indicate that the correlation

The message header described in Table 3 is followed by the message body. The message body is a business object that has been serialized using the data handler.

The Report field is set to indicate that both positive and negative action reports are expected from the receiving application. The thread that issued the message waits for a response message that indicates whether the receiving application was able to process the request.

When an application receives a synchronous request from the connector, it processes the business object and issues a report message as described in Table 4, Table 5, and Table 6.

Table 4. Response Message Descriptor Header (MQMD)

Field Description Value

Format Format name Input format of busObj as defined in the conversion properties. MessageType Message type MQMT_REPORT

Indicates constant defined by IBM.

Chapter 1. Overview 11

Table 5. Population of response message

Verb Feedback field Message body

Create SUCCESS VALCHANGE (Optional) A serialized business object reflecting

changes.

VALDUPES FAIL (Optional) An error message.

Table 6. Feedback codes and response values

WebSphere MQ feedback code Equivalent WebSphere business integration system

response

MQFB_PAN or MQFB_APPL_FIRST SUCCESS MQFB_NAN or MQFB_APPL_FIRST + 1 FAI L MQFB_APPL_FIRST + 2 VALCHANGE MQFB_APPL_FIRST + 3 VALDUPES MQFB_APPL_FIRST + 4 MULTIPLE_HITS MQFB_APPL_FIRST + 5 Not applicable MQFB_APPL_FIRST + 6 Not applicable MQFB_APPL_FIRST + 7 UNABLE_TO_LOGIN MQFB_APPL_FIRST + 8 APP_RESPONSE_TIMEOUT (results in immediate

termination of connector)

MQFB_NONE What the connector receives if no feedback code is

See the connector development guide for details.

specified in the response message

If the business object can be processed, the application creates a report message with the feedback field set to MQFB_PAN (or a specific WebSphere business integration system value). Optionally the application populates the message body with a serialized business object containing any changes. If the business object cannot be processed, the application creates a report message with the feedback field set to MQFB_NAN (or a specific WebSphere business integration system value) and then optionally includes an error message in the message body. In either case, the application sets the correlationID field of the message to the messageID of the connector message and issues it to the queue specified by the ReplyTo field.

Upon retrieval of a response message, the connector by default matches the correlationID of the response to the messageID of a request message. The connector then notifies the thread that issued the request. Depending on the feedback field of the response, the connector either expects a business object or an error message in the message body. If a business object was expected but the message body is not populated, the connector simply returns the same business object that was originally issued by the integration broker for the Request operation. If an error message was expected but the message body is not populated, a generic error message is returned to the integration broker along with the response code. However, you can also use a message selector to identify, filter and otherwise control how the adapter identifies the response message for a given request. This message selector capability is a JMS feature. It applies to synchronous request processing only and is described below.

Filtering response messages using a message selector: Upon receiving a business object for synchronous request processing, the connector checks for the presence of a response_selector string in the application-specific information of the verb. If the response_selector is undefined, the connector identifies response messages using the correlation ID as described above.

12 Adapter for SWIFT User Guide

If response_selector is defined, the connector expects a name-value pair with the following syntax:

response_selector=JMSCorrelationID LIKE ’selectorstring’

The message selectorstring must uniquely identify a response and its values be enclosed in single quotes as shown in the example below:

response_selector=JMSCorrelationID LIKE ’Oshkosh’

In the above example, after issuing the request message, the adapter would monitor the ReplyToQueue for a response message with a correlationID equal to ″Oshkosh.″ The adapter would retrieve the first message that matches this message selector and then dispatch it as the response.

Optionally, the adapter performs run-time substitutions enabling you to generate unique message selectors for each request. Instead of a message selector, you specify a placeholder in the form of an integer surrounded by curly braces, for example: ’{1}’. You then follow with a colon and a list of comma-separated attributes to use for the substitution. The integer in the placeholder acts as an index to the attribute to use for the substitution. For example, the following message selector:

response_selector=JMSCorrelationID LIKE ’{1}’: MyDynamicMO.CorrelationID

would inform the adapter to replace {1} with the value of the first attribute following the selector (in this case the attribute named CorrelationId of the child-object named MyDynamicMO. If attribute CorrelationID had a value of 123ABC, the adapter would generate and use a message selector created with the following criteria:

JMSCorrelation LIKE ’123ABC’

to identify the response message.

You can also specify multiple substitutions such as the following:

response_selector=PrimaryId LIKE ’{1}’ AND AddressId LIKE ’{2}’ : PrimaryId, Address[4].AddressId

In this example, the adapter would substitute {1} with the value of attribute PrimaryId from the top-level business object and {2} with the value of AddressId

from the 5th position of child container object Address. With this approach, you can reference any attribute in the business object and meta-object in the response message selector. For more information on how deep retrieval is performed using Address[4].AddressId, see JCDK API manual (getAttribute method)

An error is reported at run-time when any of the following occurs:

v If you specify a non-integer value between the ’{}’ symbols

v If you specify an index for which no attribute is defined

v If the attribute specified does not exist in the business or meta-object

v If the syntax of the attribute path is incorrect

For example, if you include the literal value ’{’ or ’}’ in the message selector, you can use ’{{’ or ″{}″ respectively. You can also place these characters in the attribute

Chapter 1. Overview 13

value, in which case the first ″{″ is not needed. Consider the following example using the escape character: response_selector=JMSCorrelation LIKE ’{1}’ and

CompanyName=’A{{P’: MyDynamicMO.CorrelationID

The connector would resolve this message selector as follows:

JMSCorrelationID LIKE ’123ABC’ and CompanyName=’A{P’

When the connector encounters special characters such as ’{’, ’}’, ’:’ or ’;’ in attribute values, they are inserted directly into the query string. This allows you to include special characters in a query string that also serve as application-specific information delimiters.

The next example illustrates how a literal string substitution is extracted from the attribute value:

response_selector=JMSCorrelation LIKE ’{1}’ and CompanyName=’A{{P’: MyDynamicMO.CorrelationID

If MyDynamicMO.CorrelationID contained the value {A:B}C;D, the connector would resolve the message selector as follows: JMSCorrelationID LIKE ’{A:B}C;D’ and

CompanyName=’A{P’

For more information on the response selector code, see JMS 1.0.1 specifications.

Creating custom feedback codes: You can extend the WebSphere MQ feedback codes to override default interpretations shown in Table 6 by specifying the connector property FeedbackCodeMappingMO. This property allows you to create a meta-object in which all WebSphere business integration system-specific return status values are mapped to the WebSphere MQ feedback codes. The return status assigned (using the meta-object) to a feedback code is passed to the integration broker. For more information, see “FeedbackCodeMappingMO” on page 22.

Retrieve

Business objects with the Retrieve verb support synchronous delivery only. The connector processes business objects with this verb as it does for the synchronous delivery defined for create. However, when using a Retrieve verb, the responseTimeout and replyToQueue are required. Furthermore, the message body must be populated with a serialized business object to complete the transaction.

Table 7 shows the response messages for these verbs.

Table 7. Population of response message

Verb Feedback field Message body

Retrieve FAIL

FAIL_RETRIEVE_BY_CONTENT MULTIPLE_HITS SUCCESS A serialized business object.

(Optional) An error message.

Error handling

All error messages generated by the connector are stored in a message file named SWIFTConnector.txt. (The name of the file is determined by the LogFileName standard connector configuration property.) Each error has an error number followed by the error message:

14 Adapter for SWIFT User Guide

Message number

Message text

The connector handles specific errors as described in the following sections.

Application timeout

The error message ABON_APPRESPONSETIMEOUT is returned when:

v The connector cannot establish a connection to the JMS service provider during

message retrieval.

v The connector successfully converts a business object to a message but cannot

deliver it to the outgoing queue due to connection loss.

v The connector issues a message but times out waiting for a response from a

business object whose conversion property TimeoutFatal is equal to True.

v The connector receives a response message with a return code equal to

APP_RESPONSE_TIMEOUT or UNABLE_TO_LOGIN.

Unsubscribed business object

The connector delivers a message to the queue specified by the UnsubscribedQueue property if:

v The connector retrieves a message that is associated with an unsubscribed

business object.

v The connector retrieves a message but cannot associate the text in the Format

field with a business object name.

Tracing

Note: If the UnsubscribedQueue is not defined, unsubscribed messages are

discarded.

Data handler conversion

If the data handler fails to convert a message to a business object, or if a processing error occurs that is specific to the business object (as opposed to the JMS provider), the message is delivered to the queue specified by ErrorQueue.If ErrorQueue is not defined, messages that cannot be processed due to errors are discarded.

If the data handler fails to convert a business object to a message, BON_FAIL is returned.

Tracing is an optional debugging feature you can turn on to closely follow connector behavior. Trace messages, by default, are written to STDOUT. See the connector configuration properties in Chapter 2, “Configuring the connector”, on page 17, for more on configuring trace messages. For more information on tracing, including how to enable and set it, see the Connector Development Guide.

What follows is recommended content for connector trace messages.

Level 0 This level is used for trace messages that identify the connector

version.

Level 1 Use this level for trace messages that provide key information on

each business object processed or record each time a polling thread detects a new message in an input queue.

Chapter 1. Overview 15

Level 2 Use this level for trace messages that log each time a business

object is posted to the integration broker, either from gotApplEvent() or executeCollaboration().

Level 3 Use this level for trace messages that provide information

regarding message-to-business-object and business-object-tomessage conversions or provide information about the delivery of the message to the output queue.

Level 4 Use this level for trace messages that identify when the connector

enters or exits a function.

Level 5 Use this level for trace messages that indicate connector

initialization, represent statements executed in the application, indicate whenever a message is taken off of or put onto a queue, or record business object dumps.

16 Adapter for SWIFT User Guide

+ 170 hidden pages

IBM Adapter for SWIFT User Guide

Integration broker compatibility

Contents

About this document

Audience

Prerequisites for this document

Related documents

Typographic conventions

New in this release

New in release 1.6.x

New in release 1.5.x

New in release 1.4.x

New in release 1.3.x

New in release 1.2.x

New in release 1.1.x

Chapter 1. Overview

Connector architecture

Connector for SWIFT

SWIFT data handler and mapping engine

WebSphere MQ

MQSA

SWIFTAlliance Access

Application-connector communication method

Message request

Event delivery

Event handling

Retrieval

Recovery

Archiving

Guaranteed event delivery

Business object requests

Business object mapping

Message processing

Create

Retrieve

Error handling

Application timeout

Unsubscribed business object

Tracing

Data handler conversion