Application configuration

This page contains information on how to configure your FX Mobile.

For information on how to configure the FX Mobile web app, see see Configure FX Mobile.

For information on how to configure the FX Mobile native app, contact your Caplin Account Manager.

Configuration file format

The configuration file, AppConfig.json, contains a single JSON object, with each configuration item a property of the object.

All property names and enumerated values are case sensitive unless stated otherwise.

Many properties with numeric values are written as JSON strings. This is a deliberate decision to avoid issues that may arise from floating-point rounding error.

The table below lists the properties of the configuration object.

Property Data Type Description

ACTIVATION_PICKER

Object

The order activation date-picker

AMOUNT_PICKER

Object

The amount picker

BULK_ORDER_ACTIONS

Array of strings

Bulk-order context menu.

BUTTONS_GROUP

Object

Shortcut buttons in the rate picker and the amount picker

CAPLIN.PERMISSION.CONFIG.URL

String

Internal permissions configuration.

CURRENCIES

Object

Order of currencies in the currency keyboard.

DEV

Object

Software development and testing.

EXPIRATION_PICKER

Object

The order expiration date-picker

FEATURE_RESET_FIELDS_AFTER_EXECUTION

Boolean

Reset the Amount and Tenor fields after a trade.

FEATURE_RESET_ACCOUNT_SELECTOR_AFTER_EXECUTION

Boolean

Reset the Account field after a trade.

HIGH_AND_LOWS

Object

High, low, opening, and closing price statistics

INSTRUMENT_DETAILS

Object

Uneven orders

KEYBOARDS

Object

The integer and decimal keyboards

LOGIN

Object

Username and password field lengths

MENU_ITEM_EXTERNAL_LINKS

Array of objects

Defines main-menu entries that are links to websites, email addresses, and telephone numbers.

NOTIFICATIONS

Object

Application notifications

ON_APP_LOADED

Object

Defines the initial screen to display on opening FX Mobile.

ORDER_RATE_THRESHOLD

Integer

Target-rate validation

PASSWORD_FIELDS

Object

Two-factor authentication: one-time password (OTP) entry.

PIPSCOLOUR

Object

Styling of pips

POST_TRADE_ORDER_GENERATOR

Object

Orders pre-populated with data from a specific trade.

RADIO_BUTTONS

Object

Radio buttons for order activation and order expiration

TIMEZONE

Object

The market time zone.

WATCHLISTS

Object

Watchlists
Example
{
  "ACTIVATION_PICKER": <object>,
  "AMOUNT_KEYBOARD": <object>,
  "AMOUNT_PICKER": <object>,
  "BUTTONS_GROUP": <object>,
  "BULK_ORDER_ACTIONS": <array of strings>,
  "CAPLIN.PERMISSION.CONFIG.URL": <string>,
  "CURRENCIES": <object>,
  "DEV": <object>,
  "EXPIRATION_PICKER": <object>,
  "FEATURE_RESET_FIELDS_AFTER_EXECUTION": <boolean>,
  "FEATURE_RESET_ACCOUNT_SELECTOR_AFTER_EXECUTION": <boolean>,
  "HIGH_AND_LOWS": <object>,
  "INSTRUMENT_DETAILS": <object>,
  "KEYBOARDS": <object>,
  "LOGIN": <object>,
  "MENU_ITEM_EXTERNAL_LINKS": <object>,
  "NOTIFICATIONS": <object>,
  "ON_APP_LOADED": <object>,
  "ORDER_RATE_THRESHOLD": <integer>,
  "PASSWORD_FIELDS": <object>,
  "PIPSCOLOUR": <object>,
  "POST_TRADE_ORDER_GENERATOR": <object>,
  "RADIO_BUTTONS": <object>,
  "TIMEZONE": <object>,
  "WATCHLISTS": <object>,
}

ACTIVATION_PICKER

The ACTIVATION_PICKER property configures the order-activation date picker.

This property takes a single object as its value.

ACTIVATION_PICKER object
Property Data Type Description

DEFAULT_TIME

