/
Business Rules Guide

Business Rules Guide

Jul 09, 2024

Overview

FIXEdge offers the set of Business Rules, which can be useful to determine message routing, session events, scripting, message modification, plug-in connection, histories management, automatic routing for some types of the messages. The Rules formation is defined by special syntax in the XML format that is described in this guide.

Configuring Business Rules

Business Rules are stored in ‘FixEdge/conf/BL_Config.xml’ file in XML format. This file is loaded into the memory during FIXEdge starting. The installation package contains the business layer configuration file with rules that allow to test the FIXEdge functionality, but it needs to be configured for client's business needs in accordance with the recommendations described in this section.The name of configuration file can be changed in ‘FIXEdge.properties’ file using ‘BusinessLayer.RoutingRules’ property. The XML formatting is described in ‘FIXEdge/conf/BusinessLayer.dtd’. Rules can be changed from FIXICC or by editing the file directly. They can also be reloaded immediately from FIXICC.

The following classes are defined for Business Rules:

  • Routing rules – used to transform and route FIX messages to sessions, adaptors etc.

  • Session events – used to handle events that are launched during execution: create session, destroy session etc.

The Business Rules XML file may contain the following auxiliary entities definitions that could be used in Business Rules:

  • Plug-ins – objects that encapsulate field transformation algorithm

  • Handlers – objects that encapsulate message handling algorithm

  • Histories – objects that store data from the handled messages

  • Routing strategies – objects that encapsulate algorithms of automatic message routing

All described above elements belong to the element <BusinessLayer>. 

Loading XML rules from separate files

XML rules for Business Layer can be stored in separate files. Use the following configuration property:
BusinessLayer.RoutingRules = file1.xml, file2.xml, file3.xml,…etc to load the set of rules.

Please note while configuring: each XML document must be a part of a single document. I.e. the first file must contain the standard header of XML file <?xml version="1.0" encoding="UTF-8"?> (or UTF-16).

The certain rules will be loaded into Business Layer from documents, but within tags:

<FixEdge> <BusinessLayer> <!—- the rules set... --> </BusinessLayer> </FixEdge>

The good practice is to start the list with BL_header.xml with the following content:

<?xml version="1.0" encoding="UTF-8"?> (or UTF-16). <FixEdge> <BusinessLayer>

and end up with BL_tail.xml with the following content:

</BusinessLayer> </FixEdge>

In this case the configuration property will look like this:
BusinessLayer.RoutingRules = BL_header.xml,…file1.xml, file2.xml,…,BL_tail.xml

Rules processing order

Due to the specifics of the Business Layer Configuration File more than one rule can be applied to message. It is also possible to route one message to multiple destinations or to the same destination multiple times.

There are several items to mention here:

  • All rules are applied independently.

  • Rules are not necessarily performed at the order specified in BL Configuration File. The order is not predefined.

  • If a set of transformation rules is applied to the same message, each rule receives its own copy of the original message and is applied to it.

  • Actions defined in the rule are applied in the specified order, except the cases listed below: 

Rule

<Rule> element has couple of attributes: “Enabled” and "Description". <Rule Enabled=”false”> disables rule parsing by Business Layer. By default the attribute value has a true value.
Each rule consists of:

  • Source (required section)

  • Condition (implied section)

  • Action (required section)

Refer to Rule element article for detailed description.

Default Rule

<DefaultRule> element defines special type of rules, which contains section <Action> only. Executed if no other rule is applied. Located at the end of Business Layer Configuration file. Usually contains action <DoNothing/>.

<FIXEdge> <BusinessLayer> <!-- ... --> <DefaultRule> <Action> <DoNothing/> </Action> </DefaultRule> </BusinessLayer> </FIXEdge>

Session events

FIXEdge router provides the user with a possibility to establish a set of Business Rules that handles FIXEdge events:

  • New session was created.

  • Session was destroyed.

  • Unable to route message to a specified target.

  • Session level reject was received in response to the sent application message.

  • Routing rule failed during execution.

  • Source section may have <FixSession SenderCompID="" TargetCompID=""/> element to identify a session that launches an event.

  • Source section may have <Client Name=""/> element to identify a client that launches an event.

  • Source section of any event may have <Source Name=""/> attribute of source identifier that launches an event.

Refer to Session Events for detailed description.

Plug-ins

