Best VIP Call Girls Noida Sector 18 Call Me: 8448380779
3 mystandards ug_editor_best_practices
1. 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
2. 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
3. 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
4. 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.
5. 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
6. 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:
Parameter Description Example
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:
Parameter Description Example
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.
7. 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.
8. 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.
9. 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.
10. 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.
11. Usage Guideline Editor Conventions
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.
12. 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/ST
AF
is
presen
t
Then StafClntBrkdwn/OrdrBrkdwnTp/
NSPN must be present
14. 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.
15. Usage Guideline Editor Conventions
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.
16. 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.
17. Usage Guideline Editor Conventions
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:
18. 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:
19. Usage Guideline Editor Conventions
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.
20. 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
21. Usage Guideline Editor Conventions
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:
23. Usage Guideline Editor Conventions
20 June 2012 23
For each of the elements of the Extension sequence, you need to define the contents (2):
24. 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:
25. Usage Guideline Editor Conventions
20 June 2012 25
For each of the elements of the Extension sequence, you need to define the contents (1):
26. 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.
For each of the elements of the Extension sequence, you need to define the contents (2):
27. Usage Guideline Editor Conventions
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.
28. 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.
