IBM Adapter for SWIFT User Guide

Download

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

Chapter 2. Configuring the connector

v “Prerequisites”

v “Installing the connector” on page 18

v “Connector configuration” on page 19

v “Enabling guaranteed event delivery” on page 24

v “Queue Uniform Resource Identifiers (URI)” on page 28

v “Meta-object attributes configuration” on page 29

v “Startup file configuration” on page 42

v “Startup” on page 42

This chapter describes how to install and configure the connector and how to configure the message queues to work with the connector.

Prerequisites

Prerequisite software

The following software must be installed before you install and configure the connector for SWIFT:

v WebSphere business integration system software version 4.2.x or later or

WebSphere Business Integration Adapter Framework version 2.1.0

v The connector supports interoperability with applications via WebSphere MQ,

WebSphere MQ 5.1, 5.2, software releases installed.

and 5.3. Accordingly, you must have one of these

Note: The adapter does not support Secure Socket Layers (SSL) in WebSphere

MQ 5.3. For the WebSphere MQ software version appropriate to adapter framework-integration broker communication, see the Installation Guide for your platform (Windows/Unix).

v IBM WebSphere MQ Java client libraries

Note: It’s advisable to download the latest MA88 libraries from IBM.

v For Windows systems: Microsoft Windows NT 4.0 Service Pack 6A or Windows

2000

v For Unix systems: Solaris 7 or AIX 4.3.3 Patch Level 7

v MQSA WebSphere MQ Interface for SWIFTAlliance 1.3

Note: The SWIFTAlliance Access gateway is a window through which SWIFT

messages flow to and from remote financial applications over IP or WebSphere MQ. 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:

– AIX 5.1

– SunOS 5.8 or Solaris 8

1. If your environment implements the convert-on-the-get methodology for character-set conversions you must download the latest

MA88 (JMS classes) from IBM. The patch level should be at least 5.2.2 (for MQ Series version 5.2). Doing so may avoid unsupported encoding errors.

– Windows 2000 SP2

For client setup with an NT server, see the description in the IBM publication WebSphere MQ Quick Beginnings for NT.

Installing the connector

The following subsections describe how to install the connector on a UNIX or Windows system.

Installing on a UNIX system

To install the connector on a UNIX system, run the Installer for IBM WebSphere Business Integration Adapter and select the WebSphere Business Integration Adapter for SWIFT. Installer installs all UNIX-supported connectors.

Note: If you are installing a Web release of this connector, see the Release Notes

for installation instructions.

Table 8 describes the UNIX file structure used by the connector.

Table 8. Installed UNIX file structure for the connector

Subdirectory of ProductDir Description

connectors/SWIFT/CWSwift.jar Connector jar files connectors/SWIFT/CWJMSCommon.jar connectors/SWIFT/start_SWIFT.sh The startup script for the connector. The script is called

from the generic connector manager script. When you click Install from Connector Configurator (WebSphere MQ Integrator Broker as the integration broker) or the Connector Configuration screen of System Manager (ICS as the integration broker), the installer creates a customized wrapper for this connector manager script. When the connector works with ICS, use this customized wrapper only to start and stop the connector. When the connector works with WebSphere MQ Integrator Broker, use this customized wrapper only to start the connector; use mqsiremotestopadapter to stop the connector.

connectors/messages/SWIFTConnector.txt Connector message file repository/SWIFT/CN_SWIFT.txt Connector definition DataHandlers/CwDataHandler.jar The SWIFT data handler repository/DataHandlers/MO_DataHandler_SWIFT.txt Meta-object for SWIFT data handler repository/DataHandlers/MO_DataHandler_Default.txt Data handler default object connectors/SWIFT/samples/Sample_SWIFT_MO_Config.txt Sample configuration object

/lib /bin

Contains the WBIA. jar file.

Contains the CWConnEnv.sh file.

For more information on installing the connector component, refer to one of the following guides, depending on the integration broker you are using:

v System Installation Guide for UNIX (when ICS is used as integration broker)

v Implementation Guide for WebSphere MQ Integrator Broker (when MQ Integrator

Broker is used as integration broker)

18 Adapter for SWIFT User Guide

Installing on a Windows system

To install the connector on a Windows system, run the Installer for IBM WebSphere Business Integration Adapter and select the WebSphere Business Integration Adapter for SWIFT. Installer installs standard files associated with the connector. Table 9 describes the Windows file structure used by the connector.

Note: If you are installing a Web release of this connector, see the Release Notes

for installation instructions.

Table 9. Installed Windows file structure for the connector

Subdirectory of ProductDir Description

connectors\SWIFT\CWSwift.jar Connector jar files connectors\SWIFT\CWJMSCommon.jar connectors\SWIFT\start_SWIFT.bat The startup file for the connector.

connectors\messages\SWIFTConnector.txt Connector message file repository\SWIFT\CN_SWIFT.txt Connector definition DataHandlers\CwDataHandler.jar The SWIFT data handler repository\DataHandlers\MO_DataHandler_SWIFT.txt Meta-object for SWIFT data handler repository\DataHandlers\MO_DataHandler_Default.txt Data handler default object connectors\SWIFT\samples\Sample_SWIFT_MO_Config.txt Sample configuration object

\lib \bin

Contains the WBIA. jar file.

Contains the CWConnEnv.bat file.

For more information on installing the connector component, refer to one of the following guides, depending on the integration broker you are using:

v IBM WebSphere InterChange Server System Installation Guide for Windows (when ICS

is used as integration broker)

v IBM WebSphere Business Integration Adapters Implementation Guide for WebSphre

MQ Integrator Broker (when MQ Integrator Broker is used as integration broker)

Connector configuration

Connectors have two types of configuration properties: standard configuration properties and connector-specific configuration properties. You must set the values of these properties before running the connector. Use one of the following tools to set a connector’s configuration properties:

v Connector Configurator (if ICS is the integration broker)—Access to this tool is

from the System Manager.

v Connector Configurator (if WebSphere MQ Integrator Broker is the integration

broker)—Access this tool from the WebSphere Business Integration Adapter program folder. For more information see Appendix B, “Connector Configurator” , on page 151

Standard connector properties

Standard configuration properties provide information that all connectors use. See Appendix A, “Standard configuration properties for connectors”, on page 129 for documentation of these properties.

Important: Because this connector supports both the ICS and WebSphere MQ

Integrator Broker, configuration properties for both brokers relevant to the connector.

Chapter 2. Configuring the connector 19

Connector-specific properties

Connector-specific configuration properties provide information needed by the connector at runtime. Connector-specific properties also provide a way of changing static information or logic within the connector without having to recode and rebuild the agent.

Note: Always check the values WebSphere MQ provides because they may be

incorrect or unknown. If the provided values are incorrect, specify them explicitly.

Table 10 lists the connector-specific configuration properties for the connector for SWIFT. See the sections that follow for explanations of the properties.

Table 10. Connector-specific configuration properties

Name Possible values Default value Required

“ApplicationPassword” on page 21

“ApplicationUserID” on page 21 Login user ID No “ArchiveQueue” on page 21 Queue to which copies of

“Channel” on page 21 MQ server connector channel Yes “ConfigurationMetaObject” on

page 21 “DataHandlerClassName” on

page 21

“DataHandlerConfigMO” on page 21

“DataHandlerMimeType” on page 21

“DefaultVerb” on page 21 Any verb supported by the

“ErrorQueue” on page 22 Queue for unprocessed messages queue://crossworlds.

“FeedbackCodeMappingMO” on page 22

“HostName” on page 22 WebSphere MQ server No “InDoubtEvents” on page 22 FailOnStartup Reprocess Ignore

“InputQueue” on page 23 Poll queues queue://CrossWorlds.

“InProgressQueue” on page 23 In-progress event queue queue://CrossWorlds.

“PollQuantity” on page 23 Number of messages to retrieve from

“Port” on page 24 Port established for the WebSphere

“ReplyToQueue” on page 24 Queue to which response messages

“UnsubscribedQueue” on page 24

“UseDefaults” on page 24 true or false false

queue://CrossWorlds.

successfully processed messages are sent

Name of configuration meta-object Yes

Data handler class name com.crossworlds.

Data handler meta-object MO_DataHandler_Default Ye s

MIME type of file swift No

connector.

Feedback code meta-object No

LogError

each queue specified in the InputQueue property

MQ listener

are delivered when the connector issues requests

Queue to which unsubscribed messages are sent

QueueManager/MQCONN.ARCHIVE

DataHandlers.swift. SwiftDataHandler

Create

Queue.manager/ MQCONN.ERROR

Reprocess No

QueueManager/MQCONN.IN

QueueManager/ MQCONN.IN_PROGRESS

1No

queue://CrossWorlds. QueueManager/MQCONN.REPLYTO

queue://CrossWorlds. QueueManager/MQCONN.UNSUBSCRIBE

Yes

20 Adapter for SWIFT User Guide

ApplicationPassword

Password used with the ApplicationUserID to log in to WebSphere MQ.

Default = None.

If the ApplicationPassword is left blank or removed, the connector uses the default password provided by WebSphere MQ.

ApplicationUserID

User ID used with the ApplicationPassword to log in to WebSphere MQ.

Default=None.

If the ApplicationUserID is left blank or removed, the connector uses the default user ID provided by WebSphere MQ.

ArchiveQueue

Queue to which copies of successfully processed messages are sent.

Default = queue://crossworlds.Queue.manager/MQCONN.ARCHIVE

Channel

MQ server connector channel through which the connector communicates with WebSphere MQ.

Default=None.

If the value of Channel is left blank or the property is removed, the connector uses the default server channel provided by WebSphere MQ.

ConfigurationMetaObject

Name of static meta-object containing configuration information for the connector.

Default = none.

DataHandlerClassName

Data handler class to use when converting messages to and from business objects.

Default = com.crossworlds.DataHandlers.swift.SwiftDataHandler

DataHandlerConfigMO

Meta-object passed to data handler to provide configuration information.

Default = MO_DataHandler_Default

DataHandlerMimeType

Allows you to request a data handler based on a particular MIME type.

Default = swift

DefaultVerb

Specifies the verb to be set within an incoming business object, if it has not been set by the data handler during polling.

Default= Create

Chapter 2. Configuring the connector 21

ErrorQueue

Queue to which messages that could not be processed are sent.

Default = queue://crossworlds.Queue.manager/MQCONN.ERROR

FeedbackCodeMappingMO

Allows you to override and reassign the default feedback codes used to synchronously acknowledge receipt of messages to the integration broker. This property enables you to specify a meta-object in which each attribute name is understood to represent a feedback code. The corresponding value of the feedback code is the return status that is passed to the integration broker. For a listing of the default feedback codes, see “Synchronous acknowledgment” on page 7. The connector accepts the following attribute values representing WebSphere MQ-specific feedback codes:

v MQFB_APPL_FIRST

v MQFB_APPL_FIRST_OFFSET_N where N is an integer (interpreted as the value of

MQFB_APPL_FIRST + N)

The connector accepts the following WebSphere business integration system-specific status codes as attribute values in the meta-object:

v SUCCESS

v FAIL

v APP_RESPONSE_TIMEOUT

v MULTIPLE_HITS

v UNABLE_TO_LOGIN

v VALCHANGE

v VALDUPES

Table 11 shows a sample meta-object.

Table 11. Sample feedback code meta-object attributes

Attribute Name Default Value

MQFB_APPL_FIRST SUCCESS

MQFB_APPL_FIRST + 1 FAI L

MQFB_APPL_FIRST + 2 UNABLE_TO_LOGIN

Default = none.

HostName

The name of the server hosting WebSphere MQ.

Default=None.

If the HostName is left blank or removed, the connector allows WebSphere MQ to determine the host.

InDoubtEvents

Specifies how to handle in-progress events that are not fully processed due to unexpected connector shutdown. Choose one of four actions to take if events are found in the in-progress queue during initialization:

v FailOnStartup. Log an error and immediately shut down.

22 Adapter for SWIFT User Guide

v Reprocess. Process the remaining events first, then process messages in the

input queue.

v Ignore. Disregard any messages in the in-progress queue. v LogError. Log an error but do not shut down.

Default = Reprocess.

InputQueue

Specifies the message queues that the connector polls for new messages. See the MQSA documentation to configure the WebSphere MQ queues for routing to SWIFTAlliance gateways.

The connector accepts multiple semicolon-delimited queue names. For example, to poll the queues MyQueueA, MyQueueB, and MyQueueC, the value for connector configuration property InputQueue is: MyQueueA;MyQueueB;MyQueueC.

The connector polls the queues in a round-robin manner and retrieves up to pollQuantity number of messages from each queue. For example, pollQuantity equals 2, and MyQueueA contains 2 messages, MyQueueB contains 1 message and MyQueueC contains 5 messages.

With pollQuanity set to 2, the connector retrieves at most 2 messages from each queue per call to pollForEvents. For the first cycle (1 of 2), the connector retrieves the first message from each of MyQueueA, MyQueueB, and MyQueueC. That completes the first round of polling. The connector starts a second round of polling (2 of 2) and retrieves one message each from MyQueueA and MyQueueC—it skips MqQueueB because that queue is now empty. After polling all queues twice, the call to the method pollForEvents is complete. The sequence of message retrieval is:

1. 1 message from MyQueueA

2. 1 message from MyQueueB

3. 1 message from MyQueueC

4. 1 message from MyQueueA

5. Skip MyQueueB because it is empty

6. 1 message from MyQueueC

Default = queue://crossworlds.Queue.manager/MQCONN.IN

InProgressQueue

Message queue where messages are held during processing. You can configure the connector to operate without this queue by using System Manager to remove the default InProgressQueue name from the connector-specific properties. Doing so prompts a warning at startup that event delivery may be compromised if the connector is shut down while are events pending.

Default= queue://crossworlds.Queue.manager/MQCONN.IN_PROGRESS

PollQuantity

Number of messages to retrieve from each queue specified in the InputQueue property during a pollForEvents scan.

Default =1

Chapter 2. Configuring the connector 23