Object

The default time-of-day for order activation when a date other than "good from activation" (GFA) is selected. See ACTIVATION_PICKER > DEFAULT_TIME object.
ACTIVATION_PICKER > DEFAULT_TIME object
Property Data Type Description

hours

String

Hours (0-11)

minutes

String

Minutes (0-59)

meridiem

String

"AM" or "PM"
Example
"ACTIVATION_PICKER": {
    "DEFAULT_TIME": {
        "hours": "9",
        "minutes": "00",
        "meridiem": "AM"
    }
},

AMOUNT_PICKER

The AMOUNT_PICKER property configures the currency amount picker.

This property takes a single object as its value.

AMOUNT_PICKER object
Property Data Type Description

MAX_NUMERIC_CHARACTERS

Integer

Maximum number of numeric characters
Example
"AMOUNT_PICKER": {
    "MAX_NUMERIC_CHARACTERS": 15
},

BULK_ORDER_ACTIONS

The BULK_ORDER_ACTIONS property defines the menu entries that are displayed in the Bulk Actions context menu.

This property takes an array of strings as its value.

The valid values for the array are the i18n strings:

  • "cancelAll"

  • "activateAll"

  • "deactivateAll"

Example
"BULK_ORDER_ACTIONS" : ["cancelAll", "activateAll", "deactivateAll"],

BUTTONS_GROUP

The BUTTONS_GROUP property configures the labels, values, and widths of shortcut keys in the keyboards for rate and amount entry.

This property takes a single object as its value.

BUTTONS_GROUP object
Property Data Type Description

rate-picker-shortcuts

Array of objects

Array of shortcut objects. See BUTTONS_GROUP > rate-picker-shortcuts objects.

amount-picker-shortcuts

Array of objects

Array of shortcut objects. See BUTTONS_GROUP > rate-picker-shortcuts objects.
BUTTONS_GROUP > rate-picker-shortcuts objects
Property Datatype Description

label

String

The label to display on the shortcut key.

value

String

The value of the shortcut key.

width

Integer

[Optional] The width of the shortcut key. Specify '1' for single-width (the default), '2' for double-width, '3' for triple-width, and so on.
BUTTONS_GROUP > amount-picker-shortcuts objects
Property Data Type Description

label

String

The label to display on the shortcut key.

value

String

The value of the shortcut key.

width

Integer

[Optional] The width of the shortcut key. Specify '1' for single-width (the default), '2' for double-width, '3' for triple-width, and so on.
Example
"BUTTONS_GROUP": {
    "rate-picker-shortcuts": [
        {"label": "-10", "value": "-10"},
        {"label": "-1", "value": "-1"},
        {"label": "-0.1", "value": "-0.1"},
        {"label": "Market", "value": "market", "width": 2},
        {"label": "+0.1", "value": "0.1"},
        {"label": "+1", "value": "1"},
        {"label": "+10", "value": "10"}
    ],
    "amount-picker-shortcuts": [
        {"label": "K", "value": "+1000"},
        {"label": "M", "value": "+1000000"},
        {"label": "B", "value": "+1000000000"}
    ]
},

CAPLIN.PERMISSION.CONFIG.URL

The CAPLIN.PERMISSION.CONFIG.URL property is required by internal Caplin libraries. Do not edit this property.

This property takes a string as its value.

Example
"CAPLIN.PERMISSION.CONFIG.URL": "unbundled-resources/permissionDatasourceDefinitions.xml",

CURRENCIES

The CURRENCIES property configures the display of currencies in the currency-pair keyboard.

This property takes a single object as its value.

CURRENCIES object
Property Datatype Description

CONFIG

Array of strings

Overrides the natural display order of currency codes in the currency-pair keyboard. Currency codes listed in the CONFIG array are displayed first, in the order in which occur in the CONFIG array, followed by the remaining currency codes in alphabetical order.
Example
"CURRENCIES": {
    "CONFIG": ["USD", "EUR"]
},

DEV

The DEV property includes configuration options for development and testing.

