Standards Standards Developer Kit 1.0 User Guide This document describes the components of the SWIFT Standards Developer Kit, and illustrates how they can be used to solve common standards implementation problems. 25 September 2009 Standards Developer Kit 1.0 Table of Contents Preface ............................................................................................................................................. 3 1 MT Resources ........................................................................................................................ 4 1.1 MT/XML Schema Library ........................................................................................................4 2 MX Resources ...................................................................................................................... 12 2.1 MX Repository.......................................................................................................................12 2.2 MX Enriched Schemas .........................................................................................................20 2.3 MX Spreadsheets..................................................................................................................22 A.1 Sample Implementation of ISchemaDocResolver (Java) ................................................. 24 A.2 MT Message Generation Using Apache XML Beans (fragment) ...................................... 25 A.3 Generating an MT Message Using a Commodity Mapping Tool ...................................... 25 B.1 Message Definition Query (XQuery) ................................................................................... 26 B.2 Extract Code Data Types and Details of Code Values for Messages in a Given Business Area ....................................................................................................................................... 27 C.1 Acknowledgements ............................................................................................................. 28 C.2 References and Resources ................................................................................................. 28 Legal Notices ................................................................................................................................. 29 2 User Guide Preface Preface Purpose of this document The SWIFT Standards Developer Kit (SDK) is a coherent set of machine consumable standards definitions aimed at supporting many phases of standards implementation, from analysis through to design, build, document and test. The purpose of this document is to describe the components of the kit, and illustrate how they can be used to solve common standards implementation problems. It is important to understand the philosophy that underpins the SDK. The SDK is not an application or a development tool in its own right; it is a collection of resources that can be used in conjunction with other tools – tools that you may already have, or that can be easily obtained on the market – to build standards implementations. To ensure that they can be used with the widest possible range of tools, SDK resources are delivered in technical formats that adhere to mainstream, open industry standards, such as XML, XML Schema, and Comma Separated Value (CSV). Some working samples that use easily obtainable tools are included with the SDK to illustrate the use of the resources, but these should be treated purely as examples; no endorsement of any particular tool, programming language or approach is implied, nor should the omission of a technology be taken as a sign of its unsuitability for use with the SDK. Intended audience The SDK includes components aimed at helping implementers of MT (traditional FIN messages) and MX (ISO 20022 XML) messages. Some components are suitable for technical IT developers; others are also accessible to less technical users, such as business analysts. The technical profile of the expected user of the component is indicated in the section of this document that describes it. This document assumes some knowledge of SWIFT and ISO standards, and SWIFT messaging services. More information can be found in the SWIFT User Handbook Online and at www.iso20022.org. Document conventions This document uses the following typographical conventions: Bold Names of files, parameters, API calls, user logon, and logon groups References to a directory or a menu GUI elements and command names Italics Important information and document names Courier User input, directory paths, parameter values, place holders, and system output examples Significant changes This is the first publication of this document. 25 September 2009 3 Standards Developer Kit 1.0 1 MT Resources 1.1 MT/XML Schema Library Naming Audience/Skills: Technical IT / XML The MT/XML Schema Library consists of around 250 XML schemas, one for each MT message supported by the SWIFT FIN service, plus several extras for Message User Group (MUG) – specific message variants. There is also one schema which includes definitions for the header and trailer blocks that are common to all MT messages. MT message definitions are maintained annually, but only a subset of messages are changed in any given Standards Release (SR). New schemas are only issued for messages that have changed in a given SR. The message type and standards release to which a schema relates is given in its namespace declaration. Therefore, each MT schema is updated to reflect the proper namespace relative to that Standards Release. For example, the following declaration is taken from the 2008 MT103 schema: Schema filenames are in the form: fin.nnn.yyyy.xsd where nnn is the message type and yyyy is the standards release, for example: fin.103.2008.xsd. For MUG-specific variants a qualifier is added to the name. For example the MT103+, which is a subset of the MT103 intended to enable Straight Through Processing (STP), has file name: fin.103.STP.2008.xsd, and the namespace declaration is similarly modified: 4 User Guide MT Rresources Structure A SWIFT MT user-to-user message in its native format conforms to the following structure: The message is divided into 5 blocks, labelled 1 to 5. Each block is declared: {n: <block content>} where, n is the block number. Blocks 1 and 2 are mandatory headers, which include the sender and destination address of the message, and certain other details relevant to all messages; block 3 is an optional user header; block 4 (the text block) contains the business content of the message and block 5 is a trailer that contains technical details related to communications. The message-type specific XML schemas in the MT/XML Schema Library define just the content of block 4. Definitions for the common elements that are included in the header and trailer blocks are found in one schema, file name mtmsg.2008.xsd, and namespace: This schema defines block 4 using the XML Schema xs:any construct. A full message instance should declare the namespace for the header/trailer and block 4 business content. For example: 25 September 2009 5 Standards Developer Kit 1.0 Identifiers, delimiters and separators A feature of the schemas in the MT/XML schema library is that definitions of the ‘scaffolding’ required by the MT syntax, such as block identifiers and subfield separators, are provided in schema annotations, to be applied automatically by formatting and parsing software. The user of the schema is not required to populate these syntax-specific elements. For example, the ‘ {1:’ block identifier that begins the declaration of the Basic Header does not need to be specified by the user of the schema, nor does the closing ‘ }’; the user is only required to specify the variable content of the header elements. Header and trailer blocks The content of the SWIFT header and trailer blocks is defined in the SWIFT User Handbook > FIN Operations Guide > Part D. Each header element is modelled by an XML element in the mtmsg.yyyy.xsd schema. For example, the basic header definition (see Basic header definition) is modelled in the schema (see Schema). Basic header definition Block identifier Must be the first character within the block. The block identifier for the Basic Header is 1. Application Identifier Must designate the application that has established the association used to convey the message. Service Identifier 6 Identifies the type of message. The identifier used must belong to the set of identifiers defined for the application. User Guide MT Rresources Logical Terminal address The system must know the logical terminal address, and the logical terminal address must be active. Session Number When present, must be numeric. Must also equal the current application session number of the application entity that receives the input message. Sequence Number • • • • For all General Purpose Application messages or General Purpose Application service messages that have Service Identifiers 01, 03, or 06, the sequence number must be equal to the next expected number. For all General Purpose Application messages that have Service Identifiers 21, 23, 26, or 43, the sequence number must be equal to that of the acknowledged service message. For all FIN messages or FIN service messages that have Service Identifiers 01 or 05, the sequence number must be equal to the next expected number. For all FIN messages that have Service Identifiers 21 or 25, the sequence number must be equal to that of the acknowledged service message. Schema: Note 25 September 2009 No element is defined for Block Identifier, which is populated automatically, as explained in the previous section. 7 Standards Developer Kit 1.0 Block 4 The business content of MT messages – block 4 – is defined in the SWIFT User Handbook in terms of field tags, names, format options and syntax. See the following example Tag 20 MT 103 Single Customer Credit Transfer Field Name Content/Options Sender's Reference 16x 13C Time Indication /8c/4!n1!x4!n 2 23B Bank Operation Code 4!c 3 23E Instruction Code 4!c[/30x] 4 26T 32A Transaction Type Code Value Date/Currency/Interbank Settled Amount Currency/Instructed Amount Exchange Rate Ordering Customer 3!c 6!n3!a15d 5 6 3!a15d 7 12d A, F, or K 8 9 Status M ‐‐‐‐‐> O ‐‐‐‐‐| M ‐‐‐‐‐> O ‐‐‐‐‐| O M O 33B O M Etc… 36 50a No. 1 Status indicates whether a field is Mandatory (M), or optional (O). Tag is a 2 or 3 character identifier that appears in the MT native syntax to identify the data that follows. Content identifies the syntax of the field data using a syntax notation similar to a regular expression. In some instances a data item can be represented in one of several different ways. In these cases the tag is shown with a lower-case ‘a’, and Options indicates the letters that can replace the ‘a’ in the message instance. For each letter/option, a different Content (syntax) is specified in the more detailed notes referred to in the No. column. The ‘–---|’ and ‘----->’ notation indicates repetition of fields or sequences. 8 User Guide MT Rresources In schema terms, the same message elements are represented: Note: • Field tags are indicated in element names (for example, Tag 20 is represented by element F20). • All fields are modelled as a choice of format options, even if there is a choice of only one (see F20a, F20, for example). • Fields are defined to the subfield level, for example field 13C, which contains 4 subfields: Code, Time Indication, Sign and Time Offset. • In the UHB, field 13C’s syntax is defined /8c/4!n1!x4!n. Schema users need only populate the business content of this field, as set out in 13C’s schema definition. The ‘/’ characters used to delimit Code are not required: they are included automatically by the formatting software, according to instructions given in annotations of the type definition: 25 September 2009 9 Standards Developer Kit 1.0 • Schema minOccurs and maxOccurs indicators are used to distinguish between optional and mandatory fields, and to indicate repeated fields or sequences. For example, the repetition of field 13C is reflected in the 0..∞ (unbounded) multiplicity of element F13a. • Restrictions are used to provide detailed field level validation, for example, the following definition is used to ensure that a BIC or BEI code is correctly formed: ISO 15022 generic fields ISO 15022 generic field definitions extend the field tag identifier with 4 character qualifiers, which refine the definition of the field. For example, in an MT502 sequence B1, the definition of field 90a must be extended by one of three specified qualifiers (DEAL, STOP, LIMI), to create an identifier for the data that follows. The full identifier includes the field format option (the letter after the tag number) and the qualifier, for example ’:90B::DEAL’. In schemas, the order of field format option and allowed qualifiers is reversed, in order to keep the semantic components of the definition (what the field means) separate from the format of the data representation: MT to XML conversion reference software Audience/Skills: Technical IT / XML / Java The MT/XML Schema Library is supplied with working Java software that illustrates how to convert from an MT in its native format to an XML instance and from an XML instance back to native MT. 10 User Guide MT Rresources The software is supplied as commented source code, and includes comprehensive Javadoc documentation. The software is able to convert complete MT messages, including all 5 blocks, or just block 4. When converting a complete MT message, the software first uses the mtmsg.yyyy.xsd schema to parse the headers, including block 2, which includes the 3 digit MT message type. It uses this message type identifier to determine the namespace of the schema required to parse block 4. The task of locating the schema document to use given the namespace is delegated to a class which must be provided by the user. This class must implement the ISchemaDocResolver interface. A sample implementation, which obtains schemas from the local file system, is provided in Appendix A1. For detailed information about the Conversion Reference Software, programmers should consult the Javadoc included in the package. Uses for the MT/XML Schema Library Audience/Skills: Technical IT / XML / Java The MT/XML Schema Library allows XML technology to be used to process MT messages, effectively MT-enabling users’ existing technical platforms, generic middleware and XML tools. In Java, JAXP can be used to process message instances. Schema validation can be used to verify that messages conform structurally to the standard. Because schemas include detailed field level validation in the form of facets, schema validation also catches many common field format errors. XML binding technology such as JAXB and Apache XML Beans can be used to generate Java classes based on schemas. Messages can then be populated and processed as Java objects. The code fragment in Appendix A2 shows Java logic being used to populate an instance of an MT515 class which was generated from a schema using XML Beans. A wide variety of commercial and open source XML tools are available, which can be used in conjunction with the MT/XML Schema Library to build MT implementations. Appendix A3 illustrates the use of one such tool to create an MT101 payment initiation message from payment details captured in an Excel spreadsheet. A similar approach can be used to create outgoing messages from other data sources, such as proprietary XML or database tables. Equally, such tools can be used to automate the processing of incoming MT messages, for example to create a comma-separated value (CSV) file suitable for processing in a back-office system from a received MT. 25 September 2009 11 Standards Developer Kit 1.0 2 MX Resources 2.1 MX Repository Introduction Audience/Skills: Technical / IT / Architecture / XPath / XQuery ISO 20022 message definitions and documentation are derived from a rich conceptual and logical model which is maintained in a UML repository. The repository has great potential value for implementers: it can be used to generate custom documentation and a range of other artefacts from data models to GUI definitions. The MX Repository is an extract of the UML repository in the form of an XML file which presents the content in a form meaningful to those familiar with ISO 20022, and accessible to the wide range of XML tools and APIs available in today’s technical platforms. Definitions in the repository include all the structural information that can be found in MX schemas, and the semantic information that is normally found in the MX documentation. Background: ISO 20022 ISO 20022 recognises that defining the meaning of the information conveyed in messages is critical to enabling interoperability between often disparate communities of users. The standard requires definitions to be captured at two levels– the conceptual (or business) level, and the logical (or message) level. A third (technical) level is required for the technical realisation of messages defined at the logical level, but the processes of transforming a logical definition into its technical equivalent – such as an XML schema – is purely mechanical. Definitions at the conceptual level are of the concepts and relationships that are found in the business area under consideration, for example: Payment Transaction, Settlement Instruction, Financial Institution, Individual, Cash Account, Account Owner, Account Servicer. Each concept definition includes text in English that describes the item in business terms. Definitions at the logical level are restricted to the information that needs to be exchanged in messages in order to process a transaction, but they refer to definitions in the conceptual layer, from which they gain their meaning. The ISO 20022 repository includes definitions from both layers, and the links between logical and conceptual that allow the meaning of a logical message definition to be understood. The reusable elements in the logical and physical layers are maintained in a data dictionary. Elements in the dictionary include Business Components (conceptual definitions), Message Components (logical definitions) and Data Types (shared by both levels). Message definitions, which are not reusable, are maintained outside the dictionary, but refer to the dictionary for definitions of message components which in turn refer to data types. More detailed information about ISO 20022 can be found at www.iso20022.org. The full documentation set can be purchased from www.iso.org (search for ISO 20022). The MX Repository The MX Repository includes Message Definitions and the Data Dictionary in a single XML instance described by a schema, as shown below. 12 User Guide MX Rresources The SSFD (SWIFT Standards Financial Dictionary) element contains the Data Dictionary. The Message element contains Message Definitions. Data types Data type definitions are shared by the logical and conceptual layers of the ISO 20022 repository, and include basic date, currency-amount and text types, and code lists. Data type definitions include the following information: Data Type ID Technical identifier Name ISO 20022 name (e.g. Max35Text, ISODateTime, MarketType1Code) EnhancedDefinition The ISO 20022 description of the Data Type AdministrativeData Details of ISO 20022 registration status Synonym Equivalent term in the vocabulary of another syntax (e.g. ISO 15022), DateTime, Rate Representation One of: Code (for an enumeration), Identifier (for an externally defined code like IBAN), Text, DateTime, Rate, Indicator (a boolean), Amount (of money), Quantity (of non‐monetary units) or User Defined. XMLType The XML type used to represent the value 25 September 2009 13 Standards Developer Kit 1.0 Code Code representation only: enumeration of codes names, definitions and message values Property Several uses. For Identifiers, the identification scheme; for Indicators, the meaning implied by the indicator being true or false. XMLFacet The XML facets to be used to constrain the value of the data type when it appears in XML schema representation, for example, minLength, maxLength, Pattern (regular expression). Rule Reference to a rule that may further constrain the content. XMLAttribute XML attribute used to qualify the value, for example Currency (used to qualify Amounts) Simple XPath statements can be used to extract Data Type information. For example: //DataType[Name='TaxRecordPeriod1Code']/Code Exploring the Logical Layer The diagram illustrates the relationship between XML definitions in the logical (message) layer: • A Message Definition is defined as a series of Message Building Blocks. • Each message building block is typed by a Message Component (or Choice Component). • Each message component is composed of a series (or choice, if it’s a choice component) of Message Elements. • Each message element is typed by a message component or a Data Type. • Message components reference other message components recursively, until finally each message element resolves to a data type. A specific message definition can be traced by following the references between message elements, message components and data types, as shown below: 14 User Guide MX Rresources References between definitions are defined in the repository using TypeIDRef and ID attributes, as illustrated below: XPath can be used to navigate references. The example below shows the Message Building Blocks defined for SubscriptionOrderConfirmationCancellationInstructionV01: 25 September 2009 15 Standards Developer Kit 1.0 The TypeIDRef attribute can be used to locate the definition of the message component to which the Message Identification message element refers: //MessageComponent[@ID='_45FA4A81017741F7C55600AD'] Message building blocks are always typed by message components (which may be standard or ‘choice’ components). Message elements may be typed by either message components, or by data types. The TypeOfType element in a message element definition indicates what sort of dictionary item the element refers to: it contains one of the following constants: MESSAGE_COMPONENT, CHOICE_COMPONENT or DATATYPE. Where a data type is indicated, its definition can be found in the DataType element of the dictionary, for example: //DataType[@ID='_45FA4A8101773B36F6D20334'] From here, it is easy to find the Message Components referred to by the Message Elements in a containing Message Component: //MessageComponent[@ID=//MessageComponent[Name='<ContainingComponent>']/ Messa geElement[TypeOfType != 'DATATYPE']/@TypeIDRef] Simple recursive logic can be used to traverse a complete message definition. See Appendix B for a sample XQuery that produces an HTML report of a message definition. Content of Logical Layer Definitions Message Message Building Block 16 ID Technical identifier Name ISO 20022 name (e.g. PaymentReturnV01) EnhancedDefinition The ISO 20022 description of the message AdministrativeData Details of ISO 20022 registration status MessageID The ISO 20022 ID (e.g. pacs.004.001.01) Rule Any usage rules that apply to the message, including each rule’s name and textual definition. XMLTag The XML tag that represents the message structure in the ISO 20022 XML schema. TargetNamespace The namespace declaration that appears in the ISO 20022 XML schema. TypeIDRef Reference to the Message Component that types this Message Building Block. ID Technical identifier User Guide MX Rresources Message Component Message Element 25 September 2009 Name ISO 20022 name (e.g. GroupHeader) of the element in the context of the message EnhancedDefinition The ISO 20022 description of the Message Building Block AdministrativeData Details of ISO 20022 registration status Multiplicity The minimum and maximum number of times that this element may appear in the message (minOccurs = 0 implies that this element is optional) TypeOfType The type of ISO 20022 element referred to by TypeIDRef: MESSGAGE_COMPONENT or CHOICE_COMPONENT. XMLTag The XML tag that represents the message building block in the ISO 20022 XML schema. ImpactedByRule Details of any usage or other rules that apply, including XOR rules (which imply a choice). IsBasedOnIDRef Reference to the Business Component on which this Message Component is based and from which it derives its meaning. ID Technical identifier Name ISO 20022 name (e.g.PartyIdentification1) EnhancedDefinition The ISO 20022 description of the Message Component. A blank value implies that the definition should be taken directly from the Business Component referenced by IsBasedOnIDRef. Non-blank values refine (rather than replace) the definition in the business layer. AdministrativeData Details of ISO 20022 registration status Rule Any usage rules that apply to the message, including each rule’s name and textual definition. ChoiceIndicator True if the message elements of the component are mutually exclusive (and will appear in an xs:choice structure in the associated schema) IsAlternativeFor A reference to a message component that this one supersedes in some messages. May include a description of the change and a reference to the change request. TypeIDRef Reference to the Message Component or Data Type that types this Business Element. ID Technical identifier IsBasedOnIDRef Reference to the Business Element on which this Message Element is based and from which it derives its meaning (if blank, implies that this is a technical definition; it is required for some technical-messaging related purpose and there is no corresponding Business Element). Name ISO 20022 name of the element in the context of the message EnhancedDefinition The ISO 20022 description of the Message Element AdministrativeData Details of ISO 20022 registration status Multiplicity The minimum and maximum number of times that this element may appear in the containing Message Component (minOccurs = 0 implies that this element is optional) TypeOfType The type of ISO 20022 element referred to by TypeIDRef: DATAYPE, MESSGAGE_COMPONENT or 17 Standards Developer Kit 1.0 CHOICE_COMPONENT. IsTechnical True for technical definitions (see IsBasedOnIDRef). XMLTag The XML tag that represents the message element in the ISO 20022 XML schema. Rule Details of any usage or other rules that apply, including XOR rules (which imply a choice). Exploring the Conceptual Layer The diagram illustrates the relationship between XML definitions in the conceptual (business) layer: Business Components contain Business Elements which can refer to other Business Components or to Data Types. Business Components can also refer to each other directly using Business Associations (indicated by the blue line on the diagram). The difference between the two types of business component relationship is that BC-BE-BC relationships are ones of strong dependency / containment; the referenced component has no independent existence outside the context of the referring component, whereas business associations are between 2 free-standing concepts. Business Elements refer to either Business Components or Data Types. As in the Logical Layer, references between definitions are defined in the repository using TypeIDRef and ID attributes: 18 User Guide MX Rresources Note: • Business Concepts are all maintained in the Financial Dictionary. • Business Components may be organised in inheritance hierarchies (unlike Message Components). • Business Elements are weakly typed; it is not possible to determine whether an element refers to a Business Component or a Data Type except by performing a lookup. Key values are unique across Business Component and Data Type, so only one or the other will be found. Business Associations are navigated in a similar way, using the TargetComponentIDRef attribute of the association. Content of Conceptual Layer Definitions Business Component Business Element 25 September 2009 ID Technical identifier Name ISO 20022 name (e.g.PartyIdentification1) EnhancedDefinition The ISO 20022 description of the Business Component. AdministrativeData Details of ISO 20022 registration status Synonym Synonyms for equivalent concepts in other standards / syntaxes, such as ISO 15022. Abstract True if this is an abstract definition (must have at least one subclass). ExtendedBy References to subclasses. Extends Reference to superclasses. TypeIDRef Reference to the Business Component or Data Type that types this Business Element. ID Technical identifier Name ISO 20022 name of the Business Element. EnhancedDefinition The ISO 20022 description of the Business Element 19 Standards Developer Kit 1.0 Business Association AdministrativeData Details of ISO 20022 registration status Multiplicity The minimum and maximum number of times that this element may appear in the containing Business Component (minOccurs = 0 implies that this element is optional) BusinessRule Details of any business rules that apply. TargetComponentIDRef Reference to the Business Component that this component is associated with. ID Technical identifier Name ISO 20022 name of the Business Association. EnhancedDefinition The ISO 20022 description of the Business Association AdministrativeData Details of ISO 20022 registration status Multiplicity The minimum and maximum number of times that this association may appear in the Business Component. Linking the Conceptual and Logical Layers As explained in the Background section, items in the logical layer are linked to items in the conceptual layer, from which they derive their meaning. Definitions in the logical layer that are not technical (that is, concerned only with messaging requirements, such as page numbers), are linked to business definitions in the conceptual layer. Message Components are linked to Business Components and Message Elements are linked to Business Elements. Links are made using the IsBasedOnIDRef attribute of items in the logical layer, which references the ID of the corresponding item in the conceptual layer. For example, the following XPath identifies the Business Component (SettlementInstruction) on which Message Component SettlementInformation1 is based: //BusinessComponent[@ID=//MessageComponent[Name='SettlementInformation1' ]/@IsBasedOnIDRef] In some cases, no textual definition of a Message Component is included in the logical layer; in these instances the definition should be taken from the referenced Business Component. Where a definition does exist, it should be understood to be a semantic refinement of the information in the business layer and interpreted accordingly; it does not override or replace the business definition. Uses for the MX Repository The MX Repository contains complete information for ISO 20022 logical message definitions and the ISO 20022 business model in a processable form. It can be used in a number of standards implementation scenarios, for example: 2.2 • Source for generated or customised documentation • Source for generated GUI definitions • For ad hoc reports – for example, extract all Code Data Types (with details) for messages from a given business area (see Appendix B2) MX Enriched Schemas Introduction Audience/Skills: XML, XML Schema Standard ISO 20022 XML schemas are designed to define and validate messages at a syntactic level; they contain little of the semantic information that allows a message to be understood. However, many modern schema-aware development tools include schema visualisation features 20 User Guide MX Rresources that make schemas a natural vehicle for simultaneously conveying structural, syntactic and semantic definitions. MX Enriched Schemas add semantic definitions sourced directly from the ISO 20022 repository to standards schemas to create a useful, processable reference for ISO 20022 messages. The illustration shows part of the enriched MX enriched schemas for message FItoFICustomerCrdeitTransferV02 (pacs.008.001.02), including the additional semantic information that is included for element MsgId. The semantic information is contained in XML Schema annotations, as shown in the schema fragment below: Annotation source ‘Name’ contains the full ISO 20022 name of the element, and ‘Definition’ contains the enhanced definition. Annotations are also included to describe code values defined in simple types (ISO 20022 Data Types), for example, data type RemittanceLocationMethod2Code: 25 September 2009 21 Standards Developer Kit 1.0 Note Identical information is provided in a different form in the MX Repository. Uses for MX Enriched Schemas MX Enriched Schemas can be used in conjunction with suitable tools to visualise and explore MX message definitions. Also, because schemas are themselves processable XML documents, MX enriched schemas can be used as the basis for generating useful artefacts such as GUI definitions and user documentation. 2.3 MX Spreadsheets Introduction Audience/Skills: Business Analysis/Office automation products/Microsoft Excel MX Spreadsheets are Comma Separated Values (CSV) files, which are compatible with MS Excel and other office automation applications. Each file contains a fully expanded representation of an MX message. The containment hierarchy of the message is indicated by indented element names in the left-most columns of the file. For each element, additional columns list: the XML tag name for easy cross-reference with the XML schema; the multiplicity; the type; any rules that apply to the use of the element; its full definition from the ISO 20022 repository; details of changes from previous releases; and a full XML path reference which can be used to extract data from a message instance. For data types that define code values, each code is listed with its name and a full definition. Example The illustration below shows a fragment of the MX spreadsheet for message FItoFICustomerCrditTransferV02 (pacs.008.001.02) viewed in Microsoft Excel 2007: 22 User Guide MX Rresources Uses for MX spreadsheets Users are free to hide or delete elements or columns and add columns or annotations of their own to create working analysis documents for their projects. It is also possible to import CSV files, with or without user amendments, into a technical environment for the generation of useful artefacts: meta-data definitions, documentation, and so on. 25 September 2009 23 Standards Developer Kit 1.0 Appendix A: MT/XML Schema Library samples A.1 Sample Implementation of ISchemaDocResolver (Java) Note: 24 • The constructer argument is the path to a directory of MT/XML schemas. • The name of the schema files in the directory should correspond to the namespace, plus the ‘.xsd’ file extension (this is the naming convention used in the library as supplied) User Guide Appendix A A.2 MT Message Generation Using Apache XML Beans (fragment) Note A.3 Apache XML Beans technology can be downloaded from http://xmlbeans.apache.org/. Generating an MT Message Using a Commodity Mapping Tool Note 25 September 2009 The tool shown in this example is Altova MapForce, which can read a Microsoft Excel spreadsheet and populate an XML instance based on an XSD. 25 Standards Developer Kit 1.0 Appendix B: MX Repository Samples B.1 Message Definition Query (XQuery) Note: 26 • Produces HTML output (could easily be modified to produce XML) • Function local:getElements()is called recursively to traverse the complete message structure. • $msg should be set to the name of the message to be extracted (PaymentReturnV01 in the example). • HTML output can be opened in Excel and saved as a spreadsheet (‘.XLS’ or ‘.XLSX’) file. User Guide Appendix B B.2 Extract Code Data Types and Details of Code Values for Messages in a Given Business Area Note: • Produces HTML output (could easily be modified to produce XML) • Can be modified to report on all messages in the MX Repository by removing the following from the main section: 25 September 2009 27 Standards Developer Kit 1.0 Appendix C: Acknowledgements, References and Resources C.1 Acknowledgements Screenshots of schema visualisations created using XML Spy. Screenshot of mapping tool in Appendix A3 shows MapForce. Both from Altova www.altova.com. Screenshot illustration for MX Spreadsheets created using Microsoft Excel 2007. www.microsoft.com. Java is a registered trademark of Sun Microsystems www.sun.com. C.2 References and Resources ISO 20022; see www.iso20022.org Extensible Markup Language (XML); see http://www.w3.org/XML/ XML Schema; see http://www.w3.org/XML/Schema XQuery; see http://www.w3.org/XML/Query/ (for a good tutorial see http://www.stylusstudio.com/xquery_flwor.html) Java Architecture for XML Binding (JAXB); see http://java.sun.com/developer/technicalArticles/WebServices/jaxb/ Java API for XML Processing (JAXP); see http://java.sun.com/ XML Beans; see http://xmlbeans.apache.org/ 28 User Guide Legal Notices Legal Notices Copyright SWIFT © 2009. All rights reserved. You may copy this publication within your organisation. Any such copy must include these legal notices. Confidentiality This publication may contain SWIFT or third-party confidential information. Do not disclose this publication outside your organisation without the prior written consent of SWIFT. Disclaimer SWIFT supplies this publication for information purposes only. The information in this publication may change from time to time. You must always refer to the latest available version on www.swift.com. Translations The English version of SWIFT documentation is the only official version. Trademarks SWIFT is the trade name of S.W.I.F.T. SCRL. The following are registered trademarks of SWIFT: SWIFT, the SWIFT logo, Sibos, SWIFTNet, SWIFTReady, and Accord. Other product, service, or company names in this publication are trade names, trademarks, or registered trademarks of their respective owners. 25 September 2009 29