File reference

Scenario file syntax reference.

A scenario file is a nested object structure that defines:

  • The name of the scenario
  • The scenario's description (a short bit of text displayed next to the scenario name when the mg scenarios command is used)
  • The services that should be started, and their configuration options.

Scenario files may be written in either JSON or YAML format. The examples on this page are given in YAML format.

Structure

Here is an example scenario file that shows how to configure the matching engine and some peripheral services.

name: equities_test
description: Equities example scenario
package: demo
import_processes_from:
    - ../template-1
    - ../template-2
services:
    # Core matching engine
    matching_engine:
        process: te_engine
        options:
            load: datasets/demo/equities_test_data
                Account: 1000
                Broadcast: 1000000
                Enterprise: 100
                Firm: 100
                Holding: 50000
                Holding_change: 100000
                Level1_change: 100000
                HoldingTransaction: 1000
                Industry: 100
                Instrument: 100
                InstrumentGroup: 10
                InstrumentMarket: 6
                Market: 10
                Order: 10000
                RFQ: 1000
                ScheduledTransactions: 1000
                Sector: 100
                Trade: 20000
                User: 100
                Blotter: 1
                GroupUser: 10000
                Position: 1
                TableCache: 200000
                TransactionLog: 10000
                BlobObject: 1000
                BlobObject_change: 10000

    # API services
    transaction_server:
        process: te_tserver
    snapshot_server:
        process: te_snapshots
        options:
            type: OrderBook

    # UI services
    ui_server:
        process: ui_server
    nginx:
        process: nginx
        options:
            branding: demo.default

The order of the keys is not material. The rest of this page describes each configuration key.

Reference

name

This is the name of the scenario. The scenario name is given to the mg start command when starting up the MarketGrid container. It must consist of a single word (underscores are allowed) and it should describe the function of the scenario: for example, prod_main or prod_backup.

description

The description of the scenario is printed when listing scenarios using the mg scenarios command. It is a free text field which can be used to annotate the scenario.

services

A dictionary which describes the services to run when starting the scenario. Each service is an instance of a process template.

process (required)

The process of which this service is an instance. Refer to the process reference for the list of available processes within MarketGrid. This key is required.

options (optional)

A dictionary of configuration options to pass to the service. For available options, refer to the reference page for the process.

Overriding options

Service options are applied in three ways, in increasing order of priority:

  • From the service definition;
  • From command-line options;
  • From environment variables.

This allows scenarios to be effectively parameterised.

To pass an option to a service using the command line, specify the option in the form --service.option value, where service is a key in the services dictionary of the scenario, option is a valid option name for that process, and value is a valid value for that option. The service name and option name must be separated by a full stop.

To pass an option to a service using an environment variable, specify the variable name using the form MG_SERVICE__OPTION, where SERVICE is a key in the services dictionary of the scenario given in uppercase, and OPTION is a valid option name for that process given in a case-insensitive way. The service name and option name must be separated by two underscores.

Note that mg start will fail if any invalid options are passed on the command line, but invalid options given in environment variables will be ignored.

env (optional)

A dictionary of environment variables that will be set when invoking this service.

package (optional)

The name of the package which may contain bespoke MDB code or processes, for example alerts or reports. If no package is provided, the default is demo.

← Engine Data Migration