JSONMapping Handler
- Yaroslav Melyn
Overview
JSONMapping Handler is a FIXEdge plugin that implements FIX-to-JSON and JSON-to-FIX encoding according to the FIX standard.
Handler functions
JSONMapping Handler performs the following functions:
- Converts any FIX message to JSON and stores it to XML message (MsgType = n) or any other message type of the user's choice.
- Converts any JSON message contained in XML message (MsgType = n) or any other message type back to FIX message.
Configuration parameters
The handler is configured as part of the business logic in BL_Config.xml, along with other FIXEdge handlers.
The table below represents the JSONMapping Handler config properties.
Property name | Description | Required |
|---|---|---|
Common BL handlers configuration properties | ||
Name | Reference name used in the Business Logic Actions. Example: JSONMapping | Y |
Description | A description defined by a user. Example: JSONMapping Handler | Y |
DllName | Path to a library, starting from RootDir. Example: ./libJSONMapping.so | Y |
VerifyHandlersVersion | If set to "true" FIXEdge C++ prevents the use of an unexpected version of the module in order to avoid incompatible changes between two different FIXEdge C++ versions. The recommended value is "true". If the version of the handler is different from the FIXEdge C++ version, the module will not be loaded and the corresponding error will be logged. | N |
Specific JSONMapping Handler configuration properties | ||
Direction | The direction of the conversion. Valid values: FIX-to-JSON | JSON-to-FIX | Y |
MessageType | MsgType of the encoded message container. Applicable only to FIX-to-JSON encoding. Valid values: any MsgType value The default value: n | |
FieldTag | The tag to put JSON to or to get JSON from depending on conversion direction. Valid values: any tag number The default value: 213 | N |
IncludeCustomTags | Determines whatever to include custom tags to resulting JSON (the tag is used as a field name) or to accept custom tags from incoming JSON. Valid values: true | false The default value: false | N |
FIXVersion and ParserVersion properties define the dictionary to use. FIX-to-JSON conversion: If the FIXVersion and ParserVersion properties are not defined then the container message will have the same version as the source message has. JSON-to-FIX conversion: If the FIXVersion and ParserVersion properties are not defined then the source container message property values will be used. | ||
ParserVersion | The value of the ParserVersion property is parser template string. FIX-to-JSON conversion: The ParserVersion property defines which parser (dictionaries set) to use. If the ParserVersion property is not defined then the source message parser will be used. JSON-to-FIX conversion: The ParserVersion property defines which parser (dictionaries set) to use. If the ParserVersion is not defined then the parser of the source container FIX message will be used. Examples: ParserVersion="ICE@FIXT11:FIX44_ICE", FIXVersion="FIX44_ICE" - the FIX44_ICE application protocol dictionary over FIXT11 session will be used. The value of the ParserVersion property must be defined in the AdditionalParsersList list in the engine.properties file. ParserVersion="MyParser@", FIXVersion="FIX50SP2_custom" - the FIX50SP2_custom application protocol dictionary of the custom MyParser parser will be used. The value of the ParserVersion property must be defined in the AdditionalParsersList list in the engine.properties file. ParserVersion - not provided, FIXVersion="FIX44" - the FIX44 application protocol dictionary from the source FIX message will be used. | N |
FIXVersion | The value of the FIXVersion property is the 'id' attribute of the protocol loaded from xml dictionary file. FIX-to-JSON conversion: The FIXVersion property defines which particular protocol version from the set (defined by the ParserVersion property) to use. If the FIXVersion property is not defined then the default application-level protocol version of parser defined by the ParserVersion property will be used. JSON-to-FIX conversion: The FIXVersion property defines the particular protocol version to use if JSON message doesn't provide the version explicitly by means of 1128 and 1129 tags when applicable. If the FIXVersion property is not defined then the default application-level protocol version of the parser defined by the ParserVersion property will be used. Examples: ParserVersion="FIXT11:FIX44,FIX50SP2", FIXVersion="FIX50SP2" - the standard FIX50SP2 application protocol from standard dictionaries will be used. ParserVersion="ICE@FIXT11:FIX44_ICE", FIXVersion - not provided - the FIX44_ICE application protocol dictionary over FIXT11 session will be used since there is only one application-level protocol version is specified for the parser. The value of the ParserVersion property must be defined in the AdditionalParsersList list in the engine.properties file. | N |
FIX-to-JSON Conversion Example
In the example below JSONMapping Handler is configured to convert FIX message to JSON message and store in the 213 tag of XML message (MsgType = n).
BL Rule
<DllHandlers>
<Handler Name="JSONMapping"
Description="JSONMapping Handler"
DllName="./JSONMappingHandler-MD-x64.dll"
VerifyHandlersVersion="true"/>
</DllHandlers>
<Rule Description="Mapping handler with only default properties">
<Source>
<FixSession SenderCompID="Client1" TargetCompID="Client2"/>
</Source>
<Action>
<HandlerAction Name="JSONMapping" Direction="FIX-to-JSON"/>
<Send>
<FixSession SenderCompID="Client2" TargetCompID="Client1"/>
</Send>
</Action>
</Rule>
Input Message
8=FIXT.1.1|9=195|35=i|1128=10|49=Client1|56=Client2|34=2|52=20230221-11:09:15.850|117=1116226|296=2|302=0001|304=2|295=2|299=11|132=10|299=12|133=11|302=0002|304=3|295=3|299=21|132=12|299=22|133=13|299=23|133=14|10=046
Output Message
8=FIXT.1.1|9=638|35=n|49=Client2|56=Client1|34=2|52=20230306-12:37:06.130|1128=10|212=560|213={"Header":{"BeginString":"FIXT.1.1","BodyLength":"195","MsgType":"i","ApplVerID":"10","SenderCompID":"Client1","TargetCompID":"Client2","MsgSeqNum":"2","SendingTime":"20230221-11:09:15.850"},"Body":{"QuoteID":"1116226","NoQuoteSets":[{"QuoteSetID":"0001","TotNoQuoteEntries":"2","NoQuoteEntries":[{"QuoteEntryID":"11","BidPx":"10"},{"QuoteEntryID":"12","OfferPx":"11"}]},{"QuoteSetID":"0002","TotNoQuoteEntries":"3","NoQuoteEntries":[{"QuoteEntryID":"21","BidPx":"12"},{"QuoteEntryID":"22","OfferPx":"13"},{"QuoteEntryID":"23","OfferPx":"14"}]}]},"Trailer":{}}|10=061
JSON-to-FIX Conversion Example
In the example below JSONMapping Handler is configured to convert JSON message contained in the 213 tag of XML message (MsgType = n) to FIX message with the same version as the source FIX message had.
BL Rule
<DllHandlers>
<Handler Name="JSONMapping"
Description="JSONMapping Handler"
DllName="./JSONMappingHandler-MD-x64.dll"
VerifyHandlersVersion="true"/>
</DllHandlers>
<Rule Description="Default properties">
<Source>
 <FixSession SenderCompID="Client1" TargetCompID="Client2"/>