This property takes a single object as its value.

DEV object
Property Data Type Description

USE_CUSTOM_BACKEND

Boolean

Set to true to override the connection details for Liberator held in the J2EE’s web container context. This property provides extra flexibility during development and testing. This property should be set to false in production.

LIBERATOR_ADDRESS

String

If USE_CUSTOM_BACKEND is set to true, LIBERATOR_ADDRESS overrides the LIBERATOR.PRIMARY.ADDRESS environment entry in the J2EE’s web container context.

LIBERATOR_PORT

String

If USE_CUSTOM_BACKEND is set to true, LIBERATOR_PORT overrides the LIBERATOR.PRIMARY.PORT environment entry in the J2EE’s web container context.
Example
"DEV": {
    "USE_CUSTOM_BACKEND": false,
    "LIBERATOR_ADDRESS": "liberator-qa.example.com",
    "LIBERATOR_PORT": "18080"
},

EXPIRATION_PICKER

The EXPIRATION_PICKER property configures the order-expiration date picker.

This property takes a single object as its value.

EXPIRATION_PICKER object
Property Data Type Description

DEFAULT_TIME

Object

The default time-of-day for order expiration when a date other than "good 'til cancelled" (GTC) is selected. See EXPIRATION_PICKER > DEFAULT_TIME object.
EXPIRATION_PICKER > DEFAULT_TIME object
Property Data Type Description

hours

String

Hours (0-11)

minutes

String

Minutes (0-59)

meridiem

String

"AM" or "PM"
Example
"EXPIRATION_PICKER": {
    "DEFAULT_TIME": {
        "hours": "5",
        "minutes": "00",
        "meridiem": "PM"
    }
},

FEATURE_RESET_FIELDS_AFTER_EXECUTION

From: 3.13

Reset the Amount and Tenor fields after submission of a One-Tap, RFQ, or Order ticket.

This property takes a boolean as its value.

Example
"FEATURE_RESET_FIELDS_AFTER_EXECUTION": true,

FEATURE_RESET_ACCOUNT_SELECTOR_AFTER_EXECUTION

From: 3.13

Reset the Account field after submission of a One-Tap, RFQ, or Order ticket.

This property takes a boolean as its value.

Example
"FEATURE_RESET_ACCOUNT_SELECTOR_AFTER_EXECUTION": true,

HIGH_AND_LOWS

The HIGH_AND_LOWS property configures the display of open, close, high and low statistics.

This property takes a single object as its value.

HIGH_AND_LOWS object
Property Data Type Description

SHOW_ON_SPOT

Boolean

Set to true to display open, close, high, and low statistics when the spot tenor has been selected.

SHOW_ON_FORWARD

Boolean

Set to true to display open, close, high, and low statistics when a forward tenor has been selected.

SHOW_CHANGE

Boolean

Set to true to display the difference between the opening price and the prevailing price.

FIELD_ORDER

Array of strings

The order in which open, close, high, and low statistics should be displayed. The fields are laid out in rows, from left to right. Valid values: "Open", "Close", "High", and "Low".
Example
"HIGH_AND_LOWS": {
    "SHOW_ON_SPOT": true,
    "SHOW_ON_FORWARD": false,
    "SHOW_CHANGE": true,
    "FIELD_ORDER": ["Open", "High", "Close", "Low"]
},

INSTRUMENT_DETAILS

The INSTRUMENT_DETAILS property configures the instruments available in FX Mobile.

This property takes a single object as its value.

INSTRUMENT_DETAILS object
Property Data Type Description

ORDER

Object

Configuration of orders. See INSTRUMENT_DETAILS > ORDER object.
INSTRUMENT_DETAILS > ORDER object
Property Data Type Description

ALLOW_UNEVEN_ORDERS

Boolean

Set to true to allow users to submit orders with uneven legs.
Example
"INSTRUMENT_DETAILS": {
    "ORDER": {
      "ALLOW_UNEVEN_ORDERS": false
    }
},

KEYBOARDS

