Best Practices. Usage Guideline Editor. Standards. For MyStandards

Transcription

1 Standards Usage Guideline Editor For MyStandards Best Practices This document provides best practice recommendations for users of the MyStandards Usage Guideline Editor defining their message usage guidelines. 20 June 2012

2 Usage Guideline Editor for MyStandards Table of Contents Table of Contents... 2 Preface Introduction Naming Conventions Introduction Collection Name Examples Usage Guidelines Examples Usage Guideline Editor Conventions Introduction Must not Be Used (Remove) Make Mandatory Reduce Multiplicity Ignore Rules (and Guidelines) Text Rule or Guideline Conditional Rule Fixed Value Comment Annotation Example Example Example Change Datatype Redefine a Text or Narrative Field as a Code List Redefine a Narrative Field as Structured Lines of Text (MT) Create Extension (MX Only) Scenario 1: Fixed Value Scenario 2: Fixed Value and Code List Synonyms Collections and Usage Guidelines Legal Notices Best Practices

3 Preface Preface Purpose of the document Audience This document provides best practice recommendations for users of the MyStandards Usage Guideline Editor defining their message usage guidelines. This document is for the following audience: Users of the MyStandards Usage Guideline Editor Significant changes The following tables list all significant changes to the content of the MyStandards Best Practices since the 27 April 2012 edition. These tables do not include editorial changes that SWIFT makes to improve the usability and comprehension of the document. New information New section on collections and usage guidelines Location 4 Collections and Usage Guidelines Updated information Changes to naming conventions for collections and usage guidelines Location 2.2 Collection Name 2.3 Usage Guidelines Related documentation MyStandards Service Description MyStandards Best Practices 20 June

4 Usage Guideline Editor for MyStandards 1 Introduction This document describes naming conventions and recommended approaches when specifying restrictions on message fields. It is important to have a convention when naming collections and guideline definitions so that there is a level of consistency with names and to support the easy searching of guideline definitions. The driving principle behind having best practices is to push users to formalise as much as possible. The more formal a usage guideline definition is, then the more semantic value it has and so the more meaningful any automated or manual analysis can be. This document is intended for those users that already have a good knowledge of the MyStandards Usage Guideline Editor. It is not a user manual. In most cases, the best practice principals used are the same or similar for both MT and MX. Where illustrations are used, MX (XML) messages has been used. 4 Best Practices

5 Naming Conventions 2 Naming Conventions 2.1 Introduction The naming conventions described below for collections and usage guidelines functionality are valid, although practically, there may be variants. 2.2 Collection Name A collection is a container of logical set of guideline definitions which the user must analyse and manage. The table below gives an overview of how to build up the collection name. Parameter Description Example 1 Organisational Entity - SMPG, NMPG, RMPG, CGI, PMPG 2 [Locale or initiative -] Global, IT, GB, FR, Almus 3 Business area - CA, TIC, SR, IF, Payments, FX, Derivatives, Commodities 4 Business process - 5 Version - V1, V2, V3 6 Status_ DRAFT, FINAL, WIP Events, Order & Confirmation, Block Trade, Order Status & Confirmation, Transfers, Price Reporting, High Value Payments CA = Corporate Actions TIC = Trade Initiation & Confirmation SR = Settlement & Reconciliation IF = Investment Funds WIP = Work in progress CGI = Common Global Implementation Versioning Warning Optional parameters are indicated by square brackets []. MyStandards has its own convention for versioning and will apply Version 1 to the first time a collection is uploaded, and increment the version number of subsequent uploads. This is a technical version number and is distinct from the "true" version number of a collection. For example, V1 of the IF-Orders, Status and Confirmations collection may have been updated several times as several iterations of a "work-in-progress" version are posted. Thus Version 1 of the IF Orders and Confirmations collection may have, for example, an internal MyStandards version number of 5. Therefore, there is a need for a "business version number" Examples SMPG NMPG The spaces in the following example collection names are present for readability, they do not have to be present in the actual collection name, it is up to the user. # Collection Name 1 SMPG - Global - TIC - Order & Confirmation - V1 FINAL_ 2 SMPG - Global - SR Block Trades - V1 FINAL_ 3 SMPG - Global - CA - Events - V2 DRAFT_ 4 SMPG - Global - IF - Order Status & Confirmations - V1 DRAFT_ # Collection Name 20 June

