• Author / Uploaded
• Fatou Diakhaté Touré

Citation preview

TEMENOS T24 Software Development Kit

TSDK – Implementation Guide

Information in this document is subject to change without notice. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of TEMENOS Holdings NV.

T24 Software Development Kit – Implementation Guide

Table of Content How To…................................................................................................................................................. 3 How to Write a TSDK T24 Server Side API......................................................................................... 3 Overview .......................................................................................................................................... 3 Creating and Packaging the T24 server class ................................................................................. 5 Package and deploy the class ......................................................................................................... 5 Set up the EB.API record for the new class ..................................................................................... 5 How to Write a TSDK Web Server Side API........................................................................................ 6 Overview .......................................................................................................................................... 6 Create the Web Validation Class ..................................................................................................... 6 Package and deploy the class ......................................................................................................... 8 Set up the EB.API record for the new class ..................................................................................... 8 Set up the Web Validate field on the version ................................................................................... 8 Examples ............................................................................................................................................... 10 Server side APIs ................................................................................................................................ 10 Example 1 ...................................................................................................................................... 10 Example 2 ...................................................................................................................................... 11 Web Server APIs ............................................................................................................................... 13 Example 1 ...................................................................................................................................... 13

TEMENOS T24 User Guide

Page 2 of 16

T24 Software Development Kit – Implementation Guide

How To… How to Write a TSDK T24 Server Side API Overview The following outlines the steps involved in setting up TSDK server side API’s • Create the T24 server application class (WS.CREATE) • Package and deploy the class (WS.CREATE) • Set up the EB.API record for the new class • Configure API hook to use EB.API In order to run the Web Validation Java class the class must implement the interface “com.temenos.t24browser.validation.Validator”. The interface is part of the T24Browser.jar The interface specifies that the class should implement the following method: •

public ValidationResponse runRoutine(T24Common t24Common, T24Routines t24Routines)throws FieldException;

The class should have no constructor - a blank one will get created automatically. The method runroutine passes in a t24Common containing all of the fields displayed on the current contract, and a t24Routines representation of the field that initiated the web validate. The method returns a ValidationResponse, which will contain any TProperties that have been altered and subsequently added to it in order to update the contract. The following steps should be taken when developing a Validation class: •

The class needs to import the following classes: o import com.temenos.tdsk.foundation.t24Common; o import com.temenos.tdsk.foundation.TProperty; o import com.temenos.tdsk.fx.TCustomer; //specific to any contracts that you need o import com.temenos.tdsk.validation.ValidationResponse;

•

The class can be called anything, but must implement the interface T24Api. Validate has one method that passes in a T24Common and a T24Routines. The method finally returns a ValidationResponse that will contain a list of all the properties (field data changes and errors and messages) needed for update of the contract on display.

•

On entering the method, runRoutine, the developer should create a new Contract class specific to the contract being run. E.g.:

o

o

•

When running the version CUSTOMER,SAM the class TCustomer should be created. The class will take one parameter in its constructor – the TContract passed into the method ‘runRoutine’. This will take all of the TProperties from the passed in TContract and add it to the TForex class. ƒ The global instance variable TCustomer customer should be instantiated. ƒ The class should then be created in the method • forexContract = new TForex(contract);

An instance of ValidationResponse class should be constructed for adding changed TProperties to (i.e. field data changes). This object should be returned at the end of the

TEMENOS T24 User Guide

Page 3 of 16

T24 Software Development Kit – Implementation Guide

method processRequest. The ValidationResponse also hold any errors or messages that have been reported during the validation. •

The TProperty that is passed into the method processRequest will contain the information about the field that initiated the validation request. The following methods can be used to access it: o getName() – the name of the field o getValue() - the value of the field o getMulti() - the multiValue o getSub() - the sub value

•

