# Trade model: OrderSubmission

This page describes the FX Integration API's **OrderSubmission** trade model, as defined in the file `config/TradingAdapter/Blade/DataSource/etc/trademodels.xml` in the FX Integration API Kit.

This documentation is for the FX Integration API 12.10.0.

Trade models are XML-defined state machines used by the [Java Trading API](https://docs.caplin.com/developer/api/trading_java/latest/) and Caplin Trader's [Trading API](../caplin-trader/4/trading-api/index.md) to manage trading workflows. For more information on trade model XML definitions, see the [Trade model XML schema](../caplin-platform/cis/cis-trade-model-schema.md) reference.

## State model

The OrderSubmission trade model's state model in Mermaid JS format:

```mermaid
%% State diagram for the OrderSubmission trade model
stateDiagram-v2
    [*] --> Initial
    Initial --> Submitted : Submit (client)
    Initial --> Error : Error (server)
    Submitted --> Error : Error (server)
    Submitted --> Queued : SubmitAck (server)
    Submitted --> WarningSent : Warning (server)
    Error --> [*] 
    Queued --> PendingAccept : Accepting (server)
    Queued --> Accepted : Accept (server)
    Queued --> Error : Error (server)
    PendingAccept --> Accepted : Accept (server)
    PendingAccept --> Error : Error (server)
    Accepted --> [*] 
    WarningSent --> Error : Error (server)
    WarningSent --> AcceptWarningSent : AcceptWarning (client)
    WarningSent --> ClientCloseSent : ClientClose (client)
    AcceptWarningSent --> Error : Error (server)
    AcceptWarningSent --> Queued : AcceptWarningAck (server)
    ClientCloseSent --> ClientClosed : ClientCloseAck (server)
    ClientClosed --> [*] 
```

The OrderSubmission trade model's state model in a flat state-transition matrix:

| Source state | Event trigger | Origin | Target state |
| ------------ | ------------- | ------ | ------------ |
| [*] | - | - | Initial |
| Initial | Submit | client | Submitted |
| Initial | Error | server | Error |
| Submitted | Error | server | Error |
| Submitted | SubmitAck | server | Queued |
| Submitted | Warning | server | WarningSent |
| Error | - | - | [*] |
| Queued | Accepting | server | PendingAccept |
| Queued | Accept | server | Accepted |
| Queued | Error | server | Error |
| PendingAccept | Accept | server | Accepted |
| PendingAccept | Error | server | Error |
| Accepted | - | - | [*] |
| WarningSent | Error | server | Error |
| WarningSent | AcceptWarning | client | AcceptWarningSent |
| WarningSent | ClientClose | client | ClientCloseSent |
| AcceptWarningSent | Error | server | Error |
| AcceptWarningSent | AcceptWarningAck | server | Queued |
| ClientCloseSent | ClientCloseAck | server | ClientClosed |
| ClientClosed | - | - | [*] |

## Event message specifications

This section describes the messages sent between client and server when a state-model event occurs. The origin of an event (the client or the server) is specified in brackets after the name of the event.

The specification of some events depends on the type of financial product being traded, and when this applies, the variant specifications are detailed under level-4 headings.

Back-end developers build server events by using classes in the Caplin's FX Integration API, a Java library that makes it easy to provide data to Caplin's web applications. Where appropriate, the specifications below include references to JavaDoc documentation and code examples.

### Event: AcceptWarning (client)

Message specification:

```json
{
  "trade_model_name": "OrderSubmission",
  "trade_model_trigger": "AcceptWarning",
  "message_origin": "client",
  "fields": [
    {
      "name": "MsgType",
      "type": "String",
      "flags": "",
      "definition": "Name of the transition",
      "example_value": "AcceptWarning",
      "deprecated": false
    },
    {
      "name": "RequestID",
      "type": "String",
      "flags": "",
      "definition": "The RequestID. A Unique identifier, must remain the same for each event in the trade model",
      "example_value": "",
      "deprecated": false
    }
  ]
}
```

### Event: ClientClose (client)

Message specification:

```json
{
  "trade_model_name": "OrderSubmission",
  "trade_model_trigger": "ClientClose",
  "message_origin": "client",
  "fields": [
    {
      "name": "MsgType",
      "type": "String",
      "flags": "",
      "definition": "Name of the transition",
      "example_value": "ClientClose",
      "deprecated": false
    },
    {
      "name": "RequestID",
      "type": "String",
      "flags": "",
      "definition": "The RequestID. A Unique identifier, must remain the same for each event in the trade model",
      "example_value": "",
      "deprecated": false
    }
  ]
}
```

### Event: Submit (client)

Message specification:

```json
{
  "trade_model_name": "OrderSubmission",
  "trade_model_trigger": "Submit",
  "message_origin": "client",
  "parts": [
    {
      "part_name": "OrderDetails",
      "parts": [
        {
          "part_name": "LegDetails",
          "fields": [
            {
              "name": "Ln_OrderID",
              "type": "string",
              "flags": "",
              "definition": "The id of the order.",
              "example_value": "000012345",
              "deprecated": false
            },
            {
              "name": "Ln_Amount",
              "type": "decimal",
              "flags": "",
              "definition": "The amount of a trade or order in the DealtCurrency.",
              "example_value": "",
              "deprecated": false
            },
            {
              "name": "Ln_MonitorSide",
              "type": "string",
              "flags": "",
              "definition": "The side that should be monitored for an order to be triggered.",
              "example_value": "",
              "deprecated": false
            },
            {
              "name": "Ln_DealtCurrency",
              "type": "string",
              "flags": "",
              "definition": "The currency of the Amount of a trade or order.",
              "example_value": "GBP",
              "deprecated": false
            },
            {
              "name": "Ln_BuySell",
              "type": "string",
              "flags": "",
              "definition": "The direction of the trade or trade leg, from the client's perspective. This always refers to the BaseCurrency, NOT the DealtCurrency.",
              "example_value": "",
              "deprecated": false
            },
            {
              "name": "Ln_ExecutionType",
              "type": "string",
              "flags": "",
              "definition": "The order type. Caplin supported types are [BENCHMARK, CALL-ORDER, MARKET, PEGGED, STOP-LOSS, TAKE-PROFIT]",
              "example_value": "",
              "deprecated": false
            },
            {
              "name": "Ln_BenchmarkType",
              "type": "string",
              "flags": "",
              "definition": "The benchmark order name. For example, ECB.",
              "example_value": "",
              "deprecated": false
            },
            {
              "name": "Ln_BenchmarkDate",
              "type": "date",
              "flags": "",
              "definition": "The fixing date of the benchmark in ISO-8601 format",
              "example_value": "",
              "deprecated": false
            },
            {
              "name": "Ln_BenchmarkTime",
              "type": "time",
              "flags": "",
              "definition": "The fixing time of the benchmark in ISO-8601 format",
              "example_value": "18:00",
              "deprecated": false
            },
            {
              "name": "Ln_BenchmarkTimeZone",
              "type": "timezone",
              "flags": "",
              "definition": "The TZ format timezone for the provided time and date",
              "example_value": "Europe/London",
              "deprecated": false
            },
            {
              "name": "Ln_LimitPrice",
              "type": "decimal",
              "flags": "",
              "definition": "The price at which a leg should fill.",
              "example_value": "",
              "deprecated": false
            },
            {
              "name": "Ln_Margin",
              "type": "decimal",
              "flags": "",
              "definition": "The amount of margin",
              "example_value": "",
              "deprecated": false
            },
            {
              "name": "Ln_Remarks",
              "type": "string",
              "flags": "",
              "definition": "The text content of a comment left on a leg of a trade or order, visible to Client and sales and possibly the trader, set/edited by Client or sales",
              "example_value": "",
              "deprecated": false
            },
            {
              "name": "Ln_TraderRemarks",
              "type": "string",
              "flags": "",
              "definition": "The sale's comments on an order leg - visible to only the Trader and sales, set/edited only by the sales",
              "example_value": "",
              "deprecated": false
            },
            {
              "name": "Ln_ChildLegId",
              "type": "integer",
              "flags": "",
              "definition": "The id of the child leg, if the order has a child leg",
              "example_value": "1",
              "deprecated": false
            },
            {
              "name": "Ln_ChildRelationship",
              "type": "string",
              "flags": "",
              "definition": "Describes the relationship with the child if it exists.",
              "example_value": "IF-DONE",
              "deprecated": false
            },
            {
              "name": "Ln_PartnerLegId",
              "type": "integer",
              "flags": "",
              "definition": "The id of the partner leg, if the order has a partner leg",
              "example_value": "1",
              "deprecated": false
            },
            {
              "name": "Ln_PartnerRelationship",
              "type": "string",
              "flags": "",
              "definition": "Describes the relationship with the partner leg if it exists.",
              "example_value": "OCO",
              "deprecated": false
            },
            {
              "name": "Ln_LoopLegId",
              "type": "integer",
              "flags": "",
              "definition": "The leg to loop back to upon completion.",
              "example_value": "1",
              "deprecated": false
            },
            {
              "name": "Ln_AllowPartialFill",
              "type": "boolean",
              "flags": "",
              "definition": "Indicates whether the order leg can be partially filled",
              "example_value": "",
              "deprecated": false
            },
            {
              "name": "Ln_FillMode",
              "type": "",
              "flags": "",
              "definition": "The permitted fill types for this leg, e.g. ANY, MANUAL or AUTO",
              "example_value": "",
              "deprecated": false
            },
            {
              "name": "Ln_Trigger",
              "type": "string",
              "flags": "",
              "definition": "The trigger type for the order",
              "example_value": "",
              "deprecated": false
            },
            {
              "name": "Ln_FillRate",
              "type": "string",
              "flags": "",
              "definition": "",
              "example_value": "",
              "deprecated": true
            },
            {
              "name": "Ln_Discretion",
              "type": "decimal",
              "flags": "",
              "definition": "Number of points the trader has discretion to fill the order",
              "example_value": "",
              "deprecated": false
            },
            {
              "name": "Ln_OrderTenor",
              "type": "string",
              "flags": "",
              "definition": "The tenor the order will settle on for Forward and NDF orders. Either OrderTenor or OrderSettlementDate should be provided but not both.",
              "example_value": "",
              "deprecated": false
            },
            {
              "name": "Ln_OrderSettlementDate",
              "type": "date",
              "flags": "",
              "definition": "The settlement date the order will settle on for Forward and NDF orders. Either OrderTenor or OrderSettlementDate should be provided but not both.",
              "example_value": "",
              "deprecated": false
            },
            {
              "name": "Ln_OrderFixingDate",
              "type": "date",
              "flags": "",
              "definition": "The date an NDF order will fix on if filled.",
              "example_value": "",
              "deprecated": false
            }
          ]
        }
      ],
      "fields": [
        {
          "name": "CurrencyPair",
          "type": "string",
          "flags": "",
          "definition": "The currency pair for the trade. For example, EURUSD",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "Account",
          "type": "string",
          "flags": "",
          "definition": "The account a trade or order has been submitted against. The format is <description>|<name> or <name>|<name>",
          "example_value": "Garfields|GARF",
          "deprecated": false
        },
        {
          "name": "ActivationType",
          "type": "string",
          "flags": "",
          "definition": "How the order should be activated. Caplin supported statuses are [GFA, EXPLICIT]",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "ActivationDateTime",
          "type": "datetime",
          "flags": "",
          "definition": "The time and date the order will become active. This is in ISO-8601 format.",
          "example_value": "2013-07-24T17:13:59.985",
          "deprecated": false
        },
        {
          "name": "ActivationDisplayTimeZone",
          "type": "timezone",
          "flags": "",
          "definition": "The timezone that the activation time and date should be formatted to for display. This is in the TZ database format.",
          "example_value": "Europe/London",
          "deprecated": false
        },
        {
          "name": "ExpirationType",
          "type": "string",
          "flags": "",
          "definition": "How the order should be deactivated. Caplin supported statuses are [IOC, GTC, GFD, FOK, EXPLICIT]",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "ExpirationDateTime",
          "type": "datetime",
          "flags": "",
          "definition": "The time and date the order will be deactivated. This is in ISO-8601 format.",
          "example_value": "2013-07-24T17:13:59.985",
          "deprecated": false
        },
        {
          "name": "ExpirationDisplayTimeZone",
          "type": "timezone",
          "flags": "",
          "definition": "The timezone that the expiration time and date should be formatted to for display. This is in the TZ database format.",
          "example_value": "Europe/London",
          "deprecated": false
        },
        {
          "name": "AlertType",
          "type": "string",
          "flags": "",
          "definition": "The type of alert that an order will send. Caplin supported statuses are [EMAIL, SMS].",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "EntityId",
          "type": "string",
          "flags": "",
          "definition": "The entity the trade is on behalf of. For example, if the logged in user user1@customer.co.za wishes to make a trade on behalf of entity CUSTONE, then the value of this field will be CUSTONE. If this field is absent on a leg then the default entity should be presumed.",
          "example_value": "CUSTONE",
          "deprecated": false
        },
        {
          "name": "TOBOUser",
          "type": "string",
          "flags": "",
          "definition": "The user the trade is on behalf of. For example, if the logged in user dealer1@novobank.co.za wishes to make a trade on behalf of user client@customer.co.za, then the value of this field will be client@customer.co.za.",
          "example_value": "client@customer.co.za",
          "deprecated": false
        },
        {
          "name": "StrategyType",
          "type": "string",
          "flags": "",
          "definition": "The strategy the order was submitted with. This field should not be used by the front end for structuring orders. Comma separated list of Caplin supported values are [SINGLE, IF-DONE-OCO, OCO, IF-DONE, IF-TIMEOUT, IF-DONE-LOOP, LOOP]. OTHER denotes a strategy type that is unsupported.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "AppID",
          "type": "",
          "flags": "",
          "definition": "A unique identifier for the client application",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "AlertPhoneNumber1",
          "type": "string",
          "flags": "",
          "definition": "Phone number that should be called when an order event occurs",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "AlertPhoneNumber2",
          "type": "string",
          "flags": "",
          "definition": "Phone number that should be called when an order event occurs",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "AlertPhoneNumber3",
          "type": "string",
          "flags": "",
          "definition": "Phone number that should be called when an order event occurs",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "AlertPhoneNumber4",
          "type": "string",
          "flags": "",
          "definition": "Phone number that should be called when an order event occurs",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "AlertPhoneNumber5",
          "type": "string",
          "flags": "",
          "definition": "Phone number that should be called when an order event occurs",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "AlertPhoneNumber6",
          "type": "string",
          "flags": "",
          "definition": "Phone number that should be called when an order event occurs",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "AlertPhoneNumber7",
          "type": "string",
          "flags": "",
          "definition": "Phone number that should be called when an order event occurs",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "AlertPhoneNumber8",
          "type": "string",
          "flags": "",
          "definition": "Phone number that should be called when an order event occurs",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "AlertPhoneNumber9",
          "type": "string",
          "flags": "",
          "definition": "Phone number that should be called when an order event occurs",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "AlertPhoneNumber10",
          "type": "string",
          "flags": "",
          "definition": "Phone number that should be called when an order event occurs",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "AlertEmailAddress1",
          "type": "string",
          "flags": "",
          "definition": "Email address that should be mailed when an order event occurs",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "AlertEmailAddress2",
          "type": "string",
          "flags": "",
          "definition": "Email address that should be mailed when an order event occurs",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "AlertEmailAddress3",
          "type": "string",
          "flags": "",
          "definition": "Email address that should be mailed when an order event occurs",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "AlertEmailAddress4",
          "type": "string",
          "flags": "",
          "definition": "Email address that should be mailed when an order event occurs",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "AlertEmailAddress5",
          "type": "string",
          "flags": "",
          "definition": "Email address that should be mailed when an order event occurs",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "AlertEmailAddress6",
          "type": "string",
          "flags": "",
          "definition": "Email address that should be mailed when an order event occurs",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "AlertEmailAddress7",
          "type": "string",
          "flags": "",
          "definition": "Email address that should be mailed when an order event occurs",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "AlertEmailAddress8",
          "type": "string",
          "flags": "",
          "definition": "Email address that should be mailed when an order event occurs",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "AlertEmailAddress9",
          "type": "string",
          "flags": "",
          "definition": "Email address that should be mailed when an order event occurs",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "AlertEmailAddress10",
          "type": "string",
          "flags": "",
          "definition": "Email address that should be mailed when an order event occurs",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "FixingSource",
          "type": "string",
          "flags": "",
          "definition": "Specifies where the fixing rate comes from.",
          "example_value": "WMR 8am London Time",
          "deprecated": false
        },
        {
          "name": "SettlementCurrency",
          "type": "string",
          "flags": "",
          "definition": "A currency for of settlement instruction",
          "example_value": "GBP",
          "deprecated": false
        },
        {
          "name": "Duration",
          "type": "",
          "flags": "",
          "definition": "The duration of the TWAP strategy in ISO-8601 format, e.g. PT5M",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "NumberOfSlices",
          "type": "",
          "flags": "",
          "definition": "The number of slices the strategy should release over its lifetime",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "SliceAmountVariance",
          "type": "",
          "flags": "",
          "definition": "The allowed variance of each slice. For example, an amount of 10,000 over 2 slices with a variance of 0.5 (50%) means the slice sizes will be in the range 2,500 to 7,500 (10,000/2 * (1 ± 0.5))",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "ActivationDate",
          "type": "string",
          "flags": "",
          "definition": "What date the strategy should be activated.",
          "example_value": "",
          "deprecated": true
        },
        {
          "name": "ActivationTime",
          "type": "string",
          "flags": "",
          "definition": "What time the strategy should be activated if the ActivationDate was in the format of yyyymmdd.",
          "example_value": "",
          "deprecated": true
        },
        {
          "name": "ActivationLocation",
          "type": "string",
          "flags": "",
          "definition": "When location should be used to evaluate the time to activate if the ActivationDate was in the format of yyyymmdd.",
          "example_value": "Europe/London",
          "deprecated": true
        },
        {
          "name": "ActivationUTCOffset",
          "type": "string",
          "flags": "",
          "definition": "",
          "example_value": "",
          "deprecated": true
        },
        {
          "name": "ExpirationDate",
          "type": "string",
          "flags": "",
          "definition": "What date the strategy should expire.",
          "example_value": "",
          "deprecated": true
        },
        {
          "name": "ExpirationTime",
          "type": "string",
          "flags": "",
          "definition": "What time the strategy should be activated if the ExpirationDate was in the format of yyyymmdd.",
          "example_value": "",
          "deprecated": true
        },
        {
          "name": "ExpirationLocation",
          "type": "string",
          "flags": "",
          "definition": "When location should be used to evaluate the time to expire if the ExpirationDate was in the format of yyyymmdd.",
          "example_value": "",
          "deprecated": true
        },
        {
          "name": "ExpirationUTCOffset",
          "type": "string",
          "flags": "",
          "definition": "",
          "example_value": "",
          "deprecated": true
        }
      ]
    }
  ],
  "fields": [
    {
      "name": "MsgType",
      "type": "String",
      "flags": "",
      "definition": "Name of the transition",
      "example_value": "Submit",
      "deprecated": false
    },
    {
      "name": "RequestID",
      "type": "String",
      "flags": "",
      "definition": "The RequestID. A Unique identifier, must remain the same for each event in the trade model",
      "example_value": "",
      "deprecated": false
    },
    {
      "name": "TradingSubProtocol",
      "type": "string",
      "flags": "",
      "definition": "This field is used to indicate to the back end that the user is requesting a trade with Sales functionality.",
      "example_value": "SALES_RFS",
      "deprecated": false
    }
  ]
}
```

The Submit message includes strategy fields and one or more leg fields. Each leg field is prefixed with the leg number, in the format 'L__n___', where '__n__' is the leg number.

The number of legs in a Submit message depends on the value of the `StrategyType` field:

| StrategyType | L1_*      | L2_*      | L3_*      | Notes |
|--------------|-----------|-----------|-----------|-------|
| SINGLE       | Required  | -         | -         | Leg 1 can be a take-profit, stop-loss, or call order. |
| OCO          | Required  | Required  |           | One leg must be a take-profit order and the other leg must be a stop-loss order. |
| IF-DONE      | Required  | Required  | -         | Leg 1 is the parent order and leg 2 is the child order. Leg 1 can be a take-profit order or a stop-loss order. Leg 2 can be a take-profit order or a stop-loss order. |
| IF-DONE-OCO  | Required  | Required  | Required  | The OCO component (leg 1 and leg 2) must comprise a take-profit order and a stop-loss order. Leg 1 and leg 2 cannot be of the same type. |


### Event: Accepting (server)

Message specification:

```json
{
  "trade_model_name": "OrderSubmission",
  "trade_model_trigger": "Accepting",
  "message_origin": "server"
}
```

### Event: AcceptWarningAck (server)

Message specification:

```json
{
  "trade_model_name": "OrderSubmission",
  "trade_model_trigger": "AcceptWarningAck",
  "message_origin": "server"
}
```

### Event: ClientCloseAck (server)

Message specification:

```json
{
  "trade_model_name": "OrderSubmission",
  "trade_model_trigger": "ClientCloseAck",
  "message_origin": "server"
}
```

### Event: Error (server)

Message specification:

```json
{
  "trade_model_name": "OrderSubmission",
  "trade_model_trigger": "Error",
  "message_origin": "server"
}
```

### Event: SubmitAck (server)

Message specification:

```json
{
  "trade_model_name": "OrderSubmission",
  "trade_model_trigger": "SubmitAck",
  "message_origin": "server"
}
```