Importing Data
==============

FTJ supports importing trade history from CSV and XLSX files. This is the fastest way to
get started if you already have trade data from your broker.

You can access the import function from:

- **Settings → Import Data**

.. TODO: Confirm the exact menu path(s) for triggering an import.


Supported Formats
-----------------

FTJ can import from two types of sources:

1. **cTrader Export** - The native XLSX export from the cTrader platform. FTJ auto-detects
   column mappings for cTrader's format.
2. **Custom CSV / XLSX** - Any CSV or XLSX file with a header row. You define the column
   mappings yourself.



Importing from cTrader (XLSX)
----------------------------

FTJ currently supports the cTrader XLSX export.

1. In cTrader, export your trade history / statement as XLSX.
2. In FTJ, open the Import dialog and choose **cTrader** as the template.
3. Select the exported XLSX file.
4. FTJ maps the columns automatically.



   .. list-table::
      :widths: 35 25 40
      :header-rows: 1

      * - cTrader Column
        - FTJ Field
        - Notes
      * - Symbol
        - Instrument
        - **Required.**
      * - Opening direction
        - Direction
        - **Required.** Buy/B mapped to Long, Sell/S mapped to Short.
      * - Opening time
        - Entry Date
        - **Required.**
      * - Entry price
        - Entry Price
        - **Required.**
      * - Closing Quantity
        - Lots
        - **Required** (at least one of Lots or Quantity).
      * - Closing volume
        - Quantity (units)
        - Optional. If both Lots and Quantity are present, FTJ derives the contract size.
      * - Closing time
        - Exit Date
        - Optional. If missing, trade is imported as open.
      * - Closing price
        - Exit Price
        - Optional. If missing, trade is imported as open.
      * - Commission
        - Fees
        - Optional. Forced positive via absolute value.
      * - Swap
        - Swap
        - Optional. Positive = credit, negative = debit.
      * - ID
        - External ID
        - Optional. Used for duplicate detection.
      * - Gross P/L *(currency)*
        - Gross P&L
        - Auto-detected from header. See below.
      * - Net P/L *(currency)*
        - Net P&L
        - Auto-detected from header. See below.

1. **P&L auto-detection** - cTrader P&L headers include a currency marker (e.g.
   ``Gross P/L (EUR)`` or ``Net P/L €``). FTJ prefers the header matching your account's
   base currency and ignores mismatched ones. If no P&L columns are found, FTJ calculates
   P&L from entry/exit prices and quantity.
2. **Currency detection** - FTJ reads currency codes and symbols from column headers
   (e.g. ``Balance €``) to identify the account currency.
3. FTJ handles date parsing (``dd/MM/yyyy HH:mm:ss.fff`` format, with comma-millisecond
   variant also supported).
4. Review the import summary and click **Import**.

.. note::
   Fees and swap values from cTrader are treated as being in the account's base (deposit)
   currency, not in the instrument's quote currency.

   If cTrader changes or removes XLSX export support in a future version, this import
   method may need to be updated.


Importing Custom CSV / XLSX
--------------------------

For CSV or XLSX files from other brokers or custom formats:

1. Select **Custom** as the template.
2. A **Custom Mapping Dialog** appears, showing the columns detected in your file.

   .. image:: /_static/card_custom.png
      :alt: Custom Mapping Dialog
      :align: left
      :height: 350 px

.. raw:: html

   <div style="clear: both;"></div>

3. Map each required FTJ field to the corresponding column in your file:

   **Required fields:**

   - **Symbol** - The instrument identifier.
   - **Direction** - Long/Short (or Buy/Sell - FTJ will prompt for a direction mapping).
   - **EntryDate** - The entry date/time.
   - **EntryPrice** - The entry price.
   - **Quantity** or **Lots** - The position size.

   **Optional fields:**

   - **ExitDate** - The exit date/time.
   - **ExitPrice** - The exit price.
   - **Fees** - Commissions.
   - **Swap** - Overnight charges.
   - **GrossPL** / **NetPL** - Pre-computed P&L values.

4. Set the **Delimiter** (comma ``,``, semicolon ``;``, tab, etc.).
5. Set the **Date Format** (e.g. ``yyyy-MM-dd HH:mm:ss``). If left blank, FTJ will attempt
   to auto-detect the format from the first few data rows.
6. Click **Import**.

Direction Mapping
~~~~~~~~~~~~~~~~~

If your CSV uses direction labels that FTJ doesn't recognize (e.g. "B"/"S" instead of
"Long"/"Short"), FTJ will prompt you to map each unique direction value to either Long or Short.



Import Results
--------------

After import, FTJ shows a summary:

- **Added** - Number of new trades successfully imported.
- **Skipped** - Number of trades that were skipped (duplicates or invalid data).
- **Errors** - Any issues encountered during import, with details.

A detailed import log file is generated in the database folder. Check this log
if you see unexpected skips or errors.


Account Assignment
------------------

When importing, trades are assigned to the currently selected account. Make sure you've selected
the correct account before starting the import.


Tips for Clean Imports
----------------------

- **Remove summary rows** - Some brokers add total/summary rows at the bottom of exports. Remove
  these before importing, as FTJ will try to parse them as trades.
- **Consistent date formats** - Make sure all dates in the file use the same format.
- **One file per account** - If you have exports from multiple accounts, import them separately
  with the correct account selected.
- **Encoding** - FTJ auto-detects file encoding, but if you see garbled characters, try saving
  the file as UTF-8 before importing.
- **Check exchange rates after import** - Navigate to the Rates view and use **Fetch Rates** to
  ensure all imported trades have the necessary currency conversion rates.