# Developing with FX Professional

You have the option of taking a source code release of FX Professional, which allows you to customise and extend FX Professional. This page provides an overview of how to get started.

We encourage extending Caplin source code rather than changing it. Changing core Caplin source code can make taking future upgrades more difficult.

Caplin offers training on FX Professional and can offer advice on how to customise it safely. To learn more, contact your Caplin account manager.

## Requirements

Source code:

* The source zip for FX Professional, available from the [Caplin downloads page](https://account.caplin.com/account/downloads/).

Network access:

* Network access to GitHub
* Network access to the npm registry

Build dependencies:

**FX Professional’s build requirements**

| FX Professional | Node.js | Pnpm | Yarn | OpenJDK |
| --- | --- | --- | --- | --- |
| 6.0+ | 20 | 10.28.0 | - | 11, 17 |
| 5.5–5.17 | 20 | 8 | - | 11, 17 |
| 5.3–5.4 | 20 | 8 | - | 11 |
| 5.0–5.2 | 18 | 8 | - | 11 |
| 4.3 | 18 | 8 | - | 11 |
| 4.0–4.2 | 16 | 8 | - | 11 |
| 3.0–3.40 | 14 | - | 14 | 11 |

A working Caplin Platform stack, connected to your backend systems, composed of:

**FX Professional’s Caplin Platform stack**

* [Deployment Framework](../caplin-platform/deployment-framework/index.md)
* [Liberator](../caplin-platform/liberator/index.md), with the following blades activated:
  * Auth module: TokenAuth (required for [User Config](../fx-integration-api/fxapi-user-config.md) permissioning) _or_ Caplin Permissioning Service
  * BlotterExport
* [Transformer](../caplin-platform/transformer/index.md), with the following modules:
  * [Persistence Service](../caplin-platform/transformer/transformer-activating-the-persistence-service-7.md)
  * [Persistence Service Client](../caplin-platform/transformer/transformer-activating-the-persistence-service-7.md)
  * [Refiner](../caplin-platform/transformer/transformer-deploy-the-refiner-service-module.md)
  * [Charting Service](../caplin-platform/transformer/transformer-setting-up-the-charting-blade.md) (if your FX Professional variant includes charting).
  * [Watchlist Service](../caplin-platform/transformer/configure-transformer-to-host-synchronised-watchlists.md) (if your FX Professional includes watchlists).
  * [Alerts Service](../caplin-platform/transformer/transformer-installing-the-alerts-service.md) (if your FX Professional includes notifications).
  * FieldMapper module (if your FX Professional includes post-trade allocations).
  * Any other modules specific to your deployment, as advised by Caplin.
* Integration adapters specific to your deployment, as advised by Caplin.

## Preparing for development

There are a couple of things you need to decide on for this project:

* Where to store the project’s Java dependencies.
* A Git branching strategy that makes taking future source code releases easier.

### Storing dependencies

Before you start customising FX Professional, decide where you’re going to store this project’s Java module dependencies, as listed in the file `fxpro/apps/fxtrader/server/java/dependencies.gradle`.

The FX Professional source zip includes Java dependencies required by the local development server. You have two options:

* (Recommended) Import the Java dependencies into a Maven compatible repository, such as Artifactory.
* Continue to store the Java dependencies with your project and commit them to Git

### Branching strategy

It’s important to decide on a branching strategy early on in the project to make taking upgrades to FX Professional easier. An example of a simple branching strategy follows, which uses a `caplin` branch to track changes between Caplin source code releases and merge them into an integration branch, `develop`.

![branchingstrategypro](../images/branchingstrategypro.png)

To set up this example branching strategy, follow the steps below:

1. Create a new directory to host your project.
2. Extract the FX Professional source ZIP to the project directory.
3. Initialize the git repository:

   ```console
   $ git init
   ```
4. Add all files to the staging area:

   ```console
   $ git add --all
   ```
5. Execute the initial commit:

   ```console
   $ git commit -m "Initial commit"
   ```
6. Tag the commit to record the version of the Caplin source code release:

   ```console
   $ git tag caplin-fxpro-3.0.0
   ```
7. Create an integration branch (`develop`) and a branch to track Caplin source code releases (`caplin`):

   ```console
   $ git branch develop
   $ git branch caplin
   ```

When a new version of FX Professional is released:

1. Checkout the `caplin` branch:

   ```console
   $ git checkout caplin
   ```
2. Delete all files in the `caplin` branch:

   ```console
   $ rm -r *
   ```

   **❗ IMPORTANT**\
   Do not use `git rm -r *` to delete the files. Note that if you delete the files using an IDE, it’s probable the `git rm` command is used to execute the deletion.
3. Extract the new source code release to the `caplin` branch.
4. Update Git’s staging area to match your working directory:

   ```console
   $ git add --all
   ```
5. Commit changes:

   ```console
   $ git commit -m "Caplin source code release FX Professional 3.30.0"
   ```
6. Tag the commit:

   ```console
   $ git tag caplin-fxpro-3.30.0
   ```
7. Checkout the `develop` branch:

   ```console
   $ git checkout develop
   ```
8. Merge `caplin` into `develop`:

   ```console
   $ git merge caplin
   ```
9. Resolve merge conflicts.

## Creating your development project

Follow the steps below:

1. Extract the FX Professional source zip to a new project directory (`__my-project__` in this example):

   ```plantuml
   @startsalt
   scale 1.25
   {
   {T
    + <color:goldenrod><&folder></color> //my-project//
    ++ <color:goldenrod><&folder></color> apps
    ++ <color:goldenrod><&folder></color> dev-tools
    ++ <color:goldenrod><&folder></color> packages-caplin
   }
   }
   @endsalt
   ```
2. [Professional 6.2+] By default, this project is configured to download the Gradle Wrapper from a private Caplin server. In this project’s `gradle-wrapper.properties` file, change the `distributionUrl` property to the standard distribution URL for the Gradle version or your own private mirror of it. Do not change the Gradle version.

   **Example distributionUrl for Gradle version 8.7**

   ```
   distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-bin.zip
   ```

   For more information on configuring the Gradle Wrapper, see https://docs.gradle.org/current/userguide/gradle_wrapper.html
3. If you have chosen to store your Java module dependencies in a Maven compatible repository, follow the steps below:
   1. Import all the JAR files from the `lib` directory below into your repository. For the correct Maven group ID to use for each JAR file, refer to the file `dependencies.gradle`.

      ```plantuml
      @startsalt
      scale 1.25
      {
      {T
       + <color:goldenrod><&folder></color> //my-project//
       ++ <color:goldenrod><&folder></color> apps
       +++ <color:goldenrod><&folder></color> fxtrader
       ++++ <color:goldenrod><&folder></color> server
       +++++ <color:goldenrod><&folder></color> java
       ++++++ <color:goldenrod><&folder></color> src
       +++++++ <color:goldenrod><&folder></color> main
       ++++++++ <color:goldenrod><&folder></color> webapp-common
       +++++++++ <color:goldenrod><&folder></color> WEB-INF
       ++++++++++ <color:goldenrod><&folder></color> **lib** | <color:gray>JAR files to import</color>
       ++++++ <color:cornflowerblue><&file></color> **dependencies.gradle** | <color:gray>List of dependencies and group IDs</color>
      }
      }
      @endsalt
      ```
   2. Add your Maven repository to the `repositories` block of the `build.gradle` file below:

      ```plantuml
      @startsalt
      scale 1.25
      {
      {T
       + <color:goldenrod><&folder></color> //my-project//
       ++ <color:goldenrod><&folder></color> apps
       +++ <color:goldenrod><&folder></color> fxtrader
       ++++ <color:goldenrod><&folder></color> server
       +++++ <color:goldenrod><&folder></color> java
       ++++++ <color:cornflowerblue><&file></color> **build.gradle**
      }
      }
      @endsalt
      ```

      ```groovy
      repositories {
          mavenCentral()
          maven {
              url "https://plugins.gradle.org/m2/"
          }
          maven {
              url '<your_maven_repository>'
          }
      }
      ```
4. Initialize the project root as a Git repository:

   ```
   $ git init
   ```

   ```plantuml
   @startsalt
   scale 1.25
   {
   {T
    + <color:goldenrod><&folder></color> //my-project//
    ++ <color:gray><&folder> .git</color>
    ++ <color:goldenrod><&folder></color> apps
    ++ <color:goldenrod><&folder></color> dev-tools
    ++ <color:goldenrod><&folder></color> packages-caplin
   }
   }
   @endsalt
   ```
5. Create Git branches according to your branching strategy. See [Branching strategy](#branching-strategy), above.
6. In the directory `apps/fxtrader/` run the command below to install this project’s Node modules:

   ```plantuml
   @startsalt
   scale 1.25
   {
   {T
    + <color:goldenrod><&folder></color> //my-project//
    ++ <color:goldenrod><&folder></color> apps
    +++ <color:goldenrod><&folder></color> **fxtrader**
   }
   }
   @endsalt
   ```

   **FX Professional 4**

   ```
   $ pnpm install
   ```

   **FX Professional 3**

   ```
   $ yarn install
   ```

You can now start customising the source code of FX Professional.

## Previewing your changes

To run the local development server, run the appropriate command below from `apps/fxtrader`:

* If you store your project’s Java dependencies in a Maven compatible repository, run the appropriate command below:

  **FX Professional 4**

  ```
  $ pnpm start --variant _variant_
  ```

  **FX Professional 3**

  ```
  $ yarn start --variant _variant_
  ```

  **❗ IMPORTANT**\
  This method deletes all local Java dependencies in the `apps/fxtrader/server/java/src/main/webapp-common/WEB-INF/lib` directory.
* If you store your project’s Java dependencies with your project’s source code, run the appropriate command below:

  **FX Professional 4**

  ```
  $ pnpm start --variant _variant_ --useLocalDeps
  ```

  **FX Professional 3**

  ```
  $ yarn start --variant _variant_ --useLocalDeps
  ```

  **❗ IMPORTANT**\
  If you accidentally omit the `--useLocalDeps` argument, the local Java dependencies in the `apps/fxtrader/server/java/src/main/webapp/WEB-INF/lib` directory are deleted. To use `--useLocalDeps` again, you must manually restore the Java dependencies from the FX Professional source zip file.

View a preview of your customisations at <span>http://</span>localhost:8080.

When you make a change to your project, refresh the page to view your changes.