FIX trading integrations

LUSID offers FIX trading integrations that allow you to set up EMS staging and drop copy connections to a variety of third party systems. See the full list.

Prerequisites

To get started, contact your FINBOURNE representative to enable the integration in your LUSID domain.

Further reading: Understand how LUSID’s order management system works.

Supported data types and methods

Instruments

See article: Which instruments can I trade using LUSID?

Order entities and connection types

You can use LUSID to stage orders in an execution management system (EMS) with FIX messages that interact with the following entities:

• Placements

• Executions

You can create orders in external systems (including EMS) and store records of any of the following entities in LUSID via drop copy:

• Orders

• Blocks

• Placements

• Executions

• Allocations

Setting up the integration

All FIX trading integrations have a corresponding shared configuration set in the Configuration Store that you must populate with the relevant values.

To do so:

1. Navigate to System Settings > Configuration Store and select the Shared Keys tab.

2. Locate the relevant configuration set with Scope system and Code FLAG-<external-system> and select Edit.
   

3. Supply the required key and value pairs for your integration, as listed under Required for all connection types and:

   • For EMS staging connections: EMS-only

   • For drop copy connections: Drop copy-only

Required for all connection types

ConnectionType

LUSID prepopulates one of the following connection types:

• Trading

• DropCopy

• PostTrade

• DropCopyLarge

EntityScope

Specify which scope LUSID loads orders, placements, and other data into from the external system.

QuickFIX-Session-Config

Use the following format to supply a connection configuration for FIX sessions with the external system:

[DEFAULT] 
ConnectionType=initiator 
LogoutTimeout=20 
LogonTimeout=30 
ResetOnLogon=N 
ResetOnDisconnect=N 
UseDataDictionary=Y 
DataDictionary=./FIX42.xml 
SocketConnectProtocol=TCP 

[SESSION] 
SocketConnectPort=<value> 
SocketConnectHost=<value> 
BeginString=FIX.4.2 
TargetCompId=<venue-id>
SenderCompId=<id> 
FileLogPath=log 
FileStorePath=store 
HeartBtInt=30 
StartDay=Monday 
StartTime=07:02 
EndDay=Friday 
EndTime=20:00 
SSLCertificate=<certificate> 
SSLCertificatePassword=<password>
SSLValidateCertificates=N

Your external system provider should supply you with the correct [SESSION] settings.

Note

Some FIX sessions require additional authentication types:

• FIX session Password

• SSL/TLS with server certificate validation:

  • SSLEnable=Y

  • SSLValidateCertificates=Y

  • SSLServerName=:  Extract the Common Name (CN) from the certificate provided by the external system and supply it here.

• Mutual TLS (mTLS) client certificate authentication:

  1. Obtain a client certificate (.crt or .pem) and private key (.key) from your external system.

  2. Run the following in the command line to convert the client certificate and key into a combined PFX/P12 format:

     openssl pkcs12 -export -out venue-client.pfx \
       -inkey client-private.key \
       -in client-certificate.crt

  3. Create a password when prompted and store it securely.

  4. Add the following to the [SESSION] section of the QuickFixSessionConfig:

     • SSLCertificate=SSLCertificate

     • SSLCertificatePassword=<password-from-step-3>

  5. Run the following in the command line to convert the P12 certificate into base64:

     base64 -i venue-client.pfx -o venue-client-base64.txt

  6. Supply the base64 output to the configuration set as the P12CertificateContent value.
     

P12CertificateContent

Only required for mTLS (as detailed in the note above); supply the P12 certificate provided by your external system in base64 format.

FIX-LUSID-Map

Specify a JSON that defines how to map FIX message tags to LUSID properties.

The JSON should contain the following fields:

• FixToLusidMapperType: Optional; one of the following depending on the FIX version or external system:

  • Fix42ToLusidMapper

  • Fix44ToLusidMapper

  • DTaasFix50SP2ToLusidMapper

  • VconToLusidMapper

• FixToLusidScopeProviderType: Optional; defines whether to override the specified EntityScope, retrieving the scope from elsewhere:

  • OrderEntityScopeProvider (default)

  • DtaasScopeProvider

• FixToLusidOrderEntityIdExtractorType: Optional; defines how to retrieve IDs from FIX messages:

  • DefaultOrderEntityIdProvider (default)

  • OrderIdOrderEntityIdProvider

  • VconOrderEntityIdProvider

  • VconUnsolicitedOrderEntityIdProvider