When a field is to be changed for addition to the ValidationResponse, the developer should retrieve the relevant TProperty from the newly created TContract. There are two possible ways of retrieving this from the TContract o TProperty cusProp = customer.getMnemonic(); o TProperty customer = customer.getProperty(“MNEMONIC”);

•

Any changes to be made to this field are made via this TProperty reference: o cusProp.setEnrich("enrichment") o cusProp.setError("field error")

•

On finishing the validation the TProperty is then added to the ValidationResponse: o response.addProperty(cusProp);

•

If later in the code this field is to be altered again, then just re-run the previous three steps. Due to the fact that java passes objects by reference, the updated field in the Validation response will now point to the same object that the TContract points to. So, if one is updated, then both will be updated.

•

If a general error, or message needs to be added, then it is done via the following methods on the ValidationResponse class: o o

response.addMessage("This is a message"); response.addError("This is an error");

•

If a field specific error is generated, then the following method can be called to set the TProperty: o cusProp.setError(“the error”);

•

The Enrichment of the field can also be set via a similar method: o cusProp.setEnri(“the enrichment”);

•

Finally the response should be returned in the method runRoutine

NB Enrichments set via the “setEnri” method will only be visible if the field ENRICHM.CHAR has been set in the VERSION record.

TEMENOS T24 User Guide

Page 4 of 16

T24 Software Development Kit – Implementation Guide

Creating and Packaging the T24 server class T24 application classes can be created and packaged using the supplied set of tools to create TSDK and Web Services classes. For locally developed applications, or core T24 applications that contain local reference fields, the WS.CREATE application should be used to create and package the TSDK class. Please refer to WS.CREATE section of the Administrator’s Guide

Package and deploy the class Please refer to the Administrators Guide for details on how to create TSDK classes and their JAR file. The created JAR file (or the Temenos supplied JAR file) should then be added to the T24 servers class path, either by placing it in a known class path area (the java directory under xxx.java is recommended) or by modifying the CLASSPATH environment variable. The package name at the top of the class will reflect the package structure in this JAR.

Set up the EB.API record for the new class Once a validation class has been created, an EB.API record must be created. This record specifies the name, package and details for the validation routine. In terms of the TSDK, the EB.API should define a Java class. However, EB.API is also used for external BASIC routine hooks as well. For more details on configuring EB.API please refer to the section EB.API in the Administrators Guide.

TEMENOS T24 User Guide

Page 5 of 16

T24 Software Development Kit – Implementation Guide

How to Write a TSDK Web Server Side API Overview Web Validation enables the user to perform validation of a contract on the web server. In the past this role has been tailored for by validation routines run in the T24 Application Server. Web Validation classes reside on the Web Server, thus speeding up the validation process. This method involves validation of a contract in the background, thus allowing the user to continue editing the contract while validation takes place at the web server. When the validation has completed the currently displayed contract will be updated with any field data changes, as well as any errors and messages. Note : At present Web Validation only works when the XSL transform is set to the server. This is due to a bug in IE6. This bug, according to Microsoft (Microsoft report number 323069), will be fixed in IE6 service pack 2. For more details please see the following web site: http://support.microsoft.com/default.aspx?scid=%2Fservicedesks%2Fbin%2Fkbsearch.asp%3FArticle%3D32306 9

An example has been provided to show what can be achieved with web validation, in this case, we are validating a FOREX contract. The following outlines the steps involved in setting up Web Validation: • • • • •

Create the Web Validation class Package and deploy the class Set up the EB.API record for the new class Set up the Web Validate field in the version Generating tsdk local development classes

Create the Web Validation Class In order to run the Web Validation Java class the class must implement the interface “com.temenos.t24browser.validation.Validator”. The interface is part of the T24Browser.jar The interface specifies that the class should implement the following method: •

public ValidationResponse processRequest(TContract contract,TProperty property, T24Connection connection) throws ValidationException;