<FIXEdge> <BusinessLayer> <Plugins> <Plugin Path="./Brass.dll"> <Param Name="Param1"/> </Plugin> </Plugins> </BusinessLayer> </FIXEdge>

FIXEdge offers a flexible solution for modification of FIX message partial fields - Plugins.

Plugins provide an open interface and can be written in any programming language that allows creating modules in Microsoft Windows DLL format.

The custom Plugins mechanism can be used in case Business Layer’s built-in mechanisms and engines cannot perform a specified task.
For example when conversion data must be stored from call to call or when its data must be persistent.

<Plugins> section is optional and may contain one or more <plugin> definitions.

Plugin element

Each <Plugin> element has:

Attribute 'Path'

Mandatory. Defines path and name of plugin DLL

Set of plugin parameters

Optional. Plugin parameters are defined via <Param> xml-element with a required ‘Name’ attribute.



Usage: Rule's instructionModifyField refers to the defined plugin and executes plugin method for the routed message.

Param element

Param element is used in the configuration file within <Plugin> and <Script> elements to define their parameters.

Attributes:

Name

Mandatory. Defines name of parameter

Value

Optional. Defines parameter value by default

Handlers

<FIXEdge> <BusinessLayer> <DllHandlers> <Handler VerifyHandlersVersion="true" DllName="./PSHandlerPlugin.dll" Description="Test Handler description" Name="TestHandler"/> </DllHandlers> </BusinessLayer> </FixEdge>

FIXEdge offers a flexible solution for FIX message processing - Handlers.

Handlers provide an open interface and can be written in any programming language that allows creating modules in Microsoft Windows DLL format. 

The custom Handlers mechanism can be used in case Business Layer’s built-in mechanisms and engines cannot perform a specified task.
For example when data must be stored from message to message or when data must be persistent.

FIXEdge loads Handlers only once: when it parses the business layer configuration file.

Optional <DllHandlers> section may contain one or more <handler> definitions.

Handler element

Mandatory attributes:

Name

Unique handler name that will be used in HandlerAction

Description

Handler description

DllName

Contains the path and file name of the Handler’s DLL

VerifyHandlersVersion

Specifies whether FIXEdge must verify the version of the Handler interface when loading this handler. It prevents the “dll hell” problem

Valid values: "true"|"false"



Usage:HandlerActionaction refers to the defined Handler and initiates message handling by a specified Handler.

See part FIXEdge API for BL Handlers for details.

Histories

FIXEdge offers a flexible solution for storing information that goes through the Business Layer of FIXEdge – Histories. The Business Layer supports the following types of Histories:

  • ODBCHistory - allows storing information in the ODBC database

  • SQLiteHistory - allows storing information in the SQLite database

  • FileHistory - allows storing information in the persistent file-based storage

  • MemoryHistory - allows storing information in the transient memory-based storage

Histories can be used in routing rules only when they are defined in the BL rules XML file. Each <History> element has the common attributes:

Name

Mandatory. Name of History used to refer to History from XML actions or JavaScript functions.

StorageType

Mandatory. Defines the type of History.

Valid values:  ODBC | SQLite | File | Memory

ClearTime

Optional. Defines when the everyday clear procedure is started. The format is HH:MM:SS. Clear procedure erases obsolete records.

The ClearTime attribute must be set in the UTC timezone for ODBCHistory and MemoryHistory, and in the local timezone for FileHistory.

ClearOnLoad

This attribute is available since FIXEdge C++ 6.14.3 release.

Optional. Defines whether the ClearHistory procedure will be invoked on the History creation or BL rules reload. The ClearHistory procedure is not executed on the FileHistory creation if the time specified in the ClearTime attribute has passed.

If the ExpireDateTime column is not created for the History, but the ClearOnLoad attribute is set to 'true', then this History will not be created.

Valid values: true | false

and the additional attributes depending on the History type.

The Business Layer of FIXEdge can be extended with the set of actions to work with defined Histories from XML rules and JavaScript.

The following XML actions are available:

  • SaveToHistory – saves the data retrieved from the FIX message to History.

  • ClearHistory – erases obsolete records from History.

The following JavaScript functions are defined:

ODBCHistory

Each ODBCHistory defines regulations of storage FIX message tags within the particular table of the ODBC database. ODBCHistory supports the following additional attributes:

  • TableName - Mandatory. The name of a table in the database. History will be reflected in this table.

  • ColumnSize - Optional. The default size of history string fields. If the size of the string exceeds ColumnSize string will be truncated. If the size of the string exceeds the size of the column in DB insert/update will be failed.

  • ConnectionString - Mandatory. ODBC connection string.