• GENERIC_PROPERTIES: A dictionary of mappings for FIX tags to LUSID property keys. LUSID adds the properties to each order entity it creates (for example placements and executions), for example, a mapping of "1": "FIX/Account", might populate a placement in LUSID with the property Placement/FIX/Account.

  Note

  LUSID creates property definitions on demand if the property keys specified do not yet exist. You can specify the property domain in the mapping, for example Transaction/FIX/Price, to always populate the order entity with the property in the specified domain.

• CUSTOM_INSTRUMENT_MAPPING: Optional; overrides the default security ID type mapping that LUSID extracts from the FIX message to the specified instrument identifiers

• CONSTANT_VALUE_PROPERTIES: Optional; allows you to specify one or more properties with fixed values that LUSID should add to an order entity in the format <entity>/<scope>/<code>=<value>

• PROPERTIES_FROM_REPEATING_GROUPS: Optional; allows you to specify one or more repeating groups from FIX messages that you want to add as properties in LUSID. Each list item should contain:

  • GroupTag: The tag of the start of a repeating group

  • SelectorTags: Selects the group that matches the specified tags and values, for example 452=11 and 447=D

  • ExtractTag: If the above selected group exists, extracts the value from this tag and maps it to a LUSID property

  • Property: A LUSID property to map the extractTag value to

• COUNTERPARTY_MAPPING: Optional; overrides the default counterparty tag of 76. You can specify:

  • FixTag: A FIX tag LUSID should extract the counterparty value from

  • ValueMappings: Specify one or more custom values for LUSID to convert the FIX message value to, or omit this field to use the value on the FIX message

For example:

{
  "FixToLusidMapperType": "Fix42ToLusidMapper",
  "FixToLusidScopeProviderType": "OrderEntityScopeProvider",
  "FixToLusidOrderEntityIdExtractorType": "OrderIdOrderEntityIdProvider",
  "GENERIC_PROPERTIES": {
    "1": "FIX/Account", 
    "15": "FIX/Currency",
    "17": "FIX/ExecID", 
    "37": "FIX/OrderID",
    "38": "FIX/OrderQty",
    "39": "FIX/OrdStatus",
    "44": "Transaction/FIX/Price",
    "52": "FIX/SendingTime",
    "54": "FIX/Side",
  },
  "PROPERTIES_FROM_REPEATING_GROUPS": [
    {
      "grouptag": "453",
      "selectortags": [
        {
          "tag": "452",
          "value": "11"
        },
        {
          "tag": "447",
          "value": "D"
        }
      ],
      "extracttag": "448",
      "property": "FIX/Trader"
    }
  ],
  "CUSTOM_INSTRUMENT_MAPPING": {
    "5": "Instrument/Finbourne-Examples/FIXRIC"
  },
  "CONSTANT_VALUE_PROPERTIES": {
    "Allocation": [
      "Allocation/<scope>/<code>=<value>"
    ],
    "Order": [
      "Order/Finbourne-Examples/Strategy=A"
    ],
    "Block": [
      "Block/Finbourne-Examples/Trader=JaneDoe"
    ],
    "Placement": [
      "Placement/Finbourne-Examples/Trader=JaneDoe"
    ],
    "Execution": [
      "Execution/Finbourne-Examples/Trader=JaneDoe"
    ]
  },
  "COUNTERPARTY_MAPPING": {
    "FixTag": "1",
    "ValueMappings": {
      "Value1": "v1",
      "Value2": "v2"
    }
  }
}

LusidToFixConfig

Specify a JSON that defines outbound (and some bidirectional) mappings from LUSID properties to FIX message tags.

The JSON should contain the following fields:

• FixTranslationManager: Optional; specifies one of the following translation manager types for inbound and outbound FIX messages:

  • DefaultTranslationManager (default)

  • EmsxTranslationManager

  • FlexNowTranslationManager

  • GlmxTranslationManager

  • NyfixTranslationManager

  • TradeWebTranslationManager

  • TsoxTranslationManager

• OrdTypeMap: Maps the placement type to a FIX value for tag 40, for example “Limit“: “2“

• SideMap: Maps the placement side to a FIX value for tag 54, for example “Buy“: “1“ or “Sell“: “2“