The class should have no constructor - a blank one will get created automatically. The method processRequest passes in a TContract containing all of the fields displayed on the current contract, a TProperty representation of the field that initiated the web validate, and a T24Connection which allows communication to the T24 server (currently only used for CHECKFILE enrichments processing). The method returns a ValidationResponse, which will contain any TProperties that have been altered and subsequently added to it in order to update the contract. The following steps should be taken when developing a Validation class: •

•

The class needs to import the following classes: o import com.temenos.tdsk.foundation.TContract; o import com.temenos.tdsk.foundation.TProperty; o import com.temenos.tdsk.fx.TForex; //specific to any contracts that you need o import com.temenos.tdsk.validation.Validator; o import com.temenos.tdsk.validation.ValidationResponse; The class can be called anything, but must implement the interface Validator. Validator has one method that passes in a TContract, a TProperty and a T24Connection. The method finally returns a ValidationResponse that will contain a list of all the properties (field data changes and errors and messages) needed for update of the contract on display.

TEMENOS T24 User Guide

Page 6 of 16

T24 Software Development Kit – Implementation Guide

•

On entering the method, processRequest, the developer should create a new Contract class specific to the contract being run. E.g.: o When running the version FOREX,SPOTBUY, the class TForex should be created. The class will take one parameter in its constructor – the TContract passed into the method ‘processRequest’. o This will take all of the TProperties from the passed in TContract and add it to the TForex class. ƒ The global instance variable TForex forexContract should be instantiated. ƒ The class should then be created in the method processRequest • forexContract = new TForex(contract);

•

An instance of ValidationResponse class should be constructed for adding changed TProperties to (i.e. field data changes). This object should be returned at the end of the method processRequest. The ValidationResponse also hold any errors or messages that have been reported during the validation.

•

The TProperty that is passed into the method processRequest will contain the information about the field that initiated the validation request. The following methods can be used to access it: o getName() – the name of the field o getValue() - the value of the field o getMulti() - the multiValue o getSub() - the sub value

•

When a field is to be changed for addition to the ValidationResponse, the developer should retrieve the relevant TProperty from the newly created TContract. There are two possible ways of retrieving this from the TContract o TProperty counterParty = forexContract.getCounterparty(); o TProperty counterParty = forexContract.getProperty(“COUNTERPARTY”);

•

Any changes to be made to this field are made via this TProperty reference: o counterParty.setValue("USD") o counterParty.setEnrich("enrichment") o counterParty.setError("field error")

•

On finishing the validation the TProperty is then added to the ValidationResponse: o response.addProperty(counterParty);

•

If later in the code this field is to be altered again, then just re-run the previous three steps. Due to the fact that java passes objects by reference, the updated field in the Validation response will now point to the same object that the TContract points to. So, if one is updated, then both will be updated.

•

If a general error, or message needs to be added, then it is done via the following methods on the ValidationResponse class: o o

response.addMessage("This is a message"); response.addError("This is an error");

TEMENOS T24 User Guide

Page 7 of 16

T24 Software Development Kit – Implementation Guide

•

If a field specific error is generated, then the following method can be called to set the TProperty: o counterParty.setError(“the error”);

•

The Enrichment of the field can also be set via a similar method: o counterParty.setEnri(“the enrichment”);

•

Finally the response should be returned in the method processRequest

NB Enrichments set via the “setEnri” method will only be visible if the field ENRICHM.CHAR has been set in the VERSION record.

Package and deploy the class The Validation Class should be archived in a jar. The jar should then be added to the web server’s class path. The package name at the top of the class will reflect the package structure in this jar. Taking the Web Server APACHE TOMCAT as an example, the finished jar should be placed in the following relative directory ..\Tomcat\webapps\BrowserWeb\WEB-INF\lib The web server will then be able to pick up the jar.

Set up the EB.API record for the new class See EB.API section in Administrators Guide

Set up the Web Validate field on the version The Web Validation class is then linked to a specific field on a version by assigning the field ‘Atrribs’ to WEB.VALIDATE. See the figure below:

TEMENOS T24 User Guide

Page 8 of 16

T24 Software Development Kit – Implementation Guide

A version can only have one linked Validation class. The class is linked to the version via the field ‘Web Val Rtn’. The name of the EB.API record set up for the Validation class should be referenced here. See the figure below.

TEMENOS T24 User Guide

Page 9 of 16

T24 Software Development Kit – Implementation Guide

Examples Server side APIs Example 1 The following code outlines a possible example for a Server Validation class: package com.temenos.tsdk.examples; import import import import import import import

com.temenos.tsdk.T24Api; com.temenos.tsdk.T24Routines; com.temenos.tsdk.core.TCurrency; com.temenos.tsdk.foundation.T24Common; com.temenos.tsdk.foundation.TProperty; com.temenos.tsdk.fx.TForex; com.temenos.tsdk.validation.ValidationResponse;

/** * This function will examine the value entered into the CURRENCY.BOUGHT * field and default the COUNTERPARTY field based on the value. * * If the currency Bought is USD then the COUNTERPARTY is set to * 100063 (CHASENY) if it is GBP then the COUNTERPARTY is set to * 100073 (BARCUK). * * To get this example to work you must add the following record to the EB.API * file on the T24 database you wish to use. * * DESCRIPTION....... Defaults the Forex Counterparty * PROTECTION.LEVEL.. NONE * SOURCE.TYPE....... JAVA * JAVA.METHOD....... * JAVA.CLASS........ ForexDefaultAccounts * JAVA.PACKAGE...... com.temenos.tsdk.examples * * The important fields here are the SOURCE.TYPE which tells T24 to * run this API as a java routine and then the JAVA.PACKAGE that tells * T24 which java package to find this in and JAVA.CLASS which tell it * which class to run * * Then you need to set the name of the record you created in a FOREX * version in the VALIDATION.RTN field with an '@' in front of the EB.API * record name and the corresponding VALIDATION.FLD set to CURRENCY.BOUGHT */ public class ForexDefaultAccounts implements T24Api { public ValidationResponse runRoutine(T24Common t24Common, T24Routines t24Routines) { // First we get the value that has just been entered in the // T24 contract. This is obtained as a java string by calling // the method getUserInput from the T24Common object String currencyBought = t24Common.getUserInput(); // We also want to get a copy of the current contract that // is being edited so we can update it if we find the // correct currency. The current contract will be a // TForex object. We get it by calling the getCurrentContract // method from the T24Common object. This method returns the // current contract as a TContract object. The TContract object is // the super class that the TForex class is built from so we can // 'cast' the contract, which makes it the TForex object we need. // This is done by the bracketed statement infront of the method TForex forex = (TForex)t24Common.getCurrentContract(); // // // if {

Now we check to see if the inputed currency is USD or GBP When we know what to set we use the setCounterparty method on the forex object. ( ( currencyBought != null ) && ( ! currencyBought.equals("") ) ) if (currencyBought.equals("USD")) { // The currency is USD, set the counterparty to CHASENY, which // customer number 100063 forex.setCounterparty("100063");

TEMENOS T24 User Guide

Page 10 of 16

T24 Software Development Kit – Implementation Guide

} else if(currencyBought.equals("GBP")) { // The currency is GBP, set the counterparty to BARCUK, which // customer number 100073 forex.setCounterparty("100073"); } } else { // The currency is not one we can default, so set the counterparty // to be blank forex.setCounterparty(""); } // Now we have updated the TForex object, we need to apply these // changes back to T24. We do this by adding a new TProperty to the response object. ValidationResponse myResponse = new ValidationResponse(); TProperty cp = forex.getCounterparty(); myResponse.addProperty(cp); return myResponse; } }

Example 2 This example (or series of code snippets will highlight the way a server validation is written, and used. This will highlight the use of the foundation classes and error setting. IT will also demonstrate the use of Logging facilities that can be used when implementing and running TSDK server validation. These will also highlight the ability to go to the T24 Server BASIC and back to Java code as well as setting EText (Error object)

package com.temenos.tsdk.examples; import import import import import import import import import import

com.temenos.tsdk.T24Api; com.temenos.tsdk.ac.TAccount; com.temenos.tsdk.core.TCustomer; com.temenos.tsdk.exception.ETextException; com.temenos.tsdk.exception.FieldException; com.temenos.tsdk.foundation.T24Common; com.temenos.tsdk.foundation.TProperty; com.temenos.tsdk.routines.FileHandling; com.temenos.tsdk.routines.T24Routines; com.temenos.tsdk.validation.ValidationResponse;

/** * @author Temenos * An example showing how a validation routine calls the T24 Routines to read a record, * and set the value of the Account Title of a new ACCOUNT to the ShortName of the customer */ public class AccountValidation implements T24Api { /** * Takes in a TContract containing all of the fields on the current * contract. Also passes in the TProperty - field - containing the * information about the field that initiated the validation response * * @param t24Common T24Common * @param t24Routines T24Routines * * @return ValidationResponse * * @see com.temenos.tsdk.T24Connection#runRoutine(T24Common t24Common, *T24Routines t24Routines) */ public ValidationResponse runRoutine(T24Common t24Common, T24Routines t24Routines) throws FieldException { //First we get the current record, what is in R.NEW. to get // this we call the getCurrentRecord method of the t24 object. // This returns the current record as a TContract object. We then cast

TEMENOS T24 User Guide

Page 11 of 16

T24 Software Development Kit – Implementation Guide

// this to a TAccount object which is an class inherited from the // TContract class. TAccount account = new TAccount(t24Common.getCurrentContract()); // Now get the CUSTOMER account out of the current contract. The value // of this is accessed from the getCustomer method which returns a // String object. TProperty tCusNumber = account.getCustomer(); String sCustomerNumber = tCusNumber.getValue(); String sCustomerFile = "CUSTOMER"; //create the response for adding the updated TProperties to. ValidationResponse myResponse = new ValidationResponse(); // getting the filehandling method to be able to read a record FileHandling myFileHandling = t24Routines.getFilehandling(); try { //Read a customer record TCustomer tCustomerRecord = new TCustomer(myFileHandling.readRecord(sCustomerNumber, sCustomerFile)); //We read the Short Name from the customer record String sShortName = tCustomerRecord.getShortName(0, 0).getValue(); //Create a TProperty to pass to the ValidationResponse object TProperty tAccountTitle1 = account.getAccountTitle1(); //Set the value of Account Title 1 with the ShortName you get //from Customer Record tAccountTitle1.setValue(sShortName); // Now add the updated TProperty to the ValidationResponse myResponse.addProperty(tAccountTitle1); } catch (ETextException etext) { // Set an error message tCusNumber.setError(etext.getMessage()); myResponse.addProperty(tCusNumber); } return myResponse; } }

TEMENOS T24 User Guide

Page 12 of 16

T24 Software Development Kit – Implementation Guide

Web Server APIs Example 1 The following code outlines a possible example for a Web Validation class: package com.temenos.tsdk.examples; import import import import import import import import

com.temenos.tsdk.foundation.T24Connection; com.temenos.tsdk.foundation.TContract; com.temenos.tsdk.foundation.TProperty; com.temenos.tsdk.fx.TForex; com.temenos.tsdk.exception.ValidationException; com.temenos.tsdk.validation.ValidationResponse; com.temenos.tsdk.validation.Validator; com.temenos.tsdk.validation.CurrencyValidator;

public class ForexValidator implements Validator { private TForex forexContract; // forex contract private ValidationResponse response; // the response to add changed TProperty fields to public ForexValidator() { } /** * Takes in a TContract containing all of the fields on the current contract. * Also passes in the TProperty - field - containing the information about the * field that initiated the validation response * @param TContract contract * @param TProperty field * * @return ValidationResponse */ public ValidationResponse processRequest(TContract contract, TProperty field, T24Connection connection) { //cast the contract to a Forex contract forexContract = new TForex(contract); //create the response for adding the updated TProperties to. response = new ValidationResponse(); if (field.getName().equals("COUNTERPARTY")) { validateCounterparty(); } else if ( (field.getName().equals("CURRENCY.BOUGHT")) || (field.getName().equals("CURRENCY.SOLD")) || (field.getName().equals("BROKERAGE.CCY"))) { validateCurrency(field); } return response; } private void validateCounterparty() { // extract the required fields from the forexContract TProperty cpProp = forexContract.getCounterparty(); String cpValue = cpProp.getValue(); TProperty currencyProp = forexContract.getCurrencyBought(); if (cpValue.equals("100069")) { cpProp.setEnrichment("DAO HENG BANK INC"); currencyProp.setValue("JPY"); currencyProp.setEnrichment(CurrencyValidator.getCurrencyName("JPY")); } else if (cpValue.equals("100070")) {

TEMENOS T24 User Guide

Page 13 of 16

T24 Software Development Kit – Implementation Guide

cpProp.setEnrichment("DBLA MIAMI"); currencyProp.setValue("USD"); currencyProp.setEnrichment(CurrencyValidator.getCurrencyName("USD")); } else if (cpValue.equals("100071")) { cpProp.setEnrichment("DEVCOM MERCHANT BANK LIMITED"); currencyProp.setValue("GBP"); currencyProp.setEnrichment(CurrencyValidator.getCurrencyName("GBP")); } else { cpProp.setError("Missing Customer Record"); cpProp.setEnrichment(""); } // Now add the updated counterparty TProperty to the ValidationResponse response.addProperty(cpProp); response.addProperty(currencyProp); } /** * * Validate * * @param TProperty currency */ private void validateCurrency(TProperty currency) { // extract the required fields from the forexContract TProperty currencyProp = forexContract.getProperty(currency.getName()); try { CurrencyValidator cv = new CurrencyValidator(currency.getValue()); currencyProp.setEnrichment(cv.getCurrencyName(currency.getValue())); } catch (ValidationException ve) { currencyProp.setError(ve.getMessage()); currencyProp.setEnrichment(""); } // Now add the updated currency bought TProperty to the ValidationResponse response.addProperty(currencyProp); } }

TEMENOS T24 User Guide

Page 14 of 16

T24 Software Development Kit – Implementation Guide

The following figure represents a version that has been set up to run Web Validation:

With regard to the above figure, three fields have been assigned to be Web Validate fields: o o o

Couterparty Ccy Bought Ccy Sold

(This field also contains an auto-launch enquiry)

On entering a value and tabbing out of either of these fields, the window will automatically send a Web Validate request to the web server while still displaying the contract for the user to continue editing. The web server will then create a TContract class and populate it with all of the fields on the displayed contract. The field that triggered the request will also be stored as a TProperty. Both of these classes will then be passed into the Validation class.

The Validation class will build up a list of all the fields that are to be changed on the displayed contract, and pass them back to the contract. This will result in one of the following:

o o o o o

A specific field value is updated A specific field enrichment is updated A general message is displayed in the menu A general error is displayed in the menu A field specific error is displayed in the menu

The following figure outlines several of the above:

TEMENOS T24 User Guide

Page 15 of 16

T24 Software Development Kit – Implementation Guide

On entering an invalid Counterparty field the Validation class sets an error against the field, which is displayed in the side menu. This would also be the case for any general errors set against the Validation Response instead of the individual field. Any messages displayed would be displayed under the “Messages” header.

TEMENOS T24 User Guide

Page 16 of 16