The KEYBOARDS property configures the layout and labels of keys in the keyboards for integer and decimal entry.

This property takes a single object as its value.

KEYBOARDS object
Property Data Type Description

INTEGER

Object

Configuration of the keyboard for integer entry. See KEYBOARDS > INTEGER.

DECIMAL

Object

Configuration of the keyboard for decimal entry. See KEYBOARDS > DECIMAL.
KEYBOARDS > INTEGER object
Property Data Type Description

NB_KEY_PER_LINE

Integer

The number of keys displayed per row.

KEYS

Array of objects

An array of key objects. See KEYBOARDS > INTEGER > KEYS objects.
KEYBOARDS > DECIMAL object
Property Data Type Description

NB_KEY_PER_LINE

Integer

The number of keys displayed per row.

KEYS

Array of objects

An array of key objects. See KEYBOARDS > DECIMAL > KEYS objects.
KEYBOARDS > INTEGER > KEYS objects
Property Data Type Description

label

String

The label to display on the key.

value

String

The value of the key. Valid values: "1", "2", "3", "4", "5", "6", "7", "8", "9", "0", "delete", "clear"
KEYBOARDS > DECIMAL > KEYS objects
Property Data Type Description

label

String

The label to display on the key.

value

String

The value of the key. Valid values: "1", "2", "3", "4", "5", "6", "7", "8", "9", "0", ".", "delete"
Example
"KEYBOARDS": {
    "INTEGER": {
        "NB_KEY_PER_LINE": 3,
        "KEYS": [
            {"label": "1", "value": "1"},
            {"label": "2", "value": "2"},
            {"label": "3", "value": "3"},
            {"label": "4", "value": "4"},
            {"label": "5", "value": "5"},
            {"label": "6", "value": "6"},
            {"label": "7", "value": "7"},
            {"label": "8", "value": "8"},
            {"label": "9", "value": "9"},
            {"label": "0", "value": "0"},
            {"label": "Delete", "value": "delete"},
            {"label": "Clear", "value": "clear"}
        ]
    },
    "DECIMAL": {
        "NB_KEY_PER_LINE": 3,
        "KEYS": [
            {"label": "1", "value": "1"},
            {"label": "2", "value": "2"},
            {"label": "3", "value": "3"},
            {"label": "4", "value": "4"},
            {"label": "5", "value": "5"},
            {"label": "6", "value": "6"},
            {"label": "7", "value": "7"},
            {"label": "8", "value": "8"},
            {"label": "9", "value": "9"},
            {"label": "0", "value": "0"},
            {"label": ".", "value": "."},
            {"label": "Delete", "value": "delete"}
        ]
    }
},

LOGIN

The LOGIN property configures FX Mobile’s login fields.

This property takes a single object as its value.

LOGIN object
Property Data Type Description

USERNAME

Object

Configuration of the username field. See the LOGIN > USERNAME object.

PASSWORD

Object

Configuration of the password field. See the LOGIN > PASSWORD object.
LOGIN > USERNAME object
Property Data Type Description

MIN_LENGTH

Integer

Minimum number of characters accepted by the username field.

MAX_LENGTH

Integer

Maximum number of characters accepted by the username field.
LOGIN > PASSWORD object
Property Data Type Description

MIN_LENGTH

Integer

Minimum number of characters accepted by the password field.

MAX_LENGTH

Integer

Maximum number of characters accepted by the password field.
Example
"LOGIN": {
    "USERNAME": {
        "MIN_LENGTH": 3,
        "MAX_LENGTH": 255
    },
    "PASSWORD": {
        "MIN_LENGTH": 3,
        "MAX_LENGTH": 255
    }
},

From: 3.16

Displays external links in the FX Mobile main menu.

The property takes an array of objects as its value.

MENU_ITEM_EXTERNAL_LINKS object
Property Data Type Description

label

String

Link text. Can take an i18n token.

target

String