Port

Port established for the WebSphere MQ listener.

Default=None.

If the value of Port is left blank or the property is removed, the connector allows WebSphere MQ to determine the correct port.

ReplyToQueue

Queue to which response messages are delivered when the connector issues requests.

Default = queue://crossworlds.Queue.manager/MQCONN.REPLYTO

UnsubscribedQueue

Queue to which messages about business objects that are not subscribed to are sent.

Default = queue://crossworlds.Queue.manager/MQCONN.UNSUBSCRIBED

UseDefaults

On a Create operation, if UseDefaults is set to true, the connector checks whether a valid value or a default value is provided for each isRequired business object attribute. If a value is provided, the Create operation succeeds. If the parameter is set to false, the connector checks only for a valid value and causes the Create operation to fail if it is not provided. The default is false.

Enabling guaranteed event delivery

You can configure the guaranteed-event-delivery feature for a JMS-enabled connector in one of the following ways:

v If the connector uses a JMS event store (implemented as a JMS source queue),

the connector framework can manage the JMS event store. For more information, see “Guaranteed event delivery for connectors with JMS event stores”.

v If the connector uses a non-JMS event store (for example, implemented as a

JDBC table, Email mailbox, or flat files), the connector framework can use a JMS monitor queue to ensure that no duplicate events occur. For more information, see “Guaranteed event delivery for connectors with non-JMS event stores” on page 26.

Guaranteed event delivery for connectors with JMS event stores

If the JMS-enabled connector uses JMS queues to implement its event store, the connector framework can act as a ″container″ and manage the JMS event store (the JMS source queue). In a single JMS transaction, the connector can remove a message from a source queue and place it on the destination queue. This section provides the following information about use of the guaranteed-event-delivery feature for a JMS-enabled connector that has a JMS event store:

v “Enabling the feature for connectors with JMS event stores”

v “Effect on event polling” on page 26

Enabling the feature for connectors with JMS event stores

To enable the guaranteed-event-delivery feature for a JMS-enabled connector that has a JMS event store, set the connector configuration properties to values shown in Table 12.

24 Adapter for SWIFT User Guide

Table 12. Guaranteed-event-delivery connector properties for a connector with a JMS event store

Connector property Value

DeliveryTransport JMS

ContainerManagedEvents JMS

PollQuantity The number of events to processing in a

single poll of the event store

SourceQueue Name of the JMS source queue (event store)

which the connector framework polls and from which it retrieves events for processing Note: The source queue and other JMS queues should be part of the same queue manager. If the connector’s application generates events that are stored in a different queue manager, you must define a remote queue definition on the remote queue manager. WebSphere MQ can then transfer the events from the remote queue to the queue manager that the JMS-enabled connector uses for transmission to the integration broker. For information on how to configure a remote queue definition, see your IBM WebSphere MQ documentation.

In addition to configuring the connector, you must also configure the data handler that converts between the event in the JMS store and a business object. This data-handler information consists of the connector configuration properties that Table 13 summarizes.

Table 13. Data-handler properties for guaranteed event delivery

Data-handler property Value Required?

MimeType The MIME type that the data handler

handles. This MIME type identifies which data handler to call.

DHClass The full name of the Java class that

implements the data handler

DataHandlerConfigMOName The name of the top-level meta-object that

associates MIME types and their data handlers

Yes

Optional

Note: The data-handler configuration properties reside in the connector

configuration file with the other connector configuration properties.

If you configure a connector that has a JMS event store to use guaranteed event delivery, you must set the connector properties as described in Table 12 and Table 13. To set these connector configuration properties, use the Connector Configurator tool. Connector Configurator displays the connector properties in Table 12 on its Standard Properties tab. It displays the connector properties in Table 13 on its Data Handler tab.

Note: Connector Configurator activates the fields on its Data Handler tab only

when the DeliveryTransport connector configuration property is set to JMS and ContainerManagedEvents is set to JMS.

Chapter 2. Configuring the connector 25

For information on Connector Configurator, see Appendix B, “Connector Configurator”, on page 151.

Effect on event polling

If a connector uses guaranteed event delivery by setting ContainedManagedEvents to JMS, it behaves slightly differently from a connector that does not use this feature. To provide container-managed events, the connector framework takes the following steps to poll the event store:

1. Start a JMS transaction.

2. Read a JMS message from the event store.

The event store is implemented as a JMS source queue. The JMS message contains an event record. The name of the JMS source queue is obtained from the SourceQueue connector configuration property.

3. Call the data handler to convert the event to a business object.

The connector framework calls the data handler that has been configured with the properties in Table 13 on page 25.

4. When WebSphere MQ Integrator Broker is the integration broker, convert the

business object to a message based on the configured wire format (XML).

5. Send the resulting message to the JMS destination queue. If you are using the

WebSphere ICS integration broker, the message sent to the JMS destination queue is the business object. If you are using WebSphere MQ Integrator broker, the message sent to the JMS destination queue is an XML message (which the data handler generated).

6. Commit the JMS transaction.

When the JMS transaction commits, the message is written to the JMS destination queue and removed from the JMS source queue in the same transaction.

7. Repeat step 1 through 6 in a loop. The PollQuantity connector property

determines the number of repetitions in this loop.

Important: A connector that sets the ContainerManagedEvents property is set to JMS

does not call the pollForEvents() method to perform event polling. If the connector’s base class includes a pollForEvents() method, this method is not invoked.

Guaranteed event delivery for connectors with non-JMS event stores

If the JMS-enabled connector uses a non-JMS solution to implement its event store (such as a JDBC event table, Email mailbox, or flat files), the connector framework can use duplicate event elimination to ensure that duplicate events do not occur. This section provides the following information about use of the guaranteed-event-delivery feature with a JMS-enabled connector that has a non-JMS event store:

v “Enabling the feature for connectors with non-JMS event stores”

v “Effect on event polling”

Enabling the feature for connectors with non-JMS event stores: To enable the guaranteed-event-delivery feature for a JMS-enabled connector that has a non-JMS event store, you must set the connector configuration properties to values shown in Table 14.

26 Adapter for SWIFT User Guide

Table 14. Guaranteed-event-delivery connector properties for a connector with a non-JMS event store

Connector property Value

DeliveryTransport JMS

DuplicateEventElimination true

MonitorQueue Name of the JMS monitor queue, in which

the connector framework stores the ObjectEventId of processed business objects

If you configure a connector to use guaranteed event delivery, you must set the connector properties as described in Table 14. To set these connector configuration properties, use the Connector Configurator tool. It displays these connector properties on its Standard Properties tab. For information on Connector Configurator, see Appendix B, “Connector Configurator”, on page 151.

Effect on event polling: If a connector uses guaranteed event delivery by setting DuplicateEventElimination to true, it behaves slightly differently from a connector that does not use this feature. To provide the duplicate event elimination, the connector framework uses a JMS monitor queue to track a business object. The name of the JMS monitor queue is obtained from the MonitorQueue connector configuration property.

After the connector framework receives the business object from the application-specific component (through a call to gotApplEvent() in the pollForEvents() method), it must determine if the current business object (received from gotApplEvents()) represents a duplicate event. To make this determination, the connector framework retrieves the business object from the JMS monitor queue and compares its ObjectEventId with the ObjectEventId of the current business object:

v If these two ObjectEventIds are the same, the current business object represents a

duplicate event. In this case, the connector framework ignores the event that the current business object represents; it does not send this event to the integration broker.

v If these ObjectEventIds are not the same, the business object does not represent a

duplicate event. In this case, the connector framework copies the current business object to the JMS monitor queue and then delivers it to the JMS delivery queue, all as part of the same JMS transaction. The name of the JMS delivery queue is obtained from the DeliveryQueue connector configuration property. Control returns to the connector’s pollForEvents() method, after the call to the gotApplEvent() method.

For a JMS-enabled connector to support duplicate event elimination, you must make sure that the connector’s pollForEvents() method includes the following steps:

v When you create a business object from an event record retrieved from the

non-JMS event store, save the event record’s unique event identifier as the business object’s ObjectEventId attribute.

The application generates this event identifier to uniquely identify the event record in the event store. If the connector goes down after the event has been sent to the integration broker but before this event record’s status can be changed, this event record remains in the event store with an In-Progress status. When the connector comes back up, it should recover any In-Progress events. When the connector resumes polling, it generates a business object for the event

Chapter 2. Configuring the connector 27

record that still remains in the event store. However, because both the business object that was already sent and the new one have the same event record as their ObjectEventIds, the connector framework can recognize the new business object as a duplicate and not send it to the integration broker.

v During connector recovery, make sure that you process In-Progress events before

the connector begins polling for new events.

Unless the connector changes any In-Progress events to Ready-for-Poll status when it starts up, the polling method does not pick up the event record for reprocessing.

Queue Uniform Resource Identifiers (URI)

A URI uniquely identifies a queue. A URI for a queue begins with the sequence queue:// followed by:

v The name of the queue manager on which the queue resides v A forward slash (/)

v The name of the queue

v Optionally, a list of name-value pairs to set the remaining queue properties.

For example, the following URI connects to queue IN on queue manager crossworlds.queue.manager and causes all messages to be sent as SWIFT messages

with priority 5.

queue://crossworlds.Queue.manager/MQCONN.IN?targetClient=1&priority=5

Table 15 shows property names for queue URIs.

Table 15. SWIFT-specific connector property names for queue URIs

Property name Description Values

expiry Lifetime of the message in milliseconds. 0 = unlimited.

positive integers = timeout (in ms).

priority Priority of the message. 0-9, where 1 is the highest priority. A value of

-1 means that the property is determined by the configuration of the queue. A value of -2 means that the connector can use its own default value.

persistence Whether the message should be retained in

persistent memory.

1 on page 29

CCSID

targetClient Whether the receiving application is JMS

encoding How to represent numeric fields. An integer value as described in the base

Character set of the destination. Integers - valid values listed in base WebSphere

compliant or not.

1 = non-persistent

2 = persistent

A value of -1 means that the property is determined by the configuration of the queue. A value of -2 means that the connector uses its own default value.

MQ documentation. 1 = MQ (MQMD header only) This value must

be set to 1 for SWIFTAlliance.

WebSphere MQ documentation.

28 Adapter for SWIFT User Guide

Table 15. SWIFT-specific connector property names for queue URIs (continued)

Property name Description Values

Notes:

1. The connector has no control over the character set (CCSID) or encoding attributes of data in MQMessages. For

the connector to work properly, WebSphere MQ queues require an ASCII character set, and must be configured accordingly in MQSA. Because data conversion is applied as the data is retrieved from or delivered to the message buffer, the connector relies on the IBM WebSphere MQ implementation of JMS to convert data (see the IBM WebSphere MQ Java client library documentation). Accordingly, these conversions should be bi-directionally equivalent to those performed by the native WebSphere MQ API using option MQGMO_CONVERT. The connector has no control over differences or failures in the conversion process. It can retrieve message data of any CCSID or encoding supported by WebSphere MQ without additional modifications (such as those imposed by MQSA). To deliver a message of a specific CCSID or encoding, the output queue must be a fully qualified URI and specify values for CCSID and encoding. The connector passes this information to WebSphere MQ, which (via the JMS API) uses the information when encoding data for MQMessage delivery. Often, lack of support for CCSID and encoding can be resolved by downloading the most recent version of the IBM WebSphere MQ Java client library from the IBM website. For further information on MQSA requirements, see MQSA documentation. If problems specific to CCSID and encoding persist, contact IBM Technical Support to discuss the possibility of using another Java Virtual Machine to run the connector.

Meta-object attributes configuration

The connector for SWIFT can recognize and read two kinds of meta-objects:

v Static connector meta-object

v Dynamic child meta-object

The attribute values of the dynamic child meta-object duplicate and override those of the static meta-object.

Static meta-object

The static meta-object consists of a list of conversion properties defined for different business objects. To define the conversion properties for a business object, first create a string attribute and name it using the syntax busObj_verb. For example, to define the conversion properties for a Customer object with the verb Create, create an attribute named Swift_MT502_Create. In the application-specific text of the attribute, you specify the actual conversion properties.

Additionally, a reserved attribute named Default can be defined in the meta-object. When this attribute is present, its properties act as default values for all business object conversion properties.

Note: If a static meta-object is not specified, the connector cannot map a given

message format to a specific business object type during polling. When this is the case, the connector passes the message text to the configured data handler without specifying a business object. If the data handler cannot create a business object based on the text alone, the connector reports an error indicating that this message format is unrecognized.

Chapter 2. Configuring the connector 29

Table 16 describes the meta-object properties.

Table 16. Static meta-object properties

Property name Description

CollaborationName The collaboration name must be specified in the

application-specific text of the attribute for the business object/verb combination. For example, if you expect to handle synchronous requests for the business object Customer with the Create verb, the static meta-data object must contain an attribute named Swift_MTnnn_Verb, where nnn is the Swift message type, for example, Swift_MT502_Create. The Swift_MT502_Create attribute must contain application-specific text that includes a name-value pair. For example, CollaborationName=MyCustomerProcessingCollab. See the “Application-specific information” on page 31 section for syntax details. Failure to do this results in runtime errors when the connector attempts to synchronously process a request involving the Customer business object. Note: This property is available only for synchronous requests.

DoNotReportBusObj Optionally, you can include the DoNotReportBusObj property.

By setting this property to true, all PAN report messages issued have a blank message body. This is recommended when you want to confirm that a request has been successfully processed but does not need notification of changes to the business object. This does not affect NAN reports. If this property is not found in the static meta-object, the connector defaults to false and populates the message report with the business object. Note: This property is available only for synchronous requests.

InputFormat The input format is the message format to associate with the

given business object. When a message is retrieved and is in this format, it is converted to the given business object if possible. If this format is not specified for a business object, the connector does not handle subscription deliveries for the given business object.

OutputFormat The output format is set on messages created from the given

business object. If a value for the OutputFormat property is not specified, the input format is used, if available. An OutputFormat property value defined in a dynamic child meta-object overrides the value defined in the static meta-object.

