/
BL Scripting with JavaScript

BL Scripting with JavaScript

Introduction

FIXEdge offers a flexible solution for Business Rules purposed to provide routing, transferring, and data manipulations for FIX messages that go through the Business Layer of FIXEdge. In addition to XML Rules, there are two ways to enhance the flexibility of message transferring and data manipulation. Those ways are scripting with JavaScript and XSLT. To use this feature properly, scripts should be written in one of the scripting languages and assigned to the Script instruction of Action section in a Business Rule.

The scripting subsystem gives the user the following advantages:

  • Saves time spent on business logic implementation
  • Flexibility and simplicity of modification
  • Does not bring a significant performance breakdown

FIXEdge uses SpiderMonkey JavaScript engine


Business Rule scripting with JavaScript

It is enough to mention that the script is a JavaScript in the Script tag, in order to run the script and do the proper transformations. This structure facilitates users with all the standard Javascript features and functionality. In addition to this, it enables users to use functions that provide access to the FIX message inside data and allows manipulations with fields and groups as well as whole FIX messages.

JS FIX functionality

A trivial example of a complete JS script for a business rule is shown below:  

//take the value the 11th tag from the fix message and get the last 4 characters from it
//assign the new  value for the tag 11 with format BBBBSSSSCCYYMMDD
//where
//BBBB - any 4 characters
//SSSS - last 4 characters from the old value of field 11
//CC - century
//YY- year
//MM - month
//DD - day
 
field_11 = getStringField(11);
if(field_11.length() < 4)
  return;
last4 = field_11.slice(field_11.length() - 4);
currDate = getCurrentDateStr(YYYYMMDDUtc);
century = currDate.slice(1, 3);
century++;
result = "bbbb" + last4 + century + currDate.substr(3);
setStringField(11, result);

Error handling during script execution 

In case of syntax error in script - script execution will be terminated and failed. There is no way to handle syntax errors in script during script execution. User able to stop script execution using throw statement, the result in this case will be the same. User must be able to verify and handle logical errors using verification functions (like isNaN, isMessageValid(), etc) in condition statements.

Logging in JavaScript

print(<text>)

Example Code

print (getCurrentDateStr(DATETIMEUtc));

Execution of this line results in the following record in the application log:

[NOTE]  20131023-08:28:53.651 [4320] [../FixEdge/conf/test.js] - JavaScript '../FixEdge/conf/test.js' output: 20131023-08:28:53

Operations with session

startSession(<sessionName>)

Starts session "sessionName"

Example Code

startSession("StartByEvent")
Starts the "StartByEvent" session

startSession(<senderCompId>,<targetCompId>)

Starts session where SenderCompID = "senderCompID" and TargetCompID = "targetCompID"

Example Code

startSession("FIXEdge","SimpleClient")
Starts a session where SenderCompID = "FIXEdge" and TargetCompID = "SimpleClient"

startSession(<senderCompId>,<targetCompId>,<sessionQualifier>)

Starts session where SenderCompID = "senderCompID",TargetCompID = "targetCompID",SessionQualifierValue = "sessionQualifier"


Example Code

startSession("FIXEdge","SimpleClient","Q1")
Starts a session where SenderCompID = "FIXEdge", TargetCompID = "SimpleClient", SessionQualifierValue = "Q1"

disconnectSession(<sessionName>,<reason>)

Disconnects session "sessionName" with reason "reason"

Example Code

disconnectSession("DisconnectByEvent","Disconnect by message")
Disconnects the "DisconnectByEvent"session with the "Disconnect by message" reason

disconnectSession(<senderCompId>,<targetCompId>,<reason>)

Disconnects session where SenderCompID = "senderCompId" and TargetCompID = "targetCompId" with reason "reason"

Example Code

disconnectSession("FIXEdge","SimpleClient","Disconnect by message")
Disconnects a session where SenderCompID = "FIXEdge" and TargetCompID = "SimpleClient" with reason "Disconnect by message"

disconnectSession(<senderCompId>,<targetCompId>,<sessionQualifier>,<reason>)

Starts session where SenderCompID = "senderCompID",TargetCompID = "targetCompID",SessionQualifierValue = "sessionQualifier" with reason "reason"


Example Code

disconnectSession("FIXEdge","SimpleClient","Disconnect by message","Q1")
Disconnects a session where SenderCompID = "FIXEdge", TargetCompID = "SimpleClient", SessionQualifierValue = "Q1" with reason "Disconnect by message"

terminateSession(<sessionName>,<reason>)

Terminates session "sessionName" with reason "reason"

Example Code

terminateSession("TerminateByEvent","Terminate by message")
Terminates the "TerminateByEvent" session with the "Terminate by message" reason

terminateSession(<senderCompId>,<targetCompId>,<reason>)

Terminates session where SenderCompID = "senderCompID" and TargetCompID = "targetCompID" with reason "reason"

Example Code