• InstrumentTypeSideMap: Optional; overrides the SideMap for the instrument types you specify and allows you to define custom sides for both inbound and outbound FIX messages

• TimeInForceMap: Maps the placement time-in-force to a FIX value for tag 59

• HandlInstMap: Maps the optional Placement/FIX/HandlInst property to a FIX value for tag 21

• IDSourceMap: Maps the LUSID instrument’s identifier type to a specified FIX value in tag 22

• SecurityIDSource: The default instrument identifier to populate in FIX tag 48

• InstrumentTypeIdSourceMap: Optional; overrides the default SecurityIDSource for the instrument types you specify

• LusidToEmsUserMap: Maps LUSID user IDs to external system user IDs for authentication

• PlacementCounter: A LUSID property containing a counter value; LUSID adds /<value> to the placement ID when setting ClOrderID/OrigClOrdID to track placement updates

• AllocationMode: Optional, only used by some connections; controls allocation group behaviour on outbound messages using one of the following:

  • Default: No impact on outbound messages

  • NoAllocs: LUSID populates the Allocations repeating group (FIX tag 78 unless otherwise specified in LUSID-FIX-Map NoAllocsPropertyMap). When set, LUSID populates AllocAccount (tag 79) by extracting the property specified in PortfolioAccountProperty from each of the orders in the block.

• PortfolioAccountProperty: Only required when AllocationMode is set to NoAllocs; the portfolio property key to use when retrieving accounts for the Allocations repeating group

For example:

{
  "FixTranslationManager": "EmsxTranslationManager",
  "ClientLEI": "<EMSX-only-legal-entity-identifier>",
  "DeliverToCompID": "<FlexNow-only-broker>",
  "OrdTypeMap": {
    "Market": "1",
    "Limit": "2",
    "Stop": "3"
  },
  "SideMap": {
    "Buy": "1",
    "Sell": "2"
  },
  "InstrumentTypeSideMap": {
    "Future": {
      "CustomBuy": "1",
      "CustomSell": "2"
    },
    "ExchangeTradedOption": {
      "BuyOption": "1",
      "SellShort": "2"
    }
  },
  "TimeInForceMap": {
    "Day": "0",
    "Good till cancel": "1",
    "Immediate or cancel": "3"
  },
  "HandlInstMap": {
    "private_auto": "1",
    "public_auto": "2",
    "man_best": "3"
  },
  "IDSourceMap": {
    "Instrument/default/Cusip": "1",
    "Instrument/default/Sedol": "2",
    "Instrument/default/Isin": "4",
    "Instrument/default/Figi": "S"
  },
  "SecurityIDSource": "Instrument/default/Isin",
  "InstrumentTypeIdSourceMap": {
    "Bond": "Instrument/default/Figi"
  },
  "LusidToEmsUserMap": {
    "00ufksn982mskkcvl": "external-system-id-1",
    "00usneu662ma0q00cj": "external-system-id-2"
  },
  "PlacementCounter": "Placement/FIX/ClOrdIdCounter",
  "AllocationMode": "NoAllocs",
  "PortfolioAccountProperty": "Portfolio/FIX/Account"   
}

EMS-only

LUSID-FIX-Map

For EMS staging connections, specify a JSON that defines outbound mappings from LUSID properties to FIX message tags.

The JSON should contain the following fields:

• PropertyToFixFieldMap: A list of mappings defining how to populate FIX tags from LUSID properties. Each mapping should contain:

  • PropertyKey: A placement, instrument, or block domain LUSID property key

  • Field: The FIX tag number to populate

  • FixSection: Whether to place the field in the FIX message Body or Head (see FIX documentation - though most fields should be in the message Body)

  • Required: Set to True if the property must have a value; if set to True and no value or DefaultValue exists, LUSID fails to map the placement to a FIX message and therefore doesn’t send a FIX message out

  • DefaultValue: Optional; LUSID supplies this default value if the property does not have a value

  • MessageTypes: Optional; if specified, LUSID only applies this mapping to the specified FIX message types

  • InstrumentTypes: Optional; if specified, LUSID only applies this mapping to the specified instrument types

