4 mystandards ug_editor_user_guide
TRANSCRIPT
Standards
MyStandards Usage Guideline Editor
User Guide This guide describes in detail how to use the functionalities of the Usage Guideline Editor.
26 June 2012
MyStandards
2 User Guide
Table of Contents Preface ................................................................................................................................................. 3
1 Introduction ............................................................................................................................... 4
2 Getting Started .......................................................................................................................... 5 2.1 Accessing the MyStandards Website ..................................................................................... 5 2.2 Usage Guideline Editor Installation ......................................................................................... 5 2.3 Message Definition Repositories ............................................................................................ 5 2.4 Collection Setup ...................................................................................................................... 7 2.5 Usage Guideline Setup ........................................................................................................... 8 2.6 Upload to MyStandards Website ............................................................................................ 9 2.7 Privacy Settings ....................................................................................................................10 2.8 Import into the Usage Guideline Editor .................................................................................10
3 Creating Usage Guidelines .................................................................................................... 12 3.1 Restriction Types ..................................................................................................................12 3.2 Usability Features .................................................................................................................35 3.3 Impact on the Schema ..........................................................................................................37 3.4 Supplementary Documents ...................................................................................................38
Legal Notices .................................................................................................................................... 39
Preface
26 June 2012 3
Preface Purpose of the document
This document explains in detail how to use the functionalities of the Usage Guideline Editor for the definition of message usage guidelines.
Audience This document is for the following audience: · Users of the MyStandards Usage Guideline Editor
First edition This is the first edition of the document.
Related documentation · MyStandards Service Description · MyStandards Best Practices
MyStandards
4 User Guide
1 Introduction Qualifying organisations may be granted a Premium Group license (see the MyStandards Service Description). This will include the ability to create, maintain and publish usage guidelines.
This is done in the Usage Guideline Editor, an off-line application built on the Eclipse Rich Client Platform. The Editor must be installed on the customer’s local system and is made available for download through the MyStandards website. The use of the Editor is subject to the license terms provided in the SWIFT General Terms and Conditions.
This document describes how to use the Usage Guideline Editor to specify restrictions on message fields. It will also include references to the online MyStandards platform as needed.
It is important to have a good understanding of how the functionalities in the Usage Guideline Editor work. This will result in a deeper understanding of how to set restrictions and improve productivity.
The Editor allows the creation and maintenance of usage guidelines in a structured, formal and consistent way starting from the base message definitions.
The information which is captured in the Editor is then uploaded to the MyStandards web application for publication and sharing.
The publisher controls the usage guideline privacy settings to define who they want to share information with. There are three privacy settings to choose from: public; private; restricted.
So, this document is intended for those users who already have a good basic knowledge of the MyStandards platform and who would like to learn how to start creating their own guidelines.
Getting Started
26 June 2012 5
2 Getting Started 2.1 Accessing the MyStandards Website
Connect to the website www.swift.com/mystandards and log in using your swift.com user name and password. If you don’t already have swift.com credentials, then you can create a new account by registering.
2.2 Usage Guideline Editor Installation Once you have logged in to MyStandards you must download the archive ('zip') file(s) for the application and repositories. These can be found in the Workspace section under the Guideline Editor tab.
Then extract the application and the two message definition repositories locally.
To run the application, double click the file called StandardsEditor.exe. Be aware that using a network share will result in degraded performance.
2.3 Message Definition Repositories A repository is a file which contains the full base catalogue of messages and will also contain any guidelines that you save locally.
To load the repository, you must access the menu File > Open.
Then find the repository file that you would like to load and select Open.
MyStandards
6 User Guide
Note If the Model Explorer tab is not visible, open it by going to Window > Open View > Other > Model Explorer.
Once loaded, you will be able to see the catalogue of base messages in the Model Explorer and depending which tab you select it will display the MX or MT catalogue:
Getting Started
26 June 2012 7
Note The selected repository tab sets the context of the whole Editor application. So, if you would like to work with MTs, then ensure that the MT repository tab was selected last.
2.4 Collection Setup Before being able to start defining restrictions on specific messages, a collection needs to be created. A collection contains a logical set of related messages. See the MyStandards Usage Guideline Editor Best Practices for additional guidance.
To create a collection, first select the Guidelines tab in the Model Explorer. Then right-click in the white space and in the menu select Add Collection. This will create a new node in the Model Explorer called New Collection.
Now, double click New Collection and give it a meaningful name and description. See the MyStandards Usage Guideline Editor Best Practices for naming conventions. The collection name can be changed at any time.
Once the collection has been created, it is then possible to start adding to it the messages for which you would like to create usage guidelines. To add a message to a collection, go to the Messages tab:
MyStandards
8 User Guide
Then, by browsing through the catalogue of message, find the message you would like to add.
Select and then right-click the message, find Add to Collection and choose the collection.
Note Adding multiple different, or the same, messages to a collection is possible.
2.5 Usage Guideline Setup A collection contains the message definitions you would like to restrict further. By default, the collection name is appended to the message name.
To open the message you would like to start working on, select the Guidelines tab in the Model Explorer, and then double left-click the message in the collection. This will open the message in the editor in a new tab on the right of the screen.
The message summary and metadata overview will be presented. This information should be updated - see the MyStandards Usage Guideline Editor Best Practices for additional guidance.
Getting Started
26 June 2012 9
Now, select the Usage Guidelines tab to go to the actual window which allows you to define message restrictions.
Note Section 3 Creating Usage Guidelines contains details on how to create your actual usage guidelines.
2.6 Upload to MyStandards Website First, select the collection you would like to upload and right-click Export Collection. Save the file locally, for example, in a directory called Usage Guideline Exports.
In this example, the following zip is created:
Note Do not unzip this export file.
Then, log onto the MyStandards website and go to Workspace. Here, if you have publishing rights, you will see the option Add a Usage Guideline.
MyStandards
10 User Guide
Select it and then browse to locate the zip file (in this example ITNMPGSubscription_20120210_1706.zip).
Note After the file has been selected, click to confirm and wait! The window will close by itself once the upload completes.
2.7 Privacy Settings The default when you upload a market practice onto the MyStandards website is private. There are three privacy settings: · Public: any user of MyStandards can access the content. · Private: only users within the same Group as the publisher can access the content. · Restricted: only users within selected groups can access the content.
You can change the privacy of an uploaded collection by going to the Workspace and then selecting Share.
2.8 Import into the Usage Guideline Editor In section 2.6 Upload to MyStandards Website, a collection was exported, so that it could be uploaded into the MyStandards website. However, if another user wants to continue working on the same file in its Usage Guideline Editor, then this other user must first import it into its own local Editor and save it to its local MX repository. This other user can then continue where the first person left off.
The file, in the above example, ITNMPGSubscription_20120210_1706.zip can be imported into your local MX repository. From the Guidelines tab, right-click in the white space, select Import Collection.
Getting Started
26 June 2012 11
Browse until you find the file and open it. Once it is in the Editor, you must save it. This will update your local MX repository file.
MyStandards
12 User Guide
3 Creating Usage Guidelines This section describes how to functionally define a specific restriction. It only provides a few examples and no recommended approaches. For additional guidance, see the MyStandards Usage Guideline Editor Best Practices.
Also, as a general rule, periodically save your work by going to the menu File and choose Save. This will save your work to the local repository.
3.1 Restriction Types 3.1.1 Must not Be Used (Remove)
Only optional sequences or elements may be marked as Must not be used. To indicate that a field must not be used, deselect the checkbox to the left of the field.
This can also be done by selecting the element, right-clicking and choosing Prune selected tree.
Note In this example, Pool Reference is a sequence that contains child elements. There is a ripple effect to the child elements because if a parent element is removed it will implicitly mean that child elements cannot be used either.
In this example, only two codes may be used:
Creating Usage Guidelines
26 June 2012 13
3.1.2 Make Mandatory Only optional sequences or elements may be made mandatory. To do this, select the element, highlight the 0 in the Min Occurs input box and replace it with 1.
Another way to do this is to right-click the element itself, and select Make Mandatory.
3.1.3 Reduce Multiplicity Some elements are defined in the base message as being repeatable. To reduce the repetitions of a repeatable field, select the element, highlight the * in the Max Occurs input box and replace it with 1.
Another way to do this is to right-click the element itself, and select Make Non Repetitive.
MyStandards
14 User Guide
Note The * in Max Occurs means the element can be repeated infinitely. This value can be changed to any other integer, less than the Max Occurs and at least equal to the Min Occurs.
3.1.4 Ignore Any element may be ignored. To do this, select the element and check the checkbox for Is ignored:
Another way to do this is to right-click the element itself, and select Ignore.
3.1.5 Text Rule or Guideline Select the element to which a rule must be applied, right-click, go to Add Rule and choose Add New Rule. In this example, a plain text rule is being added to the Previous Reference field.
Enter a meaningful name for the rule and provide a definition.
Creating Usage Guidelines
26 June 2012 15
3.1.6 Conditional Rule Select the element to which a rule must be applied, right-click, go to Add Rule and choose Add New Conditional Rule.
Provide a meaningful name for the rule and fill in the If, Then and Else text areas accordingly.
3.1.7 Fixed Value The fixed value textbox is available in the Additional Information section on the right when an element is selected.
MyStandards
16 User Guide
As, in our example, the fixed value is a code, then the definition of the code is specified in the associated comment box.
3.1.8 Comment A comment is for information only and can be added to any selected element. The comment text area is available in the Additional Information section on the right when an element is selected.
3.1.9 Annotation This allows the creation of a user-defined restriction which is re-usable. The annotation function should only be used when it is not possible to express the message usage information through one of the normal mechanisms. In other words, do not use it to define a rule or to re-define a semantic or to express a fixed value.
The system has no knowledge of the semantic of the restriction – there is no impact on the generated schema.
Creating Usage Guidelines
26 June 2012 17
For a number of elements, for example, it may be desirable to indicate to additional documentation, such as a related change request. Or it may be necessary to re-define the somatic of a field. Or it may be necessary to include an element definition in a local language.
Creation 1. Analyse which structure is required in the given use-case. Ensure that no other existing
restriction type is suitable and that the annotation is fully re-usable.
2. Right-click the Annotation node in the Model Explorer and select Create Annotation.
3. Give the annotation a meaningful name and documentation:
4. Add item(s) to Content. Each item is an input area or dropdown list which will represent the
user-defined restriction type:
MyStandards
18 User Guide
5. Name the item:
6. Select the kind:
In this case, a multiline text area is selected.
7. Additional items within the content may be defined if required.
Usage 1. Select and right-click the element, go to Add Annotation and select the annotation to be
added:
Creating Usage Guidelines
26 June 2012 19
Note The annotation is added as a child element.
2. Once added, select the annotation. This will result in the annotation details being displayed on the right. Update the details to describe the requirement. In this example, a reference is made to a change request and an interim solution.
Note If the annotation contained multiple items, then multiple input areas would be displayed.
MyStandards
20 User Guide
3.1.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".
Creation 1. Each collection has a Dictionary section:
2. Open the dictionary, right-click Code Sets, select New Child and then Code Set
3. Double-click the created code set and give it a name. For additional guidance on how to
name the code set, see the MyStandards Usage Guideline Editor Best Practices. In this example, we are creating a code list for Extended Order Breakdown Type, so we have named the code list ITNMPGExtendedOrderBreakdownType1.
Creating Usage Guidelines
26 June 2012 21
4. Now define the actual codes: click Content:
5. In the white space of the Content panel, right-click Create Child and select Code Value.
You end up with a green star in the Content panel:
6. Open up the unnamed code word and assign the 4-character code, it’s definition and code
word:
MyStandards
22 User Guide
7. Add a second code – use the Plus button to add the 2nd code:
8. Define the 2nd code, its name and definition.
Thus there is now a new code list called ITNMPGExtendedOrderBreakdownType1 with two values, SPEC and XPEC
Usage Open the message again, select the element (in this case, Extended Order Breakdown Type) and set the data type to the new data type:
Creating Usage Guidelines
26 June 2012 23
The new data type is now assigned.
Redefine a Narrative Field as Structured Lines of Text (MT) Fields in MTs such as field 70 (4*35x) and field 72 (6*35x) may, within a specific usage guideline or market practice, require specific data on each line of these fields.
The data type, for example, (4*35x) can be re-defined formally.
In this example, in the MT 502, field 70C PACO in sequence C1 SETPRTY has been redefined as a code list.
MyStandards
24 User Guide
Creation 1. Each collection has a Dictionary section:
2. Open the dictionary, right-click Code, select New Child and then Code
3. Double-click the newly created Code element and give it a name. This must be a name
which cannot be confused with anything already in the message. In this example, we are creating a code list for settlement party narrative field, so we have named the code list Settlement Party Narrative Code.
Creating Usage Guidelines
26 June 2012 25
4. Now define the actual codes: right-click the new code list and select Code Value.
The new code appears:
5. Open up the unnamed code word and assign the 4-character code, it’s definition and code
word:
MyStandards
26 User Guide
6. Add a second code – right-click the new code list and select Code Value, give the code a
name, code and definition: Thus there is now a new code list called ITNMPGExtendedOrderBreakdownType1 with two values, SPEC and XPEC:
Usage Open the message again, select the field (in this case, Settlement Parties \ 70 Narrative \ Party narrative [PACO] \ 70C \ Narrative \ Line 1 and set the data type to the new data type:
Creating Usage Guidelines
26 June 2012 27
The new data type is now assigned. A narrative field of 4 * 35x has now been restricted to one of two code words:
Redefine a Narrative Field as a Complex Type (MT) In this example, in the MT 502, field 70E (10*35X) TPRO in sequence B ORDRDET, is re-defined as 3 lines of structured information (in other words, anything above 3 lines is not allowed). In addition, line 1 is redefined as a code word list. Line 2 is defined so that a currency code must be specified. Line 3 is specified as 15 digits.
10 * 35x Line 1 Code list with values NEAM and GRAM and GRPE.
MyStandards
28 User Guide
Line 2 3a! – currency code
Line 3 15d
Creation – Code List Create a code list as shown in section Redefine a Text or Narrative Field as a Code List.
Creation – Complex Type 1. Each collection has a Dictionary section:
2. Open the dictionary, right-click Complex Data Type, select New Child and then Complex
Data Type
3. Double-click the newly added Complex Data Type and then give it a name:
Creating Usage Guidelines
26 June 2012 29
4. Right-click the new complex type and select Sub Field:
5. Give the subfield a meaningful name, add a definition and set the multiplicity:
6. Set the date type for line 1, AmountTypeCode to the code list
(TradeProcessingNarrativeLine1Code) that was previously created.
MyStandards
30 User Guide
7. Add two more subfields to the complex date type. Give the subfields meaning names and
definitions and set the multiplicity:
Usage Locate the field in the message which is to be typed by the new complex data type, that is, sequence B ORDRDT, field 70E (10*35X) TPRO, Narrative, Line:
Creating Usage Guidelines
26 June 2012 31
Once the data type has been selected for the field and the screen refreshed, the result is the following:
3.1.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:
Message usage can be specified in two ways:
1. documentation in the comment box
2. advanced – see below
MyStandards
32 User Guide
Example scenario In the Individual Order Details sequence, there is a need to indicate the Order sequence type. This is a code to indicate whether the order is the first order (FIST) or an additional order (FILW). Until the functionality is available in the message, this information is to be specified in an iteration of the Extension sequence:
Either
<Xtnsn> <PlcAndNm> MltplOrdrDtls/ IndvOrdrDtls/OrdrSqncTp</PlcAndNm>
<Txt>FIST or FILW</Txt> </Xtnsn>
Creation and Usage 1. Select the sequence or element to which this extension definition (that is, Order sequence
type) applies. Click the puzzle icon
2. Open up the new Item and enter a name, definition, multiplicity and data type (Extension1)
accordingly:
Creating Usage Guidelines
26 June 2012 33
3. Next – go into the Place And Name element of this new Extension sequence and enter a
Fixed value, in other words the expected content for the field:
The Place and Name field will always be an XML path.
4. Next – go into the Text element of this new Extension sequence and set the expected content for this field. In this scenario, the Text field will be type with a newly created code list.
MyStandards
34 User Guide
The newly defined usage rule for the population of the Extension sequence is now complete. The Text field in a specific iteration of the Extension sequence could be set up as a Fixed value or a code list as described above or left as text, for example Max16Text.
Creating Usage Guidelines
26 June 2012 35
3.2 Usability Features 3.2.1 Standard Practice Rules
When selecting an element and then opening up the standard practice rules lists the restrictions that have been applied to the element.
Selecting one of the applied changes and right-clicking gives a menu and allows more functionality. This particular restriction is to not allow the Address – this change can be applied to the whole message where the data type Postal address 1 is used.
This functionality might be used in the following cases:
1. If you have two sets of message usage defined for the same MX, (for example, you have defined setr.010 for use when the ordering customer is an individual and a second message restriction for when the order customer is an institution) then you can push a change to the 2nd message usage guideline.
2. It’s a manual synchronisation feature
3. Maintenance of message usage restrictions?
MyStandards
36 User Guide
3.2.2 Derive Collection Example usage: there must be two sets of message usage information, one for internal use, the 2nd for external use.
Create your collection and define usage. The derived collection (the child), at this point in time is the same as the first collection (the parent).
Creating Usage Guidelines
26 June 2012 37
The child collection is placed in the Specialisation folder:
Changes are made to the child. In some cases, changes might to be required to both the parent and child (see the section Standard Practice Rules)
When publishing the collections on MyStandards, it could be that it’s decided that the parent collection is published as PUBLIC, but that the child (the internal only specification) is published as PRIVATE. This kind of derived collection functionality may be useful for the publication of external versus internal message restrictions.
3.3 Impact on the Schema Some of the message restrictions are reflected in the schema that can be subsequently generated on the MyStandards website as a result of the message restriction work.
It should be noted that the generation of these restricted schemas or schema subsets is restricted to MyStandards customers that hold a premium license.
Typical impacts on the schema are as follows:
1. Elements designated as Must not be used are deleted from the schema.
2. If the multiplicity of an element is restricted, for example, changed from [0..n] to [0..2], the new multiplicity is reflected in the schema.
MyStandards
38 User Guide
[3] If an optional element is changed to mandatory, the new value is reflected in the schema.
[4] If a data type, such as Extended 350 Code is redefined for a specific field as a code word list, then this is reflected in the schema.
3.4 Supplementary Documents It is sometimes necessary to add documents to a collection or guideline. For example, Investment Funds global market practice documents typically consist of a business process document and then a set of message spread sheets, indicating which fields of the message are to be used globally. These business process documents may also be posted on MyStandards:
1. These documents may be posted at the level of the collection, for example, a single business process document may discuss multiple messages.
2. These documents may be posted at the level of a guideline:
Making Links: It is possible, when specifying a message restriction, to make reference to a document posted to a collection or guideline using the hyperlink.
Legal Notices
26 June 2012 39
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 > Solutions > Standards > More information.
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.