terminateSession("FIXEdge","SimpleClient","Terminate by message")
Terminates a session where SenderCompID = "FIXEdge" and TargetCompID = "SimpleClient" with reason "Terminate by message"

terminateSession(<senderCompId>,<targetCompId>,<sessionQualifier>,<reason>)

Terminates session where SenderCompID = "senderCompID",TargetCompID = "targetCompID",SessionQualifierValue = "sessionQualifier"


Example Code

terminateSession("FIXEdge","SimpleClient","Q1","Terminate by message")
Terminates a session where SenderCompID = "FIXEdge", TargetCompID = "SimpleClient", SessionQualifierValue = "Q1" with reason "Terminate by message"

Please note:

  1. The session will not be visible in FIXICC or manageable (start, disconnect, etc) from FIXICC/BL/JS/scheduler.
  2. The termination and the disconnection occur with async way after rule completion. In case of fail <OnRuleFailEvent> will be called.

Operations with messages across BL rules

setCtxKV(key,value)

Example Code

setCtxKV("messageID","123")

The function sets the value to the key to transfer information about the message between different BL rules. If the function argument's type is not a string then the function throws an exception.

getCtxKV(key,[defaultValue]) 

Example Code

var id = getCtxKV("messageID")
var id = getCtxKV("messageID","0")

The function gets the value of the key from another BL rule.

If the function argument's type is not a string then the function throws an exception.

If the default value is specified and there is a key stored in the context then the function returns the value stored for the key.

If the specified key is not stored in the context:

  • If the default value is specified then the function returns the default value.
  • If the default value is not specified then the function throws an exception.

delCtxKV(key)

Example Code

delCtxKV("messageID")

The function deletes the value of the key. If the function's argument type is not a string then the function throws an exception.

Operations with group fields

getGroup(<fieldTag>)

Returns group handle for <fieldTag> group field 

Example Code

hndl = getGroup(78);
isGroupValid(hndl)

Gets a handle on group 78 and tests whether handle 78 is valid

getGroup(<parentGroupHandle>, <entry>, <fieldTag>)

Returns group handle for <fieldTag> group field from <parentGroupHandle>[<entry>] group

Numeration of <entry> starts with 0.

Example Code

hndl = getGroup(552);
isGroupValid(hndl);
hndl2 = getGroup(hndl, 0, 518);
isGroupValid(hndl2); 
if(hndl2 != hndl){
    setNumField(552, 4);
}

Gets a handle on group 552 and tests whether the handle 552 is valid

Gets a handle from the first record of 552 group on group 518 and tests whether the handle 518 is valid

If the group handles are not identical, then increase the number of group 552 elements up to 4

removeField(<group handle>, <entry>, <fieldTag>)

Removes field from group field

Numeration of <entry> starts with 0.

Example Code

hndl = getGroup(78);
isGroupValid(hndl);
removeField(hndl, 0, 79);

Gets handle on group 78 and tests whether the handle 78 is valid 

Removes tag 79 from group 78

isGroupValid(<handle>)

Returns true or false depending on the handle value

Example Code

//see the example above 


Bulk operations with group fields

Available since FIXEdge 6.12.0 

bulkSetStringField(<group handle>, <starting entry>, <fieldTag>, <value>, [<max count>])

Populates multiple entries' specific tag with constant value, or copies values from list, depending on value type.

Numeration of <starting_entry> starts with 0.

Example Code 1 

setNumField(268, 200);
hndl = getGroup(268);
bulkSetStringField(hndl, 0, 269, '0', 100);
bulkSetStringField(hndl, 100, 269, '1', 100);


Example Code 2 

bid_qty_list = [10, 20, 30, 40, 50];
ask_qty_list = [11, 22, 33];

setNumField(268, bid_qty_list.length + ask_qty_list.length);
hndl = getGroup(268);

bulkSetStringField(hndl, 0, 271, bid_qty_list);
bulkSetStringField(hndl, bid_qty_list.length, 271, ask_qty_list);

Example 1

Resizes group 268 (NoMDEntries) to 200

Gets a handle on group 268 (NoMDEntries)

For entries 0 - 99 set tag 269 (MDEntryType) to '0' ('Bid')

For entries 100 - 199 set tag 269 (MDEntryType) to '1' ('offer')

This is equivalent to code:

for (var i = 0; i < 100; i++) {
setStringField(hndl, i, 269, '0');
}

for (var i = 100; i < 200; i++) {
setStringField(hndl, i, 269, '1');
}


Example 2

Creates a bid_qty_list variable with 5 elements and ask_qty_list with 3 elements

Resizes group 268 (NoMDEntries) to 8 (total size of 2 lists)

Gets a handle on group 268 (NoMDEntries)

For entries 0-4, copy values from bid_qty_list, so that entry[i][271] = bid_qty_list[i]

For entries 5-7, copy values from ask_qty_list, so that entry[5+i][271] = ask_qty_list[i]

This is equivalent to code:

for (var i = 0; i < bid_qty_list.length; i++) {
setStringField(hndl, i, 271, bid_qty_list[i]);
}

