TRM System Admin Guide

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 256 [warning: Documents this large are best viewed by clicking the View PDF Link!]

Wall Street Systems – Empowering Treasury Trade and Settlement
www.wallstreetsystems.com
Wallstreet Suite
TRM
System Administration Guide
Version 7.3.14
2
Information in this document is subject to change without notice and does not represent a commitment on the part
of Wall Street Systems. The software and documentation, which includes information contained in any databases,
described in this document is furnished under a license agreement or nondisclosure agreement and may only be
used or copied in accordance with the terms of the agreement. It is against the law to copy the software or
documentation except as specially allowed in the license or nondisclosure agreement. No part of this publication
may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical,
photocopying, recording, or otherwise, without the prior written permission of Wall Street Systems.
Although Wall Street Systems has tested the software and reviewed the documentation, Wall Street Systems
makes herein no warranty or representation, either expressed or implied, with respect to software or
documentation, its quality, performance, marketability, or fitness for a particular purpose. As a result, this
software is provided "as is", and in no event will Wall Street Systems be liable for direct, indirect, special,
incidental, or consequential damages from any defect in the software or by virtue of providing this
documentation, even if advised of the possibility of such damages. The documentation may contain technical
inaccuracies and omissions.
The mention of an activity or instrument in this publication does not imply that all matters relating to that activity or
instrument are supported by Wallstreet Suite, nor does it imply that processing of or by that activity or instrument is
carried out in any particular way, even if such processing is customary in some or all parts of the industry.
The windows and screen images shown herein were obtained from prototypes during software development. The
actual windows and screen images in the software may differ.
Wall Street Systems, WSS, WALLSTREET, WALLSTREET SUITE and the Wall Street Systems logos are
trademarks of Wall Street Systems Delaware, Inc.
Finance KIT, Trema and Trema logo are trademarks of Wall Street Systems Sweden AB.
Microsoft and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States
and/or other countries.
Adobe, Acrobat, and Acrobat Reader are either registered trademarks or trademarks of Adobe Systems
Incorporated in the United States and/or other countries.
All other products mentioned in this book may be trademarks or service marks of their respective companies or
organizations.
Company names, people names, and data used in examples are fictitious unless otherwise noted.
This edition applies to Wallstreet Suite version 7.3.14 and to all later releases and versions until indicated in new
editions or Wall Street Systems communications. Make sure you are using the latest edition for the release level of
the Wall Street Systems product.
© Copyright 2011 Wall Street Systems IPH AB. All rights reserved.
Second Edition (May 2011)
TRM System Administration Guide 3
Contents
Preface ...........................................................................................................................15
Associated documents ................................................................................................................ 15
1 System processes .....................................................................................................17
1.1 TRM clients ............................................................................................................................ 17
1.1.1 Server processes ............................................................................................................ 17
1.1.2 Onyx ................................................................................................................................ 19
1.1.2.1 Starting Onyx ........................................................................................................ 19
1.1.2.2 Configuring property files ...................................................................................... 19
1.1.2.3 Configuring number of service instances ............................................................. 19
1.1.2.4 Onyx log files ........................................................................................................ 19
1.1.3 User processes ............................................................................................................... 19
1.2 Network bandwidth ............................................................................................................... 20
2 Managing server processes .....................................................................................21
2.1 omniNames ............................................................................................................................ 21
2.2 Onyx rate interface ................................................................................................................ 21
2.3 Automatic start of server processes ................................................................................... 21
2.4 mdsd ....................................................................................................................................... 22
2.5 transd ..................................................................................................................................... 22
2.6 micd ........................................................................................................................................ 23
2.7 reportd .................................................................................................................................... 23
2.8 Limit Server ........................................................................................................................... 23
2.8.1 Start-up script .................................................................................................................. 24
2.8.2 Applying periodic stop/loss limits .................................................................................... 24
2.8.3 Setting up the limit daemon ............................................................................................ 25
2.8.3.1 Standard setup ..................................................................................................... 28
2.8.3.2 Setup with frozen rates ......................................................................................... 28
2.8.4 Checking the limit daemon .............................................................................................. 28
2.9 activityd .................................................................................................................................. 28
2.10 tmd ........................................................................................................................................ 29
2.10.1 Configuring views and books for Treasury Monitor ....................................................... 29
2.11 Configuring Monitor page templates ................................................................................ 31
2.12 Deal mirroring module (DMM) ............................................................................................ 31
4 © Wall Street Systems IPH AB - Confidential
3 Interfaces with other tools .......................................................................................33
3.1 Bloomberg Interface ............................................................................................................. 33
3.1.1 Environment variables .................................................................................................... 33
3.1.2 CSD possibility ................................................................................................................ 35
3.1.2.1 Entity script ...........................................................................................................35
3.1.2.2 Value Mapping Editor script .................................................................................. 36
3.1.2.3 Security Mapping Set Editor ................................................................................. 36
3.1.3 Data License Prices activity process .............................................................................. 37
3.1.4 Two step activity processing ........................................................................................... 37
3.2 Reuters Dealing 3000 Link ...................................................................................................38
3.2.1 Overview ......................................................................................................................... 38
3.2.2 Scripts ............................................................................................................................. 39
3.2.3 Log file ............................................................................................................................ 39
3.2.4 Implementation ............................................................................................................... 39
3.3 Value-at-Risk Interface ......................................................................................................... 39
3.3.1 Default VaR scenario ......................................................................................................39
3.3.2 VaR Mapping Types ....................................................................................................... 39
3.3.3 Default mapping .............................................................................................................. 40
3.3.4 Importing RiskMetrics data to TRM ................................................................................. 40
3.3.4.1 Fetching the risk files ............................................................................................ 40
3.3.4.2 Running the import script ...................................................................................... 40
3.3.5 Importing FEA data to TRM ............................................................................................ 41
3.3.6 VaR horizon .................................................................................................................... 42
3.3.7 Other scripts .................................................................................................................... 42
3.3.7.1 Fetching RM data via FTP .................................................................................... 42
3.3.7.2 Importing volatility and correlations routine .......................................................... 43
3.4 Prices import - Import Market Information Activity ........................................................... 44
3.4.1 Import process ................................................................................................................ 44
3.4.1.1 Import files list .......................................................................................................44
3.4.1.2 Validating the files ................................................................................................ 45
3.4.1.3 Parsing the files .................................................................................................... 45
3.4.2 Environment variables .................................................................................................... 46
3.4.3 Format of the import file .................................................................................................. 47
3.4.3.1 Query properties ................................................................................................... 47
3.4.3.2 Price data properties ............................................................................................ 47
3.4.3.3 Example imports ................................................................................................... 47
3.4.4 Permissions .................................................................................................................... 48
3.4.5 CSD possibilities ............................................................................................................. 48
3.4.6 Validation of Imported Prices .......................................................................................... 49
3.4.6.1 CSD validation ...................................................................................................... 49
3.5 Using comKIT ........................................................................................................................ 50
3.5.1 Overview ......................................................................................................................... 50
3.5.2 comKIT services ............................................................................................................. 50
4 Using Import Export tool ..........................................................................................53
4.1 Introduction ........................................................................................................................... 53
TRM System Administration Guide 5
4.2 Features ................................................................................................................................. 53
4.3 Structure of the Import Export tool ..................................................................................... 53
4.3.1 File organization and inheritance .................................................................................... 54
4.4 Importing data ....................................................................................................................... 54
4.5 Definition file (.def) ................................................................................................................ 55
4.5.1 Templates ....................................................................................................................... 55
4.5.2 Layout syntax of the template ......................................................................................... 55
4.5.2.1 Header ..................................................................................................................56
4.5.2.2 Body ..................................................................................................................... 56
4.5.2.3 Trailer ................................................................................................................... 56
4.5.2.4 Body template ....................................................................................................... 57
4.5.3 Variables ......................................................................................................................... 57
4.5.3.1 Definition of variables ........................................................................................... 58
4.5.3.2 Command line variables ....................................................................................... 58
4.5.3.3 Variables section in .def file .................................................................................. 58
4.5.3.4 Syntax of environment variables .......................................................................... 58
4.5.3.5 Built-in variables ................................................................................................... 59
4.5.4 Format ............................................................................................................................. 59
4.5.4.1 Data type definitions ............................................................................................. 60
4.5.4.2 Predefined data types ........................................................................................... 60
4.5.4.3 Format options of data types ................................................................................ 60
4.6 Perl functions (the Interface class) ..................................................................................... 62
4.6.1 Export hook functions .....................................................................................................62
4.6.1.1 Start functions ....................................................................................................... 62
4.6.1.2 Finish functions ..................................................................................................... 63
4.6.2 Import hook functions ...................................................................................................... 63
4.6.2.1 Start functions ....................................................................................................... 63
4.6.2.2 Finish functions ..................................................................................................... 63
4.6.3 Overriding default functions ............................................................................................ 63
4.7 External packages: predefined modules ............................................................................ 63
4.8 Running Import Export tool ................................................................................................. 64
4.8.1 Running from the command line ..................................................................................... 64
4.8.2 Methods of script execution ............................................................................................ 65
4.9 Debugging ............................................................................................................................. 65
4.10 Interface class ..................................................................................................................... 65
4.10.1 Interface class functions ............................................................................................... 66
4.10.2 Interface member functions .......................................................................................... 66
4.11 TemplateInterface class ..................................................................................................... 67
4.11.1 TemplateInterface class functions ................................................................................ 68
4.11.2 TemplateInterface member functions ........................................................................... 68
4.12 Empty sample files .............................................................................................................. 71
4.12.1 Definition file ................................................................................................................. 71
4.12.2 Empty Perl module ........................................................................................................72
5 Setting up message management ...........................................................................75
6 © Wall Street Systems IPH AB - Confidential
5.1 Overview ................................................................................................................................ 75
5.2 Transaction and Entity flow .................................................................................................76
5.3 Message Manager and Message flow ................................................................................. 76
5.4 Examples of messages ......................................................................................................... 77
5.5 Setting up Message Manager ............................................................................................... 77
5.6 Previews ................................................................................................................................. 77
5.7 Extracting data ...................................................................................................................... 78
5.7.1 Expressions .................................................................................................................... 78
5.7.1.1 Single Field ........................................................................................................... 78
5.7.1.2 Result set (multiple fields) .................................................................................... 80
5.7.1.3 System functions .................................................................................................. 82
5.7.2 SQL code in stored procedures ...................................................................................... 83
5.7.3 Filters .............................................................................................................................. 83
5.8 Setting up Document Formatter .......................................................................................... 83
5.8.1 Prerequisites ................................................................................................................... 83
5.8.2 Settings ........................................................................................................................... 84
5.8.3 Authoring template documents ....................................................................................... 84
5.8.4 Saving Word 2007 XML files ........................................................................................... 86
5.8.5 Authoring common placeholders .................................................................................... 86
5.8.6 Including reusable text (subdocuments) ......................................................................... 86
5.8.6.1 Writing and uploading templates .......................................................................... 86
5.8.6.2 Defining the expressions ...................................................................................... 88
5.8.7 Customizing the e-mail body ........................................................................................... 88
5.8.8 Customizing rounding numbers and amounts ................................................................ 89
5.9 Message transfer ................................................................................................................... 89
5.9.1 E-mail example ............................................................................................................... 90
5.9.2 Fax example 1 ................................................................................................................ 90
5.9.3 Fax example 2 ................................................................................................................ 91
5.9.4 Printer example ............................................................................................................... 91
5.10 Possible problems and solutions ...................................................................................... 92
5.10.1 Developing test cases ................................................................................................... 92
5.10.2 Previewing transactions ................................................................................................ 92
5.10.3 Test script for previewing transactions .......................................................................... 93
5.10.4 CORBA error when previewing ..................................................................................... 93
5.10.5 E-mail problems on windows ........................................................................................ 93
5.10.6 Error evaluating 'Source.field' ....................................................................................... 93
5.10.7 Checking the generated messages .............................................................................. 94
5.10.8 Filters do not work ......................................................................................................... 94
6 Managing static data .................................................................................................97
6.1 Introduction ........................................................................................................................... 97
6.1.1 Static data workflow ........................................................................................................ 97
6.1.2 Static data workflow with 4-eyes verification ................................................................... 99
6.1.3 Static data workflow: CMM and TRM .............................................................................. 99
6.2 Setting up static data management ................................................................................... 100
TRM System Administration Guide 7
6.2.1 State and state flow setup ............................................................................................. 101
6.2.1.1 Next state after an Accept action ........................................................................ 102
6.2.1.2 Creating and deleting states ............................................................................... 103
6.2.2 Mode setup ................................................................................................................... 103
6.2.2.1 The four system modes ...................................................................................... 104
6.2.2.2 Creating and deleting modes .............................................................................. 104
6.3 TRM with CMM - static data changes ................................................................................ 104
6.3.1 Dependencies between entities .................................................................................... 105
6.4 Using SDM-managed entities ............................................................................................. 107
6.4.1 Using static data editors ................................................................................................ 107
6.4.2 Using SDM Manager applications ................................................................................. 107
6.4.2.1 SDM Query application ....................................................................................... 107
6.4.2.2 SDM Verify application ....................................................................................... 107
6.4.2.3 SDM Admin application ...................................................................................... 108
6.5 Tables and processes used ............................................................................................... 108
7 Setting up transaction and entity flow ..................................................................111
7.1 Transaction flow and entity flow ....................................................................................... 111
7.2 Loading default transaction flow ....................................................................................... 111
7.3 Setting up transaction flow ................................................................................................ 112
7.3.1 Setting permissions ....................................................................................................... 112
7.3.2 Setting Transaction Status ............................................................................................ 113
7.3.3 Setting transaction tags ................................................................................................ 113
7.3.4 Setting Transaction States ............................................................................................ 114
7.3.4.1 Transaction State flags ....................................................................................... 114
7.3.4.2 Transaction State contexts ................................................................................. 116
7.3.5 Setting up flow operations ............................................................................................. 116
7.3.5.1 Setting condition Calls ........................................................................................ 117
7.3.5.2 Setting up agents ................................................................................................ 120
7.3.5.3 Using masks in agent setup ............................................................................... 125
7.3.5.4 Setting up service queues .................................................................................. 126
7.3.5.5 Testing transaction flow ...................................................................................... 127
7.3.5.6 Converting flow.py to CSV format ...................................................................... 128
7.3.5.7 Migrating a transaction flow from a pre-7.2 version ............................................ 128
7.3.6 Setting up a COMMIT operation ................................................................................... 129
7.3.7 Setting up status operations ......................................................................................... 129
7.3.8 Setting up limit operations ............................................................................................. 129
7.4 Using Transaction Manager modes .................................................................................. 130
7.4.1 Loading default modes .................................................................................................. 130
7.4.2 Setting up modes ......................................................................................................... 131
7.4.3 Example of mode setup ................................................................................................ 145
7.5 Database objects for transaction flow and modes .......................................................... 146
7.6 Loading default entity flows ............................................................................................... 147
7.6.1 Entity broker-based flow ............................................................................................... 147
7.6.2 CLM loan action-based flow .......................................................................................... 149
8 © Wall Street Systems IPH AB - Confidential
7.7 Setting up entity broker-based flow .................................................................................. 149
7.7.1 Entity States .................................................................................................................. 149
7.7.2 Cashflow actions for Call Money / Account ................................................................... 150
7.7.3 Entity Rules ................................................................................................................... 151
7.7.4 Entity broker operations ................................................................................................ 152
7.7.4.1 Condition calls .................................................................................................... 152
7.7.4.2 Agents ................................................................................................................ 154
7.7.4.3 Service queues ................................................................................................... 158
7.7.5 Entity Manager Modes .................................................................................................. 159
7.7.5.1 Loading default modes ....................................................................................... 160
7.7.5.2 Setting up modes ................................................................................................ 160
7.7.6 Setup scripts and database objects .............................................................................. 161
7.8 Setting up loan entity action-based flow .......................................................................... 163
7.8.1 Loan Entity States ......................................................................................................... 163
7.8.2 Loan Entity Rules .......................................................................................................... 164
7.8.3 Loan Entity Actions ....................................................................................................... 164
7.8.4 Setup scripts and database objects .............................................................................. 166
7.9 Setting up transaction and settlement comments ........................................................... 166
8 Controlling user access .........................................................................................169
8.1 Managing TRM users .......................................................................................................... 169
8.1.1 Creating TRM user accounts ........................................................................................ 169
8.1.2 Deleting a TRM user account ....................................................................................... 169
8.1.3 Locking a TRM user account ........................................................................................ 170
8.1.4 Setting the System Security Officer role ....................................................................... 170
8.2 User groups ......................................................................................................................... 170
8.2.1 Default user groups in TRM .......................................................................................... 170
8.2.2 Assigning users to a group ........................................................................................... 171
8.3 Password expiry .................................................................................................................. 171
8.4 Domains ............................................................................................................................... 171
8.5 Permissions ......................................................................................................................... 171
8.5.1 Setting up the object permissions ................................................................................. 171
8.5.2 Domain permission ....................................................................................................... 172
8.5.3 Portfolio access ............................................................................................................. 172
8.5.4 Mode permissions ......................................................................................................... 172
8.5.5 Payment mode permissions .......................................................................................... 172
8.6 Limiting access to activity types ....................................................................................... 172
8.7 Using Security Center ......................................................................................................... 173
8.7.1 User Administration Editor ............................................................................................ 174
8.7.1.1 Creating a new group ......................................................................................... 174
8.7.1.2 Modifying an existing group ................................................................................ 175
8.7.1.3 Deleting an existing group .................................................................................. 175
8.7.1.4 Creating a new user ........................................................................................... 175
8.7.1.5 Modifying an existing user .................................................................................. 176
8.7.1.6 Deleting an existing user .................................................................................... 176
TRM System Administration Guide 9
8.7.1.7 Searching for a user ........................................................................................... 177
8.7.1.8 Assigning portfolio permissions to users and user groups ................................. 177
8.7.1.9 Assigning domain permissions to users and user groups .................................. 178
8.7.1.10 Assigning multiple groups to users and user groups ........................................ 178
8.7.2 Password Change ......................................................................................................... 179
8.7.2.1 Password expiry and validation .......................................................................... 180
8.7.3 Permission Editor .......................................................................................................... 180
8.7.3.1 Navigating through Permission Editor ................................................................ 181
8.7.3.2 Granting a permission ........................................................................................ 181
8.7.3.3 Removing an existing permission ....................................................................... 182
8.7.3.4 Single-screen 4-eyes principle ........................................................................... 182
8.7.3.5 Granting Deal Mirroring permissions .................................................................. 182
8.7.4 Object Hierarchy Editor ................................................................................................. 183
8.7.4.1 Adding an object ................................................................................................. 183
8.7.4.2 Removing an object ............................................................................................ 183
8.7.4.3 Moving an object ................................................................................................ 184
8.7.4.4 Renaming an object ............................................................................................ 184
8.7.5 Reports ......................................................................................................................... 184
8.7.5.1 Portfolios Report ................................................................................................. 184
8.7.5.2 Domains Report .................................................................................................. 185
8.7.5.3 Objects Report .................................................................................................... 185
8.7.5.4 User Groups Report ........................................................................................... 185
8.7.5.5 Users Information Report ................................................................................... 185
8.8 Domain Editor ...................................................................................................................... 186
8.8.1 Creating a new domain ................................................................................................. 186
8.8.2 Modifying an existing domain ........................................................................................ 186
8.8.3 Deleting a domain ......................................................................................................... 187
9 Configuration Table Editor and Admin Center ....................................................189
9.1 Introduction ......................................................................................................................... 189
9.2 Configuration Table Editor ................................................................................................. 189
9.3 Admin Center ....................................................................................................................... 193
9.3.1 Renaming Tool .............................................................................................................. 194
9.3.1.1 Renaming a portfolio ID ...................................................................................... 194
9.3.1.2 Renaming a client ID .......................................................................................... 195
10 Customizing TRM user interfaces .......................................................................197
10.1 Setting up menus .............................................................................................................. 197
10.2 Setting up title bars ........................................................................................................... 197
10.3 Deactivating splash screen .............................................................................................. 197
10.4 Selecting a theme .............................................................................................................. 197
10.5 Customizing Transaction Manager ................................................................................. 198
10.5.1 Transaction Manager default configuration ................................................................. 198
10.5.2 Overriding the default configuration ............................................................................ 199
10.5.3 Adding custom parameters to Transaction Manager actions ...................................... 199
10 © Wall Street Systems IPH AB - Confidential
10.5.4 Removing a toolbar button from the Transaction Manager ......................................... 200
10.6 Customizing Enter Board ................................................................................................. 200
10.6.1 Adding the entity definition .......................................................................................... 200
10.6.2 Making fields accessible ............................................................................................. 201
10.6.3 Making properties available ........................................................................................ 201
11 Managing activities ...............................................................................................203
11.1 Overview ............................................................................................................................ 203
11.2 ActivityType table ............................................................................................................. 203
11.3 Generating Windows NT Reports .................................................................................... 203
11.3.1 Starting the cron service ............................................................................................. 203
11.3.2 Scheduling NT Reports ............................................................................................... 204
12 Setting up comKIT ................................................................................................205
12.1 Introduction ....................................................................................................................... 205
12.2 comKIT Components ........................................................................................................ 205
12.3 comKIT Server ................................................................................................................... 205
12.3.1 Architecture ................................................................................................................. 205
12.3.1.1 Garbage collecting ............................................................................................ 206
12.3.1.2 TRM Naming Service ....................................................................................... 206
12.3.1.3 comKIT Server Parameters .............................................................................. 206
12.3.2 comKIT Server Configuration ...................................................................................... 206
12.3.2.1 Naming Service ................................................................................................ 206
12.3.2.2 Firewall ............................................................................................................. 206
12.3.2.3 SSL ................................................................................................................... 207
12.3.2.4 omniORB .......................................................................................................... 207
12.4 comKIT Client .................................................................................................................... 207
12.4.1 Python ......................................................................................................................... 207
12.4.2 Java ............................................................................................................................ 207
12.4.3 Exceptions .................................................................................................................. 208
13 Configuring and customizing reports .................................................................209
13.1 Report Generator components ........................................................................................ 209
13.1.1 Dataloader modules .................................................................................................... 209
13.1.2 Report engine ............................................................................................................. 210
13.1.3 Report Generator UI ................................................................................................... 210
13.1.4 ReportD ....................................................................................................................... 210
13.1.5 Cover pages, headers, and footers ............................................................................. 210
13.2 Applying report definitions .............................................................................................. 210
13.3 Sample report definition file ............................................................................................. 211
13.3.1 Main section ................................................................................................................ 212
13.3.2 Rename section .......................................................................................................... 212
13.3.3 Filter section ................................................................................................................ 213
13.4 Configuring New Report submenu .................................................................................. 213
TRM System Administration Guide 11
13.5 Setting up layout files ....................................................................................................... 214
13.6 Running related reports ................................................................................................... 214
13.6.1 drilldown.ini files .......................................................................................................... 214
13.6.2 .frd report types ........................................................................................................... 214
13.7 Customizing reports in python ........................................................................................ 215
13.8 Customizing reports in perl ............................................................................................. 215
13.9 Printing reports from the command line (Windows only) ............................................. 215
13.9.1 Main section ................................................................................................................ 216
13.9.2 Parameters section ..................................................................................................... 216
13.10 Executing reports from the command line ................................................................... 216
14 Generating verification reports ............................................................................217
14.1 General System Auditing ................................................................................................. 217
14.1.1 Domain Map Verification report .................................................................................. 217
14.1.2 Market Info Map Verification report ............................................................................. 217
14.1.3 Property Map Verification report ................................................................................. 218
14.1.4 Price Verification report ............................................................................................... 218
14.2 Instrument auditing ........................................................................................................... 219
14.2.1 Instrument Feature Verification report ........................................................................ 219
14.2.2 Instrument Result Verification report ........................................................................... 219
14.3 Transaction Auditing ........................................................................................................ 219
14.3.1 Transaction Classification Verification report .............................................................. 219
14.4 Relationship auditing ........................................................................................................ 220
14.4.1 Entity Relationship Verification report ......................................................................... 220
14.5 Client auditing ................................................................................................................... 220
14.5.1 Client Accounts Verification Report ............................................................................ 220
15 Routine system admin operations ......................................................................223
15.1 Database administration using Admin Center ............................................................... 223
15.1.1 Database statistics (TRM tables) ................................................................................ 223
15.1.2 Connected Users ........................................................................................................ 224
15.1.3 Database consistency check (Microsoft SQL Server and Sybase only) ..................... 224
15.1.4 Log Truncation ............................................................................................................ 226
15.1.5 History Log .................................................................................................................. 227
15.1.6 Database Cleanup ...................................................................................................... 228
15.2 Setting Application Manager timeout .............................................................................. 228
16 FIX trading platform interface ..............................................................................229
16.1 Components ...................................................................................................................... 229
16.2 Component interactions ................................................................................................... 230
16.3 Workflow related to the trading platform ........................................................................ 231
16.4 Site customization ............................................................................................................ 231
12 © Wall Street Systems IPH AB - Confidential
16.4.1 process_order ............................................................................................................. 231
16.4.2 process_execution_report ........................................................................................... 232
16.4.3 process_cancel_request ............................................................................................. 232
Appendix A: Utility programs and scripts ...........................................................................233
A.1 Scripts ................................................................................................................................. 233
A.2 Real-time diagnostic tools ................................................................................................. 234
A.2.1 Monitoring Message Bus status ................................................................................... 234
A.2.1.1 Troubleshooting destinations ............................................................................. 235
A.2.2 md-status ...................................................................................................................... 235
A.2.3 md-trace ....................................................................................................................... 236
A.3 psql (Microsoft SQL Server and Sybase only) ................................................................. 237
A.3.1 Options ......................................................................................................................... 237
A.3.2 Commands ................................................................................................................... 238
A.4 Debugging ........................................................................................................................... 238
A.4.1 Tracing accesses to the database ................................................................................ 238
A.4.1.1 Tracing an end-user application (Windows) ....................................................... 238
A.4.1.2 Tracing a real-time application (UNIX) ............................................................... 239
A.4.2 Tracing TRM messages (Windows) ............................................................................. 239
A.4.2.1 Setting the trace level and log file output ........................................................... 239
A.4.2.2 Trace prefixes .................................................................................................... 240
Appendix B: Object permissions..........................................................................................243
B.1 List of TRM permissions .................................................................................................... 243
Appendix C: Unix operations................................................................................................245
C.1 Unix operations .................................................................................................................. 245
C.1.1 TRM Server Passwords ............................................................................................... 245
C.1.1.1 Passwords for server processes ....................................................................... 245
C.1.1.2 Sample .fk-login file ............................................................................................ 246
C.1.1.3 Checking shared memory .................................................................................. 247
C.1.2 Startup scripts .............................................................................................................. 247
C.1.3 Scheduled processes (crontab) .................................................................................... 247
Appendix D: Configuring Dashboard...................................................................................249
D.1 Introduction ......................................................................................................................... 249
D.2 Data sources configuration ............................................................................................... 250
D.2.1 Treasury Position ......................................................................................................... 250
D.2.2 Cash Management Reports ......................................................................................... 250
D.2.3 Report Generator ......................................................................................................... 250
D.2.4 Limits ............................................................................................................................ 251
D.2.5 Dashboard client application ........................................................................................ 251
Appendix E: Adding valuation modes..................................................................................253
TRM System Administration Guide 13
Appendix F: External valuation.............................................................................................255
14 © Wall Street Systems IPH AB - Confidential
TRM System Administration Guide 15
Preface
This guide describes the system administration tasks required for Transaction and Risk Module
(TRM).
The guide aims to:
Provide guidelines for the system administration of TRM
Provide documentation on scripts and procedures
This guide is intended for system administrators who maintain and administer TRM. Administrators
should have experience with the following:
Common Object Request Broker Architecture (CORBA)
Perl and Python scripts
The database used with TRM is a customer asset and its operation, maintenance, and administration
should be under the control of a qualified DBA. It is the DBA’s responsibility to ensure that the
maintenance of the database used with TRM reflects customer policies and procedures.
Associated documents
TRM User Guide
comKIT API Reference provided in TRM installation:
FK_HOME\support\comKIT\doc\idl\html\index.html (Windows platform only)
Wallstreet Suite Installation Guide
Wallstreet Suite System Admin Guide
Wallstreet Suite Database Setup Guide
16 © Wall Street Systems IPH AB - Confidential
TRM System Administration Guide 17
Chapter 1 System processes
1.1 TRM clients
The TRM clients can be divided into server processes that take care of the underlying information
flow between all TRM processes and user processes (for example monitors and editors).
1.1.1 Server processes
The server processes are as follows:
More details about these processes, see Chapter 2 Managing server processes on page 21.
Process Description
ActiveMQ Message bus
omniNames CORBA name server
mdsd Message Delivery System daemon (central point for all real-time traffic)
transd Deal transfer daemon for TRM
micd Market Information Calculation daemon (produces derived rates)
limitd Limit daemon
activityd Activity-launching daemon
tmd Treasury Monitor daemon
comkitd comkit daemon
reportd Generates reports on demand for TRMWeb.
serviced Service deamons, load CORBA modules to process and deliver data through
particular business logic.
sessiond Session deamons, deliver data to the end user through persistent connections
(sessions) that can be distributed among several instances.
TRM - Onyx Rate Interfaces Rate Feeder, Rate Saver, MDSD Gateway and Rate Broadcaster
1 System processes
1.1 TRM clients
18 © Wall Street Systems IPH AB - Confidential
The server processes, which may run on their own dedicated server computers, use CORBA for
inter-operability. The name server connects to all the processes and allows the server processes as
well as the user processes to locate each other. The following is a summary of how this works:
The ORB (Object Request Broker) is configured with a naming service with a dedicated port for
requests.
When an application connects to the mdsd, it uses the naming server to locate it. It then registers
a callback-object with the server. The server connects to this object whenever it needs to send
updates to the client.
A timeout parameter to the server defines how long the connection is alive, and the connection
is restored on an as-needed basis if it has timed-out.
RateFeeder SaverQ RateSaver
Broadcaster
Broadcaster Q
micd Q
Rate Monitor Q
transd Q
Topic Tree
Topic Tree
micd Other C++
apps Rate Monitor
transd
mdsd
C++ apps
mdsd
Gateway
Database
Onyx
process
C++
applications
Key:
Queue
1 System processes
1.1 TRM clients
TRM System Administration Guide 19
1.1.2 Onyx
Onyx is a simple Java application server. It is complementary to ServiceD, which is used to run
services written in Python or c++.
1.1.2.1 Starting Onyx
Onyx is started by the following command:
On Windows
> onyx.bat
On Unix
> rc.onyx
It takes a space-separated list of services as arguments. For example, to start Onyx with the
services trmstaticdata and esiadapter, enter:
> rc.onyx trmstaticdata esiadapter
1.1.2.2 Configuring property files
Configuration files for Onyx and Onyx services are located under
$FK_HOME/etc/onyx/configuration/context/properties. This directory contains files with the
extension '.properties'. Each service has a configuration file named
'<service-name>.properties' (for example esiadapter.properties).
Some property files are used by all services (jdbc.properties, jms.properties,
ssl.properties, dbkit.properties, appserver.properties). You need to configure only the
property files required by the services you want to run. See the documentation of each service for
more information.
1.1.2.3 Configuring number of service instances
Each service in Onyx can be run in a specified number of instances. To change the number of
instances, edit the file
$FK_HOME/etc/onyx/configuration/services/<service-name>-bootstrap.xml.
Do not change anything in the content of the file except of number of instances, as in this example:
<bean id="esiadapterInitializer" class="biz.wss.onyx.server.ServiceInitializer">
<property name="provider" value="esiadapterClientRequest"/>
<property name="instances" value="1"/>
</bean>
1.1.2.4 Onyx log files
By default, Onyx and all its services create log files in the $FK_HOME/var/log structure
(onyx_trmswift.log in $FK_HOME/var/log/trmswift, onyx_basics.log in
$FK_HOME/var/log/trm). To change the level of logging detail, edit the file
$FK_HOME/etc/onyx/configuration/context/log4j.xml.
For logging, Onyx uses the Java open source library Log4J.
1.1.3 User processes
The main TRM user processes are:
Transaction Managers (for example Deal Capture)
Monitors (for example Treasury Monitor)
Editors (for example Instrument Editor)
Reports. Reports are generated on demand (TRMWeb only).
1 System processes
1.2 Network bandwidth
20 © Wall Street Systems IPH AB - Confidential
They all connect to the database when they are started, to read in their configuration data.
1.2 Network bandwidth
The network bandwidth required for TRM depends totally on the usage of the system. Entering a
deal in Deal Capture, for example, initiates a stored procedure (SQL insert to the database server)
and a real-time update to the mdsd. The network traffic for this kind of operation would be very
limited. An entry made with one of the editors, for example Client Editor, would also cause very
limited traffic.
There are two main traffic types: traffic between TRM applications and the TRM server processes,
and traffic between TRM applications and the TRM database.
The network traffic that is generated by receiving market information (for example, Reuters or
Telerate) will basically depend on the instruments configured in the system and the rate that they
are receiving updates from the information source.
It is also highly dependent on how the system is used. For example, Limit Monitor generates
different network traffic depending on the data used when started. This makes it very difficult to
predict how much network traffic will be generated.
The factor that has the most impact on network traffic is the update rate on the market information.
The update rate may be different from various providers.
The network traffic generated when the users request reports will depend on the parameters that
are given as well as the size and contents of the database. Reports or Treasury Monitor can cause a
lot of network traffic.
TRM System Administration Guide 21
Chapter 2 Managing server processes
The TRM server processes use a CORBA-based messaging technique for inter-process
communication. Two processes, mdsd and limitd, are contacted by other processes and
applications.
2.1 omniNames
The CORBA Names server must be running before any of the TRM server processes can function.
2.2 Onyx rate interface
The Onyx Rate Interface consists of the following Onyx processes:
2.3 Automatic start of server processes
All server processes, including the market information links, can be automatically restarted during
boot by:
On UNIX: running the setup.fk script as follows:
cd $FK_HOME/etc
./setup.fk
Running the script puts the system passwords into memory.
Process Description
Rate Feeder Rate Feeder is responsible for retrieving the native rate format and converting it to
the standard message format used in Wallstreet Suite. Currently, the Reuters API
in version 7.3 is based on the Reuters Foundation API for Java (RFAJ) 6.3. It
Reuters’ latest and strategic API for connecting to RMDS servers. This API
introduces a new message format and a more efficient binary communication
protocol.
Rate Saver Rate Saver is responsible for storing real time or calculated rates into the
database. Special filtering logic can be applied in order to tune the frequency of
stored real time and calculated rates.
MDSD Gateway MDSD Gateway itransfers rate messages from the ActiveMQ platform to the
CORBA platform in order to distribute rates via MDSD.
Rate Broadcaster Rate Broadcaster distributes rates over the system and it takes over this role from
mdsd. Applications subscribe to the Rate Broadcaster to obtain new rate
messages.
2 Managing server processes
2.4 mdsd
22 © Wall Street Systems IPH AB - Confidential
On Windows: In Start - Control Panel - Administrative Tools - Services, ensure that the Startup Type of all
Wallstreet Suite services is Automatic.
Note: When running Telerate, the tipd process should be started as the Telerate user aws. If not,
it will not start up properly.
Refer also to the description of Process Monitor daemons in the WSS System Admin Guide.
2.4 mdsd
The mdsd (Message Delivery System Daemon) is the hub of all real-time information flow. It is
essential for the real-time components of TRM. All activities requiring real-time updates must
indicate this by creating a connection with the mdsd.
The mdsd is a message exchange service. It allows for the arrival of correctly formatted messages
that are then broadcast to the processes that have indicated an interest in that particular message.
When a client (process) connects to mdsd, it requires a response to indicate that its request has
been accepted.
All applications (user and server processes) connect to mdsd. Some only receive information, like
Treasury Monitor and FX Forward Pricing; others send information, like Editors and Transaction
Manager.
2.5 transd
The transd real-time process is used to send information to the real-time server about updates of
prices and transactions that are imported or changed in a way that is not otherwise notified to the
mdsd.
Note: This is a required process for the Limit Monitor.
The PushPendingPrices and PushPendingTransactions procedures are used to update the
PendingPrices and PendingTransactions tables which are being read by the transd process.
Option/Argument Description
--log-directory arg Directory for log files
--service-name arg Service name to register with CosNaming
--max-queue-size arg Maximum allowed queue length for clients
--timeout-interval arg Timeout for non-responsive clients
Option/Argument Description
-I arg
--interval arg
Interval in milliseconds to check (default 70000)
-T arg
--topic arg
Topic to listen to
2 Managing server processes
2.6 micd
TRM System Administration Guide 23
2.6 micd
The micd real-time process calculates yield curves and derived rates. This process logs in to the
database as user batch.
2.7 reportd
The reportd program generate reports on demand. It is launched by TRMWeb, retrieves the report
data, supplies them to TRMWeb and terminates.
2.8 Limit Server
The TRM limit deamon monitors updates of transactions and market information changes. It accepts
connections from TRM applications and sends out information about the usage of current limits. The
limit servers watch the limits that are set up.
The limit deamon exists in two versions:
limitd: the CORBA service, which only computes limits and serves data to applications
Option/Argument Description
-i arg
--include arg
Include given rates (default all)
-e arg
--exclude arg
Exclude given rates
-s arg
--init-scenario arg
List of scenarios to initialize by default
-d arg
--init-date arg
List of dates to initialize by default
-n
--dont-send
Inhibit sending of quotes, useful for debugging
-b
--batch
Batch mode, finish immediately after startup
--interval arg Interval in milliseconds to check.
--source-name arg Source name (default MICD)
Option/Argument Description
-l arg
--layout arg
Report layout
-t arg
--type arg
Report type
-f arg
--format arg (=bin)
Output format (bin|xml|xml3|html|txt|csv)
-p arg
--param arg
Report list of report parameters (-p name1=value1 -p name2=value2
etc.)
2 Managing server processes
2.8 Limit Server
24 © Wall Street Systems IPH AB - Confidential
sessiond: the distributed limit service, which monitors limits, processes limit violations, and
serves data to the end user using persistent connections via the message bus.
2.8.1 Start-up script
On Unix systems, the script $FK_HOME/etc/rc/rc.limitd -e <environment> starts the limit
daemon for the specified environment.
The limit daemon can be run in a periodic mode in the same way as Treasury Monitor, for example,
is run (both Start Date and End Date are used as a selection criteria when starting up the server).
2.8.2 Applying periodic stop/loss limits
The period against which the limit daemon is run is critical in applying periodic stop/loss limits. The
Period End Date is currently always the current date. The generation of Period Start Date is made
based on three start-up options for the limit daemon described in the following tables:
Period Method = NUMBER-OF-DAYS
This method can be used as a default if no Period Method has been given and the server is run
in a periodic mode.
Option/Argument Sessiond option Description
--use-business-days arg -s "use-business-days=arg" Use business days, affects how
period-method operates.
--start-date-value arg -s "start-date-value=arg" The number of days offset from
end-date (start-date = end-date -
offset)
--period-method arg -s "period-method=arg" Specify period method,
NUMBER-OF-DAYS, CURRENT-WEEK, or
CURRENT-MONTH
If --use-business-
days is set to No
(Default)
If NUMBER-OF-DAYS is used as Period Method and the parameter
--use-business-days is set to No, the preferred length of the period has to be
given as the number of days in parameter --start-date-value. The Start Date
for the limit daemon is then selected as:
Current Date - Start Date Value +1
where:
"1" in Start Date Value would result in the limit daemon being run with Start Date
= End Date (i.e. the current method). If nothing is given in
--Start-date-value, "1" should be used as default.
If --use-business-
days is set to Yes
If the parameter --use-business- days is set to Yes, the preferred length of
the period has to be given as number of business days in parameter
--start-date-value. The Start Date for the limit daemon is then selected as:
Current Date - Start Date Value +1
where:
Start Date Value is interpreted as business days validated against the calendar of
the base currency of the Portfolio ID used as a start up criteria for the limit
daemon.
"1" in Start Date Value would result in the limit daemon being run with Start Date
= End Date unless the previous day was a non-banking day. In this case, the
Start Date would be selected as one day after the previous business day.
2 Managing server processes
2.8 Limit Server
TRM System Administration Guide 25
Period Method = CURRENT-WEEK
Period Method = CURRENT-MONTH
2.8.3 Setting up the limit daemon
The environment variable $FK_LIMITD_SETUP is used to supply options to the rc.limitd script. On
UNIX, run $FK_HOME/sbin/limitd --help to list the available options; on Windows, run
%FK_HOME%\bin\limitd --help.
If --use-business-
days is set to No
(Default)
If CURRENT-WEEK is used as Period Method and the parameter
--use-business-days is set to No, the Start Date for the limit daemon is
selected as:
The closest past date for which the number of weekday was the same as the value
given in the parameter --start-date-value (1-7).
End Date is used as Start Date if the number of weekday of End Date (i.e. current
date) is the same as the value given in the parameter --start-date-value.
If --use-business-
days is set to Yes
If CURRENT-WEEK is used as Period Method and the parameter
--use-business-days is set to Yes, the Start Date for the limit daemon is
selected by:
Adding one day to the last business day preceding the closest past date for which
the number of weekday was the same as the value given in the parameter
--start-date-value (1-7).
For example, "1" (referring to Monday) is given as --start-date-value and the
server is started up on Wednesday.
The Start Date is selected by first going back to the previous Monday, then further
to last business day preceding Monday (normally Friday) and by adding one day to
it (i.e. ending up with Saturday).
End Date is used as a preliminary Start Date (i.e. before business day adjustment)
if the number of weekday of End Date (i.e. current date) is the same as the value
given in the parameter --start-date-value.
For example, in the previous example, the previous Saturday would be selected as
Start Date even when the server was started up on Monday.
If --use-business-
days is set to No
(Default)
If CURRENT-MONTH is used as Period Method and the parameter
--use-business-days is set to No, the Start Date for the limit daemon is
selected as:
The closest past date for which the number of day of month was the same as the
value given in the parameter --start-date-value (1-31).
End Date is used as Start Date if the number of day of month of End Date (i.e.
current date) is the same as the value given in the parameter
--start-date-value.
If --use-business-
days is set to Yes
If CURRENT-MONTH is used as Period Method and the parameter
--use-business-days is set to Yes, the Start Date for the limit daemon is
selected by:
Adding one day to the last business day preceding the closest past date for which
the number of day of month was the same as the value given in the parameter
--start-date-value (1-31).
For example, "1" is given as Start Date Value and the server is started up on 10th.
The Start Date is selected by first going back to first of month, then further back
to the last business day preceding the 1st day and then by adding one day to it.
End Date is used as a preliminary Start Date (i.e. before the business day
adjustment) if the number of day of month of End Date (i.e. current date) is the
same as the value given in the parameter --start-date-value.
2 Managing server processes
2.8 Limit Server
26 © Wall Street Systems IPH AB - Confidential
The following table outlines some of the typical definitions:
Option/Argument Description
--batch limits Run only once to compute and log the limits.
--category-warning-thresholds arg To generate a warning message when the threshold level,
expressed as a percentage, is reached for the corresponding
category. For example, if the categories CREDIT and
SETTLEMENT have been specified with the
--limit-categories parameter, then
--category-warning-threshold 75 80 specifies a
threshold of 75% for CREDIT and 80% for SETTLEMENT.
(Available categories are shown in the Limit Editor.)
--contexts arg The result contexts to include.
--end-date arg Period end-date, defaults to today.
--exclude-limit-categories arg Do not update specified limit categories.
--exclude-limits arg Do not update specified limits.
--exclude-limits-match arg Do not update limits matching.
--interval arg The update interval in milliseconds.
--limit-categories arg Update only specified limit categories.
--limits arg Update only specified limits.
--limits-match arg Update only limits matching.
--log-interval arg The logging interval in milliseconds.
--mark-all Pass all transactions through no-violation-action even if no
limit rule matches.
--min-log-interval arg The minimum logging interval.
--mode arg the valuation mode (default=0).
--no-violation-action arg This start-up parameter can be given the following values
and behavior:
--no-violation-action 0
When a transaction update results in a new limit violation, or
an old limit violation worsens, the server calls the transaction
action LIMIT VIOLATION that, by default, sets the status
LIMIT VIOLATION for the transaction. Any other types of
transaction actions can also be configured under the
action_id LIMIT VIOLATION.
--no-violation-action 1
The server behaves the same way as “0.” In addition, the
server calls the transaction action LIMIT VIOLATION CLEAR
that, by default, clears the LIMIT VIOLATION status when no
limits are violated as a result of a transaction update. (In
other words, the server automatically clears the previously
set LIMIT VIOLATION status when, following a new update,
no limits are violated by that transaction anymore.) Any
other type of transaction action can also be configured under
the action_id LIMIT VIOLATION CLEAR.
--no-violation-action 2
When value "2" is assigned, the server calls either the LIMIT
VIOLATION or NO LIMIT VIOLATION transaction action once
for the entire transaction, regardless of the number of limits
that might be affected.
2 Managing server processes
2.8 Limit Server
TRM System Administration Guide 27
--only-outstanding Include only outstanding transactions.
--pending-on-value-date Pre-Settlement Expression is used when value date = start
date.
--period-method arg Period method, NUMBER-OF-DAYS, CURRENT-WEEK, or
CURRENT-MONTH.
See 2.8.2 Applying periodic stop/loss limits on page 24.
--portfolio-id arg The top portfolio to start up.
--realized-end Period behavior Realized End.
--scenario-id arg The scenario to use.
--server-type arg Specify server type, either FINAL (default) or SIMULATION
--service-name arg The limit server name in Naming Service. Default is
limit-monitor.
--start-by-transaction When the limit server starts up, read transactions into limitd
by transaction number order, calculate limit utilizations and
call limit operations separately for every transaction.
--start-date-value arg The number of days offset from end-date (start-date =
end-date - offset).
See 2.8.2 Applying periodic stop/loss limits on page 24.
--state-context arg The state contexts to include.
--state-id arg The initial state to use.
--use-business-days Use business days, affects how period-method operates.
See 2.8.2 Applying periodic stop/loss limits on page 24.
--use-todays-fx-rate Limit daemon command line option --use-todays-fx-rate
now accepts optional arguments to support the calculation of
FX rates using the same methods as in the valuation.
If the option is not used, FX rates are calculated using the
FX method 'Spot Rate'.
If the option is used with no arguments or with argument
'=1', FX rates are calculated using the FX method 'Today's
Rate (Forward points)'.
If the option is used with argument '=2', FX rates are
calculated using the FX method 'Today's Rate (IR
Difference)'.
--valuation-method arg Valuation method:
0 = Portfolio (default)
1 = Normal
2 = Zero Coupon
3 = Benchmark
4 = Zero Spot
--var-confidence-level arg The Value-at-Risk confidence level to use
--var-horizon-id arg The Value-at-Risk horizon id to use.
--var-scenario-id arg The Value-at-Risk scenario to use
Option/Argument Description
2 Managing server processes
2.9 activityd
28 © Wall Street Systems IPH AB - Confidential
2.8.3.1 Standard setup
$ENV{FK_LIMITD_SETUP} = "
--contexts 3
--portfolio-id LIMIT
--state-id OPEN
--interval 300000
--min-log-interval 300000
--log-interval 3600000
";
This limit daemon will recalculate the limits every five minutes for all limits defined for the portfolio
tree where the LIMIT is the top portfolio. It will log the usage every 60 minutes.
2.8.3.2 Setup with frozen rates
$ENV{FK_LIMITD_SETUP} = "
--contexts 3
--portfolio-id LIMIT
--state-id OPEN
--interval 300000
--min-log-interval 300000
--log-interval 3600000
--scenario-id FREEZE
";
This limit daemon will work just like the previous one, but it will use frozen rather than default rates
to calculate the limits.
2.8.4 Checking the limit daemon
The program lm-status will show the id’s of the limits for the limit daemon. If limit users are
defined the switch -limit-user <USERNAME> should be used.
Sample output from lm-status:
ID Name
----------------------------------------------------------
FX-LIMIT Forex Limit
IR-LIMIT Limits on Interest Rate products
IR-LIMIT-2 Second Limit on Interest Rate products
VAR LIMIT VaR Limit
2.9 activityd
The activityd process launches activities as soon as they are submitted from Activity Manager.
--warning-threshold arg To generate a warning message when the threshold level n,
expressed as a percentage, is reached. This parameter can
provide the means for generating a global warning level for
all limits.
Option/Argument Description
Option/Argument Description
-n arg
--pool-size arg
The number of parallel handlers (default from database)
2 Managing server processes
2.10 tmd
TRM System Administration Guide 29
2.10 tmd
The Treasury Monitor daemon provides position monitoring on the server and is used by comKIT’s
Position service. It can also be be used to take CPU and memory usage from the client machines
running Treasury Monitor.
tmd takes the following command line options:
To use tmd from Treasury Monitor give it a service name:
tmd.exe --tmd-config-file tmpos.xml -–service-name tmdtest
and set Treasury Monitor to connect to the specified service name:
FKTreasuryMonitor.exe -–service tmdtest
2.10.1 Configuring views and books for Treasury Monitor
To limit CPU and memory usage, run tmd in preconfigured mode by providing a configuration file.
You must configure the position and portfolio views you want in the configuration file, create the
books based on that configuration, then launch Treasury Monitor to re-use those books. To do this:
1. Open Treasury Monitor from Application Manager with the startup parameters you would like to
see.
2. Configure the columns and pages you would like to see in the application.
3. Select File - Save Position and Pages as XML. This saves all data to a single XML file.
If you want to save the position and perhaps a particular page or pages then:
a. Select File - Save Position as XML (this will save the startup parameters), e.g. tmpos.xml.
b. For each Page in TM, select Page - Save Page as XML, e.g tmpage1.xml, tmpage2.xml etc.
c. In an XML editor, open the above files (the position file as well as the page files).
-t arg
--poll-time arg
The maximum time to recheck (default from database)
-l arg
--log-program arg
The program to run at the end
-e arg
--external-program arg
The program to handle external commands.
--hostname arg The name activityd will use as hostname to filter activity types.
Note: To use the hostname parameter you need to set the Check
activity host name parameter to true in the configuration
table.
Option/Argument Description
Option/Argument Description
-s arg
--service-name arg
Service name in Naming Service: default is treasury-monitor
-c arg
--tmd-config-file arg
XML configuration file
-p arg
--param arg
List of xml parameters
2 Managing server processes
2.10 tmd
30 © Wall Street Systems IPH AB - Confidential
d. Insert the page information in the position file after the <position name="tmpos” line. Here
is an example:
<?xml version="1.0" encoding="utf-8"?>
<treasury-monitor>
<position name="tmpos" type="normal" portfolio="TOP TEST">
<view-configuration name="tmpage1">
<axis type="x">
<!-- Horizontal axis grouping definitions. -->
<!-- Note that the order is important here.-->
<axis-by-figure>
<!-- Selected figures and their modes. -->
<!-- The figures are shown in the order -->
<!-- in which they appear here.-->
<key-figure mode="normal" figure="market_value"/>
<key-figure mode="normal" figure="nominal_amount"/>
<key-figure mode="normal" figure="amount"/>
<key-figure mode="normal" figure="result_realized"/>
<key-figure mode="normal" figure="result_total"/>
<key-figure mode="normal" figure="result_unrealized"/>
</axis-by-figure>
</axis>
<axis type="y">
<!-- Vertical axis grouping definitions. -->
<!-- Note that the order is important here.-->
<axis-by-currency totals-after="yes"/>
</axis>
<selection>
<!-- No restrictive selection. -->
</selection>
</view-configuration>
<view-configuration name="tmpage2">
<axis type="x">
<!-- Horizontal axis grouping definitions. -->
<!-- Note that the order is important here.-->
<axis-by-figure>
<!-- Selected figures and their modes. -->
<!-- The figures are shown in the order -->
<!-- in which they appear here.-->
<key-figure mode="normal" figure="market_value"/>
<key-figure mode="normal" figure="nominal_amount"/>
</axis-by-figure>
</axis>
<axis type="y">
<!-- Vertical axis grouping definitions. -->
<!-- Note that the order is important here.-->
<axis-by-currency totals-after="yes"/>
</axis>
<selection>
<!-- No restrictive selection. -->
</selection>
</view-configuration>
<date-to date="2004-11-05" behavior="open"/>
<date-from date="2003-11-05"/>
<currency id="EUR"/>
<start-scenario id=""/>
<end-scenario id=""/>
<var-scenario id="1"/>
<minimum-state id="OPEN"/>
<state-context id="0"/>
</position>
</treasury-monitor>
2 Managing server processes
2.11 Configuring Monitor page templates
TRM System Administration Guide 31
4. By default, tmd goes to the $FK_HOME/etc directory to find this configuration file. If you wish to
place it somewhere else, then ensure that $FK_CONFIG_HOME is set, and that its value is the path
to this configuration file.
5. This XML configuration file must be placed in the $FK_HOME/etc folder. Otherwise its location
must be explicitly defined as FK_CONFIG_HOME.
Unix:
export FK_CONFIG_HOME=/home/user/xml
Windows:
set FK_CONFIG_HOME=c:\home\user\xml
6. Start the tmd (from shell, from script…)
tmd.exe --tmd-config-file tmpos.xml –service-name tmdtest
7. Start the Treasury Monitor (from shell, from script…) on Windows
FKTreasuryMonitor.exe -–service tmdtest
8. Select the position in the Position startup parameter (tmpos), and click OK.
9. Select Page - New Grid Page. Check that you can select the pages that you saved in the XML Page
files mentioned above. Click OK, and open the next Page, and so on.
From this point, you can rename the pages to something more meaningful, and then select Save
Book As...
2.11 Configuring Monitor page templates
The Monitor page template is a file that contains preconfigured axis information for use as a starting
point in creating a new Monitor page. The Monitor application comes with a number of page
templates, each of which contains a different selection of axes (or same axes set up differently).
A Monitor configuration file contains information about the page templates available for a particular
mode of operation. Currently there are two configuration files, RM.XML and CM.XML, that
correspond to the two supported modes of operation (Rate Monitor and Calibration Monitor). The
toolbar button configuration is defined in external page template files (*.page) and cannot be
modified from Rate Monitor.
Monitor application must be launched with an appropriate configuration file specified on the
command line using the -c switch. The application uses page template information found in the
configuration file to build a hierarchical menu, allowing users to create a new page based on a
certain template simply by clicking on the appropriate menu item.
2.12 Deal mirroring module (DMM)
Deal mirroring is provided by the Mirror Loop real-time process, which uses comKIT to access TRM.
You can set DMM related variables including user name and password, and location of logs in this
script: %FK_HOME%\share\environments\mirror_config.bat (Windows) or
$FK_HOME/share/environments/mirror_config.sh (Unix).
Hint:
Under Unix, instead of keeping the password in the mirror_config.sh file, you can have
the password written into shared memory. See C.1.1 TRM Server Passwords on page 245
2 Managing server processes
2.12 Deal mirroring module (DMM)
32 © Wall Street Systems IPH AB - Confidential
which describes how do this. DMM first checks the value of the environment variable
DMM_SERVER_PASSWORD and if it finds nothing, it tries to read it from shared memory.
The configuration file is evaluated under Unix by running the eval command.
Under Windows, before launching DMM, open an evaluated shell and enter:
set DMM_CONFIG=%FK_HOME%\share\environments\mirror_config.bat
Deal mirroring can be launched by %FK_HOME%\mirror_loop.bat (process under Windows) or
$FK_HOME/bin/rc.mirror (Unix). Otherwise, see the section on Process Monitor in the WSS System
Administration Guide.
TRM System Administration Guide 33
Chapter 3 Interfaces with other tools
3.1 Bloomberg Interface
The Bloomberg interface consists of several activities. You can import and update instruments,
import corporate actions, update information in the Client Editor, or request new prices based on
information sent by Bloomberg. Each item is implemented by a dedicated activity which is described
in the TRM User Guide. Technical communication is the same for all of these activities. First, the
request is created, then it is sent via FTP communication to the Bloomberg site, the response file is
retrieved after a preset interval, and obtained data are processed based on their nature in the
Wallstreet Suite structures, instruments, clients or prices.
3.1.1 Environment variables
The following environment variables affect the behavior of all Bloomberg activities:
Name Comment Default
FK_BLOOMBERG_FTP
_REMOTE_DIR
This environment variable should point to the directory
where the request and reply files should be stored,
otherwise the default will be /tmp.
/tmp
FK_BLOOMBERG_FTP
_HOST
IP address of the primary FTP server, delivered by
Bloomberg.
bfmdr.bloomberg.com
FK_BLOOMBERG_FTP
_SEC_HOST
IP address of the secondary FTP server, delivered by
Bloomberg.
FK_BLOOMBERG_FTP
_USER
Login ID (user ID) for the Bloomberg FTP server, delivered
by Bloomberg.
FK_BLOOMBERG_FTP
_PASS
Login Password (user Password) for the Bloomberg FTP
server, delivered by Bloomberg.
FK_BLOOMBERG_FTP
_DES_PASS
Password that is used to decrypt the incoming file from
Bloomberg. The encryption/decryption method used is
DES.
FK_BLOOMBERG_FTP
_TRIES
Maximum number of attempts to download the response
file.
10
FK_BLOOMBERG_FTP
_POLL_TIME
Specifies the number of seconds in total to wait for the
reply file to appear on the FTP server.
15
FK_BLOOMBERG_FTP
_SERIALNUMBER
Serial number setup, delivered by Bloomberg.
FK_BLOOMBERG_FTP
_USERNUMBER
User number setup, delivered by Bloomberg.
FK_BLOOMBERG_FTP
_WORKSTATION
Workstation setup, delivered by Bloomberg.
FK_BLOOMBERG_FTP
_LOCAL_DIR
Local directory used for FTP communication - generated
request files are stored here.
TS_ENV_HOME/var/tmp/
FK_BLOOMBERG_FTP
_SCRIPT
Shell script that will take care of FTP communication with
Bloomberg instead of the built-in implementation.
3 Interfaces with other tools
3.1 Bloomberg Interface
34 © Wall Street Systems IPH AB - Confidential
FK_BLOOMBERG_RE
QUEST_SYSTEM
Specifies how request files are processed. Possible values:
FTP or DATA. DATA should be used only if the request files
will be communicated as Send File via the BLOOMBERG
PROFESSIONAL service.
FK_BLOOMBERG_CO
MPRESS
Specifies whether the request file should be compressed.
Possible values: YES or NO.
FK_BLOOMBERG_EN
CRYPTION_UTILITY
Utility to be used to encrypt and decrypt request and
response files. Possible values: OPENSSL and DES.
OPENSSL means that the openssl utility delivered with WSS
is used.
If DES is used, then it is necessary to specify a path to the
DES utility provided.
FK_MDI_BLOOMBER
G_PROVIDER_NAME
Name of the provider.
FK_MDI_FILE_IMPOR
T_DIR
Directory where the output files for the Data License
Output Processing activity are searched.
TS_ENV_HOME/var/impo
rt/
FK_MDI_FILE_ARCHI
VE
Archive response files if successfully processed. true
FK_MDI_FILE_ARCHI
VE_DIR
Dir where response files are archived. TS_ENV_HOME/var/archi
ve/
FK_MDI_FILE_ARCHI
VE_DIR
Pattern used to search file in FK_MDI_FILE_IMPORT_DIR '*.*'
FK_MDI_CHECK_INS
TRUMENT_EXISTS
Specifies whether duplicity instruments can be created.
Possible values: True, False
If set to true, then before each import of a specific security
(for example ISIN) a check is made to establish whether an
instrument with the same security ID already exists. If yes,
an error is reported and the security is skipped.
If set to false, no validation of whether the security id
exists is performed and the security is always imported. If
the name that should be used for the new instrument
already exists, then the counter is added at the end.
FK_MDI_UPDATE_CLI
ENT_TO_STATE
The maximum state to which the client will be accepted
after an update (valid only if SDM is installed)
Example: The client is in state FINAL before update. If the
value of the property is FINAL, the client is accepted to
state FINAL. If the value of the property is VERIFY, the
client is accepted only to state VERIFY.
FINAL
FK_MDI_SCRIPT_P
ACKAGE
The default package to be used when searching for the
scripts. The package should contain the following
subdirectories:
• field_mapping
•entity
• mapped_value
FK_MDI_SCRIPT_DIR The location of the scripts root if it is different from the
default location.
tasks.instrument.imp.scri
pt
Name Comment Default
3 Interfaces with other tools
3.1 Bloomberg Interface
TRM System Administration Guide 35
3.1.2 CSD possibility
You can adjust the behavior of the majority of Bloomberg actions according to your specific needs.
You can attach specific python scripts at various points (i.e. when inserting new instruments or
updating individual entities) to implement any necessary changes.
You need to store this python script as a python module with the extension .py in the folder
FK_MDI_SCRIPT_DIR/ FK_MDI_SCRIPT_PACKAGE/entity. Then, the name of this script (without the
.py extension) is attached to the appropriate Request or Mapping Rule Editor. Pre-save scripts are
executed before the entity is saved; Post-save scripts are executed after the entity is saved.
3.1.2.1 Entity script
You need to store the python entity script as a python module with the .py extension in the folder
FK_MDI_SCRIPT_DIR/ FK_MDI_SCRIPT_PACKAGE/entity. Then, the name of this script (without the
.py extension) is attached to the appropriate Request Editor (Instrument, Security, Corporate Action
or Client). Pre-save scripts are executed before the entity is saved; Post-save scripts are executed
after the entity is saved.
This script adjusts the entity that is supplied as the starting parameter. The ’process’ function then
returns the modified entity, which will be used in further processing.
The following provides an example of the script that is used to adjust the name of the Client entity.
def process(entity, providerData):
"""
This is a sample script to show how the entity (mapping for Client in this
case) can be processed and updated
"""
entity.setFieldValue('name', providerData['LONG_COMP_NAME'] + '__' +
providerData['ID_BB_COMPANY'])
return entity
The following provides an example of the script that is used to adjust the id of the Instrument entity.
import re
def process(entity, providerData):
"""
use pattern ${COUNTRY}G${MATURITY}_${CPN}
but take only YYYYMM of MATURITY and remove trailing zeros from coupon rate
"""
newID = providerData['COUNTRY'] + 'G'
# take only year and month from maturity date
newID = newID + providerData['MATURITY'][:-2]
# remove trailing zeros from coupon rate
newID = newID + '_' + re.sub('\.{0,1}0*$','',providerData['CPN'])
entity.setFieldValue('id',newID)
return entity
3 Interfaces with other tools
3.1 Bloomberg Interface
36 © Wall Street Systems IPH AB - Confidential
3.1.2.2 Value Mapping Editor script
You need to store the python script that is used in the Value Mapping Editor as a python module with
the .py extension in the folder FK_MDI_SCRIPT_DIR/ FK_MDI_SCRIPT_PACKAGE/ mapped_value.
Then, the name of this script (without the .py extension) will be populated in the Script field in the
Value Mapping Editor.
This script will adjust the value in the Destination field. This value is copied to the sourceValue
parameter. The ’process’ function will then return the modified value of the Destination field, which
will then be used in further processing.
Note: In general, all values from the 'process' function can be returned as strings except the
'date' fields. These fields should be returned after conversion by the DateTranslator.
3.1.2.3 Security Mapping Set Editor
You need to store the python script used in the Security Mapping Set Editor as a python module with
the .py extension in the folder FK_MDI_SCRIPT_DIR/ FK_MDI_SCRIPT_PACKAGE/ field_mapping.
Then, the name of this script (without the .py extension) will be populated in the Script field in the
Security Mapping Set Editor.
This script will adjust the value in the Provider Field. This value is copied to the sourceValue
parameter. The process function will then return the modified value, which will be used in further
processing and inserted in the defined field in the Instrument Editor.
Please note, that Script in this editor has a higher priority than Value Mapping, and only Script will be
used if Script is populated. This means that Script in the Value Mapping Editor will not be used if Script
is populated in the Security Mapping Editor.
Note: In general, all values from the 'process' function can be returned as strings except the
'date' fields. These fields should be returned after conversion by the DateTranslator.
The following provides an example of the script that is used to add a defined number of days to the
maturity date.
from tasks.instrument.imp.datatype import DateTranslator
import datetime
def process(sourceValue, localParsedEntity, localMapping):
year = int(localParsedEntity['FUT_LAST_TRADE_DT'][0:4])
month = int(localParsedEntity['FUT_LAST_TRADE_DT'][4:6])
days = int(localParsedEntity['FUT_LAST_TRADE_DT'][6:8])
print year, month, days
FUT_LAST_TRADE_DT = datetime.date(year, month, days)
print FUT_LAST_TRADE_DT
print localParsedEntity['DAYS_TDY_TO_NOTNL_MTY']
print int(localParsedEntity['DAYS_TDY_TO_NOTNL_MTY'])
DAYS_TDY_TO_NOTNL_MTY =
datetime.timedelta(int(localParsedEntity['DAYS_TDY_TO_NOTNL_MTY']))
print DAYS_TDY_TO_NOTNL_MTY
t = FUT_LAST_TRADE_DT + DAYS_TDY_TO_NOTNL_MTY
3 Interfaces with other tools
3.1 Bloomberg Interface
TRM System Administration Guide 37
print t
maturity_date_1 = t.strftime("%Y%m%d")
return DateTranslator().translate(maturity_date_1)
Note: In general, all values from the 'process' function can be returned as strings except the
'date' fields. These fields should be returned after conversion by the DateTranslator.
3.1.3 Data License Prices activity process
The following steps are performed during the Data License Prices activity process:
1. According to the query parameters in the activity, the appropriate Market Info definitions are
searched and a list of required quotations (represented by a unique identification item) is
evaluated.
2. A request for the file (in format bb-date-numberX.req) is generated and stored in the specified
folder FK_BLOOMBERG_FTP_REMOTE_DIR. If the value of the variable is not specified, the request
file will be stored in the tmp folder in the root directory (/tmp on UNIX, drive:\tmp on Windows
where the drive is the drive letter of the Wallstreet Suite installation).
3. A connection to the Data License FTP server is established based on the activity's connection
parameters.
4. The activity waits for a reply file (in format bb-date-numberX.out) from Data License, to be
stored in FK_BLOOMBERG_FTP_REMOTE_DIR.
5. The reply file is decrypted and unzipped.
6. For every quotation (represented by a unique identification item), the market info definition
valid for the date in question (either the current date or the historical rate, based on the
transaction parameters) is searched.
7. The price message containing all the necessary data such as price, scenario, and subscenario is
created. Typically, a price message consists of:
8. The price is stored in the database by calling the PushMarketInfo stored procedure.
9. The price is propagated to the message delivery system by marking the price as pending using
the PushPendingPrice stored procedure.
3.1.4 Two step activity processing
Bloomberg activities can be run either in one go, when the whole interface process is complete
(request generation, FTP communication and output processing), or you can split the process into
two executions:
1. Request generation
2. Output processing
type_id Type of instrument, for example IR-RATE, FX-RATE as defined in the
MarketInfoSource table.
period_id Price periods, as defined in the MarketInfoSource table.
period_1_id
period_2_id
source Source name, as defined in the MarketInfoSource table.
scenario Specified in the activity parameters or Market Info.
subscenario Specified in the activity parameters or Market Info.
3 Interfaces with other tools
3.2 Reuters Dealing 3000 Link
38 © Wall Street Systems IPH AB - Confidential
FTP processing is defined by user specific needs in a dedicated custom script. FTP communication
can be done asynchronously. This approach should be used in cases where there are security
limitations and direct FTP communication from the Wallstreet Suite servers is not allowed.
Both ways (all in one go and or two separate executions) are managed by the Bloomberg activities
Processing Type parameter. You need to select one of the following values:
All,
Generate Request, or
Process Output.
3.2 Reuters Dealing 3000 Link
3.2.1 Overview
The Dealing 3000 Link is used to convey foreign exchange and money market deals from the
Reuters Dealing 3000 system and its ticket output feed to TRM.
The link is run as a background process and is transparent to the user. It consists of a
communications module and a data conversion and storage module.
The communications module monitors the Dealing 3000 port and when new deals become
available it requests the deal details and passes them on to the data conversion and storage
module.
The data conversion and storage module maps the Dealing 3000 deal details into TRM
transaction fields and stores the transactions into the database.
3 Interfaces with other tools
3.3 Value-at-Risk Interface
TRM System Administration Guide 39
Transaction details that are required by TRM but cannot be extracted from Dealing 3000 output can
be defined in a special configuration file. Such transaction details are for example the portfolio and
initial state of the transaction.
All deal conversions, errors and other events in either module are logged in a file.
3.2.2 Scripts
The executable Python scripts are config.py, D3000.py and CreateTransactions.py (which is
called by D3000.py).
1. Configure config.py
2. Evaluate your environment (this requires access to FK.Cache and Corba)
3. Use a command like the following:
python D3000.py > D3000.log 2>&1
3.2.3 Log file
Debug mode is enabled by default. All the received data from D3000 server is by default saved in
.\D3000Response.dat with datetime. The debug is verbose, so the file size should be monitored.
By default, the interface ignores real-time messages and polls the server every 30 seconds.
3.2.4 Implementation
D3000.py can be used standalone for testing purposes. Just comment out the transaction_maker
call in _processDeal, line 297. If configured, it saves the received data into a file which can be used
with CreateTransactions standalone. CreateTransactions.py can also be called standalone with a
file as parameter. This file will be read line by line to create transactions.
If the feed still needs to be serial, the old read-feed perl version can be used with
CreateTransactions.py. but the python main script needs to be adapted slightly to read from
STDIN instead of a file.
In addition, in Client Editor, a property DEALING-3000-ID should be defined for all Dealing 3000
counterparts. This property is the Dealing 3000 tcid.
3.3 Value-at-Risk Interface
This section describes how to install the Value-at-Risk (VaR) data in TRM via the VaR interface.
The aim of the VaR interface is to update the TRM database with the volatility and correlation data
from RiskMetrics for the currencies, yield curves and equities defined in the system. These variables
are used in VaR analysis within Treasury Monitor and also in performance calculations and risk
reports.
3.3.1 Default VaR scenario
The default VaR scenario is created at the first installation of TRM. VaR configuration is part of the
standard build procedure. The default VaR scenario does not have any mapping or data set
associated at initiation, and is the default scenario used by the import scripts.
3.3.2 VaR Mapping Types
The standard configuration has two mapping types, GOVT and SWAP. These are in the table
VaRMappingType, where they can be modified and new types added.
3 Interfaces with other tools
3.3 Value-at-Risk Interface
40 © Wall Street Systems IPH AB - Confidential
3.3.3 Default mapping
A default mapping between TRM data (currencies and interest rates) and the corresponding
RiskMetrics variables is built automatically. You may need to make some changes to this default
mapping. To view or edit the default mapping, open VaR Mapping Editor and choose mapping
RISKMETRICS.
The following changes may be required:
1. TRM currencies are mapped to their RiskMetrics counterparts. Not all TRM currencies are
provided by RiskMetrics.
2. All TRM yield curves are mapped to the corresponding RiskMetrics swap curves. Re-mapping
TRM yield curves to different RiskMetrics curves (for example zero-coupon GBond curves may
need to be mapped to the RiskMetrics equivalent) must be carried out manually. For more
information on using different RiskMetrics IR mappings, see the TRM User Guide.
3.3.4 Importing RiskMetrics data to TRM
The RiskMetrics Group publishes their data on the Web (and ftp) in the form of compressed files (zip
or tar) for both the UNIX and Windows environments. The RiskMetrics data files for correlation and
volatility are as follows:
More information about these data sets is in the RiskMetrics Technical Document, available from the
RiskMetrics Web site http://www.riskmetrics.com.
3.3.4.1 Fetching the risk files
There are two ways of getting the risk files:
From their Web site, http://www.riskmetrics.com: Choose regular risk files, monthly and daily,
and copy them to the directory $FK_HOME/com/risk-metrics
From their FTP site. TRM provides a script to get the files from their ftp site:
$FK_HOME/share/risk-metrics/fetch-from-riskmetrics
Note: Getting the risk files is a step that can be run automatically by the import script. See below
for additional details.
3.3.4.2 Running the import script
The program $FK_HOME/share/risk-metrics/import-from-riskmetrics is the main tool to import
RiskMetrics data in TRM. It first fetches data from the RiskMetrics FTP site, evaluates the TRM
environment and then imports the volatility and correlation data in the corresponding VaR scenario
(by default, the default VaR scenario).
The following options are recognized by the program:
RiskMetrics Data Files Description
<date>.dvf
<date>.dcf
Volatility data for 1 day horizon
Correlation data for 1 day horizon
<date>.mvf
<date>.mcf
Volatility data for 30 day horizon
Correlation data for 30 day horizon
Option Description
-h <directory> TRM home directory
-i, I, e, f <> Usual TRM environment arguments
-s Skips fetching of data via FTP
3 Interfaces with other tools
3.3 Value-at-Risk Interface
TRM System Administration Guide 41
Examples:
Importing data (from RMM.zip and RMD.zip) in the default VaR scenario:
$FK_HOME/share/risk-metrics/import-from-riskmetrics -h /usr/wss/v7 -e fk7_1_env
-s -v -z zip
Importing data (from <date>.dvf, etc…) in the default VaR scenario:
$FK_HOME/share/risk-metrics/import-from-riskmetrics -h /usr/wss/v7 -e dev1 -s -v
Importing data (from RMM.tar.Z and RMD.tar.Z) in a user specific scenario:
$FK_HOME/share/risk-metrics/import-from-riskmetrics -h /usr/wss/v7 -e dev1 -s -v
-U user -P passwd -c "TEST SCENARIO" -z tarZ
Notes:
The import of RiskMetrics data in TRM is a lengthy process: about 20-30 minutes for a typical
data set (volatility and correlation, 1-day and 1-month horizon).
Once ran, check that the correlation and volatility date exist in VaR Data Board.
3.3.5 Importing FEA data to TRM
The FEA (Financial Engineering associates) http://www.fea.com/ publishes data on the Web in the
form of compressed files (zip or tar) for both UNIX and Windows environments.
Program ‘import-from-fea’ is the main tool to import FEA data in TRM. It expects data to be present
either as *.zip or *.txt, and then imports the data in TRM. The program takes the following
arguments:
-u,p,l,d <> Arguments for connection to FTP site (see below)
-y Imports yield volatility for IR market (default is price volatility for all market data)
-U <user> Database login
-P <passwd> Database password
-c <scenario> Scenario name
-z <type> Data file type:
""tarZ" : use RMD.tar.Z and RMM.tar.Z
""zip" : uses RMD.zip and RMM.zip
"If -z is not used, then it imports from *.dvf, *.dcf, *.mvf, and *.mcf.
-r Removes all data files after the import process
-v Verbose
Option Description
Option Description
-h <directory> TRM home directory
-i,I,e,f <> Usual TRM environment arguments
-y imports yield volatility (default is price vol.)
-U <user> Database login
-P <passwd> Database password
-c <scenario> Scenario name
-z <type> Datafile type ("zip"). If -z is not used then it imports from *.txt
3 Interfaces with other tools
3.3 Value-at-Risk Interface
42 © Wall Street Systems IPH AB - Confidential
Examples:
Importing data from text file in the default scenario:
$FK_HOME/share/risk-metrics/import-from-fea –h /usr/wss/v7 -e test -r -y -v
Importing data from a zip file in a user specific scenario:
$FK_HOME/share/risk-metrics/import-from-fea -h /usr/wss/v7 -e test -r -y -v -c "TEST
SCENARIO"
3.3.6 VaR horizon
To set up a horizon other than the default horizons (1 day and 1 month), use the procedure
CommitVaRHorizon. For example, to set up a horizon of 10 days which interpolates between 1 and
30 days, run:
CommitVaRHorizon @id = 10,
@scenario_id=1,
@id_1 = 1,
@id_2 = 30,
@name = "10 Day VaR Horizon"
3.3.7 Other scripts
The scripts described in this section are mainly for illustration purposes. They should not be run if
the main import script was run:
$FK_HOME/share/risk-metrics/import-from-riskmetrics.
These scripts are actually called by the main import script.
3.3.7.1 Fetching RM data via FTP
The program $FK_HOME/share/risk-metrics/fetch-from-riskmetrics fetches the RiskMetrics
data via FTP. The arguments of this program are as follows:
Example:
-r removes all data files after import process
-R removes data files and compressed file after import process
-m only import data for which a mapping exists in given scenario
-v Verbose
Option Description
Option Description
-h <site> FTP site (ftp.riskmetrics.com by default)
-u <user> FTP site user login
-p <passwd> FTP site user password
-l <directory> Remote directory on FTP site
-a Passive mode
-d Debug mode
-v Verbose
<filename1><filename2> List of files to fetch
3 Interfaces with other tools
3.3 Value-at-Risk Interface
TRM System Administration Guide 43
$FK_HOME/share/risk-metrics/fetch-from-riskmetrics -h datomatic.com -u trema -p
pass12 RMD.zip RMM.zip
3.3.7.2 Importing volatility and correlations routine
The programs $FK_HOME/share/risk-metrics/import-volatilities and
$FK_HOME/share/risk-metrics/import-correlation are used by the main import script. These
programs can be run separately and both programs have the following arguments:
The data is read from the files in command line, or from the standard input.
Note: If no scenario is specified, data are imported in the default VaR scenario. When a scenario is
specified, only the owner of the scenario can import data.
Examples:
Importing 1-day volatility data in default VaR scenario:
$FK_HOME/share/risk-metrics/import-volatilities -h 1 -v 20011231.dvf
Importing 1-month volatility data (yield volatility) in user "trema" specific VaR scenario, "TEST
SCENARIO":
$FK_HOME/share/risk-metrics/import-volatilities -u trema -y -h 30 -s "TEST
SCENARIO" -v 20011231.mvf
Option Description
-u <user> Owner of scenario
-h <horizon> The time horizon, '1' for the daily data and '30' for the monthly data.
-y Imports daily volatility (price vol by default)
-d <date> Date, if different from what is in the file.
-s
<scenario>
Scenario ID.
-r Fetches data for mapped variables only.
-v Gives some feedback of the process.
<filename> RiskMetrics data file to import.
3 Interfaces with other tools
3.4 Prices import - Import Market Information Activity
44 © Wall Street Systems IPH AB - Confidential
3.4 Prices import - Import Market Information Activity
The TRM activity Import Market Information allows you to import rates from generic CSV files. This
section describes how to set it up.
You access the Import Market Information activity from the Activity Manager application (from TRM
Application Manager) as shown below:
The fields are explained in the TRM User Guide (search on Activity Parameters).
3.4.1 Import process
Consists of:
1. Identifying the list of files to be imported
2. Validating the files
3. Parsing the files.
3.4.1.1 Import files list
The list of import files is based on the contents of the Source Subdirectory field and the environment
variables FK_IMPORT_PRICES_DIR and FK_IMPORT_PRICES_PATTERN. The final path is constructed as
follows:
[FK_IMPORT_PRICES_DIR] Source Subdirectory [FK_IMPORT_PRICES_PATTERN]
If the Source Subdirectory field contains the full path from the root, then FK_IMPORT_PRICES_DIR is
ignored.
3 Interfaces with other tools
3.4 Prices import - Import Market Information Activity
TRM System Administration Guide 45
If the path ends with name of a file (with or without wildcards), then FK_IMPORT_PRICES_PATTERN is
ignored.
Examples
V:\WSS\var\import\prices\examples contains three files: a.csv, aa.csv, and b.csv.
FK_IMPORT_PRICES_DIR=V:\ WSS\var\import\prices
FK_IMPORT_PRICES_PATTERN=*
3.4.1.2 Validating the files
Before the files are parsed, they are first validated. If errors are found then the activity fails.
3.4.1.3 Parsing the files
The following steps are performed during the import prices process:
1. All scenarios and subscenarios are fetched in order to provide a means of translating names into
system ids.
2. Before parsing every file, processes are verified if the FK_IMPORT_PRICES_VERIFY_PROCESSES
environment variable is set (see 3.4.2 Environment variables on page 46.
3. For each price (equivalent to a line in an input file):
a. If any Market Info is cached for the specified name_id and date, then MarketInfos are loaded
using FetchMarketInfoData for the specified date and name_id.
b. If Market Info is not found, then possible reasons are searched and logged, using the stored
procedure FetchMarketInfoDetail.
c. Enrich the price with data from previously loaded MarketInfos:
d. Enrich the price with the Scenario/Subscenario specified in the Activity parameters, if supplied.
e. Set the period from/to, if not provided in the input file, to the date of the price.
f. A CSD hook can be called to modify the price before storing it to database. See 3.4.5 CSD
possibilities on page 48.
g. Store the price by calling PushMarketInfo.
h. Mark the price as pending using PushPendingPrice.
4. Verify that none of the processes has been restarted meanwhile; if so, the activity fails.
If Source Subdirectory= then files processed are:
V:\ WSS\var\import\prices\examples\a.csv a.csv
examples a.csv
aa.csv
b.csv
examples\ a.csv
aa.csv
b.csv
examples\a* a.csv
aa.csv
period_id, period_1_id, and period_2_id
name_id, and type_id (e.g. EUR/USD, FX-RATE resp.)
price type
scenario_id, subscenario_id
3 Interfaces with other tools
3.4 Prices import - Import Market Information Activity
46 © Wall Street Systems IPH AB - Confidential
5. Call CSD hooks if required.
6. File is archived, based on environment settings (see FK_IMPORT_PRICES_ARCHIVE below).
Archiving moves the file to a subfolder with the name batch_<activity_batch id> and
renames the file to <start_date>_<existing_filename>.
3.4.2 Environment variables
The following environment variables affect the behavior of the Import Market Information activity.
FK_IMPORT_PRICES_VERIFY_PROCESSES
Certain processes must be running during the import to ensure that the derived prices are
automatically recomputed. The required processes are: mdsd, transd, and micd. The verification
logic uses the mdsd.get_status() service to obtain a list of processes connected to the mdsd
bus. If any of the mentioned processes is not connected to mdsd, the activity fails. Note that by
default, the FK_IMPORT_PRICES_VERIFY_PROCESSES variable is set to verify.
Default: verify
FK_IMPORT_PRICES_DIR
Defines the path to the root directory for source directory where import prices files are located.
Default: %FK_VAR_DIR%\import\prices
FK_IMPORT_PRICES_BATCH_SIZE
The number of records (batch size) to be processed before the import price activity is suspended
for a time interval equal to FK_IMPORT_PRICES_SLEEP_MSECS. Both values must be non-zero for
the suspend mechanism to work. This helps to avoid overloading the mdsd and micd processes
with huge amounts of direct and derived prices.
Default: 0
FK_IMPORT_PRICES_SLEEP_MSECS
Price import is suspended for a time interval in milliseconds after a certain number of records
(batch size) specified in FK_IMPORT_PRICES_BATCH_SIZE. Both values must be non-zero for the
suspend mechanism to work. This helps to avoid overloading the mdsd and micd processes with
huge amounts of direct and derived prices.
Default: 0
FK_IMPORT_PRICES_PATTERN
Defines which import files are processed, unless overridden by the contents of the Source
Subdirectory field. See 3.4.1 Import process on page 44.
Default: *.*
FK_IMPORT_PRICES_ARCHIVE
The import file is archived in a subdirectory after processing, and is deleted from the import
directory. If FK_IMPORT_PRICES_ARCHIVE is not set, then archiving does not happen, and the
import file is left in the source directory.
Default: True
FK_IMPORT_PRICES_ALLOW_ERROR _LINES
’False’ means that if there is an invalid datasource, no bid/ask quote, or no date of quote
specified on the particular line in the csv file, a message with severity ERROR will be logged, and
the file will not be archived.
’True’ means that in the case of an invalid datasource, no bid/ask quote, or no date of quote
specified, only WARNING messages are logged and the file is archived as processed. A message
with severity ERROR is logged and the file is not archived only in the case of 'technical' issues
3 Interfaces with other tools
3.4 Prices import - Import Market Information Activity
TRM System Administration Guide 47
such as missing permissions, no connection/access to the database and other non-source data
related issues that prevent saving the data to the database.
Default: False
3.4.3 Format of the import file
The format of each file in the import directory must conform to the CSV specification: the first line of
the file must contain names of the properties and the remaining lines must contain the data. There
are two types of properties that can be specified:
Query properties
Price data properties
3.4.3.1 Query properties
These are used to identify the Market Info record - the values are used to search for the appropriate
MarketInfo record. One of item or name_id (or both) must be specified; other values are optional.
Each row in the import file must uniquely identify exactly one record in MarketInfo table.
3.4.3.2 Price data properties
These are the price details which would be stored in the database:
Note: All query properties must be properly filled. For example, empty columns are not ignored,
but MarketInfo is searched for condition "column"="", which can then cause activity
failure, because no MarketInfo record is found.
3.4.3.3 Example imports
Using Item:
item Identifier of the Market Info record. Mandatory if name_id is not provided.
name_id Name of the instrument, currency pair, etc. Mandatory if item is not provided.
type_id Type of instrument, for example IR-RATE, FX-RATE.
period_id,
period_1_id,
period_2_id
Price periods
source Source name, as defined in the MarketInfoSource table, e.g. FILE, ECB, REUTERS.
date The date (in MMDDYYYY format) to which the price applies.
date The date (in MMDDYYYY format) to which the price applies.
period_from, period_to The date period (in MMDDYYYY format) to which the price applies.
price_1 … price_10 Price data.
bid (ask) … Synonym for price_1 (price_2 etc.).
Item Source Date Bid Ask
SAMPLE-BOND-GOVT-CA FILE 01012000 20 21
USD1YD= REUTERS 12312005 4.7 4.8
EURON= REUTERS 11012008 0.8 0.9
3 Interfaces with other tools
3.4 Prices import - Import Market Information Activity
48 © Wall Street Systems IPH AB - Confidential
Using name_id
Using unsupported format of FILE
The special source FILE is used for identifying Market Info definitions created for import via activity.
They can differ - for instance by scenario - from standard Market Info definition for source REUTERS.
If there are multiple definitions of Market Info for the same price that differs by source, then it is
necessary to distinguish between them using FILE, otherwise the activity could find two valid Market
Info definitions and it would fail.
3.4.4 Permissions
The process verifies permissions for the user that scheduled the activity. The permission checked is
for object=UpdatePrices and the permission verified is defined in the scenario or subscenario
relevant to the activity (Scenario Editor, Permission field).
3.4.5 CSD possibilities
Some CSD hooks exist in order to allow modification of prices prior to calling PushMarketInfo,
verification of processes, imported prices etc. All CSD hooks are located in csd.py. If an exception is
thrown, the importing process is terminated and the activity fails.
CSD Class
Type_id Name_id Period _id Source Date Bid Ask
UM-PRICE SAMPLE-BOND-GOVT-CA SPOT FILE 01012000 20 21
IR-RATE USD-DEPO/SWAP SPOT REUTERS 12312005 4.7 4.8
FX-RATE EUR/USD O/N REUTERS 11012008 0.8 0.9
Type_id Name_id Period _id Item Source Date Bid Ask
UM-PRICE SAMPLE-BOND-GOVT-CA SPOT FILE 01012000 20 21
IR-RATE USD-DEPO/SWAP SPOT 12312005 4.7 4.8
FX-RATE EUR/USD O/N 11012008 0.8 0.9
Name Comment
__init__ One instance of this class is created at the beginning of import.
CSD logic can be implemented in either the constructor (initialization) or
in the methods.
preprocessPrice Called for every price after the price has been enriched by market info
data. Price can be liberally modified in this hook.
postprocessPricess Called at the end of importing of one file, after all prices has been
successfully imported.
verifyProcesses This function should return True, if processes (micd, mdsd, transd)
should be verified (FK_IMPORT_PRICES_VERIFY_PROCESSES is set). If
processes should not be verified (environment variable
FK_IMPORT_PRICES_VERIFY_PROCESSES not set), it returns True
without checking the processes.
Business logic can be liberally changed here.
3 Interfaces with other tools
3.4 Prices import - Import Market Information Activity
TRM System Administration Guide 49
3.4.6 Validation of Imported Prices
In a market datastream like the Reuters interface, prices are updated continuously, which means
should a price be discarded for some reason, it is not critical since an update will soon be received.
In the price import activity, typically a price is only imported once it is critical that a price discard is
reported. The procedure FetchMarketInfoDetail is used to acquire additional information when:
There is no market information found for the name_id or item provided.
There is market information found for name_id or item but other fields in the imported line do
not match.
The activity then displays each candidate with the following additional information:
Disabled Market Info
Inactive Market Info
Inactive Instrument Quote
Inactive Currency Journal.
Also, the currently processed price and the import file line, along with the corresponding line
number, are printed out when the following errors occur:
Scheduling of price recalculation has failed.
Calling PushMarketInfo returns a non-zero code.
The user does not have object permission to UpdatePrices.
Calling GetMarketInfoId returns a non-zero code or does not fetch any data.
3.4.6.1 CSD validation
It is not possible to identify following problems and a CSD must be used where necessary:
verifyProcessesBeforeImport Called at the beginning of processing before any file is read.
The provided dictionary contains keys: transd, micd. The value under the
key contains result of the mdsd.get_status() call, that is, info usually
obtainable using the md-status utility, or None if no such process is
running.
The return value should be of type boolean:
Returning True means the processes are fine and default verification
should be omitted.
Returning False (default) means default verification should take
place.
Throw whatever exception to terminate the process and fail the activity if
the verification fails.
verifyProcessesAfterImport Called at the end of processing after all files have been imported.
The provided dictionary contains keys: transd, micd. The value under the
key contains result of the mdsd.get_status() call, that is, info usually
obtainable using the md-status utility, or None if no such process is
running.
The return value should be of type boolean:
Returning True means the processes are fine and default verification
should be omitted.
Returning False (default) means default verification should take
place.
Name Comment
3 Interfaces with other tools
3.5 Using comKIT
50 © Wall Street Systems IPH AB - Confidential
Error message if the date is not between issue_date and maturity_date
This must be handled in the CSD hook preprocessPrice. The Import Market Information activity
detects this situation only if valid_ from and valid_to dates on the quote tab are properly set
based on the maturity date and issue date of the instrument.
However, when a price is imported for an instrument after its maturity or before its issue_date, it
does not cause any problems in the system and the price is not used.
Error message if the "Calculated price" related to imported price has not stored
There is no simple link between direct (imported) price and derived (calculated) price, and therefore
the activity cannot verify that all possible derived prices are correctly calculated and stored.
However, there are mechanisms in the activity to check running processes in several places, to slow
down the importing of prices so that subsequent processes are not overloaded and can handle all
recalculation and storing of prices. Also a user-specific check can be performed that specific prices
were recalculated in the CSD hook postprocessPricess.
3.5 Using comKIT
3.5.1 Overview
Note: You can find HTML comKIT documentation in FK_HOME\support\comKIT\doc.
comKIT enables TRM to be run using an API instead of the traditional GUI. More specifically, comKIT
is a programmable interface that hides the details of the implementation and offers support for high
level objects (Business Objects) that make sense on the business side of TRM. CORBA is used to
expose methods and data to the programmer via interfaces defined in IDL. JacORB is supported for
Java interfaces. The IDL interfaces are the starting point for comKIT. These IDL files describe what
can be done using comKIT. IDL compilers exist for the most common programming languages and
these are used to generate classes.
comKIT makes importing transactions easier, since comKIT uses the same underlying software as
the transaction manager GUI to enter transactions; the calls you make in comKIT map directly to
the operations you would do in the Transaction Manager to enter a deal.
So, if a user with financial knowledge shows an interface programmer how a deal is entered in
transaction manager, it is quite easy to program the same using comKIT. There are no workarounds
and mappings to be implemented as with the cvt procedures.
Information on setting up comKIT is available in Chapter 12 Setting up comKIT on page 205.
3.5.2 comKIT services
The comKIT toolkit is made up of the following services:
Settlement service
Position service
Static Data service
Transaction service
Performance service
Each service provides access to a area of TRM functionality. In most cases, each area corresponds to
a TRM application: for example, the Position service provides access to the features you find in
Treasury Monitor. There is a direct correspondence between the manner in which you work with a
TRM application and the way you make programming calls to the relevant comKIT service. For this
3 Interfaces with other tools
3.5 Using comKIT
TRM System Administration Guide 51
reason, it is highly recommended that you become familiar with the TRM application and interface
for any service you plan to use.
3 Interfaces with other tools
3.5 Using comKIT
52 © Wall Street Systems IPH AB - Confidential
TRM System Administration Guide 53
Chapter 4 Using Import Export tool
4.1 Introduction
The Import Export Tool application aims to make a standard interface tool available which can be
used as a base for all types of data transfers.
This tool provides:
A consistent approach - making all interfaces look similar gives ease of use and maintenance.
Reduced development time - many small issues are supported automatically.
Ease of use - helps the developer to get at the available data more easily by having built-in
extensible functionality.
Import Export tool has been developed as a shell using the Perl language. The advantages of this
approach are:
Rapid prototyping
Inbuilt data conversions and pattern matching
Existing TRM interfaces for database access
Part of the standard TRM release
Object-oriented approach for hierarchical design and extensibility for newer methods
4.2 Features
The basic shell of Import Export tool provides the following features:
Formatting templates for data input (import) and output (export)
Database interface that allows the calling of stored procedures for either export or import
Data formatting including formats such as SWIFT Money
Callback hooks for pre-processing of data and post-processing of output for export and import
Automated unique file naming for file based output
4.3 Structure of the Import Export tool
When exporting data from TRM using Import Export tool, a stored procedure is used to extract the
data from the database. Each row returned from the stored procedure contains directly or indirectly
one data set for the output. This data set might contain all data to output, or it might be used for
input to routines in the perl package, which calculate the data to output.
When importing data, the stored procedure takes data from the input file and enters the data into
the TRM database.
4 Using Import Export tool
4.4 Importing data
54 © Wall Street Systems IPH AB - Confidential
When setting up the Import Export Tool for your specific data requirements, it is recommended to
use additional stored procedures rather than modifying the Perl package (i.e., adding new Perl
classes) if possible, for performance reasons. Please refer to your SQL reference for details on how
to write stored procedures.
4.3.1 File organization and inheritance
Templates, formats, and variables are defined in a definition file with extension .def.
The Perl code is put into a Perl class file, a file with extension .pm. The base part of both file names
must be the same. This name is the name of the import/export function.
If the interface is derived from another interface, a new subdirectory must be created, whose name
is that of the parent interface. For example, an interface XYZ derived from an interface called
''Payment'', which itself is derived from an interface called MYINTERFACE must have the following
file and directory structure:
MYINTERFACE.def
MYINTERFACE.pm
MYINTERFACE/
MYINTERFACE/Payment.def
MYINTERFACE/Payment.pm
MYINTERFACE/Payment/
MYINTERFACE/Payment/XYZ.def
MYINTERFACE/Payment/XYZ.pm
The corresponding Perl classes would be:
MYINTERFACE
MYINTERFACE::Payment
MYINTERFACE::Payment::XYZ
The Perl class files are not mandatory; if it is possible to define everything within the
template/stored procedures framework then you can leave out some of the Perl files and only have
the definition file. Template files are provided in the TRM package in $FK_HOME/share/interface.
4.4 Importing data
The basic principle of importing data is that the input data are compared on a row-by-row basis to
the template (header, body, and trailer). When there is a match, the regular expression engine picks
up the provided fields and puts them into an array of records. After all the records have been
successfully read, stored procedure calls are constructed for each record. Finally, these stored
procedure calls are executed.
The types of all fields must be defined because, at import time, the data types are not available from
the database.
Regular expressions are generated automatically from the template and format definitions. It is
possible, though, to override the default regular expression. This may be useful if performance is
bad with the default expression.
Once the records have been parsed, the construction of the stored procedure calls is simple. For
example, if one record has the fields number and reference with the values 766 and 'TII'
respectively, and the import procedure has the value UpdateReference, the procedure call would
be:
For Microsoft SQL Server and Sybase:
exec UpdateReference
@number = 766,
@reference = ''TII''
4 Using Import Export tool
4.5 Definition file (.def)
TRM System Administration Guide 55
For Oracle:
var r number
exec :r := HelpObjectPermission(pobject_id => 'aaa');
UpdateReference( Pnumber => 766,
Preference => 'TII');
Note that we must define the data type of the number field to be integer in the format section of
the .def definition file. (See 4.5.4 Format on page 59.) Otherwise, it will be interpreted as a string
and thus enclosed in quotes.
4.5 Definition file (.def)
Definition files define the layout of the imported/exported data files with templates (header, body,
and trailer) and the data structures used with formats and variables.
4.5.1 Templates
Templates are used to define the layout of the data file; the position of the actual data items relative
to one another and to other parts of the data file.
There are three sections in each template: header, body and trailer. There can be many different
definitions of each of these three types and it is possible to choose the correct one in the database
query or in the Perl hook functions.
The header and trailer definitions are each evaluated once only in each data transfer, at the
beginning and the end of the transfer, respectively. The body definition is evaluated for each row of
data that comes from the export query. When files are imported, the template is used to construct
regular expressions that will match into the input.
The header template sections are delimited by:
BEGIN HEADER [<NAME>]
....
END HEADER [<NAME>]
The body sections by:
BEGIN BODY [<NAME>]
....
END BODY [<NAME>]
The trailer sections:
BEGIN TRAILER [<NAME>]
....
END TRAILER [<NAME>]
where the optional <NAME> parameter specifies the name of the template if there are multiple
header, body or trailer template sections.
4.5.2 Layout syntax of the template
The layout of the header, body or trailer is described by 'example': the data is written as it will
appear in the imported/exported file, with all fill characters and line breaks, except that actual data
is replaced by variables. Variables are marked by a variable name surrounded with curly brackets
('{, }').
A sample header definition looks like this:
BEGIN HEADER
Risk metrics data from {date}
END HEADER
4 Using Import Export tool
4.5 Definition file (.def)
56 © Wall Street Systems IPH AB - Confidential
where the header in the file looks like:
Risk metrics data from 1999-04-23
At import time, the header is parsed, and the variable date is matched to '1999-04-23'.
Note: Remove trailing white space everywhere in layout definitions for importing data. The
sensitive matching process tries to match every single character in the template to the
data in the file.
4.5.2.1 Header
If the data file has a header before the start of the actual data section, the layout of this header has
to be defined. The header section of the template file defines the layout of this header. It is parsed
and read/written once. If the data file has no header, the header part in the template file should be
omitted.
There may be several layout definitions for the header. The correct template is chosen according to
the value of the variable template. This variable can either be given on the command line, in the
stored procedure, or it may be set in the Perl package. In the Perl package, it is the variable
$row->{template} that is set accordingly. In the stored procedure, an additional column with the
name template has to be returned (e.g. select template = TemplateName).
In the definition file, each of the headers would be defined with a specific name; for example:
BEGIN HEADER TemplateName
....header layout definition ....
END HEADER TemplateName
4.5.2.2 Body
The body section defines the layout of the main data in the data file which is to be imported or
exported. It defines the layout of one data set, one row in the database. It will be parsed for every
row.
There may be several layout definitions for the body. The template used is chosen according to the
value of the variable template. As described for the header above, this variable can either be given
on the command line, in the stored procedure, or it may be set in the Perl package. In the Perl
package, it is the variable $row->{template} that is set accordingly. In the stored procedure, an
additional column with the name template has to be returned (e.g. select template =
TemplateName).
BEGIN BODY TemplateName
....body layout definition ....
END BODY TemplateName
4.5.2.3 Trailer
If the data file has a trailer after the actual data section, the layout of this trailer has to be defined.
The trailer part of the template file defines this layout of the trailer. It is parsed and read/written
once. If the data file has no trailer, the trailer section in the template file should be omitted.
As for both the header and body sections, there may be several layout definitions for the trailer. The
template used is chosen according to the value of the variable template. This variable can either be
given on the command line, in the stored procedure, or it may be set in the Perl package. In the Perl
package, it is the variable $row->{template} that is set accordingly. In the stored procedure, an
additional column with the name template has to be returned (e.g. select template =
TemplateName).
BEGIN TRAILER TemplateName
....trailer layout definition ....
4 Using Import Export tool
4.5 Definition file (.def)
TRM System Administration Guide 57
END TRAILER TemplateName
4.5.2.4 Body template
The following is an example of a body template (SWIFT MT210):
BEGIN EXPORT VARIABLES
procedure=ListBatch
END EXPORT VARIABLES
BEGIN HEADER HEAD1
REC-01 Table Batch {rundate}
END HEADER HEAD1
BEGIN BODY
REC-02 {id};{date};{type};{user_id};{comment}
END BODY
BEGIN TRAILER TRAIL1
REC-09 total records {count}
END TRAILER TRAIL1
BEGIN FORMAT
id {
absolute:no
type:integer
length:10
leading_zeros:yes
}
type {
type:character
length:50
alignment:left
}
date.time_format:MM/DD/YYYY
user_id {
type:character
length:30
alignment:right
}
step.type:integer
END FORMATedure=ListBatch
4.5.3 Variables
Two types of variables can have values assigned to them:
Built-in variables like import/export file names and debug switches
Parameters of the stored procedure calls can have values assigned to them.
A full list of the built-in variables available is given in 4.5.3.5 Built-in variables on page 59.
4 Using Import Export tool
4.5 Definition file (.def)
58 © Wall Street Systems IPH AB - Confidential
Variable names can contain characters, digits and '_' ([a-zA-Z0-9_]). Parameters to stored
procedure calls always start with an @ sign. There can be any amount of white space anywhere in
variable assignments. If a variable is assigned more than once, then the last assignment is used.
4.5.3.1 Definition of variables
Variables can be assigned in the definition file and also on the command line. In addition, certain of
these variables can have values stored in normal environment variables. If variables are defined in
several places, the order of evaluation is as follows (from most dominant to least dominant):
Command line variables
Export/import variables in .def files
Common variables in .def files (apply to both import and export)
Environment variables
Variables can be assigned for export only, import only, or for both (common variables).
4.5.3.2 Command line variables
On the command line, variables are appended to the stored procedure command, separated by
space, as the following example shows:
On UNIX:
./interface MYINTERFACE::Payment::XYZ export @flags=2 @portfolio_id=\'TOP\ '
On Windows:
perl Interface MYINTERFACE::Payment::XYZ export @flags=2
@portfolio_id=TOP
Note: On UNIX, quotation marks must be preceded with backslashes to prevent expansion by the
shell.
4.5.3.3 Variables section in .def file
Variables or stored procedure parameters that are defined in the .def files exist in their own
sections. Variables that apply for both import and export are delimited by
BEGIN VARIABLES
variable=value
variable=value ....
END VARIABLES
Variables that apply for import only:
BEGIN IMPORT VARIABLES
variable=value
variable=value ....
END IMPORT VARIABLES
Variables that apply for export only:
BEGIN EXPORT VARIABLES
variable=value
variable=value ....
END EXPORT VARIABLES
4.5.3.4 Syntax of environment variables
Environment variables are of the form $FK_IMPORT_variable and $FK_EXPORT_variable for
import and export respectively. For example:
On UNIX (Bourne shell):
4 Using Import Export tool
4.5 Definition file (.def)
TRM System Administration Guide 59
set $FK_IMPORT_variable=value; \
export $FK_IMPORT_variable
On UNIX (C shell):
setenv $FK_IMPORT_variable value
On Windows:
set FK_IMPORT_variable=value
If environment variables are used, the most appropriate location to set these variables is in the TRM
system environments, which are defined in $FK_HOME/share/environments.
4.5.3.5 Built-in variables
There are several built-in variables, described in the following table:
4.5.4 Format
The format part of the definition file defines the data types used in the Import Export Tool.
Note: It is very important to specify the data types of the variables used as exactly as possible.
Import Export Tool internally generates regular expressions for each data type and
matches these regular expressions to the imported and exported data respectively.
The format section is delimited by:
BEGIN FORMAT
....
END FORMAT
Variable Description
procedure Name of the SQL stored procedure to use in export or import to extract or insert the data,
respectively.
@parameter1,
@parameter2
Possible default parameters for the stored procedure. They always start with @.
dir Specifies the directory in which the export file is created or from which the import file is
read.
file Specifies the name of the export or import file. If the name is undef (the default), the
filename is the current date plus a unique number 01..99 in the format: YYYYMMDDnn.
For example, 1999101702, would be the second file created on 1999/10/17.
ext Extension of input/output file name. Default is .exp for export files and .imp for import
files. Can be with or without the dot, i.e. ".dat" and "dat" are both accepted and will
result in ".dat" being appended.
filter Name of the program used to post process the export output. Could be a printer
command or xform, for example.
view_file If set to 1, every row will be printed to STDOUT as well as to the file.
debug If set to 1, every procedure call will be printed to STDOUT and nothing will be executed.
Default is 0.
line_terminator Character or string used to separate lines in the exported file. A typical use is to set
line_terminator to CRLF (line_terminator = \r\n). To set line_terminator to an empty
string (or remove linefeeds) use line_terminator = ''.
empty_output Output file is opened and header and trailer are written even if no data is returned from
the database query. Possible values yes and no.
my_own_variable You can define your own command-line variables.
4 Using Import Export tool
4.5 Definition file (.def)
60 © Wall Street Systems IPH AB - Confidential
4.5.4.1 Data type definitions
Every variable used in the body section of the template file has to have a data type associated with
it. This data type may be one of the pre-defined basic or built-in data types or may be defined by
the user in the format section of the template file.
There are two ways to write format definitions: by using curly brackets to group keywords for a
particular field/type or to use the field.keyword notation:
type_name {
type: value
format option: value
format_option: value
.....
}
or
variable_name.format_option: value
For example, to set the length and alignment of the field number, write:
number {
length: 16
alignment: left
}
or
number.length: 16
number.alignment: left
A user-defined data type may have any number of associated format options; user defined data
types build on existing data types and inherit all the format options of the type they are building on.
Any format option can however be overwritten by explicitly redefining it.
4.5.4.2 Predefined data types
There are a number of built-in and predefined data types. In the following table, these data types
are described and the regular expression which is internally created is shown.
4.5.4.3 Format options of data types
The following format options can be used to describe the data types:
Data type Regular expression
integer (\d*?)
float, money ([\+\-\d$decimal_separator$fill_character]*?)
(swift): ([\+\-\d,$fill_character]*?)
datetime Any digit in the time_format string is matched with \d.
character (.*?fill_character)
Formatting
keywords Description
absolute Converts integer, float or money values to their absolute value. Possible values are yes
and no.
alignment Specifies whether the formatted value is shown in the left or right end of the field (left
or right aligned), if the maximum field length exceeds the length of the formatted
value. If omitted, no alignment occurs. Possible values are left and right.
4 Using Import Export tool
4.5 Definition file (.def)
TRM System Administration Guide 61
fill_character Character used to fill fixed-length fields, if the maximum field length exceeds the length
of the formatted value. To fill in spaces one has to enclose the space character in single
quotes, i.e. ' '.
decimal_separator Specifies the character (sequence) used as decimal separator for float and money
types. To specify empty string one has to use single quotes, i.e. '', or use the undef
keyword. If the swift_format option is yes this option will be overridden.
thousand_separator Specifies the character (typically point, comma, or space) to separate adjacent 3 digit
sequences in the integer part of a number, e.g. 1,000,000.00. To have spaces one has
to enclose the space character in single quotes, i.e. ' '.
precision Specifies the decimal precision of money and float types. Possible values are
non-negative integers. If precision is zero, the decimal_separator will not be shown. If
the swift_format option is yes this option will be overridden.
leading_zeros Specifies whether zeros will be prepended to a number value if the maximum field
length exceeds the length of the formatted value. This is equivalent to setting
fill_character to 0 and alignment to right, but for negative numbers the output is
different. For instance, -100 would be displayed as -0000100 using the leading_zeros
approach and as 0000-100 using the fill_character approach.
swift_format Specifies whether the money or float value will be displayed according to the SWIFT
standard (numbers will be shown without sign, comma as the decimal separator and
without thousand separators). Possible values are yes and no.
time_format Specifies the format of dates and times for datetime types. Possible values are:
YYYY - year in four digits
YY - year in two digits
MM - month in two digits (01, 02, 03, ... ,12)
M - month in one or two digits (1, 2, 3, ..., 12)
DD - day of the month in two digits (01, 02, 03, ..., 31)
D - day of the month in one or two digits (1, 2, 3, ..., 31)
hh - hours
mm - minutes
ss - seconds
For example, to get a date/time like 1998/12/24 13:30, write YYYY/MM/DD hh:mm.
length Specifies the maximum length of the field. If the formatted value is longer then the
maximum field length, the value will be truncated. If it is shorter that the maximum
field length, it gets padded with the fill character.
case Specifies whether character type values should be shown in upper, lower or mixed case.
Possible values are upper and lower. To get mixed case one must use undef.
type Data type of the variable. This can be either one of the basic or built-in types (character,
integer, float, datetime, money) or a customized data type.
key_of Specifies the name of the database table which the field is a key of. This enables the
use of the dot notation to access database table fields. Possible values are Client,
Portfolio, Instrument and Equity.
regexp (import) With this option you can specify the regular expression to be used for internal parsing.
This option overrides the automatically created regexp. This option should be used as
an exception, only when the internal regexp generation does not work sufficiently. Do
not use, unless you know exactly what you are doing.
Formatting
keywords Description
4 Using Import Export tool
4.6 Perl functions (the Interface class)
62 © Wall Street Systems IPH AB - Confidential
4.6 Perl functions (the Interface class)
The Interface class allows complex logic to be included in the interface. If the templates and
formatting parameters are not expressive enough to create the specified output, additional logic
using Perl functions can be written (for instance, if some part of the template should not be
displayed depending on a certain condition in the input data).
The recommended approach to add this logic is to derive a new Perl class that inherits the
TemplateInterface class. (See 4.11 TemplateInterface class on page 67.) The TemplateInterface
class is a subclass of the Interface class.
Note: For performance reasons, it is generally recommended to use stored procedures as much
as possible rather than defining new classes.
The structure of a new subclass looks as follows:
package PACKAGENAME;
use TemplateInterface;
@ISA = qw (TemplateInterface);
sub new {
my ($class, @templates) = @_;
my $this = new TemplateInterface (@templates);
bless $this, $class;
return $this;
}
The new class can define so-called hook functions that can be called at certain stages in the process
of file creation to manipulate the incoming and outgoing data before and after parsing. Basically, the
hook functions can manipulate either the raw database input (start functions) or the formatted
output (finish functions).
4.6.1 Export hook functions
4.6.1.1 Start functions
export_header_start ($row)
export_body_start ($row)
export_trailer_start ($row)
These functions are called before the database query row is evaluated against the template. The
$row parameter is a reference to a hash containing name-value pairs that come from the query. It is
possible to change the existing row values and set new ones by using normal assignment.
A special feature is that one can specify the template to be used by setting $row->{template} to
the name of the required template. If, for some reason, the whole row should be excluded from
further processing, this can be achieved by returning the string ‘skip’ (return ‘‘skip’’;) from
the function export_body_start(). Other return values are ignored.
Here is an example of a start hook function that sets the template and some other fields and ignores
some rows.
sub export_body_start {
my ($this, $row) = @_;
if ($row->{layout} eq "MM") {
$row->{template} = "XYZ";
} elsif ($row->{layout} eq "FX") {
$row->{template} = "ABC";
} else {
4 Using Import Export tool
4.7 External packages: predefined modules
TRM System Administration Guide 63
return "skip";
}
$row->{count} = $count++;
}
4.6.1.2 Finish functions
export_header_finish ($output)
export_body_finish ($output)
export_trailer_finish ($output)
These functions are called after the template has been evaluated. The $output parameter is a
reference to the resulting output string. For instance, to remove new lines from the output one
would write:
$output =~ s/\n//g;
4.6.2 Import hook functions
4.6.2.1 Start functions
import_header_start ($input)
import_body_start ($input)
import_trailer_start ($input)
These functions are called before the input is matched against the appropriate templates (header,
body, trailer). The templates are tried in such an order that the one with least number of lines is
first. Generally it is not possible to say how many times these functions are called, it might be only
once or it might be as many times as there are templates.
If, for some reason, the whole row should be excluded from further processing, this can be achieved
by returning the string ‘skip’ (return ‘‘skip’’;)from the function import_body_start(). Other
return values are ignored.
4.6.2.2 Finish functions
import_header_finish ($params)
import_body_finish ($params)
import_trailer_finish ($params)
These functions are called after the input has been matched against a template. If the match was
successful, the $params variable contains a reference to the resulting name-value pairs. If the
match was not successful, $params will be undef.
4.6.3 Overriding default functions
It is, of course, possible to override any of the functions defined in the Perl classes Interface and
TemplateInterface (see 4.10 Interface class on page 65 and 4.11 TemplateInterface class on page
67).
4.7 External packages: predefined modules
Four predefined Perl modules are available for Import Export Tool. Each of the modules corresponds
to a table in the TRM database with the same name.
First, the variable used in the body part of the template file contains an extra element, the name of
the key used to index the external table, in addition to the variable name in that table.
4 Using Import Export tool
4.8 Running Import Export tool
64 © Wall Street Systems IPH AB - Confidential
BEGIN BODY
name_of_key.variable_name
END BODY
The first part is the name of the key used for indexing the respective table; the second part is the
field name from that table.
Secondly, in the format part of the definition (.def) file, the key is associated as a key of a table by
the following syntax:
BEGIN FORMAT
name_of_key.key_of: NameOfPredefinedModule
variable_name.type: type_name
END FORMAT
The variable itself must also be associated with a data type.
4.8 Running Import Export tool
4.8.1 Running from the command line
To run Import Export tool from the command line after an environment evaluation:
On UNIX:
cd $FK_HOME/share/interface/
interface <package> (import|export) [name=value ...] [@name=value ...]
On Windows:
cd %FK_HOME%\share\interface
perl Interface <package> (import|export) [name=value ...] [@name=value ...]
where:
<package> is the interface you have set up
(import|export) - choose the direction of the data transfer
[name=value ...] - to specify one of the built-in variables. (See 4.5.3 Variables on page 57.)
[@name=value ...] - to specify a stored procedure parameter variable.
For example, to export MYINTERFACE XYZ payments, use the following:
On UNIX:
./interface MYINTERFACE::Payment::XYZ export @portfolio_id='TOP'
On Windows:
perl Interface MYINTERFACE:Payment::XYZ export @portfolio_id=TOP
To import fx-match statements you could use:
On UNIX:
./interface FXMATCH import @file='/tmp/fxmatch.txt'
On Windows:
perl Interface FXMATCH import @file=/tmp/fxmatch.txt
4 Using Import Export tool
4.9 Debugging
TRM System Administration Guide 65
4.8.2 Methods of script execution
Running Import Export tool can be achieved in several different ways with TRM:
Manually: on the command line as shown above.
Repeatedly: via crontab (UNIX). For example every hour:
10 * * * * ./interface FXMATCH import @file='/tmp/fxmatch.txt'
From Money Transfer Method Editor in TRM:
Define a new method in Money Transfer Method Editor: give a unique id and method name in the
ID and Method fields, and the required command in the Command field (for example the XYZ END
FORMAT payments example shown above). The method can now be used automatically for
exporting payments. The batch_id is appended as command-line variable and can thus be used in
Import Export Tool to export the payments to a file and/or to screen.
4.9 Debugging
To debug an interface, use the following command:
On UNIX: fk-perl -d ./interface <PKGNAME> {import|export}
On Windows: perl -d Interface <PKGNAME> {import|export}
and then
c 52
to continue to line 52. From here, it is possible to set breakpoints in your own .pm file. For example:
b MYINTERFACE::Payment::XYZ::export_body_start
sets a breakpoint in the subroutine export_body_start in the XYZ class, which is a subclass of the
MYINTERFACE class.
4.10 Interface class
An abstract class from which all import and export interfaces are derived. Defined in the file
Interface.pm.
4 Using Import Export tool
4.10 Interface class
66 © Wall Street Systems IPH AB - Confidential
4.10.1 Interface class functions
4.10.2 Interface member functions
Function Description
init Initialize.
find_package Return the most specific class that is defined @param @packages list of packages.
Returns: the most specific one or undef if not found
package_split Split package name to an array of package names.
For example, $this->package_split ("abc::def::ghi") would return
("abc::def::ghi" "abc::def" "abc").
Parameters: package - name of the package
Returns: list of packages
package_to_file Construct Perl .pm file name from a package name.
Parameters: package - name of package
Returns: file name
file_exists See if a file exists in the include path.
Parameters: name - name of the file
Returns: the full file name if found, otherwise undef
default_file_name Return the default file name YYMMDDNN, where YY is the current year, MM is the current
month and DD is the current day. NN is an increasing sequence number for files with the
same date, 01 for the first file.
Parameters: dir - directory; ext - extension
Returns: file name (without directory and extension)
pad_right Add pad characters to the right of a string or truncate it.
Parameters: value - input string, width - width of the output string, pad - pad
character
•Returns: result
pad_left Add pad characters to the left of a string or truncate it.
Parameters: value - input string, width - width of the output string, pad - pad
character
•Returns: result
swift_amount Format amount in SWIFT format.
Parameters: amount - unformatted amount
Returns: formatted amount
Function Description
new Constructor.
process_args Store command line arguments.
Arguments of the type foo=bar are stored in a hash, referenced by
$this->{cmdline_variables}. Arguments of the type @foo=bar are stored in an array,
referenced by $this->{cmdline_parameters}.
export_file Fetch records from the database and write them to a file.
import_file Read records from a file and insert them to the database.
4 Using Import Export tool
4.11 TemplateInterface class
TRM System Administration Guide 67
4.11 TemplateInterface class
A class for importing and exporting files using templates. Defined in the file TemplateInterface.pm.
read_database Fetch records from the database and store them in a hash, referenced by
$this->{export_rows}. Store field types to the hash referenced by
$this->{export_types}.
write_database Insert records to the database.
write_file Write records to a file.
read_file Read records from a file.
write_file_body Loop through rows to write the body of the file. Calls pure virtual method write_row.
sql_value Format a field value for the database.
Parameters: name - field name, value - field value
Returns: formatted value
sybase_type Default function for getting Sybase type for a field
Parameters: name - field name
Returns: Sybase type
db Return the database handle.
procedure_
parameters
Return the array of parameters to the export or import stored procedure.
Parameters: direction - import or export
line_terminator Return the default line terminator.
The default line terminator is defined in the VARIABLES section of the .def file.
export_handle Return the file handle to the export file.
import_handle Return the file handle to the import file.
open_export_ file Open the export file handle for writing. If file name is not defined, write to standard
output.
close_export_file Close the export file.
open_import_file Open the import file handle for reading. If file name is not defined, read from standard
input.
close_import_file Close the import file.
file_name Return the import or export file name.
Uses the dir, file and ext variables.
Parameters: direction - import or export
Returns: filename or undef if export directory is undefined.
variable Return a variable.
Try in order: command line variable, import or export variable, common variable,
environment variable (e.g. FK_EXPORT_DIR).
Parameters: direction - import or export, variable - name of the variable
Returns: variable value or undef if not defined
Function Description
4 Using Import Export tool
4.11 TemplateInterface class
68 © Wall Street Systems IPH AB - Confidential
4.11.1 TemplateInterface class functions
4.11.2 TemplateInterface member functions
Function Description
get_fields Get field names from a template.
Parameters: template - name of the template
Returns: reference to an array of fields
read_lines Read a specified number of lines from a file handle.
Parameters: handle - file handle, count- number of lines to read
Returns: the most specific one or undef if not found
line_count Get the number of lines in a string.
For example, $this->package_split ("abc::def::ghi") would return
("abc::def::ghi" "abc::def" "abc").
Parameters: string - input string
Returns: number of lines
escape_meta Escape regular expression metacharacters in a string.
Parameters: string - input string
•Returns: result string
align Do alignment, padding and truncation.
Parameters: value - input value, length - length, fill_character - fill character,
alignment - alignment ("left" or "right")
•Returns: result
add_thousand_
separators
Add thousand separators to a number.
Parameters: value - input number, thousand_separator - thousand separator
•Returns: result
Function Description
new Constructor.
Parameters: templates - array of class names whose template files are read
read_def Read templates and format definitions from the .def file.
Parameters: class - name of the class
write_file_header Write file header.
write_row Write one record to the export file.
write_file_trailer Write file trailer.
read_file_header Read file header.
read_file_body Read file body and trailer.
template_parse Parse input using template.
Parameters: type - template type (HEADER/BODY/TRAILER), start_hook - name of
the function that is executed before parsing, finish_hook - name of the function that
is executed after parsing, input - input lines
Returns: reference to the record hash
set_type Set the type of a field.
Parameters: field - field name, type - field type
4 Using Import Export tool
4.11 TemplateInterface class
TRM System Administration Guide 69
type Get type of a field.
Parameters: field - field name
Returns: field type
select_template Select current template.
Parameters: type - template type (HEADER/BODY/TRAILER), name - template name
template Return a reference to the current or specified template.
Parameters: type - template type (HEADER/BODY/TRAILER), name - template name
or undef
Returns: reference to the current (name is undef) or specified template
template_name Return current template name.
template_type Return the file handle to the import file.
export_header_ start Virtual method that is executed before the current header template is evaluated
with the current header record.
Parameters: row - reference to the header record hash (initially empty)
export_header_finish Virtual method that is executed after the current header template has been evaluated
with the current header record.
Parameters: output - reference to the evaluated template
export_body_start Virtual method that is executed before the current body template is evaluated with the
current body record.
Parameters: row - reference to the body record hash
export_body_finish Virtual method that is executed after the current body template has been evaluated
with the current body record.
Parameters: output - reference to the evaluated template
export_trailer_start Virtual method that is executed before the current trailer template is evaluated with the
current trailer record.
Parameters: row - reference to the trailer record hash (initally empty)
export_trailer_finish Virtual method that is executed after the current trailer template has been evaluated
with the current trailer record.
Parameters: output - reference to the evaluated template
evaluate Evaluate a template
Parameters: row - reference to the input record hash
Returns: evaluated template
expand_field Expand a field of the form key1.key2. ... .field
Parameters: field - fully qualified field name, data - data record
Returns: base field name and field value
output Output a string to the export file.
Parameters: string - output string
format Format a value according to its type.
Parameters: key - field name, value - field value, row - rest of the record (optional),
sybtype - Sybase type of the field (optional)
Returns: formatted value
parse Parse header/body/trailer record
Parameters: input - input lines, template - template to be used for matching
Returns: reference to a hash containing key/value pairs, undef if template does not
match with input
Function Description
4 Using Import Export tool
4.11 TemplateInterface class
70 © Wall Street Systems IPH AB - Confidential
regexp Construct a regular expression from a field definition.
Parameters: key - field name
Returns: regular expression
get_types Get the type array for a field. Elementary type (character, integer, etc.) is the first
element in the array, field name is the last one.
Parameters: key - field name, sybtype - Sybase type (optional )
Returns: reference to the array of types
sql_type Get SQL type for a field name.
Parameters: name - field name
Returns: SQL type
get_format Get a formatting option for a type array.
Parameters: option - name of the formatting option, type_array - the type array
Returns: value of the formatting option
cleanup Clean up a parsed record.
Parameters: name - field name, value - field value
Returns: cleaned up value
import_header_start Virtual method that is executed before the current header template has been evaluated
with the current header record.
Parameters: input - reference to the header record hash
import_header_finish Virtual method that is executed after the current header template has been evaluated
with the current header record.
Parameters: params - reference to the evaluated template
import_body_start Virtual method that is executed before the current body template has been evaluated
with the current body record.
Parameters: input - reference to the body record hash
import_body_finish Virtual method that is executed after the current body template hasbeen evaluated
with the current body record.
Parameters: params - reference to the evaluated template
import_trailer_start Virtual method that is executed before the current trailer template has been evaluated
with the current trailer record.
Parameters: input - reference to the trailer record hash
import_trailer_finish Virtual method that is executed after the current trailer template has been evaluated
with the current trailer record.
Parameters: params - reference to the evaluated template
add_thousand_separ
ators
Add thousands separators to a number.
Parameters: value - input number, thousand_separator - thousands separator
Returns: result
align Do alignment, padding and truncation.
Parameters: value - input number, length - length, fill_character - fill character,
alignment - left or right.
Returns: result
escape_meta Escape regular expression metacharacters in a string.
Parameters: string - input string
Returns: result string
Function Description
4 Using Import Export tool
4.12 Empty sample files
TRM System Administration Guide 71
4.12 Empty sample files
4.12.1 Definition file
BEGIN EXPORT VARIABLES
procedure =
@param =
dir =
file =
ext =
END EXPORT VARIABLES
BEGIN EXPORT HEADER
END EXPORT HEADER
BEGIN EXPORT BODY
END EXPORT BODY
BEGIN EXPORT TRAILER
END EXPORT TRAILER
BEGIN EXPORT FORMAT
END EXPORT FORMAT
BEGIN IMPORT VARIABLES
procedure =
@param =
dir =
file =
ext =
END IMPORT VARIABLES
BEGIN IMPORT HEADER
END IMPORT HEADER
BEGIN IMPORT BODY
END IMPORT BODY
BEGIN IMPORT TRAILER
END IMPORT TRAILER
line_count Get the number of lines in a string.
Parameters: string - input string
Returns: number of lines
read_lines Read a specified number of lines from a file handle.
Parameters: handle - file handle, count - number of lines to read
Returns: lines read
Function Description
4 Using Import Export tool
4.12 Empty sample files
72 © Wall Street Systems IPH AB - Confidential
BEGIN IMPORT FORMAT
END IMPORT FORMAT
4.12.2 Empty Perl module
Template for empty import export Perl module
package Empty;
use TemplateInterface;
@ISA = qw (TemplateInterface);
sub new {
my ($class, @templates) = @_;
my $this = new TemplateInterface (@templates);
bless $this, $class;
return $this;
}
sub export_header_start{
my $this = shift;
my ($row) = @_;
}
sub export_body_start{
my $this = shift;
my ($row) = @_;
}
sub export_trailer_start{
my $this = shift;
my ($row) = @_;
}
sub export_header_finish{
my $this = shift;
my ($row) = @_;
}
sub export_body_finish{
my $this = shift;
my ($row) = @_;
}
sub export_trailer_finish{
my $this = shift;
my ($row) = @_;
}
4 Using Import Export tool
4.12 Empty sample files
TRM System Administration Guide 73
#### The import part
sub import_header_start{
my $this = shift;
my ($row) = @_;
}
sub import_body_start{
my $this = shift;
my ($row) = @_;
}
sub import_trailer_start{
my $this = shift;
my ($row) = @_;
}
sub import_header_finish{
my $this = shift;
my ($row) = @_;
}
sub import_body_finish{
my $this = shift;
my ($row) = @_;
}
sub import_trailer_finish{
my $this = shift;
my ($row) = @_;
4 Using Import Export tool
4.12 Empty sample files
74 © Wall Street Systems IPH AB - Confidential
TRM System Administration Guide 75
Chapter 5 Setting up message management
5.1 Overview
Message Manager generates documents based on information in Wallstreet Suite (Transactions,
Schedule, Payment, Client). The documents can be printed, e-mailed or faxed. For information on
message management for business users, refer to the TRM User Guide.
The creation of a document is usually triggered by the fact that a transaction or other entity is
moved from one state to another in the process flow. If there are TransactionActions, a
MessageRequest is created. Also, EntityActions support the creation of MessageRequests. The
following entities are supported:
Payment Allocation Report
Payment Reminder
Late Payment Reminder
Drawdown Fixing
FX Rate Notification
Facility (using the flow in Facility Editor)
Amount Event
Message Manager uses the serviced daemon (replacing messaged used in TRM 7.1). This daemon is
usually started by Process Monitor, but for debugging purposes, it can also be started in a TRM
environment as follows:
serviced document/document.xml
In general, serviced supports the same command line options as the other real-time services such
as tracing. For details of serviced, see the WSS System Administration Guide.
The steps in producing a message are as follows (details are given in the rest of this chapter):
1. MessageRequest is created in the process flow and sent on the message bus. This step
determines the MessageType.
2. Given a MessageRule, a MessageSubType is assigned.
3. Each MessageRule defines which MessageRuleInstance(s) to use. For example, a
DRAWDOWN-NOTIFICATION implies that one document should be e-mailed to the counterparty
and one other document should be faxed to the bank. There is a one-to-one mapping between
the MessageRuleInstance and Message. In this case there will be two messages created since
there are two MessageRuleInstances attached to the matching MessageRule.
4. The combination of MessageType, MessageSubType and MessageGroup is used to determine a
ContactPerson (found in ClientEditor). A ContactPerson contains among other things the address
such as fax number, e-mail address, language of the document etc.,
5. The combination of MessageType, MessageSubType, Language and TransferType is used to
retrieve a MessageTemplate.
6. The serviced daemon loads the data associated with the underlying message object. The data to
load is defined by the MessageType and the MessageSubType in MessageTypeEditor, using the
tab MessageContent.
7. The document is created, based on the template to use.
5 Setting up message management
5.2 Transaction and Entity flow
76 © Wall Street Systems IPH AB - Confidential
8. The command in the TransferMethod is used to transmit the message.
In Loan Drawdown Fixing Manager, Payment Allocation Manager and Payment Reminder Manager,
you can preview a message by right-clicking on the relevant line.
5.2 Transaction and Entity flow
MessageRequests can be created from both transaction flow and entity flow. An example of a
TransactionAction is as follows:
# Trade tickets for TRM transactions
(state ('OPEN'), mask (0),
rule ('TFLO-MESSAGE_TRADE-TICKET'),
send_full ('document.transaction', message_type='TRADE-TICKET',
state_id='TO-BE-TRANSMITTED')),
The message request gets the message type given by message_type. The parameter state_id
specifies the initial state_id in the message flow for the message request. By default, there are two
possible states:
TO-BE-VALIDATED: you are given the option to approve the message request in Message
Manager
TO-BE-TRANSMITTED: message transfer takes place immediately, without user intervention.
5.3 Message Manager and Message flow
The two main steps are creating messages (match rules and create message) and extracting data
(retrieving the fields defined in MessageContent for the given MessageType/MessageSubType).
To control and overview the process, use Message Manager. Message Manager is an entity board
application with a default message State ID flow is as follows:
1. TO-BE-VALIDATED typically allows the user to add comments. If the four-eyes principle is
applied, a message request is typically validated here.
2. EXECUTE is normally used just for previews. MessageRequests in this state now show in
Message Manager.
3. TO-BE-TRANSMITTED These message requests will be sent using the defined TransferMethod.
4. TRANSMITTED if external Message Manager successfully sends all subrequests, the message
request will be moved to this state.
Three thresholds are defined in the message flow (see the database setup folder):
If the MessageRequest is flagged Provisional, Message Manager will try to create messages and
extract the underlying data. For example, the first provisional state is TO-BE-VALIDATED, so
message creation and data extraction take place as soon as a MessageRequest is created.
If the MessageRequest is in a state flagged Intermediate, serviced tries to carry out the action
defined in the corresponding TransferMethod (e.g. send an e-mail, execute a script, fax or print).
By default, TO-BE-TRANSMITTED is an intermediate state.
If the MessageRequest is in a state flagged Final, no further processing takes place. For
example, if a MessageRequest consists of three messages and all are sent successfully, the
MessageRequest will be accepted into TRANSMITTED which is a state flagged as Final.
5 Setting up message management
5.4 Examples of messages
TRM System Administration Guide 77
5.4 Examples of messages
A trade ticket should be printed immediately
The MessageRequest is created in a state which is defined as "to be transmitted immediately"
(TO-BE-TRANSMITTED). Since this MessageRequest does not have any messages yet and it is in an
intermediate state, the daemon instructs Message Manager to process the message. This processing
results in:
Rule matching, finding subtype since there is no structure yet
Data extraction
Upon successful data extraction the MessageRequest is accepted. If the next state is a
transmission-enabled state (intermediate) the execution will be continued. This means that the
document will be either printed immediately, or sent as an e-mail.
A MessageRequest is created in TO-BE-VALIDATED
Since the daemon discovers that this MessageRequest does not yet have any structure, serviced will
create a structure (find subtype, match rules, messages according to the MessageRuleInstances).
The user approving messages starts Message Manager and clicks ACCEPT on the MessageRequest.
The MessageRequest will now be moved to state EXTRA-VERIFICATION (not defined by default).
This allows another person to also accept the message into an intermediate state (where it will be
transmitted). Any number of states can be created to reflect the work process.
Messages that need comments as well as approval
In this case, Message Manager allows editing of these remark fields before the message reaches a
state that allows transmission. Initially this MessageRequest is created in a provisional state . The
daemon will discover the non-existence of structure (Message), therefore it will be processed and
Messages will be created. The user starts Message Manager and edits the MessageRequest remark
fields. Then the user ACCEPTS the MessageRequest into state TO-BE-TRANSMITTED and everything
proceeds as in the above cases.
5.5 Setting up Message Manager
Set up Message Manager as follows:
1. Edit the layouts using MS Word 2003 or 2007 and save them as XML.
2. Install the XML plugin described below. This is needed in order to mark the TRM specific fields to
be replaced by real data.
3. If other type and subtype combinations than provided by the best practice package is needed,
they need to be entered in Message Type Editor.
4. Upload the templates using the script upload_documents.py
5. Review the message rules in Message Rule Editor.
6. Check Transfer Type Editor and review transfer types.
5.6 Previews
There are two kinds of previews:
Transaction Manager
When the user selects preview action, the action scans all available TransactionActions for
5 Setting up message management
5.7 Extracting data
78 © Wall Street Systems IPH AB - Confidential
possible MessageTypes and MessageSubTypes and presents a dialog box. When the user clicks
OK, a hidden MessageRequest and Message(s) created. Only the Message where the
corresponding MessageRuleInstace is flagged primary message will be displayed.
Message Manager
Right-click on a message. The message to preview is identified by its id.
5.7 Extracting data
Data extraction is based on the same modules as the GUI applications. For example, if a document
is based on a Transaction, the available fields are the same as in the corresponding Transaction
Manager view. If needed, additional static date fields can be included from static data editors.
For example, to display the name of a transaction currency:
1. Select Transaction.currency_id and Currency.name as fields in Message Type Editor. The
Currency source will not appear in the list until the transaction field is chosen).
2. Use the placeholder Transaction.currency_id.name in the document.
For cases when the built-in extraction capabilities are not enough, Message Manager provides
several ways to add and derive client-specific fields as follows:
1. Expressions (powered by python code)
Single field
Declaration in Message Type Editor (valid only in selected source and message type)
Declaration in document-config.xml (available for all message types)
Result set (many fields at a time)
In general, it is best to use expressions in Message Type Editor, because then the business user can
directly edit and review how a certain field is calculated or retrieved.
Making declarations directly in document-config.xml makes the expression available for all message
types. Expressions made in Message Type Editor are valid only in the selection message type.
Python code allows access to computed fields (same data as used by GUI applications) and is
database-independent. The python code to write depends on whether there is a need to process
only one field or many at a time.
2. SQL code in a stored procedure.
The stored procedure approach can be an easy method when migrating from earlier versions of
TRM. (database structure is relevant here). Processing SQL on the server side and returning many
fields in one call is normally efficient if performance is an issue.
5.7.1 Expressions
5.7.1.1 Single Field
Declare the expression directly in Message Type Editor. For each source, there is a special field
named Calculated. If this field is selected, the property fields become editable. Examples of
expressions that can be used in this field are:
logo='logo_wss.gif'
include_p=(cp_client_id != 'TP-CPTY')
transaction_sign_rev=if(sign_id == 'Buy','Sell','Buy')
sign_name=if(sign_id=='Buy', 'Receive', 'Pay')
date_basis1=if(type_subtype=='Netting',date_basis)
These expressions are driven by the same engine as in Transaction Manager. It is also possible to
call previously defined python functions from the expressions in the Message Type Editor.
5 Setting up message management
5.7 Extracting data
TRM System Administration Guide 79
If you have a single field to compute, this will be coded in a python function: for example, code your
"my_function" function in the python file my_functions.py (Make sure this file is in your python
path):
def my_function (number):
# do some calculation here
...
return result
Declare the calculated field in document-config.xml:
<expression source="Transaction" script="my_functions">
<field name="my_field" label="My Field"/>
my_function (number)
</field>
</expression>
It is possible to select the name of the owner or counterparty using the functions provided:
seller = if (sign_id == 'Sell', get_field ('Client',owner_id,'name'), get_field
('Client',cp_client_id,'name'))
For this to work, the following piece of python code must be saved in the python path, for example
as:
C:\wss\v7\python\lib\Lib\site-packages\functions.py
This folder is usually used for python scripts. Save the following file as functions.py:
import FK.Core
from FK.ORB import from_value, to_value
import IDL.FK.Data_Context
from FK.Cache import Cache
cache = Cache ()
# Arguments are of type value
def get_field (o,k,f):
obj = FK.ORB.from_value(o)
# k should be of type value already
key = to_value(k)
field = FK.ORB.from_value(f)
# print "get_field",obj,key,field
holder = cache.context ()
try:
umi = holder.get (obj, [key])
(found, v) = umi.get_field (field, FK.ORB.to_value ())
if found:
return FK.ORB.from_value (v)
except:
return ""
return ""
The file functions.py must be linked to the source to be used in document-config.xml:
<expression source="Transaction" script="functions"/>
This makes the get_field function available to all Transaction sources. It is also possible to define the
field in document-config directly:
<expression source="Transaction" script="dc-values">
<field name="test_name" label="Test name">
get_field('Client',cp_client_id,'name')
</field>
</expression>
5 Setting up message management
5.7 Extracting data
80 © Wall Street Systems IPH AB - Confidential
The field test_name is now available for selection in Message Type Editor and it will always contain
the name of the counterparty. It will be available for Transaction source only, but it will be available
across all Message types. If it is needed in yet other source, just add it again, but change the source
attribute.
5.7.1.2 Result set (multiple fields)
More complex processing may be required. There might be cases when the filter syntax is not
enough to get a certain cashflow. If there is a need to compute values based on several cashflows
and flags etc, the python code for this can be placed in the same python file as the above
expressions.
In general, if many parameters need to be computed at the same time, they are interdependent or
fetched altogether. Code a function called get_values in a python script, my_other_functions.py:
def get_values (ctx, values):
# compute some values
return values
The ctx parameter gives you the source you are considering (Transaction, Cashflow, UMI etc.),
values is a dictionary with fetched fields - from the source. You have to complement this list with
your own calculated information and return it. Finally link your script to Message Manager:
<service module="data/python@my_other_functions">
<fields>
<source name="Transaction">
<field name="my_field_1" label="My first field">
<dependency name="number"/>
<dependency name="comment"/>
</field>
<field name="my_field_2" label="My second field">
<dependency name="number"/>
</field>
</source>
</fields>
</service>
Pay attention to the module attribute where you setup your python script name:
module="data/python@my_other_functions"
A more detailed example of this:
<service module="data/python@myvalues">
<fields>
<source name="Transaction">
<field name="receive_principal" label="Receive Principal">
<dependency name="number"/>
</field>
<field name="pay_principal" label="Pay Principal">
<dependency name="number"/>
</field>
<field name="first_interest_amount" label="First Interest Amount">
<dependency name="number"/>
</field>
</source>
</fields>
</service>
The file myvalues.py must be in your python path. For example:
C:\wss\v7\python\lib\Lib\site-packages\myvalues.py
If above declaration is made in document-config.xml, the function get_values will be called for every
processed source (Transaction). A dictionary is passed as argument, so its contents can be changed
in the get_values function and then returned at the end. For example:
5 Setting up message management
5.7 Extracting data
TRM System Administration Guide 81
import FK.Core
import FK.ORB
FK.ORB.use_idl ("Type")
from FK.Cache import Cache
from IDL.FK.Database import Action
from FK.Module.Transaction_Manager import *
from FK.Core import Money
cache = Cache ()
def get_receive_pay_flows (flows, category_id):
receive_principal = Money (0)
pay_principal = Money (0)
for flow in flows:
if flow.type_id == 1 and flow.category_id == category_id:
amount = Money (flow.amount)
if amount > 0:
receive_principal += amount
else:
pay_principal += amount
return (receive_principal, pay_principal)
def cmp (c1, c2):
if c1.value_date == c2.value_date:
return int ((c1.id - c2.id).as_long ())
return c1.value_date - c2.value_date
def get_values (ctx, values):
print "get_values"
if values.has_key ('number'):
number = FK.ORB.from_value (values['number'])
container = Container ()
action = cache.session ().create_action ()
t = container.retrieve (action, number, True)
if t != None:
if values.has_key ('receive_principal') or values.has_key ('pay_principal'):
(values['receive_principal'], values['pay_principal']) =
get_receive_pay_flows (t.cashflows(), 0) # category settlement
if values.has_key ('receive_redemption') or values.has_key ('pay_redemption'):
(values['receive_redemption'], values['pay_redemption']) =
get_receive_pay_flows (t.cashflows(), 1) # category payback
if values.has_key ('first_interest_amount'):
flows = t.cashflows ()
flows.sort (cmp)
for flow in flows:
if flow.type_id == 2 and flow.category_id == 1: # type interest, category
payback
print '*' * 8, flow.value_date
values['first_interest_amount'] = flow.amount
break
return values
Note that it is possible to call the already existing get_field (to avoid code duplication) function to
lookup needed field in the TRM object hierarchy, for example. In the example below, depending on
transaction sign, different bank names and swift codes are selected. For the moment, all functions
are called with Type::Value arguments.
5 Setting up message management
5.7 Extracting data
82 © Wall Street Systems IPH AB - Confidential
def get_field (o,k,f):
obj = FK.ORB.from_value(o)
# k should be of type value already
key = k
field = FK.ORB.from_value(f)
print "get_field",obj,key,field
holder = cache.context ()
try:
umi = holder.get (obj, [key])
(found, v) = umi.get_field (field, FK.ORB.to_value ())
if found:
return FK.ORB.from_value (v)
except:
return ""
return ""
def get_bond_beneficiary(t):
flows = t.cashflows()
for flow in flows:
if flow.type_id == 1 and flow.sign != t.sign_id:
# Found cashflow to use
beneficiary_details = ()
client_v = FK.ORB.to_value("Client")
name_v = FK.ORB.to_value("name")
swift_v = FK.ORB.to_value("swift_code")
if t.sign_id > 0:
beneficiary_details =
(get_field(client_v,FK.ORB.to_value(flow.local_client_id),name_v),
get_field(client_v,FK.ORB.to_value(flow.local_bank_id),name_v),
flow.local_account_id,
get_field(client_v,FK.ORB.to_value(flow.local_bank_id),swift_v),
get_field(client_v,FK.ORB.to_value(flow.local_corr_bank_id),swift_v))
else:
beneficiary_details =
(get_field(client_v,FK.ORB.to_value(flow.other_client_id),name_v),
get_field(client_v,FK.ORB.to_value(flow.other_bank_id),name_v),
flow.other_account_id,
get_field(client_v,FK.ORB.to_value(flow.other_bank_id),swift_v),
get_field(client_v,FK.ORB.to_value(flow.other_corr_bank_id),swift_v))
return beneficiary_details
5.7.1.3 System functions
Message Manager also provides a set of predefined functions. Date handling is as follows:
Type Parameter Action
today None Gets the current date
year Date Extracts the year
month Date Extracts the month
day Date Extracts the date
5 Setting up message management
5.8 Setting up Document Formatter
TRM System Administration Guide 83
Multiple entities manipulation is as follows. These functions operate on all entities of a source and
return a single value. This unique value is then available on any of the source entities.
5.7.2 SQL code in stored procedures
The stored procedure and the fields to use must be declared in document-config.xml as follows:
<service module="data/stored-procedure@stored-procedure">
<procs>
<stored-procedure name="GetMyInfo" id-field="number" source="Transaction">
<field name="myfield1" label="My field 1 label"/>
<field name="myfield2" label="My field 2 label"/>
</stored-procedure>
</procs>
</service>
When fields are extracted from a transaction, the number is passed as key to GetMyInfo. This
procedure may return a lot of fields and record sets, but only myfield1 and myfield2 will be available
in Message Type Editor. In the document, the following placeholders Transaction.myfield1 and
Transaction.myfield2 can be used.
5.7.3 Filters
New sources can be configured in document-config.xml. The following example creates a new source
which is a subset of the cashflows:
<filter name="PayCashflow" source="Cashflow">
<and>
<and>
<eq field="#sign" type="INTEGER">1</eq>
<eq field="type_id" type="INTEGER">6</eq>
</and>
<eq field="XXX" type="STRING">hot</eq>
</and>
</filter>
5.8 Setting up Document Formatter
5.8.1 Prerequisites
Wallstreet Suite installation must contain the latest version of Apache FOP. There is nothing to
install except to add into the path the folder where FOP is extracted to. Since FOP is Java-based, the
Java runtime environment should also be present.
Entity Parameter Action
min_value Entity field Gets the minimum value of the field in the set of entities
max_value Entity field Gets the maximum value
total Amount field Sums the amounts
average Amount field Averages the amounts
count None Counts the entities
5 Setting up message management
5.8 Setting up Document Formatter
84 © Wall Street Systems IPH AB - Confidential
5.8.2 Settings
All document management settings are in this folder: <Suite Install Folder>/etc/document
which contains the following subfolders:
images - this is where reusable pictures are kept, for example logos and similar items.
interim - temporary folder for intermediate files and final results (PDF files). This folder location
can be customized during setup - if so, the directory to be used should be assigned to the
environment variable named FK_DOCUMENTS_INTERIM_DIRECTORY
.
processor - contains XSLT code that translates WordML to FO (contains subfolders so that we
can use several input and output formats. Read-only.
The main activity is logically splitting message templates by type, subtype, media and language,
then uploading the document into the database. The name of the document is not the file name of
the Word XML document: it is the logical name that you give to this template document, and
defaults to "default".
For example, for type preview_type, subtype preview_subtype, medium email and language en-us,
and the name of the document is not specified, the following command line should be used:
python upload_documents.py --document <template document>
[--input <doc_format(if empty then 'word')>]
[--name <save name(if empty then 'default')>]
--type <type>
--subtype <subtype>
--media <media>
--language <language>
--flags <flags> (1=Subdocument)
--output <output> 0=NONE,1=PDF,2=PS,3=FO-XML,4=TEXT
5.8.3 Authoring template documents
Template files are plain Word documents saved as XML (WordML format). Sample templates are
provided in FK_HOME/etc/document/templates. Word 2003 or 2007 is required to edit these files.
Word XML is a round-trip format, although a small amount of formatting might be lost compared to
the native format.
Option Description
--document The physical path to the MS Word XML file. If --document is ALL, all templates in the
templates folder are uploaded.
--input Defaults to MS Word. If the experimental upload of old FK XML Forms is used, put fkf here.
--name The template document logical name. If left blank, this is DEFAULT. If a header is uploaded,
for example CLIENT_HEADER, it would be the name of the document.
--type The message type, for example CONFIRMATION. Type is determined by the folder name.
--subtype The subtype of the document to upload, for example FX-SWAP. Subtype is determined by the
name of the document file.
--media The media for this document, for example TRM-MESSAGE-EMAIL or TRM-MESSAGE-PRINTER.
--language Specifies the language of the document.
--flags Set to 1 if the document is a subdocument, reusable component or header; for example
en_US or fr_FR. This also controls the localization of the document.
--output Specifies the email output type. In some cases, when creating email documents that contain
an email body and a PDF attachment, the PDF type is determined by the TransferType, but we
still need to force the email body to be text. In this case, set --output to 4 for the email
body.
5 Setting up message management
5.8 Setting up Document Formatter
TRM System Administration Guide 85
In the Templates and Add-Ins dialog:
1. Select the XML Schema tab.
2. Click Add Schema.
3. Navigate to TremaData.xsd.
Important: The next step should be done very carefully.
4. The URI in the dialog that will open must precisely match the following URI:
urn:trema.com:module-document-manager:data-tags
The alias is not important, but for consistency we suggest that the text "tdm" is entered. We
recommend that you also check (switch on) the following options in the XML Options dialog and
leaves all other options OFF (accessible from XML Structure task pane once at least one XML
schema is associated with the document):
Validate document against attached schemas
Hide namespace alias in XML Structure task pane
Show advanced XML error messages
The editing process can now proceed normally. To enter a placeholder/marker for the
transaction/cashflow data, it is enough to type the expression, like this:
Transaction.portfolio_id.name
Then select this text and click TremaData in the XML Structure task pane. The marker will be
highlighted and easily distinguishable from the rest of the text. The XML Structure task pane will
also show a list of all TremaData tags in the document for easy navigation from one to another. You
can change the formatting of the placeholder text and it will be preserved.
Sometimes there will be multiple values in the output document even though the template
document uses a simple marker. For example, if you specify Cashflow.value_date, there will be
as many values as are cashflows for the given transaction. This kind of value must be put in the
table with a single row for content and as many header rows as required. Values will be expanded to
multiple rows as necessary on the fly. There are some limitations (mainly driven by restricted
Preparing Word 2003 Preparing Word 2007
Go to the Microsoft website and download and
install a free Add-in for Word 2003.
If you have Word 2007, then you already have XML
capability, but may need to activate it as follows:
•If the Developer tab is not visible in the Word
Ribbon (toolbar):
a. Click the Office button (big round button, top
left of the Word screen).
b. Click the Word Options button.
c. In the Word Options dialog, switch on (check)
the Show Developer tab in the Ribbon switch
(checkbox).
Ensure that the XML Structure task pane. •Click
Structure in the XML box of the Developer tab.
Before you can start entering data, Word needs to know about the format of the data (which XML tags to use).
The format is defined in the XML schema file TremaData.xsd, provided in the same settings folder.
In the XML Structure task pane, click Templates and
Add-Ins.
•Click
Schema in the Developer tab.
This opens the Templates and Add-Ins dialog. From now one the instructions are similar for both Word 2003
and 2007.
5 Setting up message management
5.8 Setting up Document Formatter
86 © Wall Street Systems IPH AB - Confidential
functionality of third party tools): the table has to be manually formatted (not using AutoFormat
feature of Word) and the columns have to have fixed width (not automatic which is the default).
There is one special placeholder called Header, used for fields that are not directly data
(transaction)-related: things like remarks, recipient and address are exposed through this
placeholder. The syntax for the first remark is therefore Header.remark_0.
To insert a page break, add the following line:
<TremaData>pagebreak</TremaData>
5.8.4 Saving Word 2007 XML files
We recommend that you save templates like this: Save As - Other Formats - Word 2003 XML Document.
5.8.5 Authoring common placeholders
Besides from data from the Wallstreet Suite you may need other types of information dynamically
evaluated during document construction.
Many documents have a placeholder for the date, to be replaced with the current date at the
moment of document creation. This is done using the date field in Word: Insert->Field, choose
category Date and Time and pick Field name->Date (date format is irrelevant and is ignored for the
moment). The resulting field is evaluated as the current date of the document creation using the
format of the language set for the document (set up as described in 5.8.2 Settings on page 84).
A frequent use of images in documents is for logos. To avoid storing logos in every template
document, users should always link to the picture and not embed it in the document. To insert a
linked image, go to menu Insert->Picture->From File, then navigate to the image and instead of
just clicking on Insert button, click on an arrow on the Insert button and choose Link to File.
In contrast, if image is linked, all that needs to be done is to replace the image on the hard drive. All
linked images should be put in the images folder. During evaluation, Trema will patch the path to
the image to point to the correct folder. You can press Alt+F9 to flip fields from their evaluated form
into the formula form and back (this will help identify if a linked image has a broken path but the
name of image itself is correct, or if the image linked to does not exist at all).
5.8.6 Including reusable text (subdocuments)
You can re-use existing sections in many documents. The inclusion of reusable text (a
subdocument) is conditional: a section is included or excluded depending on a certain condition. The
main reason for reusing text is to reduce the number of templates. Examples of conditions are:
If the portfolio_id.owner is your own bank, more details are needed on the document. For
example, if the confirmation is to be sent to a counterparty, two places for signatures are
required. Note that addresses are written differently in the US and in Europe.
If the confirmation is to be sent to a certain counterparty, two places are required for signatures.
Addresses are written one way in US and one way in Europe
5.8.6.1 Writing and uploading templates
This example shows one main document and two subdocuments. The main document is as follows:
5 Setting up message management
5.8 Setting up Document Formatter
TRM System Administration Guide 87
The subdocuments are as follows:
An Include function inside TremaData tags accepts two arguments: the first one is a True/False
variable and the second refers to a document which is included if the first variable evaluates to True
or to 1.
Subdocuments should be normal documents, where the text goes in the body. The include
statements can be placed anywhere in the main document.
5 Setting up message management
5.8 Setting up Document Formatter
88 © Wall Street Systems IPH AB - Confidential
The subdocuments are loaded into the database in the same way as normal documents. To upload
the above example in the database, execute the following batch file:
set DOCMAN_TEMPLATES=d:\work\etc\subdoc
set UPLOAD_SCRIPT=d:\wss\v7\share\python\upload_documents.py
python %UPLOAD_SCRIPT% --document %DOCMAN_TEMPLATES%\default.xml --type FH --subtype
DEFAULT --media TRM-MESSAGE-EMAIL --language en_US
python %UPLOAD_SCRIPT% --document %DOCMAN_TEMPLATES%\ownbank.xml --name OWNBANK
--type FH --subtype DEFAULT --media TRM-MESSAGE-EMAIL --language en_US --flags 1
python %UPLOAD_SCRIPT% --document %DOCMAN_TEMPLATES%\special.xml --name SPECIAL
--type FH --subtype DEFAULT --media TRM-MESSAGE-EMAIL --language en_US --flags 1
Note that all are coded with the same type, subtype, media and language. The name is used to label
the subdocuments differently from the default one. To reuse the same subdocument for another
message type, upload the same xml file with the new type, subtype, media and language.
5.8.6.2 Defining the expressions
In this example there is a condition for including the header: if the owner is ABC, the ABCHEADER
subdocument should be included. This condition translates to the following expressions in the
MessageTypeEditor:
include_p=(owner_id == 'ABC')
owner_header_name=’ABCHEADER"
The fields need not be from an expression. For example the owner_header_name could also come
from a stored procedure: in this case, it is added as content, just like any other field.
Sometimes it is convenient to name the header and footer like the owner_id. In this case, this field
can be used to name the subdocument to be loaded:
owner_header_name=owner_id+'HEADER'
If the owner is ABC, the subdocument named ABCHEADER will be loaded if the following include
statement is used in the layout:
<TremaData>include(Transaction.include_p,Transaction.owner_header_name)</TremaDa
ta>
A dedicated header must be uploaded for each portfolio owner.
5.8.7 Customizing the e-mail body
Message Manager uses a default e-mail body (defined in transfer_manager.py), but you can write
an e-mail body in MS Word and use it instead of the default. TRM tags are supported as for other
documents.
The following example uses one main document which includes two subdocuments, and one body
for the e-mail:
python upload_documents.py --document %DOCMAN_TEMPLATES%\default.xml --type
TRADE-TICKET --subtype DEFAULT --media TRM-MESSAGE-EMAIL --language en_US
python upload_documents.py --document %DOCMAN_TEMPLATES%\emailbody.xml --name
EMAILBODY --type TRADE-TICKET --subtype DEFAULT --media TRM-MESSAGE-EMAIL --language
en_US --output 4
python upload_documents.py --document %DOCMAN_TEMPLATES%\ownbank.xml --name OWNBANK
--type TRADE-TICKET --subtype DEFAULT --media TRM-MESSAGE-EMAIL --language en_US
--flags 1
5 Setting up message management
5.9 Message transfer
TRM System Administration Guide 89
python upload_documents.py --document %DOCMAN_TEMPLATES%\special.xml --name SPECIAL
--type TRADE-TICKET --subtype DEFAULT --media TRM-MESSAGE-EMAIL --language en_US
--flags 1
The resulting e-mail to be sent consists of one attached document (default.xml) and the e-mail body
(emailbody.xml). The main document also uses two subdocuments (ownbank.xml and special.xml).
Note that:
The subdocuments must be flagged with bit 1 when uploading. Otherwise the formatter will
process these documents in the same way as a normal document (this is not needed, as they
will be included in the main document).
The EMAILBODY must be named "EMAILBODY" and it must have output format 4 (i.e. text - see
upload_documents.py --help). The exact name "EMAILBODY" is referenced in
transfer_manager.py, so if this name is changed, transfer_manager.py must be changed
accordingly.
5.8.8 Customizing rounding numbers and amounts
In most cases, all amount and number related fields use the same formatting as in Transaction
Manager. If a number is not correctly formatted, check if the field can be changed when configuring
Transaction Manager (using the view XML files).
In some cases, if you have customized fields it might still be necessary to fine-tune the number
formatting. One way of doing this would be to code the formatting in python and add the fields in
document-config.xml. For example, put the following functions in the python script. Numbers and
money types are handled differently:
def floatround(a,d):
return round(a,d)
def moneyround(a,d):
return a.round(d)
and in document-config.xml:
<expression source="Transaction" script="myscript">
<field name="rounded_deal_rate" label="Rounded deal rate">
floatround (deal_rate, 2)
</field>
<field name="rounded_amount" label="Rounded amount">
moneyround (amount, 2)
</field>
</expression>
5.9 Message transfer
When the message is formatted, it exists on disk as a temporary file. The format is given by the
TransferType (FO-XML, PDF or Postscript).
The next step is to transfer the file using the given TransferType. Usually, the way of transferring
the document or message is very client specific. The message transfer offers built in e-mail support
(sending e-mail document as attachment) and execution of scripts. If other processing is required, it
needs to be developed as an CSD.
The code which executes the message transfer is scripted (can be customized on site) in python to
allow for required flexibility. It can call any other script or executable (e.g. perl or fax client) with
needed arguments and all extracted data is available through CORBA.
This script is available in the following locations:
NT:
5 Setting up message management
5.9 Message transfer
90 © Wall Street Systems IPH AB - Confidential
FK_HOME\python\lib\Lib\site-packages\transfer_manager.py
UNIX:
FK_HOME/lib/python2.4/site-packages/transfer_manager.py
The daemon serviced will call a method called transfer with two arguments:
the message reference. By calling different methods on this reference, you can both fetch data
and pass information back to the caller. In the IDL, the following methods are available:
// message current status
boolean validate_field (in Type::String_Sequence field_path);
// message current status
void set_status (in Status_Type status);
// log a error message
void log_message (in string msg);
// retrieve the content of the message
Entity_Values_List get_content ()
raises (Failed);
The URL which is the path to the formatted document (FO-XML, Postscript or PDF).
5.9.1 E-mail example
The E-mail transfer type is available as an example in transfer_manager.py. It should work with
only minor modifications. For example the SMTP server and "from" address needs to be changed to
reflect your site. Edit line 207 in transfer_manager.py to a valid SMTP server and e-mail address.
The default implementation does the following:
1. Fetch address and medium_id from the message reference
2. if the medium_id equals "E-MAIL", an e-mail is constructed directly in the python servant.
3. The subject field is constructed as message type /message subtype + transaction number
(Optional)
4. The python smtplib is used to send the message.
5.9.2 Fax example 1
The client has an existing fax script:
perl send_fax.pl -n <phone_number> -u <postscript file>
To reuse this script we create a TransferType:
When the formatter finishes, a Postscript document is available at:
<FK_HOME>/etc/document/interim/tmp11467.ps
The address of the recipient is for example +12345, transfer_manager.py automatically translates
the @address@ and @url@ so that the actual call to the script will be:
Method FAX
Address Type Fax This makes Message Manager look in the
"fax" field in Contact Person tab in Client
Editor
Command perl send_fax.pl -n @address@ -u @url@
Format Postscript Desired file format of the url
5 Setting up message management
5.9 Message transfer
TRM System Administration Guide 91
perl send_fax.pl -n +12345 -u <FK_HOME>/etc/document/interim/tmp11467.ps
5.9.3 Fax example 2
Some fax gateways works by putting the fax number in a certain e-mail address. For example:
12345@mycompany.com would send the attached file as fax to number 12345. In this example we
need to modify the transfer_manager.py. First create a new TransferMethod as follows:
We choose to code this transfer inside the transfer_manager.py. Add the following code snippet just
before the create_and_send_email in the transfer method:
to_address = content['address'] + "@mycompany.com"
if medium_id == "FAX-GATEWAY":
self.create_and_send_email(url,to_address,content)
else if medium_id == "E-MAIL":
In short, we check the transfer method and then modify the address to work with the e-mail fax
gateway.
5.9.4 Printer example
Most Postscript printers (UNIX and NT) accept commands like this:
lpr -S PRINTSERVER -P TRADE_TICKET_PRINTER file.ps
By default, transfer_manager.py calls the command given in the TransferType, so to support
printing, the following transfer method is needed:
Method FAX-GATEWAY
Address Type Fax This makes Message Manager look in the "fax" field in ContactPerson tab
Command
Format PDF Desired file format of the url
url Path/url to the document to be faxed
to_address The destination e-mail address
content a python dictionary which contains all headers and extracted data
Method MYPRINTER
Address Type
Command lpr -S MYPRINTSERVER -P MYPRINTER @url@
Format PostScript Desired file format of the url
5 Setting up message management
5.10 Possible problems and solutions
92 © Wall Street Systems IPH AB - Confidential
5.10 Possible problems and solutions
5.10.1 Developing test cases
It is recommended to design well defined test cases for the documents to be created. A test case
defines how to run the test as well as its expected result. For example:
1. Duplicate transaction X
2. Commit transaction X in OPEN
3. Open MessageManager. Verify that there is a new line with message type Y and transaction X
4. After less than 20 sec., the message request should end up in state Transmitted
5. Verify that there is a PDF file created in folder Z
6. Open the PDF and verify the document itself.
If for example there is no PDF file created, there are some tools to find out why the message failed.
See sections below. The results of the scripts test.py and callproc.py are useful.
Test cases like this are a good way of measuring progress (the ratio between passed test cases and
the total number cases). They are also very valuable for CSS and R&D in case the a solution is not
found on the client site (they can be put directly into a TREMS item).
5.10.2 Previewing transactions
Start MessageManager. It is possible to examine errors on both MessageRequest level and for each
individual message.
By default, previews are not displayed in MessageManager. If the preview fails, use SQL to select
the MessageRequest like this:
select max(id) from MessageRequest
go
---------------
1298
(1 row affected)
select log from MessageRequest where id=1298
go
log
------------------------------------------------------------------------------------
Cannot find a matching message rule.
(1 row affected)
5 Setting up message management
5.10 Possible problems and solutions
TRM System Administration Guide 93
5.10.3 Test script for previewing transactions
The following is an example of a test script:
print "Initializing ..."
from FK.Core import Numeric
from FK.Cache import Cache;
from FK.ORB import Interface, to_value, from_value, get_reference
from IDL.FK.Document_Manager import Manager, Preview_Manager, Message_Manager
from IDL.FK.Document_Manager import Entity_Desc, Field_Name, Optional_Link, Link
from IDL.Type import Parameter
cache = Cache()
def test_preview (number,type):
print "Txn #%u preview" % number
manager = Interface (Preview_Manager, "document/manager", "preview-manager")
res = manager.preview (number, "Transaction", type)
print "Result in '%s'" % res
# test_preview(41,"CONFIRMATION")
# test_preview(3919,"CONFIRMATION")
test_preview(3361,"ISSUER-FAX-CONFIRMATION")
Run the script in a TRM shell like this:
set FK_TRACE_LEVEL=10
set DATABASE_DEBUG=1
python test.py > log.txt
The environment variables FK_TRACE_LEVEL and DATABASE_DEBUG are used to set the level of
details in the logging.
5.10.4 CORBA error when previewing
This section is relevant to CORBA error or something like Xalan stream error.
In most client installations, the FK file tree is not writable. When the PDF is created, Message
Manager needs a temporary folder to finish the processing. If FK_HOME\etc\document\interim is not
writable, it is necessary to use the environment variable FK_DOCUMENTS_INTERIM_DIRECTORY
which must point to an alternative location.
If TRM is launched on a Citrix server, there can be additional write problems. (no error, but file is
still not altered/created). Make sure that the location you select is really writable.
5.10.5 E-mail problems on windows
Make sure that your virus program allows messaged to do outgoing connections on the SMTP port
(25). The Wall Street virus program blocks this by default.
5.10.6 Error evaluating 'Source.field'
As a first step, check that the extraction was successful. All fields in the final document must be
added to [Message Type Editor]. There is a stored procedure called ReadMessage. This procedure
should return the Message and the extracted XML content. The message id can be found either in
MessageManager or by a simple SQL query.
However, the most common reasons for this are:
Forgot to declare the field in Message Type Editor
5 Setting up message management
5.10 Possible problems and solutions
94 © Wall Street Systems IPH AB - Confidential
Spelling mistake in the Word document
5.10.7 Checking the generated messages
The output of the stored procedure ReadMessage<tt> is useful when validating the extracted data.
A script <tt>callproc.py simplifies the calling of this stored procedure (especially on Oracle).
select max(id) from Message
go
---------------
587
Then use the script callproc.py which should work on all platforms. Example:
fkadmin3@s96td1p2:/trema/bcust/fk callproc.py
With /trema/bcust/fk/bin/callproc.py you call stored procedures interactively.
type 'help' and hit [Enter] for instructions.
dbo> readmessage @id=587
address contact_name content date flags format_id id kind language_id last_date log
medium_id number recipient_id recipient_role_id request_id stamp status
0049-180-125-4100 GCM Domestic Customer Service Fr. Dewitz null 11/07/06 2:34 PM 0 1
587 1 en_US 11/07/06 2:50 PM Failed while merging the data and the layout. Xalan
error is XalanStdOutputStreamWriteException: Error writing to standard stream.The
error code is '24'. (, line -1, column -1) FILE-OUT null DEUT-DESTR 1 1755
c8035230424323541c 3
null null
<msg xmlns="www.trema.com">
<e id="number" n="Transaction">
<f U="Instrument Type" n="_instrument_type_id"/>
<f U="Principal Settlement Amount" n="actual_amount"/>
<f U="Nominal Amount" n="amount"/>
<f U="Audit Number" n="audit_nu+ null null null 68839 null null null null null 0
null null 1755 c80352304243235164 null
null null mber"/>
<f U="" n="beneficiary_account_id"/>
<f U="" n="beneficiary_bank_name"/>
<f U="" n="beneficiary_bank_sc"/>
<f U="" n="beneficiary_bank_swift"/>
<f U="" n="beneficiary_corr_bank_sc"/>
<f U="" n="beneficiary_corr_bank_sw+ null null null 68840 null null null null
null 1 null null 1755 c803523042432352 null
null null ift"/>
<f U="" n="beneficiary_name"/>
<f U="Book Value" n="book_value"/>
<f U="" n="buyer_name"/>
<f U="Call Currency" n="call_ccy_id"/>
snip
5.10.8 Filters do not work
Example: problem with filters in the document-config.xml file. The filters are as follows:
<filter name="PayCashflow" source="Cashflow">
<and>
<eq field="sign" type="INTEGER">-1</eq>
<eq field="type_id" type="INTEGER">5</eq>
</and>
</filter>
<filter name="ReceiveCashflow" source="Cashflow">
<and>
<eq field="sign" type="INTEGER">1</eq>
5 Setting up message management
5.10 Possible problems and solutions
TRM System Administration Guide 95
<eq field="type_id" type="INTEGER">5</eq>
</and>
</filter>
Here the problem seems to be the sign. Apparently it matches what you see in the view. In
TransactionManager you'll see "+" or "-". In FK_HOME\etc\transaction-view\Cashflow.xml you see:
<column name="sign" type="INTEGER" width="8">
<label>Sign</label>
<enumerated name="CashflowSign"/>
</column>
The enumerated name CashflowSign looks as this: (FK_HOME\etc\transaction-view\Views.xml)
<enumerated name="CashflowSign">
<enumeration value="0" visible-value="" visible="false"/>
<enumeration value="1" visible-value="+"/>
<enumeration value="-1" visible-value="-"/>
</enumerated>
So, try the following in document-config.xml instead:
<filter name="ReceiveCashflow" source="Cashflow">
<and>
<eq field="sign" type="STRING">+</eq>
<eq field="type_id" type="INTEGER">5</eq>
</and>
</filter>
The type_id is the "Main Type" and it is an integer even in Cashflow view/Transaction Manager. You
can also use the "#" sign to use the underlying type and value. This is a better long-term solution, in
case the views are changed.
<filter name="PayCashflow" source="Cashflow">
<and>
<eq field="#sign" type="INTEGER">1</eq>
<eq field="type_id" type="INTEGER">6</eq>
</and>
</filter>
5 Setting up message management
5.10 Possible problems and solutions
96 © Wall Street Systems IPH AB - Confidential
TRM System Administration Guide 97
Chapter 6 Managing static data
6.1 Introduction
Wallstreet Suite manages its static data within a workflow in order to provide:
Controlled access to modifications
4-eyes verification
Synchronization of static data shared between Wallstreet Suite modules.
6.1.1 Static data workflow
A static data "entity" (for example: client, currency, country, etc) has a state that determines its
position in a workflow. An entity’s state changes depending on the last action that was performed on
the entity. The diagram below shows an example workflow of states and actions:
reject*
OPEN FINAL
REEDIT
TO-DELETE DELETED
reject*
edit
undelete
accept
accept
accept
new
delete
reject
reject,
accept
reject,
accept
delete
delete
action action that changes the state of a static data entity
STATE static data state
reject* a reject at this state reverts to the FINAL state
6 Managing static data
6.1 Introduction
98 © Wall Street Systems IPH AB - Confidential
There are five main states for all static data entities:
OPEN
The state of an entity when it is first created, as a result of the action new. For example, a user
creates a new currency in the Currency Editor.
The Wallstreet Suite production system is not yet aware of this entity.
FINAL
The entity’s state after the action accept on an entity that has been created (OPEN) or modified
(REEDIT). For example, a user has created a country entity modified an existing country entity
in the Country Editor and accepts it.
If this is a new entity, it is added to the production system. If this is a modified entity, its "live"
version in the production system is updated.
REEDIT
The state of an existing entity that is being modified, as a result of an action such as edit. For
example, a user opens the Client Editor, and selects a client entity for editing.
In this state, two versions of the entity exist: the production system’s version, and the "being
modified" version. The entity must pass to state FINAL before the production system is aware of
changes to the entity.
TO-DELETE
The state of an existing entity that is about to be deleted, as a result of an action such as
delete. For example, a user opens the Client Editor, and selects a client entity for editing.
In this state, two versions of the entity exist: the production system’s version, and the "being
modified" version. The entity must pass to state DELETED before it is deleted from the
production system.
DELETED
The state of an existing entity that has been deleted as a result of the action delete.
The entity is removed from the production system.
6 Managing static data
6.1 Introduction
TRM System Administration Guide 99
6.1.2 Static data workflow with 4-eyes verification
The next diagram shows an example of a Wallstreet Suite system with "4-eyes" verification. Two
extra states - VERIFY and DELETE-VERIFY - have been inserted into the workflow:
The two new states:
VERIFY
The entity’s state after the action accept on an entity that has been created (OPEN) or modified
(REEDIT). The second pair of eyes must accept the entity’s state again so that it can pass to
state FINAL.
DELETE-VERIFY
The entity’s state after the action accept on an entity in state TO-DELETE. The second pair of
eyes must accept the entity’s state again so that it can pass to state FINAL.
6.1.3 Static data workflow: CMM and TRM
If CMM is installed, static data management handles CMM-only static data entities and those shared
by TRM and CMM. For more information, see the CMM documentation and 6.3 TRM with CMM - static
data changes on page 104.
reject*
acceptOPEN FINALVERIFY
REEDIT
acceptTO-DELETE DELETED
DELETE-
VERIFY
reject
reject
accept1
reject*
edit
undelete
accept1
accept
new
delete
reject
reject,
accept
reject,
accept
delete
delete
delete
action action that changes the state of a static data entity
STATE static data state
reject* a reject at this state reverts to the FINAL state
accept1goes to this state when CMM not present.
6 Managing static data
6.2 Setting up static data management
100 © Wall Street Systems IPH AB - Confidential
6.2 Setting up static data management
Static data management applies to the following static data entities only:
Calendar
CalendarGroup
CMMBankAccountGroupMap
CMMInstrumentTypes
CMMRelationshipType
CommentRule
CommissionRule
Country
CreditRating
Currency
FINFormatRule
FINFormatRuleAction
Gapset
Limit
LimitCategory
LimitFactorSet
LimitItemClientQuery
LimitItemTemplate
MarketInfoSource
Portfolio
RateReasonabilityRule
ReferenceRate
Region
RulesHeader
SettlementAdviceMethod
SettlementRulesHeader
SettlementTransferMethod
SublimitTemplate
TaxRule
TraderLimit
TransferType
The following applications are available from the Application Manager to enable you to set up and
administer static data:
SDM State Editor: set up states and state flow
SDM Mode Editor: manage modes for applications, including static data Editors and the SDM
Manager applications.
6 Managing static data
6.2 Setting up static data management
TRM System Administration Guide 101
6.2.1 State and state flow setup
From the Application Manager, open the SDM State Editor.
On the left is a list of currently defined states.
A static data state has attributes that describe and determine what should happen when an action
occurs. For example, what the next state should be if the entity receives a reject or accept action, if
a user can verify his/her own changes, and so on. Use the SDM State Editor to set these attributes,
and use the table below to help you.
The table below describes the controls in the top part of this editor:
Control Description
Name A descriptive name for the state.
Reject State The entity changes from this (current) state to the state selected here after a
reject action.
Select or enter the next state. Leave blank to remain in the current state after a
reject action.
Reset State If a state is selected here, it does two things:
•When an entity reaches the current state, and the Reset State is not blank, the
production system is updated with this entity’s data. Normally this applies only
to the FINAL and DELETED state.
When an entity in this state is to be edited (i.e. modified or deleted), it goes to
the state selected in Reset State.
Except fore the FINAL and DELETED states, you should normally leave this field
blank.
Edit Allowed Switch this on to allow modifications (other than accepting and rejecting) to an
entity in this state.
6 Managing static data
6.2 Setting up static data management
102 © Wall Street Systems IPH AB - Confidential
The Allowed Groups page of this editor enables you to determine which Wallstreet Suite users and
user groups can access the currently selected state. If a user is not in a group that is defined for a
state, then all entities in that state are invisible to that user.
6.2.1.1 Next state after an Accept action
The State Flow page enables you to configure the next state that an entity is sent to when an accept
action is performed on the entity. You can define multiple "Next States, each with different
conditions.
By setting a different priority number for each "Next State", you ensure that only one "Next State"
will be chosen by the system.
There are three types of matching criteria:
Always match
By leaving the Entity Type undefined, all entities in the current state that receive an accept
action will match the criteria for this "Next State".
Creating a "Next State" with these criteria is very important where you have defined other "Next
States with more selective conditions. By setting the Priority to a higher number than all other
"Next States defined, you guarantee that if no other "Next State" match is found, this one will be
used.
Match on entity type
You can use this to change the state flow for certain entity types.
For example, for most entities in state REEDIT, you decide to send them to state VERIFY on an
accept action. So for the REEDIT state, you define a "Next State" of VERIFY, with no conditions
and a low priority. But you do not need verification for Calendar Group entities that are in the
REEDIT state: once accepted, they can be sent directly to state FINAL. So you define a second
"Next State" of FINAL, where you select Calendar Group as the Entity Type, and give this a higher
priority than the VERIFY "Next State".
Not Last User Check this to prevent a user from accepting the state change of an entity to this
state if the same user was responsible for the state change.
Apply Validation Switch this on to validate an entity before sending it to the next state.
The validation process checks that all the entity’s dependencies already exist in
the production system. For example, for the entity type Client, validation would
include ensuring that its defined Country and Currency entities already exist in the
production system.
Control Description
6 Managing static data
6.2 Setting up static data management
TRM System Administration Guide 103
The table below describes the controls in the State Flow page of this editor:
6.2.1.2 Creating and deleting states
You cannot create or delete SDM states using the SDM State Editor. Instead, you should edit the file
$FK_HOME/share/<your_database_type>/data/sdm_state.pl. If you want to create a state, then
you should use the ID numbering convention that is recommended in the file.
When modified, the content of the file sdm_state.pl must be stored in the database using the
command:
perl build.pl <connection_options> -t <sdm_state.pl>
Where <connection_options> means the database connection options as described in the WSS
Database Setup Guide (see the Appendix about the build command).
Note: This command restores the table data as defined in this file, so any data in this table that
has been modified via the SDM State Editor will be lost.
6.2.2 Mode setup
From the Application Manager, open the SDM Mode Editor.
Control Description
Next State The entity changes from this (current) state to the state selected here after an
accept action, as long as any criteria defined are met.
Priority If several "Next States are configured, and more than one match is found, the
"Next State" with the highest priority (lowest number) wins.
Entity Type If you want this "Next State" to apply to a single entity type only, select or enter
an entity name.
6 Managing static data
6.3 TRM with CMM - static data changes
104 © Wall Street Systems IPH AB - Confidential
On the left is a list of currently defined modes.
A static data mode is a collection of static data states. There are four system modes, and modes
used as views and filters by the Static Data Manager applications - see 6.4.2 Using SDM Manager
applications on page 107.
6.2.2.1 The four system modes
These are:
1. EDITOR
This is the mode used by all static data Editor applications. This mode should contain all states
except the "system" states controlled by the TRM/CMM synchronization process (all states
shown in the greyed area of the diagram under Static data flow: TRM with CMM and 4-eyes
verification on page 105.
The EDITOR mode determines how a static data Editor behaves when in its Edit mode. In Edit
mode, an Editor displays entities in all states (except the "deletion" states - state names that
begin with "DELETE..."), but it allows users to use Tools - Accept/Reject only on entities that are in
states defined in the EDITOR mode.
2. SEND
This defines the SDM Synchronizer mode for selecting entities to send to CMM.
3. SEND-DELETED
This defines the SDM Synchronizer mode for selecting entities to be deleted, and sending them
to CMM. This mode contains the DELETE-SEND state only.
4. HOLD
This is an internal SDM Synchronizer mode which contains the HOLD and DELETE-HOLD states.
The last three modes are only relevant if you have CMM installed. for more information, see 6.3 TRM
with CMM - static data changes on page 104.
6.2.2.2 Creating and deleting modes
You cannot create or delete SDM modes using the SDM Mode Editor. Instead, you should edit the file
$FK_HOME/share/<your_database_type>/data/sdm_mode.pl. If you want to create a mode, then
you should use the ID numbering convention that is recommended in the file.
When modified, the content of the file sdm_mode.pl must be stored in the database using the
command:
perl build.pl <connection_options> -t <sdm_mode.pl>
Where <connection_options> means the database connection options as described in the WSS
Database Setup Guide (see the Appendix about the build command).
Note: This command restores the table data as defined in this file, so any data in this table that
has been modified via the SDM Mode Editor will be lost.
6.3 TRM with CMM - static data changes
When CMM is installed, TRM handles the administration and editing of CMM-only static data entities
as well as those entities shared by both modules.
The SDM Synchronizer is a software system that provides the bridge between static data entities in
the TRM database and the CMM database, and provides the system states SEND, FAILED, HOLD,
DELETE-SEND, DELETE-FAILED, and DELETE-HOLD that help manage the synchronization of static
data between TRM and CMM. See the CMM documentation for installation details.
6 Managing static data
6.3 TRM with CMM - static data changes
TRM System Administration Guide 105
Static data flow: TRM with CMM and 4-eyes verification
6.3.1 Dependencies between entities
When an entity is sent from TRM to CMM, CMM fails the entity if its dependent entities do not exist.
The table below shows the dependencies for SDM-enabled entities. CMM entities are indicated.
Dependencies with further dependencies are marked "-->".
reject*
acceptOPEN FINALVERIFY SEND HOLD
REEDIT
DELETE-
FAILED
accept2accept accept
FAILED
reject
reject
acceptTO-DELETE DELETED
DELETE-
VERIFY DELETE-SEND DELETE-HOLDaccept2accept accept
reject
reject
reject
reject
accept
accept1
reject*
edit
accept
undelete
accept1
SDM - synchronizer flow for entity types that are shared between TRM and CMM, and entities that are CMM-only
action action that changes the state of a static data entity
STATE static data state
reject* a reject at this state reverts to the FINAL state
accept
accept1
goes to this state when CMM is present, and applies only to shared TRM/CMM entities and CMM-specific entities:
Currencies, Countries...
accept2
goes to this state when CMM not present.
new
delete
reject
reject
reject,
accept
reject,
accept
reject
delete
delete
delete
6 Managing static data
6.3 TRM with CMM - static data changes
106 © Wall Street Systems IPH AB - Confidential
Entity Dependency
CalendarGroup CommissionRule
Country (CMM) -->
Currency (CMM) -->
GapSet
MarketInfo
Client (CMM) Accounting
AccountingClosingBook
CMMBankAccountGroup (CMM)
CommissionRule
Limit
LimitFactorSet
LimitItemClientQuery
Portfolio
RulesHeader
SettlementRulesHeader
Ta x R u l e
ClientAccount CommissionRule
Country (CMM) Client (CMM) -->
LimitItemClientQuery
CreditRating Client (CMM) -->
Currency (CMM) AccountingClosingBook
CMMBankAccountGroup (CMM)
Client (CMM) -->
CommissionRule
Country (CMM) -->
Limit
LimitFactorSet
Portfolio -->
ReferenceRate (CMM)
RulesHeader -->
TraderLimit
GapSet Currency (CMM) -->
LimitCategory Limit
LimitItemClientQuery Limit
LimitItemTemplate Limit
Portfolio Client (CMM) -->
Limit
LimitFactorSet
Portfolio -->
Region (CMM) Client (CMM) -->
6 Managing static data
6.4 Using SDM-managed entities
TRM System Administration Guide 107
6.4 Using SDM-managed entities
6.4.1 Using static data editors
When you open the Static Data Editor for an SDM-managed entity, the options in the Tools menu
and editor main window are as follows:
6.4.2 Using SDM Manager applications
There are three SDM Manager applications: SDM Query, SDM Admin, and SDM Verify.
6.4.2.1 SDM Query application
Use this to view the status of SDM-managed entities. The entity states that you may view here
depends on the states selected for the QUERY mode in the SDM Mode Editor.
You can edit an entity by selecting one in the Query results and selecting the Command - Edit menu
option.
6.4.2.2 SDM Verify application
Use this to view the status of SDM-managed entities, and accept or reject their current status. The
entity states that you may view here depends on the states selected for the VERIFY mode in the
SDM Mode Editor.
You can edit an entity by selecting one in the Query results and selecting the Command - Edit menu
option.
RulesHeader Accounting
Client (CMM) -->
FINFormatRule
SettlementRulesHeader FINFormatRule
PaymentAdviceType
SublimitTemplate Limit
TransferType Settlem e n tR u le s H e ader -->
Entity Dependency
Menu Option Description
Swap View/Edit Mode When the Editor is launched, it starts up in View mode and no changes can be
made. Select Swap View/Edit Mode to launch a new instance of the editor in
Edit mode.
Accept and Reject In Edit mode, these options are available to users who have the right to
accept or reject the entity in its current state. Accepting or rejecting an entity
changes it to the state defined for that entity in the State Editor: see 6.2.1
State and state flow setup on page 101.
SDM Read-only/SDM Edit One of these views can be selected from a pull-down menu on the main
toolbar. If SDM Edit is selected, the left and right arrow buttons can be used to
specify SDM Accept or SDM Reject.
6 Managing static data
6.5 Tables and processes used
108 © Wall Street Systems IPH AB - Confidential
6.4.2.3 SDM Admin application
Use this to view the status of SDM-managed entities, and accept or reject their current status. The
entity states that you may view here depends on the states selected for the ADMIN mode in the
SDM Mode Editor.
You can edit an entity by selecting one in the Query results and selecting the Command - Edit menu
option.
6.5 Tables and processes used
Every aspect is defined and processed for a given entity type (Payment, PaymentAlloc…).
Table Data
EntityState States
[EntityRule] Rules used to activate / inactivate specific work flow transitions (relates to
EntityAction)
EntityAction Work flow transitions
ModeColumn (shared with
Transaction work flow)
Columns for a given view (Transaction, Cashflow, Schedule…) to be granted or not
(relates to EntityMode) for a given mode
ModeAction (shared with
Transaction work flow)
Menu, entity and sub-entity level action (New Transaction, Duplicate, Early-expire,
Fix…) to be granted or not (relates to EntityMode) for a given mode
EntityMode Modes, each of them operating on a set of states.
Two granting aspects:
grant_p: relates to ModeColumn
action_grant_p: relates to ModeAction
where:
0 means all is granted but what is listed in underlying table
1 means only what is listed in underlying table is granted
Setup Process Action
SetupEntityState Enables setup of EntityState
SetupEntityAction Enables setup of EntityAction
SetupModeColumn (shared
with Transaction work flow)
Enables setup of ModeColumn
SetupModeAction (shared with
Transaction work flow)
Enables setup of ModeAction
SetupEntityMode Enables setup of EntityMode
RenumberEntityStates Enables renumbering of states with regular gaps
Action Process Action
DoEntityAction Enables the sequential processing of entity actions as a chain driven by order
number and rule (uses MatchingEntityRule)
6 Managing static data
6.5 Tables and processes used
TRM System Administration Guide 109
MatchingEntityRule Enables entity rule matching (used by DoEntityAction, relates to EntityRule)
DoAmountEventSetState Specific action proc to set state for AmountEvent entity type
DoPASetState Specific action proc to set state for PaymentAlloc entity type
DoMessageRequestSetState Specific action proc to set state for MessageRequest entity type
DoPSetState Specific action proc to set state for Payment entity type
DoCancelEntityInput Cancels entity event / accounting input
DoEntityInput Creates entity event / accounting input
Setup Script Action
amount_event_flow.sql For Amount Event entity
message_flow.sql For Message Request entity
payment_alloc_flow.sql For Payment Allocation entity
payment_flow.sql For Payment entity
Action Process Action
6 Managing static data
6.5 Tables and processes used
110 © Wall Street Systems IPH AB - Confidential
TRM System Administration Guide 111
Chapter 7 Setting up transaction and entity flow
7.1 Transaction flow and entity flow
The transaction flow describes the states through which a transaction moves, reflecting the
workflow within the user organization. It can ensure that only specified functions can change a
transaction, and can be used to specify who can process the transaction; for example, to specify
that only Front Office staff can change the price of a transaction.
The entity flow describes the states through which various other entities (e.g. settlement or
message) move in their respective workflows.
Flow functionality is implemented using transaction and entity broker services. These services
provide a set of agents which execute tasks like those executed by Transaction and Entity Actions in
previous versions, e.g. set transaction/entity state, set/clear transaction status and call stored
procedures. They also support sending the transactions and entities to various queues for further
processing, like creating message requests for confirmation processing or generating settlements
from transactions. This chapter includes a description of how to migrate to a TRM 7.2-onwards
transaction flow.
7.2 Loading default transaction flow
TRM has a default transaction flow setup. To load it, run the following setup scripts available in
$FK_HOME\share\<database>\setup to load default definitions of the permissions, transaction
status and transaction states to be used in the flow into the database:
permission.sql
status.sql
tag.sql
transaction_state.sql
Then execute the following command to build the default transaction flow:
python -m flow.build
This command executes the following setup scripts as one logical step to build the entire transaction
flow:
flow.py
commit.py
status.py
tag.py
limit.py
irp.py
These scripts can also be run individually from the directory $FK_HOME\share\python\flow (e.g.
python status.py) but the recommendation is to always use the python -m flow.build command
and build the whole flow in one step. The roles of the individual scripts are as follows:
flow.py creates ACCEPT and REJECT operations, defining transitions between states as well as
all other processing automatically triggered by accepting or rejecting transactions from their
current states
7 Setting up transaction and entity flow
7.3 Setting up transaction flow
112 © Wall Street Systems IPH AB - Confidential
commit.py creates a COMMIT operation and a NOTIFY operation, defining all processing
automatically triggered by applying a new or existing transaction.
status.py creates SET/CLEAR operations for transaction status, defining all processing
automatically triggered by manually setting or clearing the relevant status in a transaction.
tag.py creates SET/CLEAR operations for transaction tags, defining all processing automatically
triggered by manually setting or clearing the relevant tag in a transaction.
limit.py creates operations used by the limit server in limit violation-related processing of
transactions.