6 Usage Guideline Editor for MyStandards 1 NMPG - FR - IF - Order & Confirmation - V1 FINAL_ 2 NMPG - DE - IF - Price Reporting - V1 FINAL_ 3 NMPG - DE - IF - Statements - V3 DRAFT_ 4 NMPG - US TIC - Trade Initiation & Confirmation - V1 DRAFT_ RMPG # Collection Name 1 RMPG ALMUS - IF - Order & Confirmation - V1 FINAL_ 2 RMPG - AFAC - IF - Order & Confirmation - V1 FINAL_ 3 RMPG - FINDEL - IF - Order & Confirmation - V2 FINAL_ 4 RMPG - FINDEL - IF - Transfer - V1 DRAFT_ 5 RMPG - SHARP - IF - Order & Confirmation - V1 FINAL_ CGI # Collection Name 1 CGI - Global - Payments -Corporate to Bank - V1 FINAL_ PMPG # Collection Name 1 PMPG - Global - Payments -PACS High Value Payments - V1 FINAL_ 2.3 Usage Guidelines A usage guideline represents a message definition which has been restricted by the user. The table below gives an overview of how to build up the usage guideline name for the MX or ISO XML messages: Parameter Description Example 1 Message Name & Identifier 2 [ Additional optional parameter - ] Subscription Order_ setr Subscription Leg, Redemption Leg The table below gives an overview of how to build up the usage guideline name for the MT: Parameter Description Example 1 Message Identifier & Message Name - 541_ Receive Against Payment 2 [For MT: SR year - ] SR2011, SR [ Additional optional parameter - ] Bonus Issue Warning Optional parameters are indicated by square brackets [] Examples The spaces in the following examples of collection and usage guideline names are present for readability, they do not have to be present in the actual collection name, it is up to the user. 6 Best Practices

7 Naming Conventions SMPG # Usage Guideline Name 1 541_Receive Against Payment 2 502_Order To Buy Or Sell - SR Subscription Leg 3 Subscription Order_setr Institutional 4 Subscription Order_setr CGI # Usage Guideline Name 1 Customer Credit Transfer Initiation_pain ACH Domestic & International 2 Customer Credit Transfer Initiation_pain Wires Domestic & International 3 Customer Credit Transfer Initiation _pain Cheques / Drafts PMPG # Usage Guideline Name 1 FI To FI Customer Credit Transfer_pacs IG 2 Financial Institution Credit Transfer_pacs IG General 3 Financial Institution Credit Transfer_pacs IG Cover Other, for example, commodities # Usage Guideline Name 1 600_Commodity Trade Confirmation Note When a message is added to a collection, the name of the collection is automatically appended in front of the message name. The collection name should be deleted from the message name. 20 June

8 Usage Guideline Editor for MyStandards 3 Usage Guideline Editor Conventions 3.1 Introduction The Usage Guideline Editor makes it very easy for a user to accurately and unambiguously describe their specific usage of a message. It allows a user to easily apply additional restrictions on top of the base message definition. Note A "restriction" is an additional limitation defined by the user on the base message definition which an implementer would need to follow in order to be compliant with the guideline. In some contexts the term "rule" would be used instead of "restriction". The list below describes the different restriction types that may be applied: # Restriction Type Description 1 Must not be used (Remove) An optional field or element must not be populated. 2 Make Mandatory An optional field or element must be populated. 3 Reduce Multiplicity A repeating field or element must repeat fewer times. 4 Ignore A field or element could be populated but is ignored by the receiver. 5 Text Rule A mandatory, unstructured, rule. 6 Conditional Rule A mandatory, if-then-else, rule. 7 Fixed Value A field or element must contain a given value. 8 Comment 9 Annotation 10 Change Datatype Information which cannot be expressed in a more structured way. A user-defined structure if a built in restriction is insufficient. A user-defined datatype replaces an existing simple datatype. 11 Create Extension A user-defined extension - MX specific. 12 Synonym A field or element has another name. The first four basic restriction types are very easy to set up in the message usage editor in an unambiguous way. The other more advanced restriction types, such as rules, comments and annotations require more thought before their use. It s possible to confuse their distinct functionality and the next sections attempts to define when it is appropriate to use each kind of functionality. 3.2 Must not Be Used (Remove) Indicating a field must not be used (removed), means that in order to be compliant with the userdefined guideline, a particular field must not be populated. If the sender of a message does populate the "removed" field, then the message will not be viewed as being compliant to the usage guideline. As a result, the receiver of the message may stop any processing and end the business transaction. Care must be taken when using this functionality since its implementation may be costly to the sender, if the sender has already implemented the message. An alternative solution that minimises the impact on a message already implemented by the sender is "Ignore" in other words, a field or element may be populated by the sender but it is ignored by the receiver. 8 Best Practices

