ifx implementation guideworkspace.ifxforum.org/apps/group_public/download.php... · web view©...

Interactive Financial eXchange

IFX Implementation GuideBased on IFX Specification Version 2

May 2014

Interactive Financial eXchange Forum, Inc. Publicationshttp://www.ifxforum.org

Copyright © 2014, by the Interactive Financial eXchange Forum, Inc. All rights reserved.

http://www.ifxforum.org/

DisclaimerThe IFX Forum makes no warranties whatsoever with respect to the contents of this specification. Without limitation, the IFX Forum makes no warranty (i) that the information contained in the specification is accurate, error-free or describes a practically realizable product or service, or (ii) that the product or service described in the specification can be produced or provided without infringing third-party rights or violating applicable laws or regulations.

RESERVATION OF RIGHTS: The contents of this specification are protected by copyright and other intellectual property laws. The IFX Forum expressly reserves all rights in such content.

Document Change Summary

Date/Revision

Who Section(s) Changed

Revision summary

May 14, 2014 IFX SOA WG All Original Publication

© 2014, by the Interactive Financial eXchange Forum, Inc.

Table of Contents1 Introduction.....................................................................................................................................5

2 Intended Use....................................................................................................................................5

3 Common Vocabulary........................................................................................................................5

4 Web Services Concepts....................................................................................................................7

5 IFX Service Architecture / Framework..............................................................................................8

5.1 Overall Framework......................................................................................................................8

5.2 Object Framework.......................................................................................................................8

5.2.1 Object Representation.........................................................................................................8

5.2.2 Object Extension..................................................................................................................9

5.3 Message Framework....................................................................................................................9

5.4 Service Provider and Service Objects...........................................................................................9

5.4.1 Service Provider Object......................................................................................................10

5.4.2 Service Object....................................................................................................................12

5.4.3 Summary............................................................................................................................14

6 Implementation Process................................................................................................................15

6.1 Pre-Requisites............................................................................................................................15

6.2 Business Process Flow................................................................................................................15

6.3 Service Scope Definition............................................................................................................16

6.3.1 Reusability.........................................................................................................................16

6.3.2 Responsibility.....................................................................................................................16

6.3.3 Transactionality..................................................................................................................16

6.3.4 Maintainability...................................................................................................................16

6.4 Determine Applicable IFX Messages..........................................................................................17

6.5 Service Definition.......................................................................................................................17

6.5.1 Status Messages and Error Handling..................................................................................17

6.5.2 Service Versioning..............................................................................................................18

6.6 Map IFX Message Content to System of Record........................................................................19

6.6.1 Mapping Documentation...................................................................................................19

6.6.2 Extending the IFX Schema..................................................................................................20

6.6.3 Namespaces.......................................................................................................................20

6.7 Define the Service Interface......................................................................................................21


6.8 Generate XML Bindings.............................................................................................................21

6.9 Implementation & Deployment.................................................................................................21

7 Use Cases.......................................................................................................................................22

7.1 Create and Fund a New Account...............................................................................................22

7.1.1 Use Case Description.........................................................................................................22

7.1.2 Applicable IFX Objects........................................................................................................23

7.1.3 System of Record Mapping................................................................................................24

7.1.4 Service Definition...............................................................................................................26

7.2 Online Banking...........................................................................................................................27


7.2.2 Applicable IFX Objects........................................................................................................27



7.3 New Card Setup Using BIAN Service Domains...........................................................................31


7.3.2 Service Scope Definition....................................................................................................32

7.3.3 Applicable IFX Messages....................................................................................................32



8 Appendix A – IFX BMS Object Search.............................................................................................34

9 Appendix B – IFX Messages............................................................................................................37

10 Appendix C – Data Representation................................................................................................39

10.1.1 Data Types.........................................................................................................................39

10.1.2 Abstract vs. Concrete Aggregates......................................................................................39

10.1.3 Keys (xxxKeys)....................................................................................................................39

10.1.4 Reference (xxxRef).............................................................................................................40

10.1.5 Selection (xxxSel)...............................................................................................................40


1 IntroductionThe Interactive Financial eXchange (IFX) Business Message Specification is developed and maintained as a cooperative industry effort among major financial institutions, service providers, and information technology partners to achieve a single, open financial services industry standard. It provides a comprehensive message set for developing new financial industry services and software.

The Service Oriented Architecture (SOA) Working Group of the IFX Forum has developed a set of guidelines and standard specifications to demonstrate the practical use of the IFX framework and standard messages. No change is made to the Basic Message Service data, although several styles of composing messages are defined.

This Guide is the result of collaboration by many members of the IFX Forum. We believe it presents best practices that allow the use of Web Services to transport IFX messages. The goal of this work has not been to define an exhaustive specification for IFX implementations, nor to indicate a preferred implementation of any particular service. Rather, the goal has been to provide an appropriate level of information to enable using Web Services technology and the IFX framework. This implementation guide is accompanied by a Web Services Supplement which provides specific guidance on using the IFX messages in a Web Services implementation including working code examples.

The concepts in this Guide rely upon the currently published version 2.x of the IFX Business Message Specification (BMS) which is available at this URL. http://bms.ifxforum.org/rel2. In many cases, there are hyperlinks from this document to the BMS for convenient reference to details in the specification.

2 Intended UseThis document is an Implementation Guide for parties interested in building an interoperable software application for financial message processing, using the business messages of the Interactive Financial eXchange (IFX) Specification..

3 Common VocabularyThe IFX Business Management Specification (BMS) utilizes several terms that may have somewhat different meanings for users versed in particular Web Services standards and tools. The purpose of this section is to provide context to several terms to clarify concepts within the IFX Messaging Standard.

Within this document, these terms will be prefixed with IFX when referring to the term as defined in the IFX BMS in order to avoid ambiguity.

Object

IFX Objects can be somewhat simplistically viewed as organized sets of data of a particular type. As in any typical banking environment, the IFX Objects are subject to action in more than one service interaction. Further discussion of IFX Objects can be found in Appendix A – IFX BMS Object Search.


http://bms.ifxforum.org/rel2

Message

IFX Messages are defined to affect the state and content of IFX objects. The standard does not define implementation details, but IFX Messages are readily represented in XML and can easily be mapped to typical database CRUD (‘Create’, ‘Read’, ‘Update’, ‘Delete’) activities. Details of IFX Messages can be found in Appendix B – IFX Messages.

Operation

An IFX Operation is a particular type of IFX Message, composed of a sequenced collection of regular IFX Messages that are processed together, with defined transaction rules also expressed as part of the message. These messages are related, and processed utilizing the set of rules that fulfill a specific business function. The practical result of this design approach is to assemble a set of granular messages into a single message that accomplishes a particular task.

Service

Within the IFX Specification, the term Service is used to describe a collection of capabilities. These capabilities may be fine-grained operations, congruent with the IFX Message Framework, or they can be a collection of coarse-grained operations, fulfilling client business requirements internally through orchestration of fine-grained operations.

Specific services are not defined by the IFX Forum, and the IFX Specification places no restriction on scope or boundary of a service definition; it simply standardizes the representation of those services. Service Providers define Services at a level of granularity and functionality convenient to them. These may be a very broad set of capabilities or very specific functional capabilities.

Interface

In the context of IFX, an Interface is a collection of IFX Messages and Operations, synonymous with a Service. The IFX Interface is considered a design-time construct of an IFX Service, describing the capabilities it provides.

Web Service

A Web Service is a realization of a Service, according to the World Wide Web Consortium (W3C) standards. The IFX BMS does not mandate W3C Web Service standard compliance, or place any restriction on choice of service implementation.

To summarize, the IFX BMS defines a set of objects and messages. The messages and objects adhere to consistent design patterns that simplify understanding and provide an obvious framework for extensions. A set of messages represents an IFX Service. These services can then be realized using Web Service technologies and standards. The IFX Message Specification places no restriction on the organization of operations or services, nor on the manner in which these are implemented.