InputQueue The input queue that the connector polls to detect new

messages. You can use connector-specific properties to configure multiple InputQueues and optionally map different data handlers to each queue.

OutputQueue The output queue is the queue to which messages derived

from the given business object are delivered. An OutputQueue property value defined in a dynamic child meta-object overrides the value defined in the static meta-object.

30 Adapter for SWIFT User Guide

Table 16. Static meta-object properties (continued)

Property name Description

ResponseTimeout The length of time in milliseconds to wait for a response

before timing out. The connector returns SUCCESS immediately without waiting for a response if this property is undefined or has a value less than zero. A ResponseTimeout property value defined in a dynamic child meta-object overrides the value defined in the static meta-object.

TimeoutFatal If this property is defined and has a value of true, the

connector returns APP_RESPONSE_TIMEOUT when a response is not received within the time specified by ResponseTimeout. All other threads waiting for response messages immediately return APP_RESPONSE_TIMEOUT to the integration broker. This causes the integration broker to terminate the connection to the connector. A TimeoutFatal property defined in a dynamic child meta-object overrides the value defined in the static meta-object.

Application-specific information

The application-specific information is structured in name-value pair format, separated by semicolons. For example:

InputFormat=ORDER_IN;OutputFormat=ORDER_OUT

You can use application-specific information to map a data handler to an input queue.

Mapping data handlers to InputQueues

You can use the InputQueue property in the application-specific information of the static meta-object to associate a data handler with an input queue. This feature is useful when dealing with multiple trading partners who have different formats and conversion requirements. To do so you must:

1. Use connector-specific properties (see “InputQueue” on page 23) to configure

one or more input queues.

2. For each input queue, specify the queue manager and input queue name as

well as data handler class name and mime type in the application-specific information.

For example, the following attribute in a static meta-object associates a data handler with an InputQueue named CompReceipts:

[Attribute] Name = Swift_MT502_Create Type = String Cardinality = 1 MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = false AppSpecificInfo = InputQueue=//queue.manager/CompReceipts;

DataHandlerClassName=com.crossworlds.

DataHandlers.swift.disposition_notification;

DataHandlerMimeType=message/ disposition_notification IsRequiredServerBound = false [End]

Chapter 2. Configuring the connector 31

Overloading input formats

When retrieving a message, the connector normally matches the input format to one specific business object and verb combination. The connector then passes the business object name and the contents of the message to the data handler. This allows the data handler to verify that the message contents correspond to the business object that the user expects.

If, however, the same input format is defined for more than one business object, the connector cannot determine which business object the data represents before passing it to the data handler. In such cases, the connector passes the message contents only to the data handler and then looks up conversion properties based on the business object that is generated. Accordingly, the data handler must determine the business object based on the message content alone.

If the verb on the generated business object is not set, the connector searches for conversion properties defined for this business object with any verb. If only one set of conversion properties is found, the connector assigns the specified verb. If more properties are found, the connector fails the message because it is unable to distinguish among the verbs.

A sample static meta-object

The static meta-object shown below configures the connector to convert

SWIFT_MT502 business objects using verbs Create and Retrieve. Note that attribute Default is defined in the meta-object. The connector uses the conversion properties

of this attribute:

OutputQueue=CustomerQueue1;ResponseTimeout=5000;TimeoutFatal=true

as default values for all other conversion properties. Thus, unless specified otherwise by an attribute or overridden by a dynamic child meta-object value, the connector issues all business objects to queue CustomerQueue1 and then waits for a response message. If a response does not arrive within 5000 milliseconds, the connector terminates immediately.

Business object with verb create: Attribute Swift_MT502_Create indicates to the connector that any messages of format NEW should be converted to a business object with the verb Create. Because an output format is not defined, the connector sends messages representing this object-verb combination using the format defined for input (in this case NEW).

Business object with verb retrieve: Attribute Swift_MT502_Retrieve specifies that business objects with verb Retrieve should be sent as messages with format RETRIEVE. Note that the default response time has been overridden so that the connector can wait up 10000 milliseconds before timing out (it still terminates if a response is not received).

[ReposCopy] Version = 3.1.0 Repositories = 1cHyILNuPTc= [End] [BusinessObjectDefinition] Name = Sample_MO Version = 1.0.0

[Attribute] Name = Default Type = String Cardinality = 1 MaxLength = 1 IsKey = true

32 Adapter for SWIFT User Guide

IsForeignKey = false IsRequired = false AppSpecificInfo = OutputQueue=CustomerQueue1;ResponseTimeout=5000;TimeoutFatal=true IsRequiredServerBound = false [End] [Attribute] Name = Swift_MT502_Create Type = String Cardinality = 1 MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = false AppSpecificInfo = InputFormat=NEW IsRequiredServerBound = false [End] [Attribute] Name = Swift_MT502_Retrieve Type = String Cardinality = 1 MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = false AppSpecificInfo = OutputFormat=RETRIEVE;ResponseTimeout=10000 IsRequiredServerBound = false [End] [Attribute] Name = ObjectEventId Type = String MaxLength = 255 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End]

[Verb] Name = Create [End]

[Verb] Name = Retrieve [End]

[End]

Dynamic child meta-object

If it is difficult or unfeasible to specify the necessary meta-data through a static meta-object, the connector can optionally accept meta-data specified at runtime for each business object instance.

The connector recognizes and reads conversion properties from a dynamic meta-object that is added as a child to the top-level business object passed to the connector. The attribute values of the dynamic child meta-object duplicate the conversion properties that you can specify via the static meta-object that is used to configure the connector.

Because dynamic child meta object properties override those found in static meta-objects, if you specify a dynamic child meta-object, you need not include a connector property that specifies the static meta-object. Accordingly, you can use either a dynamic child meta-object or a static meta-object, or both.

Chapter 2. Configuring the connector 33

Table 17 shows sample static meta-object properties for business object Swift_MT502_Create. Note that the application-specific text consists of semicolon-delimited name-value pairs

Table 17. Static meta-object structure for Swift_MT502_Create

Attribute name Application-specific text

Swift_MT502_Create InputFormat=ORDER_IN;OutputFormat=ORDER_OUT;OutputQueue=QueueA;Respons

Table 18 shows a sample dynamic child meta-object for business object Swift_MT_Create.

Table 18. Dynamic child meta-object Structure for Swift_MT502_Create

Property name Value

OutputFormat ORDER_OUT OutputQueue QueueA ResponseTimeout 10000 TimeoutFatal False

The connector checks the application-specific text of the top-level business object received to determine whether tag cw_mo_conn specifies a child meta-object. If so, the dynamic child meta-object values override those specified in the static meta-object.

Population of the dynamic child meta-object during polling

In order to provide the integration broker with more information regarding messages retrieved during polling, the connector populates specific attributes of the dynamic meta-object, if already defined for the business object created.

Table Table 19 shows how a dynamic child meta-object might be structured for polling.

Table 19. JMS dynamic child meta-object structure for polling

Property name Sample value

InputFormat ORDER_IN InputQueue MYInputQueue OutputFormat CxIgnore OutputQueue CxIgnore ResponseTimeout CxIgnore TimeoutFatal CxIgnore

As shown in Table 19, you can define an additional property, InputQueue,ina dynamic child meta-object. This property contains the name of the queue from which a given message has been retrieved. If this property is not defined in the child meta-object, it will not be populated.

Example scenario: v The connector retrieves a message with the format ORDER_IN from the queue

WebSphere MQ queue.

v The connector converts this message to an order business object and checks the

application-specific text to determine if a meta-object is defined.

34 Adapter for SWIFT User Guide

v If so, the connector creates an instance of this meta-object and populates the

InputQueue and InputFormat properties accordingly, then publishes the business object to available processes.

Sample dynamic child meta-object

[BusinessObjectDefinition] Name = MO_Sample_Config Version = 1.0.0

[Attribute] Name = OutputFormat Type = String MaxLength = 1 IsKey = true IsForeignKey = false IsRequired = false DefaultValue = ORDER IsRequiredServerBound = false [End] [Attribute] Name = OutputQueue Type = String MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = false DefaultValue = OUT IsRequiredServerBound = false [End] [Attribute] Name = ResponseTimeout Type = String MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = false DefaultValue = -1 IsRequiredServerBound = false [End] [Attribute] Name = TimeoutFatal Type = String MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = false DefaultValue = false IsRequiredServerBound = false [End] [Attribute] Name = InputFormat Type = String MaxLength = 1 IsKey = true IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End] [Attribute] Name = InputQueue Type = String MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false

Chapter 2. Configuring the connector 35

[End] [Attribute] Name = ObjectEventId Type = String MaxLength = 255 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End]

[Verb] Name = Create [End]

[Verb] Name = Retrieve [End]

[End] [BusinessObjectDefinition] Name = Swift_MT502 Version = 1.0.0 AppSpecificInfo = cw_mo_conn=MyConfig

[Attribute] Name = FirstName Type = String MaxLength = 1 IsKey = true IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End] [Attribute] Name = LastName Type = String MaxLength = 1 IsKey = true IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End] [Attribute] Name = Telephone Type = String MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End] [Attribute] Name = MyConfig Type = MO_Sample_Config ContainedObjectVersion = 1.0.0 Relationship = Containment Cardinality = 1 MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End] [Attribute] Name = ObjectEventId

36 Adapter for SWIFT User Guide

Type = String MaxLength = 255 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End]

[Verb] Name = Create [End]

[Verb] Name = Retrieve [End]

[End]

JMS headers, SWIFT message properties, and dynamic child meta-object attributes

You can add attributes to a dynamic meta-object to gain more information about, and more control over, the message transport. Adding such attributes allows you to modify JMS properties, to control the ReplyToQueue on a per-request basis (rather than using the default ReplyToQueue specified in the adapter properties), and to re-target a message CorrelationID. This section describes these attributes and how they affect event notification and request processing in both synchronous and asynchronous modes.

The following attributes, which reflect JMS and SWIFT header properties, are recognized in the dynamic meta-object.

Table 20. Dynamic meta-object header attributes

Header attribute name Mode Corresponding JMS header

CorrelationID

ReplyToQueue

DeliveryMode

Priority

Destination

Expiration

MessageID

Redelivered

TimeStamp

Type

UserID

AppID

DeliveryCount

GroupID

GroupSeq

JMSProperties

Read/Write JMSCorrelationID

Read/Write JMSReplyTo

Read JMSDeliveryMode

Read JMSPriority

Read JMSDestination

Read JMSExpiration

Read JMSMessageID

Read JMSRedelivered

Read JMSTimeStamp

Read JMSType

Read JMSXUserID

Read JMSXAppID

Read JMSXDeliveryCount

Read JMSXGroupID

Read JMSXGroupSeq

Read/Write

Chapter 2. Configuring the connector 37

Read-only attributes are read from a message header during event notification and written to the dynamic meta-object. These properties also populate the dynamic MO when a response message is issued during request processing. Read/write attributes are set on message headers created during request processing. During event notification, read/write attributes are read from message headers to populate the dynamic meta-object.

The interpretation and use of these attributes are described in the sections below.

Note: None of the above attributes are required. You may add any attributes to the

dynamic meta-object that relate to your business process.

JMS Properties: Unlike other attributes in the dynamic meta-object, JMSProperties must define a single-cardinality child object. Every attribute in this child object must define a single property to be read/written in the variable portion of the JMS message header as follows:

1. The name of the attribute has no semantic value.

2. The type of the attribute should always be String regardless of the JMS

property type.

3. The application-specific information of the attribute must contain two

name-value pairs defining the name and format of the JMS message property to which the attribute maps.

The table below shows application-specific information properties that you must define for attributes in the JMSProperties object.

Table 21. Application-specific information for JMS property attributes

Name Possible values Comments

Name Any valid JMS property

name

Type String, Int, Boolean, Float,

Double, Long, Short

This is the name of the JMS property. Some vendors reserve certain properties to provide extended functionality. In general, users should not define custom properties that begin with JMS unless they are seeking access to these vendor-specific features.

This is the type of the JMS property. The JMS API provides a number of methods for setting values in the JMS Message:

setIntProperty, setLongProperty, setStringProperty, etc. The

type of the JMS property specified here dictates which of these methods is used for setting the property value in the message.

The figure below shows attribute JMSProperties in the dynamic meta-object and definitions for four properties in the JMS message header: ID, GID, RESPONSE and RESPONSE_PERSIST. The application-specific information of the attributes

38 Adapter for SWIFT User Guide

defines the name and type of each. For example, attribute ID maps to JMS property ID of type String).

Figure 4. JMS properties attribute in a dynamic meta-object

Asynchronous event notification: If a dynamic meta-object with header attributes is present in the event business object, the connector performs the following steps (in addition to populating the meta-object with transport-related data):

1. Populates the CorrelationId attribute of the meta-object with the value

specified in the JMSCorrelationID header field of the message.

2. Populates the ReplyToQueue attribute of the meta-object with the queue

specified in the JMSReplyTo header field of the message. Since this header field is represented by a Java object in the message, the attribute is populated with the name of the queue (often a URI).

3. Populates the DeliveryMode attribute of the meta-object with the value

specified in the JMSDeliveryMode header field of the message.

4. Populates the Priority attribute of the meta-object with the JMSPriority

header field of the message.

5. Populates the Destination attribute of the meta-object with the name of the

JMSDestination header field of the message. Since the Destination is

represented by an object, the attribute is populated with the name of the Destination object.

6. Populates the Expiration attribute of the meta-object with the value of the

JMSExpiration header field of the message.

7. Populates the MessageID attribute of the meta-object with the value of the

JMSMessageID header field of the message.

8. Populates the Redelivered attribute of the meta-object with the value of the

JMSRedelivered header field of the message.

9. Populates the TimeStamp attribute of the meta-object with the value of the

JMSTimeStamp header field of the message.

10. Populates the Type attribute of the meta-object with the value of the JMSType

header field of the message.

11. Populates the UserID attribute of the meta-object with the value of the