for (var i = 0; i < ask_qty_list.length; i++) {
setStringField(hndl, bid_qty_list.length + i, 271, ask_qty_list[i]);
}

bulkSetStringFieldMapped(<group handle>, <starting entry>, <fieldTag>, <source list>, <key> [, <max count>])

Populates multiple entries' specific tag by copying values from nested elements of source Javascript array.

Numeration of <starting entry> starts with 0.

Numeration of <source list> starts with 0.

Example Code

bids = [ [0.1, 10], [0.2, 20], [0.3, 30], [0.4, 40], [0.5, 50] ] ;

asks = [ [1.1, 11], [2.2, 20], [3.3, 30] ] ;

setNumField(268, bid_qty_list.length + ask_qty_list.length);
hndl = getGroup(268);

bulkSetStringFieldMapped(hndl, 0, 270, bids, 0);
bulkSetStringFieldMapped(hndl, 0, 271, bids, 1);

bulkSetStringFieldMapped(hndl, bid_qty_list.length, 270, bids, 0);
bulkSetStringFieldMapped(hndl, bid_qty_list.length, 271, bids, 1);

For alternative source structure

bids = [ {"price": 0.1, "qty": 10}, 
{"price": 0.2, "qty": 20},
{"price": 0.3, "qty": 30},
{"price": 0.4, "qty": 40},
{"price": 0.5, "qty": 50}] ;

asks = [ {"price": 1.1, "qty": 11},
{"price": 2.2, "qty": 22},
{"price": 3.3, "qty": 33}] ;

setNumField(268, bid_qty_list.length + ask_qty_list.length);
hndl = getGroup(268);

bulkSetStringFieldMapped(hndl, 0, 270, bids, 'price');
bulkSetStringFieldMapped(hndl, 0, 271, bids, 'qty');

bulkSetStringFieldMapped(hndl, bid_qty_list.length, 270, bids, 'price');
bulkSetStringFieldMapped(hndl, bid_qty_list.length, 271, bids, 'qty');

Creates a bids variable with 5 nested pairs of elements, and ask_qty_list with 3 pairs.

Resizes group 268 (NoMDEntries) to 8 (total size of 2 lists)

Gets a handle on group 268 (NoMDEntries)

For entries 0-4, copy Price(270) and Size(271) values from bids;

For entries 5-7, copy Price(270) and Size(271) values from asks.

This is equivalent to code:

for (var i = 0; i < bid_qty_list.length; i++) {
bid = bid_qty_list[i];
setStringField(hndl, i, 270, bid[0]);
setStringField(hndl, i, 271, bid[1]);
}

for (var i = 0; i < ask_qty_list.length; i++) {
ask = ask_qty_list[i];
setStringField(noMDEntries, bid_qty_list.length + i, 270, ask[0]);
setStringField(noMDEntries, bid_qty_list.length + i, 271, ask[1]);
}


For alternative source structure

for (var i = 0; i < bid_qty_list.length; i++) {
bid = bid_qty_list[i];
setStringField(hndl, i, 270, bid['price']);
setStringField(hndl, i, 271, bid['qty']);
}

for (var i = 0; i < ask_qty_list.length; i++) {
ask = ask_qty_list[i];
setStringField(noMDEntries, bid_qty_list.length + i, 270, ask['price']);
setStringField(noMDEntries, bid_qty_list.length + i, 271, ask['qty']);
}

Operations with message fields

removeField(<fieldTag>)

Removes field from message

Example Code

removeField(58);

Removes tag 58 from the message

createReject("session")

Creating reject

Example code

createReject("Target42sohSender42");

Creating reject and sending status message 35=3

isSupportedField(<fieldTag>)

Returns true if the field is defined in the dictionary, i.e. it can be presented in the message. False means the tag is not expected in this message type

Example Code:

if ( isSupportedField( 58 ) )
    removeField( 58 );

The example shows how to remove tag 58 from the message if it is defined in the dictionary

The script checks if tag 58 is defined for the message
And remove it from the message.

isSupportedField( <group handle> , <fieldTag>)

Returns true if the field is defined in the dictionary for the specific group, i.e. it can be presented in the repeating group of the message. False means the tag is not expected in this specific group for this  message type

Example Code

partiesGrp = getGroup(448);
if ( isGroupValid(partiesGrp) && isSupportedField(partiesGrp, 2376) )
    removeField( partiesGrp, 0 , 2376 );

The example shows how to remove non required tag 2376 from the Parties group entry #0. 

The script gets the repeating group 448 handle.
Then checks if the group is valid and present in the message. And if tag 2376 is defined in the dictionary.
Then removes tag 2376 from the group entry #0

getNumField(<fieldTag>)

Returns numeric value of the <fieldTag> field

Example Code

getNumField(78);

Returns a numeric value of field 78

getNumField(<group handle>, <entry>, <fieldTag>)

Returns number value of the <fieldTag> field from group <group handle>[<entry>]