• PropertyToFixGroupMap: Optional; a list of mappings defining how to populate FIX repeating groups from LUSID properties. Each mapping should contain:

  • ID: A unique identifier for the group

  • GroupNumber: The FIX tag number for the repeating group

  • Fields: A list of field mappings, each containing:

    • PropertyKey: A LUSID property key

    • Field: The FIX tag number within the group

    • DefaultValue: Optional; LUSID supplies this default value if the property does not have a value

  • InstrumentTypes: Optional; if specified, LUSID only populates this group for the specified instrument types

  • MessageTypes: Optional; if specified, LUSID only populates this group for the specified FIX message types

  • Required: Set to True if the group must be populated

• NoAllocsPropertyMap: Only required if AllocationMode is set to NoAllocs in the LusidToFixConfig; overrides the default allocations repeating group structure. This field follows the same structure as PropertyToFixGroupMap, and additionally supports:

  • NestedGroups: A list of nested repeating groups within the allocations group, each following the same structure as the parent group

For example:

{
  "PropertyToFixFieldMap": [
    {
      "PropertyKey": "Placement/FIX/SecurityType",
      "Field": "167",
      "FixSection": "Body",
      "Required": "True",
      "DefaultValue": "CS",
      "MessageTypes": ["NewOrderSingle", "OrderCancelReplaceRequest"]
    },
    {
      "PropertyKey": "Placement/FIX/DeliverToLocationID",
      "Field": "145",
      "FixSection": "Head",
      "Required": "True",
      "DefaultValue": "FI",
      "MessageTypes": [],
      "InstrumentTypes": ["CDS"]
    }
  ],
  "PropertyToFixGroupMap": [
    {
      "Id": "CompanyId",
      "Fields": [
        {
          "PropertyKey": "Placement/FIX/CompanyId",
          "Field": "448",
          "DefaultValue": "AcmeCo"
        },
        {
          "PropertyKey": "Instrument/FIX/CompanyIdRole",
          "Field": "452",
          "DefaultValue": "11"
        }
      ],
      "GroupNumber": "453",
      "InstrumentTypes": ["CDS"],
      "Required": "True",
      "MessageTypes": []
    }
  ],
  "NoAllocsPropertyMap": {
    "Id": "NoAllocs",
    "Fields": [
      {
        "PropertyKey": "Portfolio/FIX/Account",
        "Field": "79"
      }
    ],
    "GroupNumber": "78",
    "InstrumentTypes": ["CDS"],
    "Required": "True",
    "MessageTypes": [],
    "NestedGroups": [
      {
        "Id": "NoNestedPartyIds",
        "Fields": [
          {
            "PropertyKey": "Portfolio/FIX/FCMID",
            "Field": "524"
          },
          {
            "PropertyKey": "Portfolio/FIX/FCMIDSource",
            "Field": "525",
            "DefaultValue": "N"
          }
        ],
        "GroupNumber": "539",
        "InstrumentTypes": [],
        "Required": "True",
        "MessageTypes": []
      }
    ]
  }
}

Drop copy-only

EntityUpsertType

For drop copy connections, specify which order entities to upsert to LUSID from FIX messages:

• OrdersAndAllocations

• PlacementsAndExecutions

• PlacementsBlocksOrderAndExecutions

• AllEntitiesFromFill

• OrdersAndAllocationsFromFill

PortfolioScope and PortfolioCode

Specify a portfolio scope and code for LUSID to upsert drop copy order entities to.

Running the integration

Once your configuration set is set up, you can start trading using LUSID or your chosen external system.

How you trade depends on your integration type:

• EMS: Stage trades using the Order Blotter, then place them via your EMS

• Drop copy: Trade using your external system and monitor your records in LUSID

Monitoring and troubleshooting integration runs

You can view your integrated placements and executions in LUSID via Portfolio Management > Order Blotter or Order Management. LUSID stores each record under your chosen EntityScope:

To monitor and troubleshoot FIX messages LUSID receives and errors that occur on the LUSID side of the process:

1. Navigate to the Order Blotter and enable the Details grid.
   

2. Click the Configuration icon in the Details grid.
   

3. Select the following columns to add to your dashboard:

   • <entity>/FIX/Error: Displays errors that occurred on the LUSID side of the process

   • <entity>/FIX/FIXMessage: Displays errors that occurred on the FIX side of the process

   • <entity>/FIX/Text: Extracts the text from the FIX message and displays it as a human-friendly value

   

4. Click Save.

Note

For drop copy connections, check whether the entities you expect to have been created exist in the Order Blotter dashboard. If you think an entity is missing, contact support.