JMSXUserID property field of the message.

12. Populates the AppID attribute of the meta-object with the value of the

JMSXAppID property field of the message.

13. Populates the DeliveryCount attribute of the meta-object with the value of the

JMSXDeliveryCount property field of the message.

14. Populates the GroupID attribute of the meta-object with the value of the

JMSXGroupID property field of the message.

15. Populates the GroupSeq attribute of the meta-object with the value of the

JMSXGroupSeq property field of the message.

Chapter 2. Configuring the connector 39

16. Examines the object defined for the JMSProperties attribute of the meta-object.

The adapter populates each attribute of this object with the value of the

corresponding property in the message. If a specific property is undefined in

the message, the adapter sets the value of the attribute to CxBlank.

Synchronous event notification: For synchronous event processing, the adapter posts an event and waits for a response from the integration broker before sending a response message back to the application. Any changes to the business data are reflected in the response message returned. Before posting the event, the adapter populates the dynamic meta-object just as described for asynchronous event notification. The values set in the dynamic meta-object are reflected in the response-issued header as described below (all other read-only header attributes in the dynamic meta-object are ignored.):

v CorrelationID If the dynamic meta-object includes the attribute CorrelationId,

you must set it to the value expected by the originating application. The application uses the CorrelationID to match a message returned from the connector to the original request. Unexpected or invalid values for a CorrelationID will cause problems. It is helpful to determine how the application handles correlating request and response messages before using this attribute. You have four options for populating the CorrelationID in a synchronous request.

1. Leave the value unchanged. The CorrelationID of the response message will

be the same as the CorrelationID of the request message. This is equivalent to the WebSphere MQ option MQRO_PASS_CORREL_ID.

2. Change the value to CxIgnore. The connector by default copies the message

ID of the request to the CorrelationID of the response. This is equivalent to the WebSphere MQ option MQRO_COPY_MSG_ID_TO_CORREL_ID.

3. Change the value to CxBlank. The connector will not set the CorrelationID

on the response message.

4. Change the value to a custom value. This requires that the application

processing the response recognize the custom value.

If you do not define attribute CorrelationID in the meta-object, the connector handles the CorrelationID automatically.

v ReplyToQueue If you update the dynamic meta-object by specifying a different

queue for attribute ReplyToQueue, the connector sends the response message to the queue you specify. This is not recommended. Having the connector send response messages to different queues may interfere with communication because an application that sets a specific reply queue in a request message is assumed to be waiting for a response on that queue.

v JMS properties The values set for the JMS Properties attribute in the dynamic

meta-object when the updated business object is returned to the connector are set in the response message.

Asynchronous request processing: The connector uses the dynamic meta-object, if present, to populate the request message prior to issuing it. The connector performs the following steps before sending a request message:

1. If attribute CorrelationID is present in the dynamic meta-object, the connector

sets the CorrelationID of the outbound request message to this value.

2. If attribute ReplyToQueue is specified in the dynamic meta-object, the connector

passes this queue via the request message and waits on this queue for a response. This allows you to override the ReplyToQueuevalue specified in the connector configuration properties. If you additionally specify a negative

40 Adapter for SWIFT User Guide

ResponseTimeout (meaning that the connector should not wait for a response), theReplyToQueue is set in the response message, even though the connector does not actually wait for a response.

3. If attribute JMSProperties is specified in the dynamic meta-object, the

corresponding JMS properties specified in the child dynamic meta-object are set in the outbound message sent by the connector.

Note: If header attributes in the dynamic meta-object are undefined or specify

CxIgnore, the connector follows its default settings.

Synchronous request processing: The connector uses the dynamic meta-object, if present, to populate the request message prior to issuing it. If the dynamic meta-object contains header attributes, the connector populates it with corresponding new values found in the response message. The connector performs the following steps (in addition to populating the meta-object with transport-related data) after receiving a response message:

1. If attribute CorrelationID is present in the dynamic meta-object, the adapter

updates this attribute with the JMSCorrelationID specified in the response message.

2. If attribute ReplyToQueue is defined in the dynamic meta-object, the adapter

updates this attribute with the name of the JMSReplyTo specified in the response message.

3. If attribute DeliveryMode is present in the dynamic meta-object, the adapter

updates this attribute with the value of the JMSDeliveryMode header field of the message.

4. If attribute Priority is present in the dynamic meta-object, the adapter

updates this attribute with the value of the JMSPriority header field of the message.

5. If attribute Destination is defined in the dynamic meta-object, the adapter

updates this attribute with the name of the JMSDestination specified in the response message.

6. If attribute Expiration is present in the dynamic meta-object, the adapter

updates this attribute with the value of the JMSExpiration header field of the message.

7. If attribute MessageID is present in the dynamic meta-object, the adapter

updates this attribute with the value of the JMSMessageID header field of the message.

8. If attribute Redelivered is present in the dynamic meta-object, the adapter

updates this attribute with the value of the JMSRedelivered header field of the message.

9. If attribute TimeStamp is present in the dynamic meta-object, the adapter

updates this attribute with the value of the JMSTimeStamp header field of the message.

10. If attribute Type is present in the dynamic meta-object, the adapter updates

this attribute with the value of the JMSType header field of the message.

11. If attribute UserID is present in the dynamic meta-object, the adapter updates

this attribute with the value of the JMSXUserID header field of the message.

12. If attribute AppID is present in the dynamic meta-object, the adapter updates

this attribute with the value of the JMSXAppID property field of the message.

13. If attribute DeliveryCount is present in the dynamic meta-object, the adapter

updates this attribute with the value of the JMSXDeliveryCount header field of the message.

Chapter 2. Configuring the connector 41

14. If attribute GroupID is present in the dynamic meta-object, the adapter updates

this attribute with the value of the JMSXGroupID header field of the message.

15. If attribute GroupSeq is present in the dynamic meta-object, the adapter

updates this attribute with the value of the JMSXGroupSeq header field of the

message.

16. If attribute JMSProperties is defined in the dynamic meta-object, the adapter

updates any properties defined in the child object with the values found in

the response message. If a property defined in the child object does not exist

in the message, the value is set to CxBlank.

Note: Using the dynamic meta-object to change the CorrelationID set in the

request message does not affect the way the adapter identifies the response message—the adapter by default expects that the CorrelationID of any response message equals the message ID of the request sent by the adapter.

Error handling: If a JMS property cannot be read from or written to a message, the connector logs an error and the request or event fails. If a user-specified ReplyToQueue does not exist or cannot be accessed, the connector logs an error and the request fails. If a CorrelationID is invalid or cannot be set, the connector logs an error and the request fails. In all cases, the message logged is from the connector message file.

Startup file configuration

Startup

Before you start the connector for SWIFT, you must configure the startup file. The sections below describe how to do this for Windows and UNIX systems.

Windows

To complete the configuration of the connector for Windows platforms, you must modify the start_SWIFT.bat file:

1. Open the start_SWIFT.bat file.

2. Scroll to the section beginning with “Set the directory containing your MQ

Java client libraries,” and specify the location of your MQ Java client libraries.

UNIX

To complete the configuration of the connector for UNIX platforms, you must modify the start_SWIFT.sh file:

1. Open the start_SWIFT.sh file.

2. Scroll to the section beginning with “Set the directory containing your

WebSphere MQ Java client libraries,” and specify the location of your WebSphere MQ Java client libraries.

For information on starting a connector, stopping a connector, and the connector’s temporary startup log file, see thestartup chapter in the System Installation Guide for your platform.

42 Adapter for SWIFT User Guide

Chapter 3. Business objects

v “Connector business object requirements”

v “Overview of SWIFT message structure” on page 47

v “Overview of business objects for SWIFT” on page 48

v “SWIFT message and business object data mapping” on page 49

The connector for SWIFT is a meta-data-driven connector. In WebSphere business objects, meta-data is data about the application’s data, which is stored in a business object definition and which helps the connector interact with an application. A meta-data-driven connector handles each business object that it supports based on meta-data encoded in the business object definition rather than on instructions hard-coded in the connector.

Business object meta-data includes the structure of a business object, the settings of its attribute properties, and the content of its application-specific text. Because the connector is meta-data-driven, it can handle new or modified business objects without requiring modifications to the connector code. However, the connector’s configured data handler makes assumptions about the structure of its business objects, object cardinality, the format of the application-specific text, and the database representation of the business object. Therefore, when you create or modify a business object for SWIFT, your modifications must conform to the rules the connector is designed to follow, or the connector cannot process new or modified business objects correctly.

Important: The connector supports business object mapping between the ISO

7775-15022 message formats for SWIFT Category 5, Securities Markets, but only with the expanded business object definitions available with release 1.3 (and later) of this connector. To install the object definition files, see Chapter 2, “Configuring the connector”, on page 17. If you use

business object definitions from release 1.2 or earlier, the connector cannot perform ISO 7775-15022 business object transformations.

This chapter describes how the connector processes business objects and describes the assumptions the connector makes. You can use this information as a guide to implementing new business objects.

Connector business object requirements

The business object requirements for the connector reflect the way the SWIFT data handler converts:

v a SWIFT message into a WebSphere business object, and vice versa

v a business object representing a SWIFT ISO 7775 message into a business object

representing the corresponding SWIFT ISO 15022 message, and vice versa.

The sections below discuss the requirements for WebSphere business objects as well as the SWIFT message structure. For a step-by-step description of how the SWIFT data handler interacts with WebSphere business objects and SWIFT messages, see Chapter 5, “SWIFT Data Handler”, on page 123.

A review of the following WebSphere documents is strongly recommended:

v IBM WebSphere InterChange Server Technical Introduction to IBM WebSphere

InterChange Server (when ICS is the integration broker)

v IBM WebSphere Business Integration Adapters Implementation Guide for WebSphere

MQ Integrator Broker (when MQ Integrator Broker is the integration broker)

v Business Object Development Guide

Business object hierarchy

WebSphere business objects can be flat or hierarchical. All the attributes of a flat business object are simple (that is, each attribute represents a single value, such as a String or Integer or Date).

In addition to containing simple attributes, a hierarchical business object has attributes that represent a child business object, an array of child business objects, or a combination of both. In turn, each child business object can contain a child business object or an array of business objects, and so on.

Important: A business object array can contain data whose type is a business

object. It cannot contain data of any other type, such as String or Integer.

There are two types of relationships between parent and child business objects:

v Single-cardinality—When an attribute in a parent business object represents a

single child business object. The attribute is of the same type as the child business object.

v Multiple-cardinality—When an attribute in the parent business object represents

an array of child business objects. The attribute is an array of the same type as the child business objects.

WebSphere uses the following terms when describing business objects:

v hierarchical—Refers to a complete business object, including the top-level

business object and its the child business objects at any level.

v parent—Refers to a business object that contains at least one child business

object. A top-level business object is also a parent.

v individual—Refers to a single business object, independent of any child business

objects it might contain or that contain it.

v top-level—Refers to the individual business object at the top of the hierarchy,

which does not itself have a parent business object.

v wrapper—Refers to a top-level business object that contains information used to

process its child business objects. For example, the XML connector requires the wrapper business object to contain information that determines the format of its child data business objects and routes the children.

Business object attribute properties

Business object architecture defines various properties that apply to attributes. This section describes how the connector interprets several of these properties. For further information on these properties, see Business Object Attributes and Attribute Properties in Chapter 2 of the Business Object Development Guide.

Name property

Each business object attribute must have a unique name within the business object. The name should describe the data that the attribute contains.

44 Adapter for SWIFT User Guide

For an application-specific business object, check the connector or data handler guide for specific naming requirements.

The name can be up to 80 alphanumeric characters and underscores. It cannot contain spaces, punctuation, or special characters.

Type property

The Type property defines the data type of the attribute:

v For a simple attribute, the supported types are Boolean, Integer, Float, Double,

String, Date, and LongText.

v If the attribute represents a child business object, specify the type as the name of

the child business object definition (for example, Type = MT502A) and specify the cardinality as 1.

v If the attribute represents an array of child business objects, specify the type as

the name of the child business object definition and specify the cardinality as n.

Note: All attributes that represent child business objects also have a

ContainedObjectVersion property (which specifies the child’s version number) and a Relationship property (which specifies the value Containment).

Cardinality property

Each simple attribute has cardinality 1. Each business object attribute that represents a child or array of child business objects has cardinality 1 or n, respectively.

Note: When specified for a required attribute, cardinality 1 indicates a child

business object must exist, and cardinality n indicates zero to many instances of a child business object.

Key property

At least one attribute in each business object must be specified as the key. To define an attribute as a key, set this property to true.

When you specify as key an attribute that represents a child business object, the key is the concatenation of the keys in the child business object. When you specify as key an attribute that represents an array of child business objects, the key is the concatenation of the keys in the child business object at location 0 in the array.

Note: Key information is not available in the collaboration mapping process

(relevant only when ICS is the integration broker).

Foreign key property

The Foreign Key property is typically used in application-specific business objects to specify that the value of an attribute holds the primary key of another business object, serving as a means of linking the two business objects. The attribute that holds the primary key of another business object is called a foreign key. Define the Foreign Key property as true for each attribute that represents a foreign key.

You can also use the Foreign Key property for other processing instructions. For example, this property can be used to specify what kind of foreign key lookup the connector performs. In this case, you might set Foreign Key to true to indicate that the connector checks for the existence of the entity in the database and creates the relationship only if the record for the entity exists.

Chapter 3. Business objects 45

Required property

The Required property specifies whether an attribute must contain a value. If a particular attribute in the business object that you are creating must contain a value, set the Required property for the attribute to true.

For information on enforcing the Required property for attributes, see the section on initAndValidateAttributes() in Connector Reference: C++ Class Library and Connector Reference: Java Class Library.

AppSpecificInfo

The AppSpecificInfo property is a String no longer than 255 characters that is specified primarily for an application-specific business object.

Note: Application-specific text is not available in the collaboration mapping

process (relevant only when ICS is the integration broker).

Max length property