</Source>
<Action>
<HandlerAction Name="JSONMapping" Direction="JSON-to-FIX" FIXVersion=""/>
<Send>
<FixSession SenderCompID="Client2" TargetCompID="Client1"/>
</Send>
</Action>
</Rule>
Input Message
8=FIXT.1.1|9=638|35=n|1128=10|49=Client1|56=Client2|34=2|52=20230306-12:27:01.730|212=560|213={"Header":{"BeginString":"FIXT.1.1","BodyLength":"195","MsgType":"i","ApplVerID":"10","SenderCompID":"Client1","TargetCompID":"Client2","MsgSeqNum":"2","SendingTime":"20230221-11:09:15.850"},"Body":{"QuoteID":"1116226","NoQuoteSets":[{"QuoteSetID":"0001","TotNoQuoteEntries":"2","NoQuoteEntries":[{"QuoteEntryID":"11","BidPx":"10"},{"QuoteEntryID":"12","OfferPx":"11"}]},{"QuoteSetID":"0002","TotNoQuoteEntries":"3","NoQuoteEntries":[{"QuoteEntryID":"21","BidPx":"12"},{"QuoteEntryID":"22","OfferPx":"13"},{"QuoteEntryID":"23","OfferPx":"14"}]}]},"Trailer":{}}|10=061
Output Message
8=FIXT.1.1|9=195|35=i|49=Client2|56=Client1|34=2|52=20230306-12:27:01.736|1128=10|117=1116226|296=2|302=0001|304=2|295=2|299=11|132=10|299=12|133=11|302=0002|304=3|295=3|299=21|132=12|299=22|133=13|299=23|133=14|10=049