ODBCHistory supports the following types of fields:

  • Int

  • Float

  • Numeric. Additional required attributes for this type are Precision (max number of decimal digits, must have value from 1 to 38) and Scale (max number of decimal digits that can be stored to the right of a decimal point, should be not less than 0 and not greater than Precision)

  • Date

  • DateTime

  • String. Default data type

KeyField and Field XML elements define the field in the table that will store the particular tag of the FIX message.

Example:

BL_Config.xml
//Defines history "SampleODBCHistory" that reflects on the Orders table in database SampleBase. // Following FIX message tags mapped into the Orders table fields: // ClOrdID(11) -> ClOrdID, type - string // SenderCompId(49) -> SenderCompId, type - string[512] // TargetCompId(56) -> TargetCompId, type - string // SettlDate(64) -> SettlDate, type - date // History maps the record's ExpireDateTime attribute to the database field TransactTime <History Name="SampleODBCHistory" StorageType="ODBC" TableName="SampleBase.dbo.Orders" ClearTime="22:00:00" ColumnSize="256" ConnectionString="DSN=SampleBase;UID=test;PWD=test123;"> <KeyField ColumnName="ClOrdID">11</KeyField> <Field ColumnName="SenderCompID" ColumnSize="512">49</Field> <Field ColumnName="TargetCompID">56</Field> <Field ColumnName="Price" DataType="Numeric" Precision="20" Scale="6">44</Field> <Field ColumnName="SettlDate" DataType="Date" ColumnSize="10">64</Field> <Field ColumnName="TransactTime">ExpireDateTime</Field> </History>

KeyField element

The KeyField element defines a key field in the history and a tag of the FIX message that will be stored in it. The KeyField element represents a primary key for the table in the ODBC database.

There must be at least one KeyField element defined for the ODBCHistory.

The following attributes can be defined for the KeyField element in the ODBCHistory:

ColumnName

Mandatory. Name of table field.

DataType

Optional. Type of table field.

Valid values: Int | Float | Numeric | Date | DateTime | String

Default value: String

ColumnSize

Optional. The size of the column in the database table.

DecimalDigits

Optional. Mandatory if DataType = Float.

Precision

Optional. Defiles the max number of decimal digits. Mandatory if DataType = Numeric.

Valid values: 1 - 38

Scale

Optional. Defines the max number of decimal digits that can be stored to the right of a decimal point. Mandatory if DataType = Numeric.

Valid values: not less than 0 but not greater than the Precision

Example:



BL_Config.xml
<KeyField ColumnSize="7" ColumnName="ClOrdID">11</KeyField>

Field element

The Field element defines the field and the tag of the FIX message that will be stored in it.

The following attributes can be defined for the Field element in the ODBCHistory:

ColumnName

Mandatory. Name of table field.

DataType

Optional. Type of table field.

Valid values: Int | Float | Numeric | Date | DateTime | String

Default value: String

ColumnSize

Optional. The size of the column in the database table.

DecimalDigits

Optional. Mandatory if DataType = Float.

Precision

Optional. Defines the max of decimal digits. Mandatory if DataType = Numeric.

Valid values: 1 - 38

Scale

Optional. Defines the max number of decimal digits that can be stored to the right of a decimal point. Mandatory if DataType = Numeric.

Valid values: not less than 0 but not greater than Precision

Example:

BL_Config.xml
<Field ColumnSize="15" ColumnName="ExDestination">100</Field> <Field ColumnSize="19" ColumnName="Quantity" DecimalDigits="10" DataType="Float">53</Field> <Field ColumnSize="12" ColumnName="TransactTime" DataType="Datetime">60</Field> <Field ColumnSize="19" ColumnName="OfferPx" DecimalDigits="7" DataType="Float">133</Field> <Field ColumnSize="19" ColumnName="OfferSize" DecimalDigits="7" DataType="Float">135</Field>

ExpireDateTime field

The ExpireDateTime field defines the timestamp since which the record will be considered expired. The expired records trigger the ClearHistory procedure which cleans up the history. The ClearHistory procedure is triggered automatically on FIXEdge startup.