9 Usage Guideline Editor Conventions 3.3 Make Mandatory Making an optional field mandatory, means that in order to be compliant with the user-defined guideline, a particular field must be populated. If the sender of a message does not populate the "mandatory" field, then the message will not be viewed as being compliant to the usage guideline. As a result, the receiver of the message may stop any processing and end the business transaction. 3.4 Reduce Multiplicity Some fields are defined in the base message as being repeatable. The user-defined guideline could contain a restriction which reduces the amount of times a field can be repeated. If the sender of a message repeats a field more times than is allowed in the usage guideline, then the message will not be viewed as being compliant. As a result, the receiver of the message may stop any processing and end the business transaction. It is not possible to increase the multiplicity of a field or element. 20 June

10 Usage Guideline Editor for MyStandards 3.5 Ignore Indicating a field must be ignored, means that in order to be compliant with the user-defined guideline, a particular field may or may not be populated. If the sender of a message does populate the "ignored" field, then the message is still viewed as being compliant to the usage guideline. However, the receiver of the message will not use the data in any way. In other words, the data in the field will not influence either the processing or the business transaction. 3.6 Rules (and Guidelines) Over and above restrictions such as "must not use" (remove), "must be used", "use only once" and "ignore", additional rules may be added to a field, which means that in order to be compliant with the user-defined guideline, the rule must be followed. If the sender of a message does not follow the additional rule on a field, then the message will not be viewed as being compliant to the usage guideline. As a result, the receiver of the message may stop any processing and end the business transaction. 1. A rule should contain a single constraint. If more than one rule constraint is necessary on a single field, these should be added in additional, separate rules. 2. The rule should be given a meaningful name. It is sensible to differentiate message usage rules or guidelines from the rules and guidelines actually present in the message standard. Prefixing the rule name with something like "ITNMPG" will help with this differentiation. Each rule should end in the word "Rule". 3. If a text rule (see below) is to be considered a guideline rather than a rule, then the rule name should end in the word "guideline". 4. Where possible, it is recommended to use the "Conditional Rule" format, over the "Text Rule" format as it increases interpretation clarity. 5. A rule should not be added if it is already part of, or conflicts with, the base message standard definition. 10 Best Practices

11 Usage Guideline Editor Conventions 6. Do not use punctuation, spaces or underscore types of characters. Follow the camel case convention. These restrictions are to allow for potential future functionality. 7. The cross element rule checkbox should be used as necessary. Differentiation between a Rule and a Guideline. Type Description Example Guideline Rule Text Rule or Guideline Compliance is recommended and so often contains the word "may". Compliance is mandatory and so contain the word "must". "The use of an ISIN is recommended." "The field may be used to quote the reference of the account opening instruction." "The field must contain the reference of the account opening instruction." This is a simple usage rule which is described in a plain text paragraph. It will require the user to interpret the rule carefully. So, it is recommended that the rule is concise and precise language is used. Example 1 text rule Example 2 guideline Conditional Rule 1. The rule is added to the first element (as referenced in <element>) of the conditional rule. 2. It is recommended that the rule definition is empty. In most cases the "if-then-else" text fields should be sufficient to describe the rule. 20 June

