3 mystandards ug_editor_best_practices

Standards

MyStandards Usage Guideline Editor

Best Practices This document provides best practice recommendations for users of the MyStandards Usage Guideline Editor defining their message usage guidelines.

20 June 2012

MyStandards

2 Best Practices

Table of Contents Table of Contents ............................................................................................................................... 2

Preface ................................................................................................................................................. 3

1 Introduction ............................................................................................................................... 4

2 Naming Conventions ................................................................................................................ 5 2.1 Introduction ............................................................................................................................. 5 2.2 Collection Name ...................................................................................................................... 5

2.2.1 Examples ............................................................................................................................ 5 2.3 Usage Guidelines .................................................................................................................... 6

2.3.1 Examples ............................................................................................................................ 6

3 Usage Guideline Editor Conventions ..................................................................................... 8 3.1 Introduction ............................................................................................................................. 8 3.2 Must not Be Used (Remove) ................................................................................................... 8 3.3 Make Mandatory ..................................................................................................................... 9 3.4 Reduce Multiplicity .................................................................................................................. 9 3.5 Ignore ....................................................................................................................................10 3.6 Rules (and Guidelines)..........................................................................................................10

3.6.1 Text Rule or Guideline ...................................................................................................... 11 3.6.2 Conditional Rule ............................................................................................................... 11

3.7 Fixed Value ...........................................................................................................................14 3.8 Comment ...............................................................................................................................15 3.9 Annotation .............................................................................................................................16

3.9.1 Example 1 ......................................................................................................................... 17 3.9.2 Example 2 ......................................................................................................................... 18 3.9.3 Example 3 ......................................................................................................................... 18

3.10 Change Datatype ..................................................................................................................19 3.10.1 Redefine a Text or Narrative Field as a Code List ............................................................ 19 3.10.2 Redefine a Narrative Field as Structured Lines of Text (MT) ........................................... 20

3.11 Create Extension (MX Only) .................................................................................................21 3.11.1 Scenario 1: Fixed Value ................................................................................................... 21 3.11.2 Scenario 2: Fixed Value and Code List ............................................................................ 24

3.12 Synonyms .............................................................................................................................27

4 Collections and Usage Guidelines ....................................................................................... 28

Legal Notices .................................................................................................................................... 29

Preface

20 June 2012 3

Preface Purpose of the document

This document provides best practice recommendations for users of the MyStandards Usage Guideline Editor defining their message usage guidelines.

Audience 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 Location

New section on collections and usage guidelines

4 Collections and Usage Guidelines

Updated information Location

Changes to naming conventions for collections and usage guidelines

2.2 Collection Name 2.3 Usage Guidelines

Related documentation · MyStandards Service Description · MyStandards Best Practices

MyStandards

4 Best Practices

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.

Naming Conventions

20 June 2012 5

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 -

Events, Order & Confirmation, Block Trade, Order Status & Confirmation, Transfers, Price Reporting, High Value Payments

5 Version - V1, V2, V3

6 Status_ DRAFT, FINAL, WIP CA = Corporate Actions TIC = Trade Initiation & Confirmation SR = Settlement & Reconciliation IF = Investment Funds WIP = Work in progress CGI = Common Global Implementation

Warning Optional parameters are indicated by square brackets [].

Versioning 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".

2.2.1 Examples 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.

SMPG # 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_

NMPG # Collection Name

MyStandards

6 Best Practices

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 20022 XML messages:


1 Message Name & Identifier Subscription Order_ setr.010.001.03

2 [ Additional optional parameter - ] Subscription Leg, Redemption Leg

The table below gives an overview of how to build up the usage guideline name for the MT:


1 Message Identifier & Message Name - 541_ Receive Against Payment

2 [For MT: SR year - ] SR2011, SR2012

3 [ Additional optional parameter - ] Bonus Issue

Warning Optional parameters are indicated by square brackets [].

2.3.1 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.

Naming Conventions

20 June 2012 7

SMPG # Usage Guideline Name

1 541_Receive Against Payment

2 502_Order To Buy Or Sell - SR2011 - Subscription Leg

3 Subscription Order_setr.010.001.03 - Institutional

4 Subscription Order_setr.010.001.03

CGI # Usage Guideline Name

1 Customer Credit Transfer Initiation_pain.001.001.03 - ACH Domestic & International

2 Customer Credit Transfer Initiation_pain.001.001.03 - Wires Domestic & International

3 Customer Credit Transfer Initiation _pain.001.001.03 - Cheques / Drafts

PMPG # Usage Guideline Name

1 FI To FI Customer Credit Transfer_pacs.008.001.02 - IG

2 Financial Institution Credit Transfer_pacs.008.001.02 - IG General

3 Financial Institution Credit Transfer_pacs.008.001.02 - 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.

MyStandards

8 Best Practices

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 Information which cannot be expressed in a more structured way.

9 Annotation A user-defined structure if a built in restriction is insufficient.

10 Change Datatype 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 user-defined 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.

Usage Guideline Editor Conventions

20 June 2012 9

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.

MyStandards

10 Best Practices

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.


20 June 2012 11

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 Compliance is recommended and so often contains the word "may".

· "The use of an ISIN is recommended." · "The field may be used to quote the

reference of the account opening instruction."

Rule Compliance is mandatory and so contain the word "must".

· "The field must contain the reference of the account opening instruction."

3.6.1 Text Rule or Guideline 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

3.6.2 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.

MyStandards

12 Best Practices

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

EUR Then Amount must not contain decimals

Else Amount may contain decimals

If OrdrTp/STAF

is present

Then StafClntBrkdwn/OrdrBrkdwnTp/NSPN must be present


20 June 2012 13

Example 1

MyStandards

14 Best Practices

Example 2

3.7 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.


20 June 2012 15

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.

MyStandards

16 Best Practices

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.


20 June 2012 17

Annotations should be given meaningful names and definitions:

3.9.1 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:

MyStandards

18 Best Practices

3.9.2 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:

3.9.3 Example 3 The IT NMPG, for example, has the need to include definitions in Italian:


20 June 2012 19

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.

3.10.1 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.

MyStandards

20 Best Practices

The individual codes must be entered, and each code must be given a code word and a definition:

3.10.2 Redefine a Narrative Field as Structured Lines of Text (MT) 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.

Example 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 June 2012 21

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

3.11.1 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:

MyStandards

22 Best Practices

For each of the elements of the Extension sequence, you need to define the contents (1):


20 June 2012 23


MyStandards

24 Best Practices

3.11.2 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:


20 June 2012 25


MyStandards

26 Best Practices

The first element will be defined with "Fixed value" and this will be the XML path. A comment for the fixed value is entered.



20 June 2012 27

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).

3.12 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.

MyStandards

28 Best Practices

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.

Legal Notices

20 June 2012 29

Legal Notices Copyright SWIFT © 2012. 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 www.swift.com.

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 www.swift.com > 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.

http://www.swift.com/

http://www.swift.com/about_swift/legal/swiftstandards_ipr_policy.page?

3 mystandards ug_editor_best_practices

Economy & Finance

message usage guidelines

best practice recommendations

text rule

naming conventions

conditional rule

fixed value