A website URL (https://…), an email URL (mailto:…), or a telephone number (tel:…). The value can include the substitution token [username], which is replaced at run time with the logged in user’s username.

modalMessage

String

Optional. If set, it displays the value as a modal dialog with the options to Continue or Cancel. The URL in the target property is only followed if the user taps Continue.
Example
"MENU_ITEM_EXTERNAL_LINKS": [
  {
    "label": "@{mobile.global-nav-menu.external-link.contact}",
    "target": "https://www.example.com/contact-us"
  },
  {
    "label": "@{mobile.global-nav-menu.external-link.feedback}",
    "target": "mailto:email@example.com?subject=FX Mobile Feedback from [userName]",
    "modalMessage": "@{mobile.global-nav-menu.external-link.feedback-message}"
  },
  {
    "label": "Terms",
    "target": "https://www.example.com/terms-and-conditions"
  }
]

NOTIFICATIONS

The NOTIFICATIONS property configures application notifications.

This property takes a single object as its value.

NOTIFICATIONS object
Property Datatype Description

ENABLED

Boolean

Set to true to enable application notifications.
Example
"NOTIFICATIONS": {
    "ENABLED": true
},

ON_APP_LOADED

The ON_APP_LOADED property defines the initial screen to display on opening FX Mobile.

This property takes a single object as its value.

ON_APP_LOADED object
Property Data Type Description

PHONE

Object

Defines the initial screen to show when FX Mobile is loaded on a smartphone. See ON_APP_LOADED > PHONE.
ON_APP_LOADED > PHONE object
Property Data Type Description

BLOTTER_TYPE

String

If the value of ROUTE is a route to a blotter, set BLOTTER_TYPE to the type of the blotter: 'Orders' or 'Trades'.

If the value of ROUTE is 'home' or 'watchlist', the value of BLOTTER_TYPE is ignored and can be set to an empty string.

ROUTE

String

The route of the first screen to display when the application is loaded on a phone. The value must be one of the following:

  • A route to a trade blotter

  • A route to an order blotter

  • home — the route to the smartphone home screen, which provides links to trade blotters, order blotters, and watchlists

  • watchlist — the route to the user’s primary watchlist
Example
"ON_APP_LOADED": {
    "PHONE": {
        "BLOTTER_TYPE": "",
        "ROUTE": "home"
    },
    "TABLET": {
        "BLOTTER_TYPE": "Trades",
        "ROUTE": "trade-blotter"
    }
}

ORDER_RATE_THRESHOLD

The ORDER_RATE_THRESHOLD property defines the minimum permitted difference between the current market rate and the target rate of an order, expressed as a percentage of the market rate. For example, if the market rate is 1 and the ORDER_RATE_THRESHOLD is 5(%), then the target rate must be 0.95 or lower, or 1.05 or higher.

This property takes an integer as its value.

Example
"ORDER_RATE_THRESHOLD" : 5,

PASSWORD_FIELDS

The PASSWORD_FIELDS property configures one-time password (OTP) entry, required for two-factor authentication.

This property takes a single object as its value.

PASSWORD_FIELDS object
Property Datatype Description

NB_TOKEN

Integer

The number of digits in the numeric one-time password (OTP)
Example
"PASSWORD_FIELDS": {
    "NB_TOKEN": 6
},

PIPSCOLOUR

The PIPSCOLOUR property configures the dynamic styling of pips.

This property takes a single object as its value.

PIPSCOLOUR object
Property Data Type Description

FLAT

String

Colour of pips when there is no change in their value. Valid values: "inherit" (standard colour) or a CSS colour.

UP

String

Colour of pips when there is a positive change in their value. Valid values: "inherit" (standard colour) or a CSS colour.

DOWN

String

Colour of pips when there is a negative change in their value. Valid values: "inherit" (standard colour) or a CSS colour.

ENABLE_ON_TABLET

Boolean

Set to true to enable dynamic styling of pips on tablets.

ENABLE_ON_PHONE

Boolean

Set to true to enable dynamic styling of pips on smart phones.
Example
"PIPSCOLOUR": {
    "FLAT": "inherit",
    "UP": "inherit",
    "DOWN": "inherit",
    "ENABLE_ON_TABLET": true,
    "ENABLE_ON_PHONE": true
},

POST_TRADE_ORDER_GENERATOR

The POST_TRADE_ORDER_GENERATOR property configures orders created directly from a trade confirmation message.

This property takes a single object as its value.

POST_TRADE_ORDER_GENERATOR object
Property Data Type Description

TARGET_RATE_POINTS_OFFSET

String

For orders generated from a trade confirmation message, pre-populate the target rate field with a rate TARGET_RATE_POINTS_OFFSET different from the rate at which the trade was made. Valid values: "0" or a positive number.
Example
"POST_TRADE_ORDER_GENERATOR": {
    "TARGET_RATE_POINTS_OFFSET": "100"
}

RADIO_BUTTONS

The RADIO_BUTTONS property configures the radio buttons on the activation and expiration pickers.

This property takes a single object as its value.

BUTTONS_GROUP object
Property Data Type Description

activation

Array of objects

Configuration of the radio buttons displayed on the activation picker. See BUTTONS_GROUP > activation objects.

expiration

Array of objects

Configuration of the radio buttons displayed on the expiration picker. See BUTTONS_GROUP > expiration objects.
BUTTONS_GROUP > activation objects
Property Data Type Description

label

String

Radio button label

value

String

Radio button value. Only one valid value: "gfa".
BUTTONS_GROUP > expiration objects
Property Data Type Description

label

Array of objects

Radio button label

value

Array of objects

Radio button value. Only one valid value: "gtc"
Example
"RADIO_BUTTONS": {
    "activation": [
        {
            "label": "GFA",
            "value": "gfa"
        }
    ],
    "expiration": [
        {
            "label": "GTC",
            "value": "gtc"
        }
    ]
},

TIMEZONE

The TIMEZONE property defines the market’s time zone. This property must be manually adjusted for daylight savings time.

This property takes a single object as its value.

TIMEZONE object
Property Data Type Description

OFFSET

String

The time zone’s offset in hours from coordinated universal time (UTC). Example values: "0", "1", and "-1".

LABEL

String

The time zone’s abbreviation. Example values: "GMT", and "BST".
Example
"TIMEZONE" : {
    "OFFSET": "1",
    "LABEL": "BST"
},

WATCHLISTS

The WATCHLISTS property includes configuration options for new and default watchlists.

This property takes a single object as its value.

WATCHLISTS object
Property Datatype Description

DEFAULT_TAB

String

The default tab to display when a currency pair is selected in a watchlist. Valid values are: "overview", "trade", and "order".

DEFAULT_WATCHLISTS

Array of objects

Pre-configured watchlists available to all users. Each object in the array represents a watchlist specification.

See WATCHLISTS > DEFAULT_WATCHLISTS in this section.

NEW_WATCHLIST_NAME

String

The default name for new watchlists.

MAX_INSTRUMENTS

Integer

The maximum number of financial instruments a watchlist can hold.
WATCHLISTS > DEFAULT_WATCHLISTS objects
Property Datatype Description

name

String

The name of the watchlist. If the user already has a watchlist of the same name, the user’s watchlist definition takes precedence.

instruments

Array of strings

An array of financial instrument codes, in the order in which they should be displayed.
Example
"WATCHLISTS": {
    "DEFAULT_TAB": "overview",
    "DEFAULT_WATCHLISTS": [
        {
            "name": "Majors",
            "instruments": [
                "EURUSD",
                "USDJPY",
                "GBPUSD",
                "USDCHF",
                "EURGBP",
                "EURJPY",
                "EURCHF",
                "AUDUSD",
                "USDCAD",
                "NZDUSD"
            ]
        },
        {
            "name": "Minors",
            "instruments": [
                "CADMXN",
                "EURISK",
                "EURLTL",
                "EURRON",
                "EURZAR",
                "MXNJPY"
            ]
        }
    ],
    "NEW_WATCHLIST_NAME": "New Watchlist",
    "MAX_INSTRUMENTS": 20
},