12 Usage Guideline Editor for MyStandards 3. When referring to other fields in the rule, then the XML tag or field name must be used. In some cases, it may be necessary to include some "path" information (see example below). Path information may also be needed in those cases where the same element name is used in different parts of the message. 4. Recommended structures of the "if", "then" and "else" text boxes is: <element> <logic> [ <value> ] - <element> represents the element or field being referenced. - <logic> represents the operator - <value> optional value to which relates to the content in <element> Example usage would be: <element> <logic> <value> <element> <logic> <value> <element> <logic> <value> If Currency is equal to If OrdrTp/ST AF is presen t EUR Then Amount must not contain decimals Then StafClntBrkdwn/OrdrBrkdwnTp/ NSPN must be present Else Amount may contain decimals 12 Best Practices

13 Usage Guideline Editor Conventions Example 1 20 June

14 Usage Guideline Editor for MyStandards Example Fixed Value Setting a fixed value for a field, means that in order to be compliant with the user-defined guideline, a particular field, when present, must be populated with the specified fixed value. If the sender of a message does not populate the field with the fixed value, then the message will not be viewed as being compliant to the usage guideline. As a result, the receiver of the message may stop any processing and end the business transaction. A fixed value may only be used on fields containing simple types, for example, Max35Text or Extended350Code. Examples of fixed field values are a user-defined code word, or a specific currency code. 14 Best Practices

15 Usage Guideline Editor Conventions The fixed value is entered in the "Fixed value" text field. If the fixed value is a code, then the definition of the code should be specified in the associated comment box. Note that a separate definition box for fixed value has been requested. 3.8 Comment A comment can only be used to contain information which cannot be expressed using more structured restriction types, like "make mandatory" or "must not be used". So, it should only be populated if a more restrictive restriction type cannot be used. It is "for information only". Don t use a comment for the following: To redefine the semantic of a field. To create a local language definition. To redefine the base message standard definition. To state the field is "recommended". If a field is recommended, this is better expressed as a guideline, using the "Add rule" functionality. To specify a fixed value. This is to be expressed using the Fixed Value box. However, the comment box is used to give the definition of the fixed value when it is a code word, until the Fixed Value has its own definition box. 20 June

16 Usage Guideline Editor for MyStandards Example 3.9 Annotation The built-in restriction types may not cover all the scenarios which a user may need to apply in their usage guideline. The annotation mechanism allows the user to create a re-usable restriction type to cover its particular requirement. So, annotations should only be used when it is not possible to express the message usage information through one of the "normal" mechanisms. For example, do not use an annotation to define a rule or to or to express a fixed value. Note The MyStandards platform has no knowledge of the semantics of annotations there is no impact on the generated schema. An annotation appears in the generated spreadsheet in the Annotation column. 16 Best Practices

17 Usage Guideline Editor Conventions Annotations should be given meaningful names and definitions: Example 1 The IT NMPG, for example, has the need to attach change request information to a field. An annotation function can be defined for such usage: 20 June

18 Usage Guideline Editor for MyStandards Example 2 The IT NMPG, for example, has the need to redefine the semantic of an element for local use. An annotation function can be defined for such usage: Example 3 The IT NMPG, for example, has the need to include definitions in Italian: 18 Best Practices

19 Usage Guideline Editor Conventions 3.10 Change Datatype Some fields are defined in the base message as being "simple data types", such as text, a number, a date. The user may choose to redefine a field's simple datatype to a more restrictive existing datatype, which is already available in the repository, or to use a newly created datatype. It is recommended to re-use existing datatypes Redefine a Text or Narrative Field as a Code List A user may redefine a text field as a code list, to enable a more formal way of specifying that, for example, "this field may contain the values SPEC and XPEC". This involves two steps, first, the setting up of the new code list and, secondly, redefining the type of the relevant field to use the new code list. When setting up the new code list, care must be taken to give the code list datatype a meaningful name: A definition at this level is probably not necessary. 20 June