If the ClearTime attribute is set for the History but the expireDateTime column is not defined then the following ERROR message will be added to the log file during clearing:

ERROR History  '<history_name>' unable to clear: the ExpireDateTime filed is not defined!

Example:

BL_Config.xml
<Field ColumnName="TransactTime">ExpireDateTime</Field>

The ExpireDateTime field of the History is optional since FIXEdge 6.14.0 release.

If the History was created without the ExpireDateTime field then records will be inserted/updated in it without the expireDateTime value.

In such a case the WARN level record below will be logged:

WARN The 'ExpireDateTime' field isn't defined for File History '<history_name>' - clear operation is prohibited!

SQLiteHistory

SQLiteHistory is available since FIXEdge C++ 6.15.1 release.

Each SQLiteHistory defines regulations of storage FIX message tags within the particular table of the SQLite database. SQLiteHistory supports the following additional attributes:

  • TableName - Mandatory. The name of a table in the database. History will be reflected in this table. If the specified TableName doesn't exist, then a new table will be created with the columns defined.

  • StorageFileName - Mandatory. The name of the SQLiteHistory storage file or path to this file. If the path is not absolute, then it will be resolved against FIXEdge.RootDir directory. If the specified StorageFileName doesn't exist, then a new storage will be created.

SQLiteHistory supports the following types of fields:

  • Int

  • Float

  • Numeric

  • Date

  • DateTime

  • String. Default data type

KeyField and Field XML elements define the field in the table that will store the particular tag of the FIX message.

Example: 

BL_Config.xml
//Defines history "SampleSQLiteHistory" that reflects on the Orders table in database SampleBase. // Following FIX message tags mapped into the Orders table fields: // ClOrdID(11) -> ClOrdID, type - string // SenderCompId(49) -> SenderCompId, type - string // TargetCompId(56) -> TargetCompId, type - string // SettlDate(64) -> SettlDate, type - date <History Name="SampleSQLiteHistory"             StorageType="SQLite"             StorageFileName="SQLite_Trade.db"             TableName="SampleBase_Orders"             ClearTime="22:00:00">             <KeyField ColumnName="ClOrdID">11</KeyField> <Field ColumnName="SenderCompID">49</Field> <Field ColumnName="TargetCompID">56</Field> <Field ColumnName="Price" DataType="Numeric">44</Field> <Field ColumnName="SettlDate" DataType="Date">64</Field> <Field ColumnName="TransactTime">ExpireDateTime</Field> </History>

KeyField element

The KeyField element defines a key field in the history and a tag of the FIX message that will be stored in it. The KeyField element represents a primary key for the table in the SQLite database.

There must be at least one KeyField element defined for the SQLiteHistory.

The following attributes can be defined for the KeyField element in the SQLiteHistory:

ColumnName

Mandatory. Name of table field.

DataType

Optional. Type of table field.

Valid values: Int | Float | Numeric | Date | DateTime | String

Default value: String

Example:

BL_Config.xml
<KeyField ColumnName="ClOrdID">11</KeyField>

Field element

The Field element defines the field and the tag of the FIX message that will be stored in it.

The following attributes can be defined for the Field element in the SQLiteHistory:

ColumnName

Mandatory. Name of table field.

DataType

Optional. Type of table field.

Valid values: Int | Float | Numeric | Date | DateTime | String

Default value: String

Example:

BL_Config.xml
<Field ColumnSize="15" ColumnName="ExDestination">100</Field> <Field ColumnSize="19" ColumnName="Quantity" DataType="Float">53</Field> <Field ColumnSize="12" ColumnName="TransactTime" DataType="Datetime">60</Field> <Field ColumnSize="19" ColumnName="OfferPx" DataType="Float">133</Field> <Field ColumnSize="19" ColumnName="OfferSize" DataType="Float">135</Field>

ExpireDateTime field

The ExpireDateTime field defines the timestamp since which the record will be considered expired. The expired records trigger the ClearHistory procedure which cleans up the history. The ClearHistory procedure is triggered automatically on FIXEdge startup.

If the ClearTime attribute is set for the SQLiteHistory but the expireDateTime column is not defined then the following ERROR message will be added to the log file during clearing:

ERROR History  '<history_name>' unable to clear: the ExpireDateTime filed is not defined!

Example:

BL_Config.xml
<Field ColumnName="TransactTime">ExpireDateTime</Field>

If the History was created without the ExpireDateTime field then records will be inserted/updated in it without the expireDateTime value.

