Developing with FX Sales

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

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

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

Requirements

Development environment:

  • The variantsalestrader-version.zip source archive for your variant of FX Sales, available from the Caplin downloads page.

  • OpenJDK 8 or 11.

  • Network access to GitHub.

  • Network access to the npm registry.

  • FX Sales 3 requirements:

    • Node.js 16

    • Pnpm 7+

  • FX Sales 2 requirements:

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

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 Java dependencies

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

  • Continue to store the Java dependencies with your project and commit them to Git

  • (Recommended) Import the Java dependencies into a Maven compatible repository, such as Artifactory.

Choosing a branching strategy

It’s important to decide on a branching strategy early on in the project to make taking upgrades to FX Sales 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.

branchingstrategysales

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

  1. Create a new directory to host your project.

  2. Extract the 'variantsalestrader-version.zip' file to the project directory.

  3. Initialize the git repository:

    $ git init

  4. Add all files to the staging area:

    $ git add --all

  5. Execute the initial commit:

    $ git commit -m "Initial commit"

  6. Tag the commit to record the version of the Caplin source code release:

    $ git tag caplin-fxsales-2.0.0

  7. Create an integration branch (develop) and a branch to track Caplin source code releases (caplin):

    $ git branch develop
$ git branch caplin

When a new version of FX Sales is released:

  1. Checkout the caplin branch:

    $ git checkout caplin

  2. Delete all files in the caplin branch:

    $ rm -r *
    Do not use git rm -r * to delete the files. If you delete the files using an IDE, it will likely run the git rm command 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:

    $ git add --all

  5. Commit changes:

    $ git commit -m "Caplin source code release FX Sales 2.21.0"

  6. Tag the commit:

    $ git tag caplin-fxsales-2.21.0

  7. Checkout the develop branch:

    $ git checkout develop

  8. Merge caplin into develop:

    $ git merge caplin

  9. Resolve merge conflicts.

Creating your development project

Follow the steps below:

  1. Extract variantsalestrader-version.zip to a directory (my-project in this example):

     my-projectappsdev-toolspackages-caplin

  2. 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 group ID to use for each JAR file, refer to the file dependencies.gradle.

       my-projectappssalestraderserverjavasrcmainwebappWEB-INF libJAR files to import dependencies.gradleList of dependencies and group IDs

    2. Add your Maven repository to the repositories block of the build.gradle file below:

       my-projectappssalestraderserverjava build.gradle 
      repositories {
    mavenCentral()
    maven {
        url "https://plugins.gradle.org/m2/"
    }
    maven {
        url '<your_maven_repository>'
    }
}

  3. Initialize the project root as a Git repository:

    $ git init
     my-project.gitappsdev-toolspackages-caplin

  4. Create Git branches according to your branching strategy. See Choosing a branching strategy, above.

  5. In the directory apps/salestrader/ run the command below to install this project’s Node modules:

     my-projectapps salestrader
    FX Sales 3
    $ pnpm install
    FX Sales 2
    $ yarn install

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

Previewing your changes

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

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

    FX Sales 3
    $ pnpm start --variant variant
    FX Sales 2
    $ yarn start --variant variant
    This method deletes all local Java dependencies in the apps/salestrader/server/java/src/main/webapp/WEB-INF/lib directory.

  • If you store your project’s Java dependencies with your project’s source code, run the appropriate command below:

    FX Sales 3
    $ pnpm start --variant variant --useLocalDeps
    FX Sales 2
    $ yarn start --variant variant --useLocalDeps
    If you accidentally omit the --useLocalDeps argument, the local Java dependencies in the apps/salestrader/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 Sales source zip file.

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

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