20 Usage Guideline Editor for MyStandards The individual codes must be entered, and each code must be given a code word and a definition: Redefine a Narrative Field as Structured Lines of Text (MT) Example A user may redefine a narrative field, for example, 6 * 35x, so that it is more structured. This involves two or three steps, depending on the requirements. First, the new complex type is set up. And second, the relevant field is typed by the new complex type. When setting up the new complex datatype, care must be taken to make sure it and all its subfields have relevant names and, if necessary, meaningful definitions. And for the subfields, multiplicity must be set to override the default multiplicity proposed by the usage guideline editor. In turn, each of the subfields can each have their own datatype. In this scenario, in a usage guideline for the MT 502, field 70E (10*35X) TPRO in sequence B ORDRDET, is re-defined in the following way: Original definition in MT New definition Data Type 10 * 35x Line 1 Subfield 1 Code list with values NEAM and GRAM and GRPE Line 2 Subfield 2 3!a currency code Line 3 Subfield 3 15d 20 Best Practices

21 Usage Guideline Editor Conventions 3.11 Create Extension (MX Only) Because the investment funds order messages have not been maintained for some considerable time, many markets have defined the use of the Extension sequence for additional functionality, pending the maintenance. Extension sequence Scenario 1: Fixed Value There is a requirement to be able to optionally specify an SLA Reference in the Charge Details sequence of a message. The NMPG has agreed that this should be specified in an Extension sequence. An iteration of an Extension sequence is inserted in the Charge Details sequence. Following the addition of a new Extension sequence, give it a meaningful name and definition: 20 June

22 Usage Guideline Editor for MyStandards For each of the elements of the Extension sequence, you need to define the contents (1): 22 Best Practices

23 Usage Guideline Editor Conventions For each of the elements of the Extension sequence, you need to define the contents (2): 20 June

24 Usage Guideline Editor for MyStandards Scenario 2: Fixed Value and Code List There is a requirement to be able to optionally specify information about "order sequencing" in the message. The order sequencing can be either FIST (first) or FIILW (additional order). The NMPG has agreed that this should be specified in an Extension sequence. An iteration of an Extension sequence is inserted in the Individual Order Details sequence. Following the addition of a new Extension sequence, give it a meaningful name and definition: 24 Best Practices

25 Usage Guideline Editor Conventions For each of the elements of the Extension sequence, you need to define the contents (1): 20 June

26 Usage Guideline Editor for MyStandards The first element will be defined with "Fixed value" and this will be the XML path. A comment for the fixed value is entered. For each of the elements of the Extension sequence, you need to define the contents (2): 26 Best Practices

27 Usage Guideline Editor Conventions In this example, the second element (Text: Max350Text) can be one of two codes and therefore a code list has been created and the element Text has been typed by it (See Redefine a Text or Narrative Field as a Code List) Synonyms Every field in a base message has a specific name with associated meaning. A user-defined guideline may link another name, from a different context, to the given field. Examples: A back-office system may use another, proprietary, format. This proprietary format also has fields which match fields in the base message. A synonym can then be used to link the base message field to the proprietary format field. A non-english speaking country may want to use the base message, however the fact that all base messages are in English means adoption is hampered. A synonym can then be used to link the base message field to the translation of that field which should ease adoption. 20 June

28 Usage Guideline Editor for MyStandards 4 Collections and Usage Guidelines A collection is a container of logical set of guideline definitions which the user must analyse and manage. Typically, a "collection" will be for a specific business process and contain usage guidelines for messages that support the business process. Example There will be cases where a collection contains a single message. Publishers of usage guidelines, market practices, implementation guidelines, etc., on MyStandards should try to organise their work so that it s published as a logical collection. 28 Best Practices

29 Legal Notices Legal Notices Copyright SWIFT All rights reserved. You may copy this publication within your organisation. Any such copy must include these legal notices. Confidentiality This publication contains SWIFT or third-party confidential information. Do not disclose this publication outside your organisation without the prior written consent of SWIFT. Disclaimer The information in this publication may change from time to time. You must always refer to the latest available version on SWIFT Standards Intellectual Property Rights (IPR) Policy - End-User License Agreement SWIFT Standards are licensed subject to the terms and conditions of the SWIFT Standards IPR Policy - End-User License Agreement, available at > About SWIFT > Legal > SWIFT Standards IPR Policy. Translations The English version of SWIFT documentation is the only official and binding version. Trademarks SWIFT is the trade name of S.W.I.F.T. SCRL. The following are registered trademarks of SWIFT: SWIFT, the SWIFT logo, the Standards Forum logo, 3SKey, Innotribe, 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. 20 June