In such a case the WARN level record below will be logged:

WARN The 'ExpireDateTime' field isn't defined for File History '<history_name>' - clear operation is prohibited!

FileHistory

Each FileHistory defines regulations of storage FIX message tags within the particular file. FileHistory supports the following additional attributes:

  • WorkingDirectory – Mandatory. Path to stored FileHistory files.

  • StorageFileName – Mandatory. The name of the FileHistory storage file.

Both KeyFields and Fields XML elements define a set of tags. Tags within the KeyFields element are used as a record composite key.

Example:

BL_Config.xml
//Defines history "SampleFileHistory", history saves data to the file .\logs\SmplFileHistory // The ClOrdID(11), SenderCompId(49) and TargetCompId(56) FIX tags used as a record composite key <History Name="SampleFileHistory" WorkingDirectory=".\logs" StorageType="File" StorageFileName="SmplFileHistory" ClearTime="22:00:00"> <KeyFields>11, 49, 56</KeyFields> <Fields>99,18,63,64,528,529,100</Fields> <Field>ExpireDateTime</Field> </History>

KeyFields element

Contains a set of comma-separated FIX message tags. Tags are used to search the message data within the file or memory.

Fields element

Contains a set of comma-separated FIX message tags.

MemoryHistory

MemoryHistory defines regulations of storage FIX message tags within the FIXEdge server memory. MemoryHistory does not require additional attributes.

Both KeyFields and Fields XML elements define a set of tags. Tags within the KeyFields attribute are used as a record composite key.

Example:

BL_Config.xml
//Defines history "SampleMemHistory" // The ClOrdID(11), SenderCompId(49) and TargetCompId(56) FIX tags used as a record composite key <History Name="SampleMemHistory" StorageType="Memory" ClearTime="22:00:00"> <KeyFields>11, 49, 56</KeyFields> <Fields>99,18,63,64,528,529,100</Fields> <Field>ExpireDateTime</Field> </History>

Direct Database API

Please refer to the Direct Database API page for more details.

To establish connectivity to a database, you need to configure it in the BL_Config.xml file. This is achieved using the DatabaseConnection element, located under the /FIXEdge/BusinessLayer/DatabaseConnection path.

Here's an example configuration for an ODBC database:

<DatabaseConnection Name="SampleODBCDatabase" StorageType="ODBC" ConnectionString="DSN=SampleBase;UID=test;PWD=test123;" MinPoolSize="1" MaxPoolSize="5" />

Parameters:

  • Name: This case-sensitive identifier is used to reference the connection throughout your FIXEdge configuration.

  • StorageType: This case-insensitive option specifies the type of database connection you are using. Currently, only ODBC is supported.

  • ConnectionString: This string contains the information needed to connect to your database. The format will vary depending on your specific DBMS.

  • MinPoolSize: This defines the minimum number of connections that will be available in the pool at FIXEdge system startup. Default: 1

  • MaxPoolSize: This sets the maximum number of connections that FIXEdge can create in the pool. Default: 16

Please note that, at this stage, all operations performed on configured database connections are automatically committed. This mimics the default autocommit behaviour in ODBC (AUTOCOMMIT_ON=true). This means you don't need to explicitly manage transactions.

Scripts

FIXEdge offers a flexible solution for routing and transferring of FIX messages that go through the Business Layer of FIXEdge and data manipulations. 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. The proper usage of this feature requires scripts 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 the time spent on business logic implementation

  • Flexibility and simplicity of modification

  • Does not cause significant losses in performance

You can find more details about Javascript and XSTL scripting here: BL Scripting with JavaScript and BL Scripting with XSLT

In case of the JavaScript usage you can control the number of parallel scripts using the BusinessLayer.JS.ExecuteInParallel parameter. More detailed information about it is available here: FIX Engine parameters#BusinessLayer.JS.ExecuteInParallel

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 perform the proper transformations.

FIXEdge Javascript act provides the user with all the standard Javascript features and functionality. In addition to this, it enables the user to use functions that provide access to FIX message inside data, allows manipulations with fields and groups as well as whole FIX messages.
Predefined FIX date formats:

  • HHMMSSUtc for the UTC "HH:MM:SS" date format

  • HHMMSSsssUtc for the UTC "HH:MM:SS.sss" date format

  • YYYYMM for the "YYYYMM" date format