The Max Length property is set to the number of bytes that a String-type attribute can contain. Although this value is not enforced by the WebSphere system, specific connectors or data handlers may use this value. Check the guide for the connector or data handler that will process the business object to determine minimum and maximum allowed lengths.

Note: The Max Length property is very important when you use a fixed width

data handler. Attribute length is not available in the collaboration mapping process (relevant only when ICS is the integration broker).

Default value property

The Default Value property can specify a default value for an attribute.

If this property is specified for an application-specific business object, and the UseDefaults connector configuration property is set to true, the connector can use the default values specified in the business object definition to provide values for attributes that have no values at runtime.

For more information on how the Default Value property is used, see the section on initAndValidateAttributes() in Connector Reference: C++ Class Library and Connector Reference: Java Class Library.

Comments property

The Comments property allows you to specify a human-readable comment for an attribute. Unlike the AppSpecificInfo property, which is used to process a business object, the Comments property provides only documentation information.

Special attribute value

Simple attributes in business object can have the special value, CxIgnore. When it receives a business object from an integration broker, the connector ignores all attributes with a value of CxIgnore. It is as if those attributes were invisible to the connector.

If no value is required, the connector sets the value of that attribute to CxIgnore by default.

Application-specific text at the attribute level

Note: Business object level application-specific text is not used by the connector.

46 Adapter for SWIFT User Guide

For business object attributes, the application-specific text format consists of name-value parameters. Each name-value parameter includes the parameter name and its value. The format of attribute application-specific text is as follows:

name=value[:name_n=value_n][...]

Each parameter set is separated from the next by a colon (:) delimiter.

Table 22 describes the name-value parameters for attribute application-specific text.

Table 22. Name-value parameters in AppSpecificText for attributes

Parameter Required Description

block Yes for top-level object

only

parse Yes for attributes of

the top-level object only

tag Yes for attributes of

type tag business object

letter=a Yes for each attribute

that points to a tag business object

content No The qualifier in the SWIFT message format. For

The number of the block in the SWIFT message. Values range from 0-5. For information on the SWIFT message blocks, see “Overview of SWIFT message structure” on page 47.

Describes whether, and how, to parse the SWIFT message block. Values are: fixlen—parse as fixed length delim—parse as delimited text field—Block 4 only no—Do not parse; treat as a single string.

The tag number of the field. For more on SWIFT message tags, see Appendix D, “SWIFT message structure”, on page 173. For further information on sequence and field business objects, see “Block 4 business object structure” on page 61.

One or more supported letters appended to the tag in the SWIFT message format. For example 20A or [A|B|NULL] (A or B or null). Note that NULL must be specified for tags where no letter is a possibility, or for tags that do not have a letter option at all. For example, tag 59.

example, in a SWIFT message MT502, tag20C, the qualifier = SEME.

Note: The application-specific information for production instruction meta-objects

(PIMOs) contains name-value pairs that indicate compute instructions. For more information, see Chapter 4, “ISO 7775 to ISO 15022 mapping”, on page 81.

Overview of SWIFT message structure

SWIFT messages consist of five blocks of data. In addition, the MQSA component adds two blocks that are used for queue management. The high-level structure of a SWIFT message is as follows:

MQSA UUID

SWIFT 1:Basic Header Block

SWIFT 2: Application Header Block

SWIFT 3:User Header Block

SWIFT 4: Text Block

SWIFT 5: Trailer

MQSA S Block

Chapter 3. Business objects 47

Note: The MQSA component adds the UUID (User Unique Message Identifier) and

S blocks. Neither are parsed by the SWIFT data handler. The S block has the same structure as SWIFT block 5, except that field tags consist of three char strings. For example, {S:{COP:P}}.

For further information on SWIFT message structure, see Appendix D, “SWIFT message structure”, on page 173, and All Things SWIFT: the SWIFT User Handbook.

Overview of business objects for SWIFT

As shown in Figure 5 there are five kinds of business objects for SWIFT:

Msg BO

= SWIFT message

MsgBlk BO

MsgData BO

MsgBlk BO

= SWIFT message blocks 1, 2, or 3

= SWIFT data block 4

MsgSeq BO

MsgField BO

= SWIFT Message Block 5

= Block 4 data sequence

= Block 4 data field

Figure 5. Business objects map to SWIFT message components

v Message business object (Msg BO) This is the top-level business object whose

attributes correspond to the blocks in a SWIFT message. For further information, see “Top-level business object structure” on page 49.

v Message block business object (MsgBlk BO) A child object of the Msg BO that

can represent blocks 1, 2, 3, or 5 in a SWIFT message. For further information, see “Block 1 business object structure” on page 53.

v Message data business object (MsgData BO) A child object of the Msg BO that

represents block 4 of the SWIFT message. For further information, see “Block 4 business object structure” on page 61.

v Message sequence business object (MsgSeq BO) A child object of a MsgData

BO or of another MsgSeq BO. A MsgSeq BO represents a sequence of fields occurring in block 4 of the SWIFT message. For further information, see “Sequence business object structure” on page 66.

48 Adapter for SWIFT User Guide

v Message field business object (MsgField BO) A child object of the MsgData BO

or of a MsgSeq BO that contains the content of a field. Fields correspond to tags in SWIFT messages. For further information, see “Field business object definitions” on page 69.

Each of these business objects consist of the following:

v Name The name of the business object consists of a SWIFT Message name, a

SWIFT message sequence name, or a SWIFT field name. More detailed naming conventions, if any, are provided in the sections for each kind of business object listed below. For example:

– Swift_MT502 is the name of the Msg BO. For further information, see

“Top-level business object structure” on page 49.

– Swift_ApplicationHeader is the name of a MsgBlk BO. For further

information, see “Block 1 business object structure” on page 53, “Block 2 business object structure” on page 55, and “Block 3 business object structure” on page 59.

– Swift_MT502Data is the name of a MsgData BO. For further information, see

“Block 4 business object structure” on page 61.

– Swift_MT502_B1 is the name of a MsgSeq BO. For further information, see

“Sequence business object structure” on page 66.

– Swift_Tag_22 is the name of a MsgField BO. For further information, see

“Field business object definitions” on page 69.

v Version The version of the business object is set to 1.1.0. For example:

Version = 1.1.0

v Attributes Each business object contains one or more attributes. For more

information see “Business object attribute properties” on page 44 and the sections below on each kind of business object.

v Verbs Each business object supports the following standard verbs:

– Create

– Retrieve

SWIFT message and business object data mapping

The IBM WebSphere Business Integration Adapter for SWIFT supports two kinds of mapping:

v SWIFT-message-to-WebSphere-business-object The sections below describe the

data mapping that occurs between SWIFT messages and WebSphere business objects.

v Business-object-to-business-object The mapping used to transform a business

object that represents an ISO 7775 SWIFT message into a business object that represents the corresponding ISO 15022 SWIFT message, and vice versa. For further information, see Chapter 4, “ISO 7775 to ISO 15022 mapping”, on page 81.

Top-level business object structure

The structure of the top-level business object for a SWIFT message, or Msg BO, reflects that of the SWIFT message. WebSphere requires a business object for each SWIFT block. As shown in Table 23, the top-level business object must have at least 5 attributes, one for each SWIFT block.

Note: Only attribute properties of consequence are shown in Table 23. For a listing

of all attribute properties, see “Sample top-level Business Object (Msg BO)

Chapter 3. Business objects 49

definition” on page 51.

Table 23. Top-level business object structure

Name Type Key Required Application specific

info

UUID (MQSA prepended)

Swift_01Header Swift_BasicHeader No Yes block=1;parse=fixlen Swift_02Header Swift_ApplicationHeader No No block=2;parse=fixlen Swift_03Header Swift_UserHeader No No block=3;parse=delim Swift_Data Swift_Text No No block=4;parse=field Swift_05Trailer String No No block=5;parse=no Swift_BlockS (MQSA

appended)

String Yes No block=0;parse=no

String No No block=6;parse=no

The following rules apply to the top-level business object:

v The name of the top-level object must be constructed in the following way:

BOPrefix_MTMessageType

where:

BOPrefix = an attribute of the meta-object (MO). For further information on the meta-object, see “Static meta-object” on page 29.

_MT = a constant string.

MessageType = an attribute of block 2 of the SWIFT message. For further information, see All Things SWIFT: the SWIFT User Handbook

An example of a top-level business object name is Swift_MT502.

v UUID, prepended to the message by the MQSA, is represented with a String

attribute

v Blocks 1-4 are represented with single-cardinality containers

v Block 5 is a string attribute, and is not extracted from the message by the SWIFT

data handler.

Note: It is possible to create business objects for block 5 and block S using block 3

as a template.

See Table 22 for the attribute application-specific information.

Figure 6 shows a business object definition for a top-level business object of a SWIFT message. This Msg BO definition was created in the WebSphere development environment.

The application-specific information contains the block number and parsing parameters for each attribute. For further information on attribute application-specific text, see Table 22. The Swift_ attributes correspond to child business objects discussed in the following sections. For a full specification of this sample business object definition, see “Sample top-level Business Object (Msg BO) definition” on page 51. Of special note is the type for the data block attribute, Swift_MT502Data, which indicates SWIFT message type 502, an order to buy or sell.

50 Adapter for SWIFT User Guide

This attribute corresponds to a child object of the top-level Msg BO that represents block 4 of the SWIFT message. The child object is a message data business object (MsgData BO).

All SWIFT top-level business object definitions are identical to that shown in Figure 6 with one exception: Block 4, shown as Swift_MT502Data, reflects the actual data definition of a specific SWIFT message.

Figure 6. Definition for top-level business object of a SWIFT message

Note: To create a top-level business object definition for a SWIFT message, you

must start Business Object Designer and then create all the child objects first.

Sample top-level Business Object (Msg BO) definition

This section presents a sample definition of a top-level business object, or Msg BO, for a SWIFT message of type MT502—an order to buy or sell.

[BusinessObjectDefinition] Name = Swift_MT502 Version = 1.1.0

[Attribute] Name = UUID Type = String Cardinality = 1 MaxLength = 255 IsKey = true IsForeignKey = false IsRequired = false AppSpecificInfo = block=0;parse=no IsRequiredServerBound = false [End] [Attribute] Name = Swift_01Header Type = Swift_BasicHeader ContainedObjectVersion = 1.0.0 Relationship = Containment Cardinality = 1 MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = false AppSpecificInfo = block=1;parse=fixlen IsRequiredServerBound = false [End] [Attribute] Name = Swift_02Header Type = Swift_ApplicationHeader ContainedObjectVersion = 1.0.0 Relationship = Containment Cardinality = 1 MaxLength = 1 IsKey = false

Chapter 3. Business objects 51

IsForeignKey = false IsRequired = false AppSpecificInfo = block=2;parse=fixlen IsRequiredServerBound = false [End] [Attribute] Name = Swift_03Header Type = Swift_UserHeader ContainedObjectVersion = 1.0.0 Relationship = Containment Cardinality = 1 MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = false AppSpecificInfo = block=3;parse=delim IsRequiredServerBound = false [End] [Attribute] Name = Swift_MT502Data Type = Swift_MT502Data ContainedObjectVersion = 1.0.0 Relationship = Containment Cardinality = 1 MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = false AppSpecificInfo = block=4;parse=field IsRequiredServerBound = false [End] [Attribute] Name = Swift_05Trailer Type = String Cardinality = 1 MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = false AppSpecificInfo = block=5;parse=no IsRequiredServerBound = false [End] [Attribute] Name = Swift_BlockS Type = String Cardinality = 1 MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = false AppSpecificInfo = block=6;parse=no IsRequiredServerBound = false [End] [Attribute] Name = ObjectEventId Type = String MaxLength = 255 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End]

[Verb] Name = Create [End]

52 Adapter for SWIFT User Guide

[Verb] Name = Retrieve [End]

Block 1 business object structure

The MsgBlck BO, Swift_BasicHeader, has the format and attributes shown in Table 24. The SWIFT data handler converts each of the SWIFT fields in this block into attributes in the Swift_BasicHeader business object. Note that there is no attribute application-specific information for this business object.

Note: Only attribute properties of consequence are shown in Table 24. For a listing

of all attribute properties, see “Sample block 1 business object definition” on page 54.

Table 24. Block 1 business object structure

Name Type Key Foreign

key

BlockIdentifier String Yes No Yes 1 1: ApplicationIdentifierString No No Yes 1 1 ServiceIdentifier String No No Yes 1 2 LTIdentifier String No No Yes 1 12 SessionNumber String No No Yes 1 4 SequenceNumber String No No No 1 4

The BlockIdentifier attribute includes the delimiter ”:” as in “1:”.

Required Cardinality Default Max

length

See Table 22 for the attribute application-specific information.

Figure 7 shows a block 1 business object definition that has been manually created in a WebSphere development environment. Each attribute name (ApplicationIdentifier, ServiceIdentifier, and so on) corresponds to a field in this SWIFT message block. For further information on this SWIFT message block, see Appendix D, “SWIFT message structure”, on page 173, and All Things SWIFT: the SWIFT User Handbook. Specify Type String for each named attribute. Note that there is no attribute application-specific information for the components of this business object.

Note: Be sure to specify the correct MaxLength values for the attribute names in

this fixed-length block business definition.

Chapter 3. Business objects 53

Figure 7. Block 1 business object definition

Note: To create a block 1 business object definition for a SWIFT message, start

Business Object Designer and then enter values for the attributes shown in “Sample block 1 business object definition” on page 54.

Sample block 1 business object definition

This section presents a sample definition of a block 1 business object for a SWIFT message of type MT502—an order to buy or sell.

[BusinessObjectDefinition] Name = Swift_BasicHeader Version = 1.1.0

[Attribute] Name = BlockIdentifier Type = String Cardinality = 1 MaxLength = 2 IsKey = true IsForeignKey = false IsRequired = true DefaultValue = 1: IsRequiredServerBound = false [End] [Attribute] Name = ApplicationIdentifier Type = String Cardinality = 1 MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = true IsRequiredServerBound = false [End] [Attribute] Name = ServiceIdentifier Type = String Cardinality = 1 MaxLength = 2 IsKey = false IsForeignKey = false IsRequired = true IsRequiredServerBound = false [End] [Attribute] Name = LTIdentifier Type = String Cardinality = 1 MaxLength = 12