4 Web Services ConceptsThis document assumes basic understanding of Web Services concepts and the artifacts involved in design and development of a Web Service, and will draw correlation, when possible, to the W3C Working Group Notes for Web Services Architecture (http://www.w3.org/TR/ws-arch/).

Web Services Description Language (WSDL) – The standard for describing web services (e.g., the messages that are exchanged between provider and agent)

Service Oriented Architecture Protocol (SOAP) – The standard framework for packaging and exchanging XML messages

The Web Services Supplement, a companion publication to this guide, offers specific guidance on using the IFX messages in a Web Services implementation including working code examples. The Web Services Supplement covers these topics specific to Web Service implementations.

Starting with IFX Web Services Implementation WSDL Creation Create a Java IFX Service Using Apache CXF Module


http://www.w3.org/TR/ws-arch/

5 IFX Service Architecture / FrameworkThe IFX Framework consists of an Object Framework, outlining the structure and common elements of message content and a Message Framework, which provides the structure of IFX compliant messages consumed and produced by service implementations.

5.1 Overall FrameworkThe IFX Business Message Specification is designed to operate in stateless, multi-tiered, service-oriented environments. The framework consists of Common Object Definitions with well-defined data semantics and a Request-Response message protocol, where each message is targeted to act upon one object and each response indicates success or failure to ensure common understanding of object states after each attempted or successful message operation.

The framework is depicted below with some examples of defined IFX Objects.

Standard Request-ResponseMsgRq

MsgRs

Common Object Definition

Add Mod Del InqCan Aud Adv Sync Status

AccountParty

BillPayment

5.2 Object FrameworkAn IFX Object is a set of data that is organized according to a consistent pattern and supports a well-defined set of operations. IFX Messages cause IFX Objects to be created, modified, and destroyed. IFX Objects are constructed from basic building blocks of data Elements and data Aggregates, where elements are single pieces of information with defined data types and aggregates are groups of related elements identified using a single name for convenience.

For more specific information on data typing and object representation, see Appendix C – Data Representation

5.2.1 Object RepresentationAs depicted in the figure at right, each instance of an IFX Object is a record (xxxREC) with a unique ID, the identity of the service that created the Object (xxxSvcIDENT), a set of client-managed data properties contained in an INFO aggregate, a set of environmental (ENVR) data properties managed by the server, and a STATUS aggregate describing the Object’s current state.


xxxRec+xxxSvcIdentxxxID+xxxInfo+xxxEnvr+xxxStatus

xxxStatusxxxStatusCodeStatusDescEffDtStatusModByObjectSpecificStatusData

xxxInfodataAttributes

(All object-specific instance data)

xxxEnvrExtends BaseEnvrCreatedDtLastUpdateDtLastUpdateRqUIDLoginNamePointOfServiceData

(Other data about the environment in which the object was created)

ObjectSpecificEnvrData

xxxSvcIdentSvcProviderNameSvcName

Detailed information for these object representations can be found in the Object Framework section of the BMS at http://bms.ifxforum.org /rel2.

5.2.1.1 Object Identity and OwnershipIn the IFX framework, a core concept is that every object is assigned a unique ID within the context of a particular service. In practice, this often corresponds to a database key assigned when the Object record is created. This works perfectly well in a self-contained environment with a single system of record. However, there are situations where multiple systems are capable of creating and managing IDs for Objects. To address this condition, the SvcIdent aggregate is used as a unique qualifier for the Object ID.

Every IFX Object also includes an xxxKeys aggregate that consists of at least two elements – an optional Service Identifier and either an Object ID or a business-defined identifier (such as an IBAN for account identification).

5.2.1.1.1 SvcIdentThe Service Identifier <SvcIdent> is the combination of the SvcProviderName and the SvcName. Since the former is globally unique and the latter is unique within that provider’s environment, the combination is unique. When combined with an object ID or object key, it is possible to unambiguously identify every object in an IFX implementation across any number of organizational boundaries.

Furthermore, <SvcIdent> is available in the Message Request Header <MsgRqHdr>, so it is possible to send a message directly to the owner of the object – the creator of the object’s ID. This technique can also facilitate internal message routing through a message hub that examines the MsgRqHdr to discover the internal service provider for a particular message.

5.2.2 Object ExtensionXML, by definition, is extensible, and the IFX Specification supports extending the BMS to suit implementation needs. The Implementation Process section provides details on motivation and considerations when extending the IFX XML schema. Objects within the IFX Specification follow a consistent design pattern, facilitating object extension.

5.3 Message FrameworkThe messages comprising the IFX Specification are listed in Appendix B – IFX Messages. The specification supports implementation of a subset of messages based on the services that are going to be offered.

5.4 Service Provider and Service Objects A fundamental assumption underlying the IFX Specification is that one or more services are being offered by a Service Provider. A Service Provider may manage these services directly or may choose to partner with others to provide the service. Businesses (typically financial institutions) that adopt the IFX Specification to provide services to customers (clients) are known as Service Providers. Service Providers are identified by a URL, which is also the access point for clients to invoke the services offered. All client messages are directed to the Service Provider at the specified URL.

Specific services are not defined by the IFX Forum. Rather, Service Providers define Services at a level of granularity and functionality convenient to them. These may be very broad sets of capabilities or very specific functionality. For each Service offered, the Service Provider creates a Svc Object.


http://bms.ifxforum.org/rel2/content/DisplayTag.jsp?id=1854


http://bms.ifxforum.org/

If the Service Provider does not wish to describe detailed services, a single Svc Object can be created that simply provides identifying characteristics of the Service Provider and all of the messages to which the server responds.

The diagram below describes the relationship between clients, Service Providers, and Services in their simplest form.

Request Messages are directed to the Service Provider by the client

The Service Provider uses one or more Services to satisfy the request

The client receives a response

Service Providers may invoke services provided by a business partner (another Service Provider) to fulfill a particular capability. The client has a single point of access to invoke a service and this secondary relationship is not known to the client. The Service Provider known to the client handles all message requests and message responses on behalf of the client, routing requests to any other partner or system desired, and routing responses back to the client. The following diagram illustrates this slightly more complex model.

5.4.1 Service Provider ObjectThe Service Provider object <SvcProvider> describes the basic characteristics of the Service Provider, such as the legal name, contact information, and a list of services offered. The SvcProvider object has a unique SvcProviderID that is consistent with the object definition pattern enforced by the IFX Framework. However, the object also has a SvcProviderName that is defined as a URL, assumed to be globally unique. The SvcProviderName (URL) is the mechanism used by clients to direct messages that invoke services of the provider.

There is no limit to the number of services a Service Provider offers, but there must be at least one named service.


http://bms.ifxforum.org/rel2_3/content/DisplayIfxObject.jsp?id=92

Note: It is hypothetically possible to discover which services are offered by a Service Provider by sending a SvcProviderInqRq to the SvcProvider. However, many implementations do not support this, relying instead on other infrastructure management techniques. Similar inquiry messages could provide the processing schedules and current status of services but, again, most implementations rely on other infrastructure management techniques.

5.4.1.1 ExampleThe diagram below illustrates a sample Service Provider.

SvcProviderRec+SvcIdent<SvcProviderID>0123456789abcdeffedcba9876543210+SvcProviderInfo+SvcProviderEnvr+SvcProviderStatus

SvcProviderStatusActiveActiveServiceStatus2013-12-31CSP

SvcProviderInfocom.SampleCustomerServiceProviderCSP Bank, Inc.CSP Bank Holding Co.+ContactSampleAcctOnlySetupSampleSecondService2013-12-31

SvcProviderEnvr<CreatedDt>2013-12-31

SvcIdentcom.SampleCustomerServiceProviderSampleAcctOnlySetup

5.4.1.2 An XML Representation of the Same Service Provider

<SvcProviderRec xsi:noNamespaceSchemaLocation="SvcProviderRec.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<SvcIdent><SvcProviderName>SampleCustomerServiceProvider</SvcProviderName><SvcName>Service Name is not meaningful in this context</SvcName>

</SvcIdent><SvcProviderId>0123456789abcdeffedcba9876543210</SvcProviderId><SvcProviderInfo>

<SvcProviderName>SampleCustomerServiceProvider</SvcProviderName><LegalName>CSP Bank, Inc.</LegalName><HoldCoIdent>CSP Holding Co.</HoldCoIdent><Contact>

<Language>en</Language><PhoneNum>

<PhoneType>DayPhone</PhoneType><Phone>555-555-5555</Phone>

</PhoneNum><ContactType>CustSvc</ContactType><PreferredInd>true</PreferredInd><ContactName>Customer Service</ContactName>

</Contact><SvcRef>

<SvcKeys><SvcIdent>

<SvcProviderName>com.SampleCustomerServiceProvider</SvcProviderName><SvcName>SampleAcctOnlySetup </SvcName>

</SvcIdent>


The diagram shows the contents of a Service Provider Record for SampleCustomerServiceProvider.

This Service Provider offers two services – namely SampleAcctOnlySetup and SampleSecondService.

The XML snippet below shows some additional details.

<SvcId>0123456789abcdeffedcba9876543210</SvcId></SvcKeys>

</SvcRef><SvcStatusDt>2013-12-31</SvcStatusDt><SvcRef>

<SvcKeys><SvcIdent>

<SvcProviderName>com.SampleCustomerServiceProvider</SvcProviderName><SvcName>SampleSecondService</SvcName>

</SvcIdent><SvcId>01234567899876543210abcdeffedcba</SvcId>

</SvcKeys></SvcRef><SvcStatusDt>2013-12-31</SvcStatusDt>

</SvcProviderInfo><SvcProviderEnvr>

<CreatedDt>2013-12-31</CreatedDt></SvcProviderEnvr><SvcProviderStatus>

<SvcProviderStatusCode>Active</SvcProviderStatusCode><StatusDesc>Active Service Provider</StatusDesc><EffDt>2013-12-31</EffDt><StatusModBy>CSP</StatusModBy>

</SvcProviderStatus></SvcProviderRec>

5.4.2 Service ObjectConceptually, Service Objects <Svc> are simply a named list of messages where the name of the service is unique within the Service Provider’s environment. The Svc Object has a unique SvcId that is consistent with the object definition pattern enforced by the IFX Framework. Importantly, the object also has a SvcName, which also must be unique with the service provider’s infrastructure.

In addition to the list of messages that comprise an IFX Service, the Service object may also contain a list of IFX operations defined to support the capabilities. Other attributes include version, processing schedule, references to disclosures, and status date.

There is no limit to the number of IFX Messages (or IFX Operations) defined as part of a service, but every Service must have at least one message.


http://bms.ifxforum.org/rel2/content/DisplayIfxObject.jsp?id=93

5.4.2.1 ExampleThis guide will include several example Services. This example shows one such Service.

SvcRec+SvcIdent<SvcID>0123456789abcdeffedcba9876543210+SvcInfo+SvcEnvr+SvcStatus

SvcStatusActiveActiveServiceStatus2013-12-31CSP

SvcInfoSampleAcctOnlySetup2.3AcctAddAcctInqAcctModAcctStatusInqAcctStatusMod

SvcEnvr<CreatedDt>2013-12-31

SvcIdentcom.SampleCustomerServiceProviderSampleAcctOnlySetup

PrcSched(See XML sample)

5.4.2.2 An XML Representation of the Same Service

<SvcRec xsi:noNamespaceSchemaLocation="SvcRecChoice.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<SvcIdent><SvcProviderName>com.SampleCustomerServiceProvider</SvcProviderName><SvcName>SampleAcctOnlySetup</SvcName>

</SvcIdent><SvcId>0123456789abcdeffedcba9876543210</SvcId><SvcInfo>

<SvcName> SampleAcctOnlySetup </SvcName><Version>2.3</Version><PrcSched>

<PrcDaysOff>Saturday</PrcDaysOff><PrcDaysOff>Sunday</PrcDaysOff><CutoffTm>20:00:00.0Z</CutoffTm><PrcDtAdj>Later</PrcDtAdj><HolidayData>

<Name>New Years Day</Name><HolidayTimeframe>

<StartDt>2014-01-01</StartDt><EndDt>2014-01-01</EndDt><AllDayEvent>true</AllDayEvent>

</HolidayTimeframe></HolidayData>

</PrcSched><MsgSupt>AcctAdd</MsgSupt><MsgSupt>AcctInq</MsgSupt><MsgSupt>AcctMod</MsgSupt><MsgSupt>AcctStatusInq</MsgSupt><MsgSupt>AcctStatusMod</MsgSupt><SvcStatusDt>2013-12-31</SvcStatusDt>


The diagram shows the content a Service Record named SampleAcctOnlySetup being offered by SampleCustomerServiceProvider. The message support set (AcctAdd, AcctInq, etc.) listed in SvcInfo implies the necessary functionality to test whether an account exists (AcctInq), add an account (AcctAdd),modify the details (AcctMod) and manage the account status (AcctStatusInq, AcctStatusMod). The XML snippet shows some additional details.

</SvcInfo><SvcEnvr>

<CreatedDt>2013-12-31</CreatedDt></SvcEnvr><SvcStatus>

<SvcStatusCode>Active</SvcStatusCode><StatusDesc>Active Service Status</StatusDesc><EffDt>2013-12-31</EffDt><StatusModBy>CSP</StatusModBy>

</SvcStatus></SvcRec>

5.4.3 SummaryThe IFX Standard is based on Service Oriented Architecture.

1. A Service Provider is uniquely identifiable. IFX mandates the use of a URL as the identifier.2. Each Service is uniquely identifiable within the Service Provider's domain. This, in effect, makes

the combination of Service Provider plus Service Name globally unique – i.e., a Service Identifier, <SvcIdent>.

3. IFX Objects are "owned” or managed by the Service that creates or instantiates the object. 4. IFX Messages are directed to a Service Provider, who may in turn redirect the message(s) to

another service provider.5. Although it is typical for networks, mainframes, servers, and databases to be involved in

supporting a service offering, IFX makes no assumptions about the technical infrastructure used to provide services.


6 Implementation ProcessThis section provides an outline of the steps usually taken during an implementation. The document will provide more in-depth detail of the steps, while taking each use scenario from use case to implementation.

At a high level, implementing a Web Service using the IFX Message Specification can be broken down into the following steps:

1. Documenting the Business Process Flow2. Defining the scope and intent of service(s)3. Determining appropriate IFX Messages4. Defining IFX Service(s)5. Mapping IFX Message content to elements of System of Record (SOR)6. Generating the Supporting Schema7. Defining the Interface / WSDL8. Generating XML Bindings9. Implementation and Deployment.

The following section provides a definition of each of these steps, and experiences of participants in the working group. The subsequent sections provide walkthroughs of realizing an IFX Service based on common use cases.

6.1 Pre-RequisitesThis document assumes that existing business scenarios have been provided, or a set of software requirements has already been defined. Additionally, this document tries to make no assumptions about the technical aspects of the implementation or operational environment, and strives to stay neutral to any development process or implementation choices. The appendices provide rudimentary examples, and they should not be taken as a basis for implementation.

6.2 Business Process FlowThere are many business analysis and modeling techniques that can be used to document the boundaries and expectations of the service implementation given that description of the scope. We start by breaking the use case down into the specific steps that fulfill the use case. This process flow definition can be used to scope the services created, and identify the messages that pertain to each step.


6.3 Service Scope DefinitionDefining the business process flow provides insight as to the scope of the realized services and will help to reveal service boundaries. “Scope” is defined as the process of determining the range of service calls a given service supports. “Boundaries” defines the effect a service has on the supporting System(s) of Record (SOR), and/or the organizations that support them. How a service is scoped, and where its boundaries are set, can influence the lifecycle of the service in several key aspects.

6.3.1 Reusability Consider the operations the service will support, and how they might be reused in other services. If the operation is specialized, then there is likely no need to abstract the service into a separate interface. Services used sequentially in execution may be combined into a composite service, suited to the use case. Or, services may be defined at a fine-grained level, in cases where a service is used multiple times through the flow, or if the service can be leveraged in future use cases.

6.3.2 Responsibility What systems the service may touch can affect the implementation as well. Composite services are more likely to cross an application boundary, which adds complexity to the development process. Services that cross organizational boundaries can additionally add complexity to the requirements, as well as the management of the development lifecycle. If there are multiple applications, then it is likely multiple specialists are involved, and implementation might be best accomplished by aligning service definitions along application boundaries.

6.3.3 Transactionality Along with responsibility, the transactional boundaries should be considered. If a service interacts with multiple SORs, then controlling the transactionality is more complicated, and therefore more error prone. If using fine-grained services, or a service operation that encompasses multiple interactions with an SOR, consider how the service should react with partial successes. Consider applicable Web Service standards such as WS-Atomic or WS-Coordination.

Composite services, operating against a single SOR, trade flexibility for more manageable (and traditional) transactional support.

6.3.4 Maintainability Consider the lifecycle of the service itself. This is also influenced by boundaries, but also by the projected lifespan of the service, as multiple versions may need to be supported simultaneously. The service also may need to evolve as the underlying SOR is maintained and enhanced.


6.4 Determine Applicable IFX MessagesAt this point, flow and scope are defined, so the information exists to begin mapping the SOR to the IFX Specification. The key activity is documenting the mapping between the IFX Specification and the SOR. The service itself can be modeled as well.

The first step in identifying entities involved is to see if it has already been done. If the implementation is layering an IFX Service on an existing System of Record, a data dictionary may have already been created. From there, it is just a matter of identifying the entities involved in the use case being fulfilled.

If no data dictionary is available, then one must be created. Even if there is an existing data dictionary, it may be useful to document it separately, if the SOR is not directly under control and may be modified over the lifespan of the services. There are many methodologies to apply in this scenario, but for this exercise, Domain Driven Design, a methodology defined by Eric Evans in the book of the same name, is used. Consider the following elements of a domain model created using Domain Driven Design (DDD):

Entity Value Objects Aggregate Service Factory.

Conceptually, entities represent a thread of identity that runs through time and often across distinct representations.1 Each of these entities requires unique identification and has a lifespan within the System of Record. For these entities, use the IFX BMS to locate similar objects (see Appendix A – IFX BMS Object Search).

Next, determine the actions associated with each of the entities. The actions supported for each IFX Object are listed under the ‘Object Methods’ section of the IFX Object definition in the BMS. Additionally, review the relationships between objects. Most relationships are distinct objects within IFX, and therefore can have their own operations as well.

6.5 Service DefinitionOnce the appropriate IFX messages are determined and are organized according to the desired scope, the service itself can be defined using standard development process and artifacts. The service can also be defined using the previously discussed Service and Service Provider Objects.

As this step is akin to the detailed design of the service, there are several additional, more operational aspects to consider that were absent from the service scoping.

6.5.1 Status Messages and Error HandlingConsider how process and system errors (from the SOR) might be intercepted and handled. Proper error handling implementation helps to solidify service boundaries and improves maintainability of the service.

1 Eric Evans, Domain Driven Design (New York: Addison-Wesley Professional, 2003), 91.


Web Services should strive to obscure the underlying SOR. Status messages and errors should be translated into a form that is useful to the caller as well. To that end, every IFX Message includes a status code, status severity, and status description in its response. Therefore, at any point in the process when the status indicates an error, it is possible for the logic of the managing service to react accordingly. Because each message is intended to act on a single object, when errors occur the impact is isolated.

The IFX Status aggregate supports multiple status aggregates (<AdditionalStatus>) to facilitate status messages from composite services, which may need to contain the responses from multiple underlying message invocations, and to return SOR response codes for troubleshooting or special handling.

Common implementation approaches for status mapping (as well as error mapping) include using mapping files (such as Java’s property files), or using a separate database to capture mapping of the messages. In either case, any translation that is required should be captured in the service mapping documentation as well. Mapping documentation typically includes mapping of any SOR status codes from the SOR format/content to the IFX Status Message structure.

6.5.2 Service VersioningService versioning creates a contract between a Web Services provider and its clients. This also allows providers to improve services without forcing clients to continually change their side of the interface to maintain compatibility. Whether this is a concern or not, it is still prudent to put some versioning mechanism into the system.

When implementing Web Services via IFX, the same principles should be followed as when versioning any web service. In other words, it is a matter of supporting backward compatibility or not for the service itself. Examples of backward compatible changes are:

Addition of new messages to the WSDL Addition of new types that are not contained within existing types.

Examples of non-backward compatible changes are:

Removing an operation Renaming an operation Changing the parameters (in data type or order) of an operation Changing the structure of a complex data type.

There are many ways to implement service versioning, and thorough discussion of them is outside the scope of this document. To quickly summarize, versioning can take place at various places in the flow of execution:

WSDL Definition/Service Binding – In essence, versioning the service by treating each version as a distinct service

Request Routing – Maintaining a single instance, but implementing a strategy to route specific versions of the message to the appropriate service implementation, based on the content of the message


http://bms.ifxforum.org/rel2_3/content/DisplayTag.jsp?id=1391

Within the Service Implementation – Allowing the service implementation to identify the version used by an incoming message, and tailoring the processing to the version.

IFX supports versioning by Request Routing and Service Implementation by providing an aggregate (ClientApp) within the MsgRqHdr, to allow communication of a client version, when required by implementation.

6.6 Map IFX Message Content to System of RecordIt is important to understand SOR data model with its data types, required elements, and description. Data type compatibility also needs to be taken into consideration when performing data mapping, to ensure that proper type conversion is implemented when necessary, and to enforce compatibility with the SOR.

6.6.1 Mapping DocumentationGenerally, these mappings are kept as spreadsheets. The resulting artifact can be used as a specification between Business Analysts and the developers. The artifact typically allows for specification of translation between the two formats (required fields, type conversions etc.). An IFX Request Message must contain all relevant data required by the SOR, so the required elements of the message must be documented. First, create a data dictionary of the SOR.

Entity info Type Length Required DescriptionCustomer.Id Numbe

r12 Y Primary key

Customer.FullName Varchar 150 Y

Then, map the service inputs and outputs. Most implementations use an XPath style notation to represent the fully qualified data path.

Business Reference

XPath element reference Type Usage TableColumn

Type Length Req’d Note

Service InputParty Identifier

PartyInqRq/PartySel/PartyKeys/PartyId

NC-36 Req’d Customer.Id Num 12 Yes Primary key

…Service OutputParty Identifier

PartyInqRs/PartyRec/PartyId NC-36 Req’d Customer.Id Num 12 Yes

Party full name

PartyInqRs/PartyRec/PersonPartyInfo/PersonData/PersonName/FullName

C-96 Req’d Customer.FullName

Varchar 150 Yes

There are additional aspects to consider when mapping that are beyond the scope of this document:

Aggregation – Mapping multiple columns to one element Decomposition – Splitting a value within an element into multiple fields Validation – Validating input within elements of the request


Translation – Translating or formatting of internal codes for abstraction, presentation or language translation

Derivation – Creating new fields for input or output, based on the request or response message.

6.6.2 Extending the IFX SchemaIn the process of modeling the target SOR to IFX, it is likely that there are elements within the SOR that have no direct mapping into IFX. It would be impossible for the IFX Specification to cover every aspect of a financial SOR, so there will inevitably come a time where adjustments need to be made to the schema to support unique characteristics of the underlying system. There are several strategies for handling this, and each has their pros and cons. These changes fall into the following categories:

Alteration: Taking the existing IFX schema and altering it to suit implementation constraints Extension: Building on top of the existing schema to provide additional information.

Altering the IFX schema is straightforward from an implementation perspective, but creates a tight coupling with the selected version of IFX, and is inherently incompatible with any future versions of IFX. Additionally, it hampers interoperability with other systems using the IFX Specification. An exception to this is IFX support of enumerations. In the specification, enumerations can be either closed or open. Valid values for closed enumerations are limited to those defined in the specification, and are designed to maximize interoperability. Open enumerations can accept values defined in the specification, as well as any values not specified. The IFX Specification specifies that implementations must respond to unknown values with the most specific response code possible (for example, "<value> not supported"). Otherwise, if the client or server receives a value that it does not recognize, it must be treated as the type "other."

Extending the standard schema allows for an adoption of the base schema, as well as room for specialization to suit the constraints of the implementation. By isolating specific implementation alterations from common elements, it improves maintainability of the hierarchy. This sets the stage for interoperability. The preferred method to organize extension is via XML namespaces.

6.6.3 NamespacesManaging extensions to the IFX Schema requires consideration of the context in which the Specification is being used. The approach to creating or using a namespace may vary based on the scope of the effort. A small, vertically oriented effort may approach extending the schema differently than an enterprise-wide SOA implementation effort. Integration service providers may handle namespace management differently as well. There are two approaches to extending the schema

Using the existing IFX namespace Separating the schema changes into their own namespace.

The IFX Schema should remain isolated in its own namespace. On small-scale implementations, this is not as easy to maintain as simply using the existing IFX namespace, but it will ease the ability to upgrade between IFX versions, and clearly isolate any extensions to the schema made over the course of the implementation.


Additionally, the initial extra effort of isolating extensions into their own namespace will promote better manageability, and ease adaptation of the IFX Specification into other services. Implementing in such a manner will provide a common extension base for other business units to build from, promoting better interoperability.

It should also be considered whether the entire IFX Schema should be taken into the project, or if only the relevant messages and objects should be used. If the long-term vision is more IFX compliant services overall, then building a complete set of IFX bindings for implementation and treating it as a discrete package that can be leveraged by different teams may prove beneficial.

6.7 Define the Service Interface In this step, an interface is created that can be used to generate code stubs for implementation, and can be used by clients to create their interface to the service. See the Web Services Supplement for the technical details on transforming an XML schema into bindings for specific programming languages.

6.8 Generate XML BindingsThis step captures the process to transform the defined schema into object bindings for the implementation language to be used to realize the service. See the Web Services Supplement for the technical details on transforming an XML schema into bindings for specific programming languages.

6.9 Implementation & DeploymentAfter completing the preceding steps, all that remains is implementation and deployment of the service. These aspects of development are highly specific to each business. For reference, see the Web Services Supplement for an example of implementing a basic IFX Service implementation in the Java programming language.


7 Use CasesThe following Use Cases are presented as common scenarios where a Service Oriented Architecture may be leveraged in this domain. The goal is to present situations where the design fulfilling the scenario could be varied between an implementation using a set of fine-grained services or one delivering a set of composite services that combine fine-grained services.

7.1 Create and Fund a New Account

7.1.1 Use Case Description In this scenario, an established party (customer) wishes to create and fund a new account. This scenario is executed in a branch office. The branch office Customer Service Representative (CSR) verifies the identity of the party and confirms that he/she is a customer of the financial institution. The CSR then requests the set of products that are available to the party. The party selects a product, and the CSR provides the party with a list of funding options. The party selects one of these options. The CSR completes the transaction by submitting the selections, with which the system creates the account, associates the account with the party, and executes the transactions necessary to fund the account.

The process can be depicted as shown in Figure 1.

Figure 1 - Open and Fund Account Use Case

Customer

Branch Bank CSR

Manage Account Setup

Fund Account

<<uses>>

<<uses>>

Check Eligibility<<invokes>>

<<invokes>>

Provide Funds

Select Product

Verify Identity

<<uses>>

Account Setup

<<invokes>>

<<extends>>

<<uses>>

<<uses>>


BUSINESS PROCESS FLOW

1. CSR validates existing Customer.2. CSR presents available products.3. Customer selects product.4. CSR presents funding options.5. Customer selects funding.6. CSR adds account.7. CSR adds Party Account

Relationship.8. CSR adds Funding Transaction

7.1.2 Applicable IFX ObjectsIn this case, the following elements would be considered entities:

Customer (Financial) Product Account Transaction.

Each of these entities requires unique identification and has a lifespan within the System of Record. For these entities, the IFX BMS was used to locate similar objects (see Appendix A – IFX BMS Object Search).

Entity IFX ObjectCustomer Party(Financial) Product ProdIntRateAccount AcctTransaction Credit, Xfer

Next, determine the actions associated with each of the entities.

Customer: In this use case, the customer is an existing one, and the CSR needs to confirm identity. So the service will need to support query for customer. For the Party Object, this results in a requirement to support PartyInq.

Product: The rates of available products need to be available to the CSR, so the service should support ProdIntRateInq.

Account: The service will be required to create an account, so support for AcctAdd is required.

Transaction: The new account must be funded, so supporting credit and/or transfer operations are required. This is done through the CreditAdd or XferAdd actions.

Additionally, the relationship between the existing customer and the new account needs to be established. A relationship is a distinct object in IFX, PartyAcctRel. In order to support creating the relationship between the Customer and the Account, the service will need to support PartyAcctRelAdd.

To summarize, the following IFX Objects will be supported

PartyInq ProdIntRateInq AcctAdd PartyAcctRelAdd CreditAdd (or XferAdd)







At this point, a high-level mapping between the entities existing in the System of Record and IFX Objects has been created. From there, actions needed to support this use case have been identified. The next step in the process is to map the attributes between the System of Record and the IFX Objects.

In this use case, the messages in use are executed independently, so status messages returned will correlate directly with the message sent.

7.1.3 System of Record MappingMapping an IFX Message to the SOR data model is the process of creating logical links between IFX Message elements and distinct data model attributes. Data mapping defines rules for transforming between the source context and the target context. A typical artifact of this phase is a mapping document, produced by the collaborative effort of a business analyst and software developer. The mapping document is typically produced in the requirements analysis phase. It is used as input to the architecture and design phase, intended to capture business rules, data flow mapping, and data movement requirements.

The high-level mapping was created in the previous step. The IFX BMS defines Object Methods for each IFX Object by request message, response message, and status codes. To map the attributes between the SOR and the IFX Objects, a Schema definition (XSD) is a useful reference.

IFX request and response messages are aggregates consisting of specific object components described in section 6 of the IFX BMS (xxxID, xxxInfo, xxxRef, xxxSel, xxxKeys…), with a focus on the xxxInfo and xxxKey aggregates.

For example, XPath can be used to map XML Schema elements to the SOR data model. A high-level view may look like this, specifying just field links between IFX Message and the SOR model:

XML Schema elements SOR model entityParty CustomerPartyRec/PartyId IdPersonPartyInfo/PersonData/PersonName/FullName FullNamePersonPartyInfo/PersonData/Contact/PhoneNum/Phone PhoneNumberPersonPartyInfo/PersonData/Contact/Email/EmailAddr Email

Typical mapping exercises start by listing elements of SOR data model in a table containing entity details similar to the one below:

Entity info Type Length Required DescriptionCustomer.Id Number 12 Y Primary keyCustomer.FullName Varchar 150 YCustomer.Phone Varchar 50 N Home PhoneCustomer.Email Varchar 200 N


Entity info Type Length Required DescriptionCustomer.WorkPhone Varchar 50 N Work PhoneCustomer.Address Varchar 200 Y ResidenceCustomer.City Varchar 200 Y City of ResidenceCustomer.StateProv Varchar 32 Y State or Providence

of ResidenceCustomer.PostalCode Varchar 11 Y Postal Code of

ResidenceCustomer.CountryCode Varchar 32 Y Country of Residence

The core of the mapping document includes a map from the column to the fully qualified aggregate within IFX. Typically included are the type mapping, usage constraints, and notes related to validation or conversion between IFX and the SOR.

Business Reference



Service InputParty Identifier

PartyInqRq/PartySel/PartyKeys/PartyId

NC-36 Req’d Customer.Id Num 12 Yes Primary key

…Service OutputParty Identifier

PartyInqRs/PartyRec/PartyId NC-36 Req’d Customer.Id Num 12 Yes

Party full name

PartyInqRs/PartyRec/PersonPartyInfo/PersonData/PersonName/FullName

C-96 Req’d Customer.FullName

Varchar 150 Yes

Home phone number

PersonPartyInfo/PersonData/Contact/PhoneNum/Phone

Required Varchar Yes

Home phone number

PersonPartyInfo/PersonData/Contact/PhoneNum/PhoneType

Open Enum

Req’d Constant Enum Always set to ‘Home’

Work phone number

PersonPartyInfo/PersonData/Contact/PhoneNum/Phone

Required Varchar Yes

Work phone number

PersonPartyInfo/PersonData/Contact/PhoneNum/PhoneType

Open Enum

Req’d Constant Enum Always set to ‘Work’

Address Type

PersonPartyInfo/PersonData/Contact/PostAddr/AddrType

Open Enum

Req’d Constant Yes Primary Residence

Address Field

PersonPartyInfo/PersonData/Contact/PostAddr/Addr1

C-64 Req’d Varchar Yes

Address Field



Address Field



City PersonPartyInfo/PersonData/Contact/PostAddr/City

C-32 Req’d Enum Yes Use translation

County PersonPartyInfo/PersonData/Contact/PostAddr/CountyDistrict

C-32 Req’d Enum Yes

State PersonPartyInfo/PersonData/Contact/PostAddr/StateProv

C-32 Req’d Enum Yes


Business Reference



Postal Code PersonPartyInfo/PersonData/Contact/PostAddr/PostalCode

C-11 Req’d Yes

Country Code Type

PersonPartyInfo/PersonData/Contact/PostAddr/ ResidenceCountry/CountryCodeSource

Open Enum

Enum Default to ISO3166-Alpha-3

Country PersonPartyInfo/PersonData/Contact/PostAddr/ ResidenceCountry /CountryCodeValue

Open Enum

Req’d Enum Yes

7.1.4 Service DefinitionOne way to describe a high-level service that implements particular business capabilities is to describe the interaction of the underlying technical services necessary to realize the desired result. The UML sequence diagram below represents this use case.

Figure 2 - Open and Fund Account Message Sequence

Manage Account Setup

Party Data Management Product Selection Account Setup

PartyInqRq

PartyInqRs

ProdIntRateInqRq

ProdIntRateInqRs

CreditAddRs

AcctAddRq

AcctAddRs

PartyAcctRelAddRs

PartyAcctRelAddRq

CreditAddRq

ProdIntRateInqRs

ProdIntRateInqRq

Check Eligibility Transactions


7.2 Online Banking

7.2.1 Use Case DescriptionIn this scenario, an established party (customer) wishes to transfer funds from savings to checking account. The party enters login credentials and then views available accounts. The party selects the funds transfer option, which presents a dialog page to the party requesting funds transfer information. The party enters the information for the funds transfer and submits the request, with which the system creates the funds transfer.

The process can be depicted as shown in Figure 3.

Figure 3 - Online Funds Transfer Use Case

Customer

On-line Banking

<<invokes>>

Account Transfers

Verify Identity

<<uses>>

Account Inquiry

<<invokes>>

<<uses>>

7.2.2 Applicable IFX ObjectsIn this case, the following elements would be considered entities:

Customer Account Transaction.

Each of these entities requires unique identification and has a lifespan within the system of record. For these entities, the IFX BMS was used to locate similar objects (see Appendix A – IFX BMS Object Search).



1. System validates existing Customer.2. System present accounts related to

Customer (some balance information).3. Customer selects Funds Transfer option.4. Customer enters from account, to

account, transfer amount, transfer date.5. System adds Funds Transfer

Transaction.

Entity IFX ObjectCustomer PartyAccount AcctTransaction Credit, Xfer

Message:

PartyInqRq/Rs AcctInqRq/Rs XferAddRq/Rs

7.2.3 System of Record MappingParty information was covered in the previous scenario, so this example will focus on the account and transfer records. For simplicity, each account only has one owner.

The SOR Data Dictionary:

Entity info Type Length Required DescriptionAccount.Id Number 12 Y Account

NumberAccount.Term Varchar 150 YAccount.Type Varchar 5 N Type of

AccountAccount.Balance Varchar 200 N Current

BalanceAccount.Open Date Y Open DateAccount.Owner Number 12 Y Account

Owner

For the Transfer:

Entity info Type Length Required DescriptionTXN.ID Number 12 Y IDTXN.ACCT Number 12 Y AccountTXN.AMT Decimal 22 Y AmountTXN.DESC Varchar 200 N DescriptionTXN.DC Varchar 1 Y Debit/Credit






The Detailed Mapping:

Business Reference

XPath element reference

Type Usage TableColumn


Service InputCustomer AcctInqRq/RecSel NC-

200Req’d Account.Id Num 12 Yes Supported

Values:PartyRec[PartyId=ID]

…Service OutputAccount Identifier

AcctInqRs/AcctRec/AcctId

NC-12 Req’d Account.Id Num 12 Yes One AcctRec aggregate per response

Account Type AcctInqRs/AcctRec/AcctType/AcctTypeValue

Enum Req’d Account.Type Varchar 5 Yes

Account Balance

AcctInqRs/AcctRec/AcctBal/CurAmt/Amt

Decimal

Req’d Account.Balance Varchar Yes

Note: see Appendix C – Data Representation for a more detailed discussion of the xxxSel aggregate structure and usage.

For the Credit:

Business Reference

XPath element reference

Type Usage TableColumn


Service InputAccount Number

CreditAddRq/ToAcctRef/AcctKeys/AcctIdent/AcctIdentValue

NC-12 Req’d TXN.ACCT Num 12 Yes

Amount CreditAddRq/CreditInfo/ CompositeCurAmt/CurAmt/Amt

Decimal

Req’d TXN.AMT Decimal 22 Yes

Debit/Credit TXN.DC Varchar 1 N/A Constant ‘C’Description TXN.DESC Varchar 200 N/A Constant ‘ATM

Credit’Service OutputTransaction Id CreditAddRs/

CreditIdNC-12 Req’d TXN.ID Num 12 Yes System

GeneratedAccount Identifier

CreditAddRs/CreditRec/CreditInfo/AcctRef/AcctKeys/AcctIdent/AcctIdentValue

NC-12 Req’d TXN.ACCT Num 12 Yes

Total Credit CreditAddRs/ CreditRec/CreditInfo/ CompositeCurAmt/CurAmt/Amt

Decimal

Req’d Account.Balance Varchar Yes


7.2.4 Service DefinitionOne way to describe a high-level service that implements particular business capabilities is to describe the interaction of the underlying technical services necessary to realize the desired result. The UML sequence diagram below represents this use case.

Note: this diagram illustrates the funds transfer as an IFX Operation that consists of a CreditAdd request and DebitAdd request.

Figure 4 - Online Funds Transfer Message Sequence

On-Line Banking UI

Party Data Management Account Inquiry

PartyInqRq

PartyInqRs

CreditAddRs

AcctInqRq

AcctInqRs

TransferOperRs

TransferOperRqCreditAddRq

Check Credentials

TransactionControl

PartyInqRq

PartyInqRs

Account Transactions

DebitAddRq

DebitAddRs


7.3 New Card Setup Using BIAN Service Domains

7.3.1 Use Case DescriptionThe New Card Setup process occurs when a new prospect applies for a credit card from the bank. This use-case starts with an architectural assumption that the bank has adopted BIAN Service Domains and wishes to use IFX Objects and Messages to implement the capability.

This process flow can be depicted in a UML model as shown in Figure 5.

Figure 5 - Use Case Diagram for New Card Setup

Customer Prospect

Sales Rep

Manage Offer Process

Check Credit

Manage Documents

<<invokes>>

<<uses>>

<<uses>>

<<invokes>>

Check Eligibility

<<invokes>>

Order Card

Apply for Credit Card

Create Customer Agreement

<<invokes>>

Accept Terms

<<uses>>

Establish Accounts

<<invokes>>

Create Welcome Pack

<<extends>>

<<invokes>>

Create Card Product

Agreement

<<invokes>>

<<invokes>>



1. A new prospect applies for a credit card from the bank. The branch sales representative initiates the offer process, first checking that this is indeed a new customer.

2. Next, the details provided by the prospect are used to initiate a credit check.

3. A customer master agreement is completed, followed by a product-specific terms and conditions agreement that includes making the necessary disclosures and eligibility checks.

4. The offer is accepted and the new card facility setup is initiated. 5. The underlying customer accounts are set up and a credit card ordered.6. The prospect is captured as a new customer and a welcome pack is later

sent with the supporting documents and guidelines for the customer.

Note: This use-case is described in greater detail in a Proof of Concept Report recently published by the IFX Forum and BIAN, available on the IFX Forum website.

http://www.ifxforum.org/

7.3.2 Service Scope DefinitionThe BIAN Service Domains define capabilities with implied boundaries. Each domain’s service operations define available Interfaces, or services, available to the "outside world." The BIAN Standard does not define which service domains may call upon the services of other service domains, nor does it prescribe how such collaborations are to be implemented.

The work necessary to realize this use case is: Identify participating BIAN Service Domains Identify the participating IFX Objects Map the appropriate IFX Messages to the interactions between service domains.

7.3.3 Applicable IFX MessagesThe table below resulted from the analysis and mapping described in the previous section.

BIAN Service Domain Action IFX Message(s) IFX Object(s)Party Data Management

Identify Prospect PartyAddPartyInq

Party

Offer Management Offer Product OfferAdd OfferCustomer Agreement Execute Customer

AgreementPartyMod Party

Document Services Record Customer Agreement

PartyMod Party

Sales Product Agreement

Execute Product Agreement

PartyCardRelAdd PartyCardRel

Document Services Record Product Agreement PartyMod PartyCustomer Credit Rating Qualify Customer AcctAdd

AcctModAcct

Position Keeping Setup card transaction tracking

AcctAddPartyAcctRelAddCardAcctRelAdd

AcctPartyAcctRelCardAcctRel

Card Facility Card Order CardOrdAdd CardOrdToken Inventory Create Card CardAdd CardCorrespondence Send Welcome Pack PartyMod Party


7.3.4 Service DefinitionOne way to describe a high-level service that implements particular business capabilities is to describe the interaction of the underlying technical services necessary to realize the desired result. The UML sequence diagram below represents this use case. Message names ending in Rq and Rs are IFX request and response messages. The other messages are outside of the scope of the IFX Business Message Specification and would require extensions to the IFX Standard or external interfaces with other applications and services.

Offer Management

Party Data Management

Customer Credit Rating

Customer Agreement

Sales Product Agreement Card Facility Position Keeping Token Inventory Correspondence Document

Services

(1)PartyInqRq

PartyInqRs

(2)RequestCreditRating

CreditRating

(3)PartyAddRq

(3Rs)PartyAddRs

(4)OfferAddRq

OfferAddRs

(5)CardAddRq

(5Rs)CardAddRs

(6)AcctAddRq

AcctAddRs

(7)PartyAcctRelAddRq

(11)PartyCardRelAddRq

PartyCardRelAddRs

PartyAcctRelAddRs

(6a)AcctAddRq

(9)CardAcctRelRq

(10)CardOrdAddRq

CardOrdAddRs

(12)CreateWelcomePackage

(13)PartyModRq

PartyModRs

(14)PartyModRq

PartyModRs

(3a)PartyAddRq

(3b)CaptureCustomerAgreementPartyAddRs

(4a)CaptureCardAgreement

(8)CardAddRq

7.3.5 System of Record MappingThe exercise of mapping data to a system of record has been adequately described in the previous use-cases.


8 Appendix A – IFX BMS Object SearchThis appendix will help the reader locate a BMS Object that may be abbreviated or just have a different, but synonymous, name for the topic being researched. The online BMS is a good tool for doing research but, if the topic has been abbreviated in the BMS, the topic may be difficult to locate. If the reader is a member of the IFX Forum, a pdf file containing all of the BMS documentation is available for download from the Architecture area of the members-only website. The pdf can be used to search for a keyword that will point to an object of the BMS. This appendix is valuable if the pdf is not available. To use this appendix effectively, search using a keyword such as Mortgage, Payment, Statement, etc.

BMS Object Name KeywordsAcct Deposit Account, Loan Account, Certificate of Deposit, CD, Time Deposit, Credit

Account, Rewards Account, Mortgage Account, Secured Loan Account, Unsecured Loan Account.

AcctAcctRel Sweep, Interest Distribution, Overdraft, Notional Pooling.AcctHold Account Hold, Permanent Hold, Check Hold, Court Order Hold, Restriction, ACH

Hold, Authorization Hold, Collateral Hold, Secured Account Hold.AcctPayOff Loan PayOff, Payoff Request, PayOff EstimateAcctStmt Account Statement, Financial Statement, Bank Statement, Interim StatementAcctTrn Transaction History, Transaction Search, Account TransactionAcctTrnImg Check Image, Deposit Slip ImageAlert Notification, SMS Text,Ath Authorization, Transaction Authorization, Credit AuthorizationBill Account Statement, Invoice, Notification, Billing StatementBiller CreditorCard ATM Card, Debit Card, Credit Card, Prepaid Card, Pin Reset, Temporary PINCardAcctRel Card Account Relationship, Credit Card Account, Card to Account RelationshipCardOrder New Card Order, Pin OrderCardUpdate Issuer Script Command, Prescript, Pre-ScriptChkAccept Check Acceptance, Check Authorization, Check Verification, Funds VerificationChkIssue Check Issue, Positive PayChkOrd Check Order, Order ChecksChkSum CheckSumCompRemitStmt Comprehensible Remittance Statement, LockboxCredit Credit Transaction, Deposit, Cash Deposit, Check Deposit, Merchandise Return,

Check Payment, Envelope DepositCustPayee Customer Payee, Add Biller, Add BillDebit Debit Transaction, Withdrawal, Fee, Purchase, Purchase Cash Back, Credit Card

Advance, ACH VerificationDepBkOrd Deposit Book OrderDev DeviceDisc Disclosure, Agreement, Terms And Conditions


BMS Object Name KeywordsDispute Dispute, Credit Card Dispute, Transaction DisputeForExDeal Foreign Exchange Deal, FXForExQuote Foreign Exchange Quote, FXForExRateSheet Foreign Exchange Rate Sheet, Rate Inquiry, FXICCUpdate Issuer Script Command, Prescript, Pre-ScriptInventory Cards, Order Volume, Reorder Level, Seasonal Order, Stamps, Check Stock, Money

Orders, EnvelopesMagCardUpdate Issuer Script Command, Prescript, Pre-ScriptMediaAcct Media Account, Teller Drawer, ATM Container, Safe, Recycler, Cassette, VaultMediaAcctTrn Media Account Transaction, Buy, Sell, Dispense, Replenish, Set BalanceNote Comments, Special Instructions, RemarksOffer Opportunity, Campaign, Products, ServicesParty Customer, Consumer, Prospect, User, Attorney, Ownership, Responsibility,

Signatory, Organization, Retail, Trustee, Guarantor, Guardian, Executor, Administrator, Borrower, Co-Borrower

PartyAcctRel Party Account Relationship, Owner, Individual, Joint Tenant, POD, Payable on Death, Power Of Attorney, POA, Trustee, Guarantor, Guardian, Executor, Administrator, Signatory, Borrower, Co-Borrower

PartyCardRel Party Card Relationship, Primary, SecondaryPartyPartyRel Party Party Relationship, Householding, Customer GroupingPartySvcAcctRel Party Service Account Relationship, Billpay, Account LinkPartySvcRel Party Service Relationship, Service LinkPassbk PassbookPassbkItem Passbook, Transaction, Printed ItemPmt Payment, Credit, ACH, SWIFT, CHAPS, CHIPS, Book Transfer, Debit Network, ePay,

Federal Reserve Network, RemittancePmtBatch Payment Batch, ISO20022, PAIN, Direct Debit, Payment Cancellation, Payment

Reversal, Credit TransferPmtBatchStat Payment Batch Status, ISO20022 Payment Status ReportPmtEncl Payment Enclosed Transaction, Envelope Deposit, Cash Deposit, Check DepositProdIntRate Product Interest Rate, APY, Rate Tier, Accrual Method, Compound, Prime, LIBOR,

APRPurchItem Purchase Item, PrepaidRecurChkOrd Recurring Check Order, Recurring Model, Repeating, Instances, see ChkOrdRecurPmt Recurring Payment, Recurring Model, Repeating, Instances, see PmtRecurXfer Recurring Transfer, Recurring Model, Repeating, Instances, see XferRemit Remittance, Payment, Bill, Invoice, Payable, see PmtSecObj Security Object, PIN, Key, Encryption, Password, CertificateStdPayee Standard Payee, Biller, Creditor, Payable ToStopChk Stop Check, Stop PaymentSvc Service


BMS Object Name KeywordsSvcProvider Service Provider, Host, Application, OwnerTerminalObj Terminal Object, ATM, POS, DeviceTerminalSPObj Terminal Service Provider Object, Host, Application, OwnerTrn Transaction, Credit, DebitXfer Transfer, Credit, Debit


9 Appendix B – IFX Messages IFX Message names adhere to a consistent pattern – ObjectActionDirection – where Object is the name of the IFX Object that will be acted on, Action is one of the “verbs” (or methods) shown below and Direction is either Rq (Request) or Rs (Response). It is not necessary to implement all messages for an object, and there are many instances where the standard implements only a small subset of the message set for an object.

Two special cases are noteworthy: Authorization and Status. The IFX Specification facilitates inquiry and modification of the Authorization and Status aggregates associated with a specific object by implementing a Record construct that can be targeted by a message. For example, AcctStatusInqRq will ask for the current status record associated with an Account, which will be returned in the AcctStatusInqRs message.

Name Message DescriptionAdd Add The xxxAdd Messages support creating a new instance of the specified

xxx object.Advise Advise The xxx Advise Message is used to notify interested parties that an xxx

object was created or modified. The Advise Message set does not imply any action to take (such as add, or update). It is up to the receiving entity to decide what action to take based on the contents of the Advise Message.

Aud Audit The xxx Audit Message supports the ability for the client to trace the message history for all changes affecting the specified xxx object.

AuthInq Authorization Inquiry

The xxx Authorization Inquiry Message is used to request an inquiry of authorization information for the specified xxx object.

AuthMod Authorization Modification

The xxx Authorization Modify Message is used to change authorization information for the specified xxx object.

Can Cancel The xxx Cancel Message, often used on transactional objects, is used by a client to cancel a previously added instance of xxx object, or to cancel an existing scheduled object.

Del Delete The xxx Delete Message removes an existing object. In certain instances, deleting an object will require additional Cancel and/or Delete Message(s) to related objects within the object hierarchy. This process is called Cascading Deletes.

Inq Inquiry The Inquiry Message is used to search for and/or gain information about the current state of existing xxx objects. Inquiry Messages limit the response set to records matching the Select fields included in the request. Several <Status> codes are available to help the client understand the results of an Inquiry Message.


Name Message DescriptionMod Modify The xxx Modify Message is used to modify the information previously

supplied in an xxx Add Request. The Modify Message must act on exactly one identifiable object, and acts as a complete replacement of the specified object, unless the Modify Message includes aggregates that indicate the specific elements updated (DelElements, UpdElements, NewElements).

Rev Reversal The xxx Reversal Message is used to reverse the effect of a message. This must either refer to an existing instance of an object xxx (such as reversing an existing debit using <DebitRevRq>) or a message that is not based on any object (such as reversing a balance inquiry using <BalRevRq>). In general, the Reversal Message provides the capability to "undo" a previous request. For example, performing a reversal on a Modify Request would place that object back to the state it was in prior to the modification. Note that a request to reverse a message is not guaranteed to be successful.

StatusInq Status Inquiry The xxx Status Inquiry Message allows a user to inquire on the status of xxx object.

StatusMod Status Modification

The xxx Status Modify Message allows a user to change the status of xxx object.

Sync Sync The xxx Sync Messages provide the ability for a client device to be brought up to date on changes made to the specified xxx object.


10 Appendix C – Data Representation

10.1.1 Data TypesIFX uses common primitive data type representation, as well as definition for types commonly used within IFX Objects (Date, Time, Phone Numbers etc.) Please see the BMS section 3.3 for detailed description of the supported data types.

10.1.2 Abstract vs. Concrete AggregatesAbstract Aggregates were introduced for ease of modelling and building the BMS. Abstract Aggregates contain characteristics common to groups of data elements. An Abstract Aggregate will never appear in a message; only its “concrete” extensions will actually appear in transmitted messages. For example, <SecToken > is an Abstract Aggregate that is extended by the SecTokenLogin, SecTokenSecretAnswer, SecTokenMagCard, and other aggregates used for the purpose of collecting, modifying, or retrieving attributes associated with security (authentication/authorization). The Abstract Aggregate replaced the ‘choice’ between aggregates; however, using the ‘choice’ xml structure is still a viable option when downloading the BMS Schema. Abstract Aggregates allow easier customization of the BMS when an implementation requires another ‘choice;’ a new custom aggregate can be established that extends the Standard Abstract Aggregate.

10.1.2.1 Aggregate ExtensionNon-abstract Aggregates can also be extended to create a more robust model. Extensions of an Object retain the structure of their base object, but allow for additional aggregates, or naming that is more specific to the data being represented. For example, the CurAmt Aggregate is extended 40+ times within the BMS Standard alone. Extensions such as LimitAmt, LOCLimit, LowCurAmt, MaxCurAmt and MinAmtDue were created to support aggregates with specific usage scenarios.

10.1.3 Keys (xxxKeys)The Keys Aggregate contains a set of attributes that, when used together, form a unique identifier of the object. In other words, the Keys of the object can be used to locate a unique/single occurrence of an object in a datastore. The Keys Aggregate may only contain a single attribute, as long as the single attribute's value can uniquely identify one instance/occurrence of an object from all other occurrences of the object. The name of this single attribute is xxxId* where xxx is the object name. The Keys Aggregate must always contain the Id of the object. In addition to the Id, the Keys Aggregate may contain other attributes for the purpose of locating a unique occurrence of the object. These other attributes are referred to as Business (or natural) Keys. For example, a Party may have a unique PartyId or a unique Login Name. The Login Name is a Business Key; i.e., it is an attribute of the object that serves a business purpose, in this case, logging in from an Internet site.

An alternate identifier may require multiple attributes. For example, a Stop Payment record may be unique based on Check Number and Account Number. In this example the Keys Aggregate for the StopChk object (IFX object for Stop Payment is StopChk) would contain a choice between the StopChkId and a sequence (grouping) of the two attributes: Account Number (AcctId) and Check Number (ChkNum).




http://bms.ifxforum.org/rel2_3/content/DisplayDoctext.jsp?doctextid=7764&lineage=003-003

The primary requirement for a Keys Aggregate is that it selects one target object or fails. A Keys value that can match multiple target objects on a server is invalid, and either must be resolved by the server using a business priority scheme or the request is failed by the server.

The purpose of the Keys Aggregate is to support inquiry or update when the Business Keys are known but the arbitrary unique identifier (xxxId) is not known.

10.1.4 Reference (xxxRef)A Reference Segment is an indirect reference to another object. On the wire, it will usually contain the ID or Keys of another IFX Object, but it supports other options. The supported reference options are the target object's ID and any defined business or natural keys for the target object, a serialized representation of the target object (xxxInfo), or the object data or properties (xxxRec).

The xxxRef Aggregate was introduced to support a standard way of referencing another object, as opposed to picking and choosing specific object attributes to include. For example, the AcctTrnInfo contains AcctRef, and this allows each implementation to include acct attributes in the AcctTrn message. One implementation may just want the AcctId and AcctBal (where BalTypeValue = ‘Ledger’), while another implementation may also want the account’s BranchIdent and AcctType.

10.1.5 Selection (xxxSel)A Selection Aggregate is an indirect reference to a collection of objects. On the wire, it will usually contain object-supported selection criteria for the target object. The Selection Aggregate is not meant for ad hoc reporting, but rather inquiries to complete specific financial institution business objectives (for example, has a check paid? what accounts does a customer have?, what inventory is low?).

The primary requirement for a Selection is that it selects one or more target objects (selecting zero is not an error but results in a warning – Status 1120). The Elements/Aggregates within the xxxSel make up the search criteria of an object, and are represented using the IfxPath Type. The IfxPath Type is similar to an XPath selection in XML. For example, consider a selection of transaction records that are cash withdrawals or credit card advances in amounts greater than or equal to $100.00:

< xxxInqRq > ... < RecSelect > (/DebitRec/DebitInfo[DebitType=CashWithdrawal] | /DebitRec/DebitInfo[DebitType=CreditCardAdvance]) & /DebitRec/DebitInfo/CompositeCurAmt[CompositeCurAmtType=Debit & CurAmt > =100.00]/CurAmt < /RecSelect >< /xxxInqRq >

The records in the result must match all input values (unless the host does not support a specified data element); the elements/aggregates are 'AND'ed together. The xxxSel Aggregate can be repeated. When this happens, the set of search criteria is 'OR'ed such that the result set must match the search criteria of one of the occurrences of the xxxSel Aggregate. See 6.11 — Record Selection (RecSelect) in the BMS for a more detailed discussion of logical operations within the Selection Aggregate.

* * *


http://bms.ifxforum.org/rel2/content/DisplayDoctext.jsp?doctextid=7857&lineage=006-011