54 Adapter for SWIFT User Guide

IsKey = false IsForeignKey = false IsRequired = true IsRequiredServerBound = false [End] [Attribute] Name = SessionNumber Type = String Cardinality = 1 MaxLength = 4 IsKey = false IsForeignKey = false IsRequired = true IsRequiredServerBound = false [End] [Attribute] Name = SequenceNumber Type = String Cardinality = 1 MaxLength = 6 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End] [Attribute] Name = ObjectEventId Type = String Cardinality = 1 MaxLength = 255 IsKey = true IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End]

[Verb] Name = Create [End]

Block 2 business object structure

The block 2 MsgBlk BO, Swift_ApplicationHeader, has the format and attributes shown in Table 25. The SWIFT data handler converts each of the SWIFT fields in this block into attributes in the Swift_ApplicationHeader business object. Note that there is no attribute application-specific information for this business object.

Note: Only attribute properties of consequence are shown in Table 25. For a listing

of all attribute properties, see “Sample block 2 business object definition” on page 56.

Table 25. Block 2 business object structure

Name Type Key Required Cardinality Default Max

Block Identifier String No Yes 1 2: IOIdentifier String No Yes 1 1 MessageType String No Yes 1 3 I_ReceiverAddress String No Yes 1 12 I_MessagePriority String No Yes 1 1 I_DeliveryMonitoring String No No 1 1 I_ObsolescencePeriod String No No 1 3 O_InputTime String No Yes 1 4

length

Chapter 3. Business objects 55

Table 25. Block 2 business object structure (continued)

Name Type Key Required Cardinality Default Max

length

O_MessageInputReference String No Yes 1 28 O_OutputDate String No No 1 6 O_OutputMessagePriority String No No 1 6

The BlockIdentifier attribute includes the delimiter ”:” as in “2:”.

The first three attributes in Table 25 are I/O attributes. Attributes that start with I_ are input attributes and are populated during SWIFT-to-business-object conversion. Attributes that start with O_ are output attributes and are populated in business-object-to-SWIFT conversions. The CxIgnore property must be set for business-object-to-SWIFT conversions.

See Table 22 for the attribute application-specific information.

Figure 8 shows a block 2 business object definition that has been manually created in a WebSphere development environment. Each attribute name (BlockIdentifier, IOIdentifier, and so on) corresponds to a field in this SWIFT message block. The definition shown is for the input attributes ( I_) are populated during SWIFT-to-business-object conversion. For further information on this SWIFT message block, see Appendix D, “SWIFT message structure”, on page 173, and All

Things SWIFT: the SWIFT User Handbook. Specify type String for each named attribute.

Note that there is no attribute application-specific information for the components of this business object.

Note: Be sure to specify the correct MaxLength values for the attribute names in

this fixed-length block business definition.

Figure 8. Block 2 business object definition

Note: To create a block 2 business object definition for a SWIFT message, start

Business Object Designer and then enter values for the attributes shown in “Sample block 2 business object definition” on page 56.

Sample block 2 business object definition

This section presents a sample definition of a block 2 business object for a SWIFT message of type MT502—an order to buy or sell.

56 Adapter for SWIFT User Guide

[BusinessObjectDefinition] Name = Swift_ApplicationHeader Version = 1.1.0

[Attribute] Name = BlockIdentifier Type = String Cardinality = 1 MaxLength = 2 IsKey = false IsForeignKey = false IsRequired = true DefaultValue = 2: IsRequiredServerBound = false [End] [Attribute] Name = IOIdentifier Type = String Cardinality = 1 MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = true DefaultValue = O IsRequiredServerBound = false [End] [Attribute] Name = MessageType Type = String Cardinality = 1 MaxLength = 3 IsKey = false IsForeignKey = false IsRequired = true IsRequiredServerBound = false [End] [Attribute] Name = O_InputTime Type = String Cardinality = 1 MaxLength = 4 IsKey = false IsForeignKey = false IsRequired = true IsRequiredServerBound = false [End] [Attribute] Name = O_MessageInputReference Type = String Cardinality = 1 MaxLength = 28 IsKey = false IsForeignKey = false IsRequired = true IsRequiredServerBound = false [End] [Attribute] Name = O_OutputDate Type = String Cardinality = 1 MaxLength = 6 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End] [Attribute]

Chapter 3. Business objects 57

Name = O_OutputTime Type = String Cardinality = 1 MaxLength = 4 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End] [Attribute] Name = O_OutputMessagePriority Type = String Cardinality = 1 MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End] [Attribute] Name = I_ReceiverAddress Type = String Cardinality = 1 MaxLength = 12 IsKey = false IsForeignKey = false IsRequired = true IsRequiredServerBound = false [End] [Attribute] Name = I_MessagePriority Type = String Cardinality = 1 MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = true IsRequiredServerBound = false [End] [Attribute] Name = I_DeliveryMonitoring Type = String Cardinality = 1 MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End] [Attribute] Name = I_ObsolescencePeriod Type = String Cardinality = 1 MaxLength = 3 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End] [Attribute] Name = ObjectEventId Type = String Cardinality = 1 MaxLength = 255 IsKey = true IsForeignKey = false IsRequired = false

58 Adapter for SWIFT User Guide

IsRequiredServerBound = false [End]

[Verb] Name = Create [End]

Block 3 business object structure

The block 3 MsgBlk BO, Swift_UserHeader, has the format and attributes shown in Table 26. Note that there is attribute application-specific information for this business object: the Tag parameter. For Tag parameters see Table 22.

Note: Only attribute properties of consequence are shown in Table 26. For a listing

of all attribute properties, see “Sample block 3 business object definition” on page 60.

Table 26. Block 3 business object structure

Name Type Key Foreign Required Cardinality Application

specific information

Tag103 String Yes No No 1 Tag=103 6 Tag113 String No No No 1 Tag=113 6 Tag108 String No No No 1 Tag=108 6 Tag119 String No No No 1 Tag=119 6 Tag115 String No No No 1 Tag=115 6

Max length

Figure 9 shows a block 3 business object definition that has been manually created in a WebSphere development environment. Each attribute name (Tag103, Tag113, and so on,) corresponds to a field in this SWIFT message block. For further information on this SWIFT message block, see Appendix D, “SWIFT message structure”, on page 173, and All Things SWIFT: the SWIFT User Handbook. Specify type String for each named attribute. Note that the application-specific information for the components of this business object are SWIFT tags.

Figure 9. Block 3 business object definition

Note: To create a block 3 business object definition for a SWIFT message, start

Business Object Designer and then enter values for the attributes shown in “Sample block 3 business object definition” on page 60.

Chapter 3. Business objects 59

Sample block 3 business object definition

This section presents a sample definition of a block 3 business object for a SWIFT message of type MT502—an order to buy or sell.

[BusinessObjectDefinition] Name = Swift_UserHeader Version = 1.1.0

[Attribute] Name = Tag103 Type = String Cardinality = 1 MaxLength = 255 IsKey = true IsForeignKey = false IsRequired = false AppSpecificInfo = Tag=103 IsRequiredServerBound = false [End] [Attribute] Name = Tag113 Type = String Cardinality = 1 MaxLength = 255 IsKey = false IsForeignKey = false IsRequired = false AppSpecificInfo = Tag=113 IsRequiredServerBound = false [End] [Attribute] Name = Tag108 Type = String Cardinality = 1 MaxLength = 255 IsKey = false IsForeignKey = false IsRequired = false AppSpecificInfo = Tag=108 IsRequiredServerBound = false [End] [Attribute] Name = Tag119 Type = String Cardinality = 1 MaxLength = 255 IsKey = false IsForeignKey = false IsRequired = false AppSpecificInfo = Tag=119 IsRequiredServerBound = false [End] [Attribute] Name = Tag115 Type = String Cardinality = 1 MaxLength = 255 IsKey = false IsForeignKey = false IsRequired = false AppSpecificInfo = Tag=115 IsRequiredServerBound = false [End] [Attribute] Name = ObjectEventId Type = String Cardinality = 1

60 Adapter for SWIFT User Guide

MaxLength = 255 IsKey = true IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End]

[Verb] Name = Create [End]

Block 4 business object structure

SWIFT block 4 contains the body of the SWIFT message. Block 4 is made up of fields of message tags and their contents on the one hand, and on the other, of sequences of message tags. This data content makes the block 4 business object structure unlike that of blocks 1, 2, and 3. The block 4 business object is the message data business object (MsgData BO).

Every tag and sequence in a SWIFT message is modeled as a child business object of the MsgData BO. Accordingly, a MsgData BO has child objects of two types: field business objects (MsgField BO) and sequence business objects (MsgSeq BO). These business objects reflect how the SWIFT data is formatted in block 4. More specifically, attributes in these business objects model the content (message tags and their content) and order (sequence) that is specified in a SWIFT message format specification. The sequence of the message tags is crucial if the business object definition is to faithfully represent the SWIFT message. For further information on MsgField BOs and MsgSeq BOs, see “Sequence and field business objects” on page 66.

Figure 10 shows a portion of the format specification from the SWIFT Standards Release Guide for MT502, an order to buy or sell.

Chapter 3. Business objects 61

Figure 10. SWIFT message type 502 format specification

Figure 11 shows the corresponding portion of a business object definition, which reflects the structure of the message tags and sequences in the SWIFT message:

v The Status—M (mandatory) or O (optional)—field in the SWIFT message is

mapped to the Required property in the business object definition. For example, the status of SWIFT Tag 98a (shown in Figure 10) is O or optional; Figure 11 shows the corresponding business object attribute, Preparation_DateTime (of type Swift_Tag_98), for which the Required property is not checked.

v The Tag, Qualifier, and Content/Options fields from the SWIFT message are

mapped as attribute application-specific text in the business object definition. For example, in the SWIFT message shown in Figure 10, Start of Block is Tag16R with Content of GENL. The corresponding entry shown in Figure 11 is the attribute Start_Of_Block of type Swift_Tag_16 with application-specific information property parameters that identify the Tag, the Tag’s letter, and Content (Tag=16;Letter=R;Content=GENL).

v Data formats are often indicated in the Content/Options field in a SWIFT

message. For example, Figure 10 shows the sender’s reference for “Mandatory Sequence A General Information” as Tag20C, with a SEME qualifier and Content consisting of data format instructions (:4!c[/4!c]). Figure 11 shows the corresponding attribute application-specific text: only the Tag and Letter are shown in the AppSpecInfo field (Tag=20;Letter=C). The SWIFT data handler also parses the field’s data content—the formatting information (:4!c[/4!c])is

62 Adapter for SWIFT User Guide

included in the business object definition in ways that support mapping between ISO 7775 and ISO 15022 message formats.

v Repeating sequences in SWIFT messages are indicated by “---->” in the SWIFT

Format Specifications as shown in Figure 10. Nonrepeating sequences are marked “-----|” . In the business object definition, a repeating sequence is assigned cardinality n. For example, the repeating sequence Tag22F shown in Figure 10 is mapped to the attribute Indicator of type Swift_Tag_22 with a cardinality property of n.

Figure 11. Partial block 4 business object definition

MsgData BO format

The format of a MsgData BO is summarized in the sections below.

MsgData BO name: The naming convention for the MsgData BO representing block 4 of a SWIFT message is as follows:

Swift_MT<message_type>Data

For example:

Name = Swift_MT502Data

MsgData BO attribute names: Each attribute of the MsgData BO represents one of the following:

v a MsgSeq BO

v a MsgField BO

Accordingly, the attribute names are the same as those for MsgSeq BOs and MsgField BOs. The naming convention for MsgField BO attributes is as follows:

Swift_<tag_number>_<position_in_the_SWIFT_message>

For example:

Name = Swift_94_1

Chapter 3. Business objects 63

The naming convention for MsgSeq BO attributes is as follows:

Swift_MT<message_type>_<SWIFT_sequence_name>

For example:

Name = Swift_MT502_B

For further information see “Sequence business object structure” on page 66 and “Field business object definitions” on page 69.

MsgData BO attribute types: The type for MsgData attributes is as follows:

For MsgField BO attributes:

Swift_Tag_<tag_number>

For example:

Type = Swift_Tag_94

For MsgSeq BO attributes:

Swift_MT<message_type>_<SWIFT_sequence_name>

For example:

Type = Swift_MT502_B

MsgData BO attribute ContainedObjectVersion: The contained object version for the MsgData BO as well as for the its MsgSeq BO attributes is 1.1.0. For example:

[Attribute] Name = Swift_MT502_B Type = Swift_MT502_B

...

ContainedObjectVersion = 1.1.0

...

[End]

Note: MsgField BO attributes are simple, and have no ContainedObjectVersion.

MsgData BO attribute relationship: The relationship attribute property for

MsgData BO and its MsgSeq BO attributes is Containment. For example:

[Attribute] Name = Swift_MT502Data Type = Swift_MT502Data

...

Relationship = Containment

...

[End]

MsgData BO attribute cardinality: The MsgData BO and its MsgSeq BO attributes have a cardinality property of n. MsgField BO attributes that represent repeating fields also have cardinality n. All others attributes have cardinality 1. For example:

64 Adapter for SWIFT User Guide

[Attribute] Name = Swift_16_1 Type = Swift_Tag_16

...

Cardinality = n

...

[End]

MsgData BO attribute IsKey: Each MsgData BO definition must contain at least one attribute defined as the key attribute (IsKey = true). The rule is that the first single cardinality attribute in each BO definition must be defined as key attribute.

For example:

[Attribute] Name = Swift_16.1 Type = Swift_Tag_16

...

Cardinality = 1

IsKey = true

[End]

MsgData BO attribute AppSpecificInfo: In MsgData BO definitions, only MsgField BO attributes have application-specific information; this property is always null for MsgSeq BO attributes. The convention for application-specific information for MsgField BO attributes is as follows:

Tag=nn;Letter=xx;Content=string

where nn is the SWIFT tag number of the field, xx is one or a list of supported letter options for the tag, and string is the value of the qualifier for a non-generic field as described in Table 22 on page 47. For example:

[Attribute] Name = Swift_16_22 Type = Swift_Tag_16

...

AppSpecificInfo = Tag=16;Letter=S;Content=OTHRPRTY

...

[End]

When MsgField BO attributes appear in MsgSeq BOs and the application specific information indicates:

...;Union=True

The MsgField child object—a TagUnion business object and its child objects, TagLetterOption objects—will be populated instead of the DataField attribute. For information on TagUnion business objects, see “Field business object definitions” on page 69.

Chapter 3. Business objects 65

Sequence and field business objects

As noted above, the connector models sequences and tags in SWIFT messages as sequence business objects (MsgSeq BO) and field business objects (MsgField BO), respectively. Figure 12 illustrates the hierarchical relationship of these business objects.

MsgData BO

MsgSeq attribute

MsgField attribute

MsgField BO MsgSeq attribute MsgField attribute

Figure 12. Field and sequence business objects in the (block 4) MsgData BO

MsgSeq attribute

MsgSeq BO

MsgField BO

Figure 13 shows part of a definition for a SWIFT message (MT502) that illustrates a sequence containing field and sequence attributes. The sequence attribute Swift_MT02_B_Order_Details not only includes several attributes of type Tag (for example, Swift_Tag_16, Swift_Tag_94), but also the subsequence Swift_MT502_B1_Price. This subsequence is a repeating optional sequence, and its properties reflect this (Required= no; Cardinality=n). Note that the sequences contain no application-specific information.

Figure 13. A Sequence containing tag and subsequence attributes

Sequence business object structure

As shown in Figure 14, each sequence business object (MsgSeq BO) attribute indicates one of the following:

v another MsgSeq BO, or subsequence

66 Adapter for SWIFT User Guide

v a MsgField BO

There is no limit to the number of subsequences that a MsqSeq BO can nest.

MsgSeq BO

MsgSeq attribute

MsgField attribute

Figure 14. Field and Subsequence Business Objects in the MsgSeq BO

MsgSeq BO

MsgField BO

Figure 15 shows another excerpt of a MsgSeq BO. In this excerpt, the Swift_Tag_ attributes represent MsgField BOs. The Swift_MT502_A1_Linkages attribute is for a child object that is a subsequence MsgSeq BO.

Figure 15. Excerpt from a sequence business object (MsgSeq BO)

The following rules apply to sequence business objects:

v A subsequence business object is an attribute of a particular sequence business

object type.

v A collection of more than one repeating field is treated as a subsequence. v The application-specific information of a sequence attribute is always NULL.

For a sample sequence business object, see “Sample sequence business object definition” on page 68.

Chapter 3. Business objects 67

MsgSeq BO format

Like a MsgData BO, a MsgSeq BO consists of attributes that are either MsgSeq BOs or MsgField BOs. For information on the format of these attributes, see “MsgData BO format” on page 63.

Sample sequence business object definition

This section presents a sample definition of a MsgSeq BO for a SWIFT message of type MT502—an order to buy or sell. The definition is of a Mandatory Sequence A Order to Buy or Sell.

[BusinessObjectDefinition] Name = Swift_MT502_A_General_Information Version = 1.0.0

[Attribute] Name = Start_Of_Block Type = Swift_Tag_16 ContainedObjectVersion = 1.0.0 Relationship = Containment Cardinality = 1 MaxLength = 1 IsKey = true IsForeignKey = false IsRequired = true AppSpecificInfo = Tag=16;Letter=R;Content=GENL IsRequiredServerBound = false [End] [Attribute] Name = Senders_Reference Type = Swift_Tag_20 ContainedObjectVersion = 1.0.0 Relationship = Containment Cardinality = 1 MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = true AppSpecificInfo = Tag=20;Letter=C IsRequiredServerBound = false [End] [Attribute] Name = Function_Of_The_Message Type = Swift_Tag_23 ContainedObjectVersion = 1.0.0 Relationship = Containment Cardinality = 1 MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = true AppSpecificInfo = Tag=23;Letter=G IsRequiredServerBound = false [End] [Attribute] Name = Preparation_DateTime Type = Swift_Tag_98 ContainedObjectVersion = 1.0.0 Relationship = Containment Cardinality = 1 MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = false AppSpecificInfo = Tag=98;Letter=A|C IsRequiredServerBound = false [End]

68 Adapter for SWIFT User Guide

[Attribute] Name = Indicator Type = Swift_Tag_22 ContainedObjectVersion = 1.0.0 Relationship = Containment Cardinality = n MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = true AppSpecificInfo = Tag=22;Letter=F IsRequiredServerBound = false [End] [Attribute] Name = Swift_MT502_A1_Linkages Type = Swift_MT502_A1_Linkages ContainedObjectVersion = 1.0.0 Relationship = Containment Cardinality = n MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End] [Attribute] Name = End_Of_Block Type = Swift_Tag_16 ContainedObjectVersion = 1.0.0 Relationship = Containment Cardinality = 1 MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = true AppSpecificInfo = Tag=16;Letter=S;Content=GENL IsRequiredServerBound = false [End] [Attribute] Name = ObjectEventId Type = String MaxLength = 255 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End]

[Verb] Name = Create [End]

[Verb] Name = Retrieve [End]

Field business object definitions

WebSphere represents every SWIFT tag as a field business object (MsgField BO). Each MsgField BO is modeled using the SWIFT generic field structure, even if the field is non-generic. WebSphere uses two additional business object models to represent the combination of letters and options used to represent and combine SWIFT message components as subfields in business objects:

v Tag union business object (TagUnion BO) This is a child object of the MsgField

BO. A TagUnion BO contains all possible letter options for a specific tag, and is not specific to a particular message type.

Chapter 3. Business objects 69

MsgField BO

Letter attribute

Qualifier attribute IC Attribute Data Attribute DataField Attribute

v Tag letter option business object (TagLetterOption BO) This is a letter option

child object of the TagUnion BO that defines the content of the subfield as well as its format including delimiters.

MsgField BO format

As shown in Figure 16, each MsgField BO contains five attributes, including one and only one TagUnion BO, with the data type shown in parentheses () below:

TagUnion BO

TagLetterOption attribute

Figure 16. Attributes and business objects in the MsgField BO

The content and order of all subfields other than the SWIFT Qualifier and Issuer Code (IC) are captured in the child object of DataField, which is the TagUnion BO and its child objects, TagLetterOption BOs. The attributes and business objects shown in Figure 16 are discussed in the section below.

MsgField BO, TagUnion BO, and TagLetterOption BO names: The naming convention for a MsgField BO is as follows:

Swift_Tag_<N>

where N stands for the message number. For example:

Name = Swift_Tag_22

The naming convention for a TagUnion BO is as follows:

Swift_Tag_Union_<tag_number>

where tag_number is the numeric representation of tag number. For example:

Name = Swift_Tag_Union_20

TagLetterOption BO

The naming convention for a TagLetterOption BO is as follows:

Swift_Tag_Union_<tag_number>_Opt_[<letter_option>]

where tag_number is the numeric representation of tag number and [<letter_option>] is the letter option when a tag is associated with a letter. If the tag has no letter associated with it, then the name ends at Opt.For example:

Name = Swift_Tag_Union_20_Opt_C

MsgField BO, TagUnion BO, and TagLetter BO Attribute names: The names of the five attributes in a MsgField BO are as follows:

v Letter v Qualifier v IC

70 Adapter for SWIFT User Guide

v Data v DataField

The names of attributes in TagUnion BOs are as follows:

Swift_<tag_number>_[<letter_option>]

where tag_number is the numeric representation of the tag number and the square brackets signify that the letter is appended only when it is associated with the tag. For example:

Swift_20_C

The name of the attribute in TagLetterOption BOs is the concatenation of words in the subfield name shown in the SWIFT format specification table. The first letter of each word in the concatenated string is always capitalized, with subsequent letters in the word appearing in lowercase, regardless of how the words are spelled in the SWIFT format specification. Spaces and non-alphabetic symbols are left out of the concatenated name. If a field has no subfield, the word Subfield is used as an attribute name. For example, for the subfield “Proprietary Code” in 95R, the corresponding attribute name in the definition of TagLetterOption BO

Swift_Tag_Union_95_Opt_R is as follows:

Name = ProprietaryCode

MsgField BO, TagUnion BO, and TagLetterOption BO attribute types: The type for MsgField attributes is as follows:

v Letter (String)

v Qualifier (String)

v Issuer Code (String)

v Data (String) v DataField (TagUnion_BO)

For example, in a MsgField BO definition, the type for a Swift_Tag_20 attribute would be listed as follows:

[Attribute] Name = DataField Type = Swift_Tag_Union_20

The type for attributes in the TagUnion BO is the name of the TagLetterOption BO child object. For example, in a TagUnion BO definition for Swift_Tag_Union_20, the type for the TagLetterOption attribute is as follows:

[Attribute] Name = Swift_20_C Type = Swift_Tag_Union_20_Opt_C

The type for attributes in TagLetterOption BOs is always String.

MsgField BO, TagUnion BO, and TagLetterOption BO ContainedObjectVersion:

The contained object version for the MsgField BO, the TagUnion BO, and the TagLetterOption BO is 1.1.0. For example:

as well as for the its MsgSeq BO attributes is 1.1.0. For example:

[Attribute] Name = Swift_20_C Type = Swift_Tag_Union_20_Opt_C

...

Chapter 3. Business objects 71

ContainedObjectVersion = 1.1.0

... [End]

Note: MsgField BO attributes are simple, and have no ContainedObjectVersion.

MsgField BO, TagUnion BO, and TagLetterOption BO attribute cardinality: The

cardinality of attributes in TagUnion BOs and TagLetterOption BOs is always set to

1. For example:

[Attribute] Name = Swift_20_C Type = Swift_Tag_Union_20_Opt_C

...

Cardinality = 1

...

[End]

MsgField BO, TagUnion BO, and TagLetterOption BO attribute IsKey: In each MsgField BO, the attribute Letter must be defined as the key attribute.

For example:

[Attribute]

Name = Letter Type = String IsKey = true

...

[End]

The first attribute of a TagUnionBO is defined as key.

The first attribute of TagLetterOption BO is defined as key.

TagLetterOption BO attribute AppSpecificInfo: The AppSpecificInfo attribute definition of a TagLetterOption BO provides crucial SWIFT message formatting information for business object subfields. The AppSpecificInfo attribute must contain the following information:

Format=***;Delim=$$$

where

*** stands for the SWIFT subfield format specification, which excludes delimiter information

$$$ stands for one or more letters that constitute the delimiter between the current subfield and the next subfield.

When the delimiters are CrLf, the symbol string CrLf specifies that a carriage return is immediately followed by a line feed.

For example, the AppSpecificInfo attribute for a TagLetterOption BO, Swift_Tag_Union_95_Opt_C, might appear as follows:

72 Adapter for SWIFT User Guide

[Attribute]

Name = CountryCode Type = String

...

AppSpecificInfo = Format=2!a;Delim=/

...

[End]

For a sample object and attribute definitions, see “Sample MsgField BO, TagUnion BO, and TagLetterOption BO definitions” on page 73.

Sample MsgField BO, TagUnion BO, and TagLetterOption BO definitions

This section presents a sample definition of a MsgField BO definition that illustrates TagUnion and TagLetterOption attributes and objects.

The sample MsgField BO, Swift_Tag_21, is as follows:

[BusinessObjectDefinition] Name = Swift_Tag_21 Version = 3.0.0

[Attribute] Name = Letter Type = String MaxLength = 255 IsKey = true IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End]

[Attribute] Name = Qualifier Type = String MaxLength = 255 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End]

[Attribute] Name = IC Type = String MaxLength = 255 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End]

[Attribute] Name = Data Type = String MaxLength = 255 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End]

Chapter 3. Business objects 73

[Attribute] Name = DataField Type = Swift_Tag_Union_21 ContainedObjectVersion = 3.0.0 Relationship = Containment Cardinality = 1 MaxLength = 0 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End]

[Attribute] Name = ObjectEventId Type = String MaxLength = 255 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End]

[Verb] Name = Create [End]

[Verb] Name = Delete [End]

[Verb] Name = Retrieve [End]

[Verb] Name = Update [End]

[End]

Note that the DataField attribute indicates a TagUnion BO, whose name is defined by the Type attribute, Swift_Tag_Union_21. Here is that TagUnion BO, which lists as attributes all the letter options for Swift_Tag_21.

[BusinessObjectDefinition] Name = Swift_Tag_Union_21 Version = 1.1.0

[Attribute] Name = Swift_21 Type = Swift_Tag_Union_21_Opt ContainedObjectVersion = 1.0.0 Relationship = Containment Cardinality = 1 MaxLength = 0 IsKey = true IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End]

[Attribute] Name = Swift_21_A Type = Swift_Tag_Union_21_Opt_A ContainedObjectVersion = 1.0.0 Relationship = Containment

74 Adapter for SWIFT User Guide

Cardinality = 1 MaxLength = 0 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End]

[Attribute] Name = Swift_21_B Type = Swift_Tag_Union_21_Opt_B ContainedObjectVersion = 1.0.0 Relationship = Containment Cardinality = 1 MaxLength = 0 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End]

[Attribute] Name = Swift_21_C Type = Swift_Tag_Union_21_Opt_C ContainedObjectVersion = 1.0.0 Relationship = Containment Cardinality = 1 MaxLength = 0 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End]

[Attribute] Name = Swift_21_D Type = Swift_Tag_Union_21_Opt_D ContainedObjectVersion = 1.0.0 Relationship = Containment Cardinality = 1 MaxLength = 0 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End]

[Attribute] Name = Swift_21_E Type = Swift_Tag_Union_21_Opt_E ContainedObjectVersion = 1.0.0 Relationship = Containment Cardinality = 1 MaxLength = 0 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End]

[Attribute] Name = Swift_21_F Type = Swift_Tag_Union_21_Opt_F ContainedObjectVersion = 1.0.0 Relationship = Containment Cardinality = 1 MaxLength = 0

Chapter 3. Business objects 75

IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End]

[Attribute] Name = Swift_21_G Type = Swift_Tag_Union_21_Opt_G ContainedObjectVersion = 1.0.0 Relationship = Containment Cardinality = 1 MaxLength = 0 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End]

[Attribute] Name = Swift_21_N Type = Swift_Tag_Union_21_Opt_N ContainedObjectVersion = 1.0.0 Relationship = Containment Cardinality = 1 MaxLength = 0 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End]

[Attribute] Name = Swift_21_P Type = Swift_Tag_Union_21_Opt_P ContainedObjectVersion = 1.0.0 Relationship = Containment Cardinality = 1 MaxLength = 0 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End]

[Attribute] Name = Swift_21_R Type = Swift_Tag_Union_21_Opt_R ContainedObjectVersion = 1.0.0 Relationship = Containment Cardinality = 1 MaxLength = 0 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End]

[Attribute] Name = ObjectEventId Type = String MaxLength = 255 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End]

76 Adapter for SWIFT User Guide

[Verb] Name = Create [End]

[Verb] Name = Retrieve [End]

[End]

Note that IsKey = true for the first attribute in the TagUnion BO above, Swift_21.

The attribute Swift_21_A indicates a child object TagLetterOption BO. This child object’s name is defined by the attribute’s Type attribute,

Swift_Tag_Union_21_Opt_A. Here is that TagLetterOption BO:

[BusinessObjectDefinition] Name = Swift_Tag_Union_21_Opt_A Version = 1.0.0

[Attribute] Name = ReferenceOfTheIndividualAllocation Type = String MaxLength = 255 IsKey = true IsForeignKey = false IsRequired = false AppSpecificInfo = Format=16x IsRequiredServerBound = false [End]

[Attribute] Name = ObjectEventId Type = String MaxLength = 255 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End]

[Verb] Name = Create [End]

[Verb] Name = Retrieve [End]

Note that the only attribute of this TagLetterOption BO, ReferenceOfTheIndividualAllocation, is a concatenation of the corresponding SWIFT subfield name for this tag option, with the first letter of each word in uppercase. The Qualifier and Issuer Code subfields are excluded from the attribute of the TagLetterOption BOs. The IsKey property is also true for this attribute.

Note: A TagUnion BO contains both generic and non-generic fields. A non-generic

field has no subfields.

The TagLetterOption BO can represent simple and complex SWIFT field and subfield formatting. Here is a business object definition for Swift_Tag_Union_22_Opt, a TagLetterOption BO whose attributes and application-specific information specify the subfield formatting for SWIFT Field 22, a function for a Common Reference between a sender and receiver. Notice that the

Chapter 3. Business objects 77

AppSpecificInfo for Function specifies the format and the delimiter with which to parse the data in the SWIFT message. CommonReference is the concatenation of the subfield name. The AppSpecificInfo for CommonReference corresponds to that shown in Figure 17.

[BusinessObjectDefinition] Name = Swift_Tag_Union_22_Opt Version = 1.0.0

[Attribute] Name = Function Type = String MaxLength = 255 IsKey = true IsForeignKey = false IsRequired = false AppSpecificInfo = Format=8a;Delim=/ IsRequiredServerBound = false [End]

[Attribute] Name = CommonReference Type = String MaxLength = 255 IsKey = false IsForeignKey = false IsRequired = false AppSpecificInfo = Format=4!a2!c4!n4!a2!c IsRequiredServerBound = false [End]

[Attribute] Name = ObjectEventId Type = String MaxLength = 255 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [End]

[Verb] Name = Create [End]

[Verb] Name = Retrieve [End]

[End]

78 Adapter for SWIFT User Guide

Figure 17. SWIFT field definition

Chapter 3. Business objects 79

80 Adapter for SWIFT User Guide

Chapter 4. ISO 7775 to ISO 15022 mapping

v “Production instruction meta-objects (PIMOs)”

v “Creating PIMOs” on page 88

v “Modifying PIMOs: Map summary” on page 96

The IBM WebSphere Business Adapter for SWIFT dynamically transforms a business object representing an ISO 7775 SWIFT message into a business object representing the corresponding ISO 15022 SWIFT message and vice versa. The transformation is performed by a mapping engine. The mapping engine is governed by a production instruction meta-object (PIMO). This chapter describes PIMOs, how they map business object attributes, and how to create or modify a PIMO.

Important: 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 Chapter 3, “Business objects”, on page 43, and only on Solaris platforms. The mapping capability does not support transformation of business objects released with 1.2 or earlier releases of the adapter for SWIFT.

Production instruction meta-objects (PIMOs)

A PIMO is a hierarchical meta-object that supports the transformation of business objects from one format to another. PIMOs specify not only the attribute-to-attribute mapping but also the computation instructions required to perform the transformation. The mapping and the computation instructions constitute meta-data that is used by the mapping engine.

Map_objects.txt contains 20 PIMOs in their entirety. Each PIMO contains all of the meta-data required to transform a business object representing an ISO 7775- or 15022-formatted SWIFT message to a business object representing the corresponding ISO 15022- or 7775-formatted SWIFT message. For more on these PIMOs and how to create or modify them, see “Creating PIMOs” on page 88.

PIMO structure and syntax

As Figure 18 shows, a simple PIMO has two mandatory child objects, Port and Action, and an optional child object, Declaration.

Figure 18. Simple PIMO

The attribute structure is as follows:

Port This child object always contains an input port and output port.

v IPort The input port

v OPort The output port

Declaration This optional child object contains attributes that name local variables.

Action This attribute describes objects that contain compute instructions. The

instructions, which reside in the attribute’s application-specific information, are used to process Declaration variables and Port objects. Action child objects represent computational sub-tasks listed in the order of execution:

v Action1

v Action2

v ... v Actionn

In fact, as shown in Figure 19, the PIMOs that are used to map SWIFT business objects are hierarchical objects that contain many nested levels of PIMOs, each with their own Port, Action, and Declaration objects as well as discrete mapping and computing instructions. At every level, however, the Port, Action and Declaration attributes exhibit the same syntax, structure, and function, which are described in the sections below.

Note: A simple PIMO can have multiple nested levels of Port, Declaration, and

82 Adapter for SWIFT User Guide

Action objects. A complex PIMO has more than one Port object on the same level. The PIMOs available with this release are simple PIMOs.

Figure 19. Excerpt of expanded PIMO

Port

The Port object type describes the specific transformation the mapping engine undertakes and has the following naming syntax:

PimoName>_Port

In Figure 18, for example, the Port is of type Map_Swift_MT520_to_MT540_Port, which names the transformation of a business object representing an ISO 7775 SWIFT message to an object representing an ISO 15022 SWIFT message.

Port contains as child objects IPort (input port) and OPort (output port). The types of the IPort and OPort attributes describe the parameters to be mapped: an IPort is used to pass an input parameter (for example, Swift_MT_520), and an OPort is used to pass an output parameter (for example Swift_MT_540). The parameters are passed by way of reference to their object types.

The IPort and OPort object may be a primitive type, such as int, float,orString, or a business object, such as Swift_MT520. The computation instructions contained in an Action child object refer to, and act on, these IPort and OPort object types.

Note: IPort and OPort cannot specify a meta-object as a type.

By convention, the Port and IPort attributes are marked as key (IsKey = true).

Declaration

The Declaration object type describes the objects to be transformed and has the following naming syntax:

PimoName_Declaration

Chapter 4. ISO 7775 to ISO 15022 mapping 83

The attributes in Declaration child objects specify local variables for the computing instructions that are detailed in Action objects for the Port. The attribute type declares the type of variable.

Variables can be constant or variable. The keyword final in a Declaration object’s

AppSpecificInfo designates a constant variable. If a Declaration object’s AppSpecificInfo is blank, the variable is not constant. In the PIMO excerpt shown in Figure 20, for example, Qualifier and Letter are declared constant variables; Var Boolean and the Map_Swift_Tag35E_to_70E_Declaration itself are variable.

Figure 20. Declarations in a PIMO

By convention, the first variable in the Declaration object is marked as key (IsKey = true).

Note: A Declaration object is optional; when Action objects require no local

Action

The Action object describes the computing instructions that the mapping engine performs. The top-level Action object has the following naming syntax:

PimoName_Action

The computing instructions specified in Action objects act on the IPort and OPort objects and use the variables specified in Declaration objects. For each Port and Declaration, the Action objects aggregate, in sequential order, all of the computing instructions for the map engine. No space or period is allowed in the Action type names.

Actions can be one of the following types:

v Compute

v Delegate

v Native

v Scenario

variable, the Declaration attribute can be omitted. The data type of the Declaration child object cannot be a meta-object.

Compute action: A Compute type indicates that the Action can be performed by a simple operation. All compute type Actions use the keyword opCode to specify the

84 Adapter for SWIFT User Guide

name of operation. The keyword Target designates the receiving party of the operation. The syntax for a compute type Action is specified in its AppSpecificInfo and is as follows:

opCode=<opCode>;target=<variable>;<parameters>

where opCode, variable, and parameters are described in Table 27.

Table 27. Compute action opCodes

opCode Example Description

+ type=compute;opCode=+;target=Var_B;Var_1;Var_2Addition. Var_2 is added to

Var_1 and the sum assigned to

the target, Var_B; applies to string and numeric type variables.

- type=compute;opCode=;target=Var_B;Var_1;Var_2

move type=compute;opCode=move;target=OPort;Var_1Copy the value of Var_1 to the

index type=compute;opCode=

index;target=var_4;Var_1;Var_2;Var_3

Subtraction. Var_2 is subtracted from Var1 and the difference is assigned to the target, Var_B. Applies to numeric type variables.

target, OPort. Applies to all variable types.

Looks for first occurrence of string Var_2 in the string Var_1, starting at the position Var_3.

Returns Var_4 to the target, OPort. Var_4 can be –1 if Var_2 is not found. Applies to string variables only.

substring type=compute;opCode=

substring;target=result;sourceString;index1;index2

append type=compute;opCode=

append;target=result;source1String;index;source2String

size type=compute;opCode=

size;target=OPort;Var;

Assign target the result of the sub-string of sourceString from index1 to index2. When index2 exceeds the string length of sourceString, index2 is deemed the same length as that of sourceString.

Append source2String to source1String at index. The result is assigned to the target, result.

Assign target the length of variable Var when Var is of type

String. When Var is of type containment, assign target the number of instances of Var.

Delegate action: Delegate Action is specified when more than one Compute Action is required. A Delegate Action relies on nested PIMOs to complete the Action, and in this sense is analogous to a function call. The syntax of a Delegate Action object is specified in its AppSpecificInfo and is as follows:

type=delegate;<var1>;<var2>

where type indicates the Delegate Action type and var1 is passed to the IPort of a child PIMO, and var2 is passed to the OPort of the child PIMO. The relative position of the variables corresponds to the sequence of Ports in the invoked PIMO. (The invoked PIMO is the PIMO to which Action is delegated.) Looping

Chapter 4. ISO 7775 to ISO 15022 mapping 85

occurs if one or both of the IPort and OPort objects in the invoked PIMO is of cardinality n.The loop syntax of the delegation is as follows:

v If both the IPort and OPort objects in the invoked PIMO have cardinality n, then

for each instance of these Port objects, an object is created and passed on to the invoked PIMO’s IPort and OPort. Looping occurs as many times as the number of object instances, and delegation is passed by reference along with each instance.

v If the IPort object in the invoked PIMO has cardinality n and the OPort object

does not have cardinality n, then for each instance of the IPort object, an object is created and passed on to the IPort of the invoked PIMO along with a reference to the type of the OPort object. Looping occurs as many times as the number of IPort object instances, and delegation is passed by reference along with each instance.

For example, in Figure 21, Action6 is of type Delegate. The computing tasks for this action are too complex for specification using Compute Action. In fact, the computing tasks require two levels of Delegate Action. The first Delegate Action is to a nested PIMO, Map_Swift_MT520_A_to_MT540_A_Port. The Action of this Port is also of type Delegate, with its variables passed to the IPort and OPort of Map_Swift_Tag_20_to_20C_Port. The Action of this nested PIMO is of the compute type, and the results are passed back up to the invoking PIMOs, just like a function call.

Figure 21. Delegate action in a PIMO

Native action: Native Action is used to invoke components implemented in Java. In particular, a Native Action object supports calls to the public static method of a Java class, which allows you to develop more complicated processing functions in Java. The syntax of a Native Action object is specified in its AppSpecificInfo and is as follows:

type=nativeStatic;class=<className>;method=<methodName>; target=return;var1;var2, varn

86 Adapter for SWIFT User Guide

IBM Adapter for SWIFT User Guide

Specifications and Main Features

Frequently Asked Questions

User Manual

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

Chapter 2. Configuring the connector

Prerequisites

Prerequisite software

Installing the connector

Installing on a UNIX system

Installing on a Windows system

Connector configuration

Standard connector properties

Connector-specific properties

Enabling guaranteed event delivery

Guaranteed event delivery for connectors with JMS event stores

Queue Uniform Resource Identifiers (URI)

Meta-object attributes configuration

Static meta-object

Dynamic child meta-object

Startup file configuration

Startup

Windows

UNIX

Chapter 3. Business objects

Connector business object requirements

Business object hierarchy

Business object attribute properties

Application-specific text at the attribute level

Overview of SWIFT message structure

Overview of business objects for SWIFT

SWIFT message and business object data mapping

Top-level business object structure

Block 1 business object structure

Block 2 business object structure

Block 3 business object structure

Block 4 business object structure

Sequence and field business objects

Chapter 4. ISO 7775 to ISO 15022 mapping

Production instruction meta-objects (PIMOs)

PIMO structure and syntax