finrem-ccd-definitions

Financial Remedy configuration definitions for CCD.

This allows for the FR CCD Config to be easily edited and stored in GitHub as JSON rather than version controlled in Confluence as Xlsx files.

Setup

To install the dependencies for both this project and the submodule (ccd-definition-processor), run: yarn install && yarn reset-ccd-submodule

Setup for M1 chip Macs

If running yarn install throws an error with this output:

The chromium binary is not available for arm64

1. Run brew install chromium
2. Run xattr -cr /Applications/Chromium.app
3. Add these env variables to your .zshrc file export PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true export PUPPETEER_EXECUTABLE_PATH=`which chromium`
4. Save file and restart terminal
5. Run source ~/.zshrc
6. yarn install && yarn reset-ccd-submodule

Convert JSON to Excel

Depending on if you want the generated Excel to be for the Consented or Contested Journeys - add the appropriate journey to the end of the command.

Generate Excel Configs for all environments (Local, Demo, ITHC, AAT & Prod)

For Consented Journey:

yarn generate-excel-all-consented

For Contested Journey:

yarn generate-excel-all-contested

The generated Excel files will be in defintions/consented/xlsx or defintions/contested/xlsx respectively.

Generate Excel Configs for a specific environment i.e. AAT/DEMO/DEMO-PROD-LIKE/ITHC/PERFTEST

• Note DEMO-PROD-LIKE does not include '-nonprod' files so should be a replication of the Production config, just pointing to Demo.

yarn generate-bulk-excel-(local/demo/aat/ithc/perftest/demo-prod-like/prod)

E.g.: yarn generate-excel-aat-consented or yarn generate-excel-aat-contested

Convert Excel to JSON

If you prefer to make the changes directly to the Excel Configuration file, and then convert back to JSON:

1. Generate a fresh base Excel file from the existing JSON for the appropriate journey using the yarn generate-excel-{consented/contested}. The generated Excel file will be in defintions/{CHOSEN_JOURNEY}/xlsx/ccd-config-base-{JOURNEY}.xlsx and will contain placeholder URLs.
2. Make your changes to ccd-config-base.xlsx but ensure you don't modify the placeholder URLS (${CCD_DEF_COS_URL}/). These are used to dynamically change the callback URLs for each environment.
3. Once you're finished with your changes in the Excel file, convert back to JSON using yarn generate-json-{consented/contested}
4. Review the JSON file changes to ensure all your changes are correct

Dependency Vulnerabilities Check

Run this script to perform a security audit on Yarn dependencies.

./yarn-audit-with-suppressions.sh

Run E2E Tests Locally

E2E tests can be run locally, although they still use AAT.

Setup

yarn playwright install

Import AAT environment variables. Ask a colleague for an e2e-aat.env file. This should not be stored in GitHub.

source ./e2e-aat.env

Code Linting

We use ESLint to ensure consistent code quality, formatting, and filename conventions across the project.

• Running Linting

To check for linting errors, run:

yarn lint

• Fixing Linting Errors

To automatically fix linting issues where possible, run:

yarn lint --fix

• Filename Conventions

To avoid linting errors, filenames must follow these conventions:

• snake_case: playwright-e2e/test/, playwright-e2e/resources/tab_content/

• kebab-case: playwright-e2e/config/, playwright-e2e/fixtures/, playwright-e2e/resources/** (excluding tab_content)

• PascalCase: playwright-e2e/pages/, playwright-e2e/data-utils/

• camelCase: playwright-e2e/helpers/**

Example:

✅ login_page.spec.ts (snake_case)

✅ checkout-flow.json (kebab-case)

❌ LoginPage.spec.ts (should be snake_case for test files)

ESLint is configured with eslint-plugin-unicorn to enforce these rules automatically for file names in their respective folders.

To run the unit tests to verify you have correctly made changes:

yarn test

Run full E2E Tests for both Journeys:

Run full E2E tests of both the Consented & Contested Journeys on CCD

1. Configure defined env variables from Jenkinsfile_nightly pipeline .
2. Values for env variables can be found in Azure finrem aat key vault.
3. yarn test:functional will create both Consented and Contested cases via API (runs on PR and master AAT).
4. To create cases on demo RUNNING_ENV=demo, run the scenario tests.

Running additional tests in the Jenkins PR Pipeline

1. Add one or more appropriate labels to your PR in GitHub. Valid labels are:

• enable_full_functional_tests

2. Trigger a build of your PR in Jenkins.

ccd-definition-processor

This repo makes use of https://github.com/hmcts/ccd-definition-processor to generate the excel file. You may have to update this repo if, for example, you need to add a column to the definitions spreadsheet.

Ideally this should be a published NPM package, so that we can include it in package.json but at the moment we include it as a git submodule

A submodule is simply a pointer to a repo and a commit. If you want to reset that repo to the latest upstream master, run:

yarn reset-ccd-submodule

You need to use this if you have accidentally change this pointer reference to something other than what you intended (you can instead modify the above command to package.json to check out a specific commit/version of that submodule)

It's also important to note that once you update to a new reference (i.e you commit a change to the ccd-definition-processor file) you need to make sure everyone else runs yarn setup again to get the updated reference as well.

Feature toggle

If you want to test something on local, aat or demo env, but don't want to release it on prod make sure you move all definitions you don't want to release to a file with suffix "-nonprod.json".

Similarly, each file can have a "prod" version where we store all definitions that will ONLY go to prod, but not on test environment spreadsheets.

A combination of the 2 can also be used, for example to toggle a CaseEvent to behave differently in PROD and AAT, the CaseEvent can be declared once in the "nonprod" version and once in the "prod" version

To do it, you need to create a folder for files related to that xlsx tab, eg: "AuthorisationCaseEvent" where you move the production file "AuthorisationCaseEvent.json" and you create another one with definitions you don't want to release yet (eg. AuthorisationCaseEvent-noprod.json, but can be any name such as "definitions-for-bsp-ABC-nonprod.json").

When "toggled off" definitions can be released, just move them to the prod file and remove them from nonprod file. Then follow the typical release process.

Please read more here: https://tools.hmcts.net/confluence/display/FR/Feature+toggles+for+CCD+definition

How to access a PR deployment

A PR will create a full CCD/ExUI stack in the preview environment as defined in the Helm chart.

If you require a particular finrem-cos PR image rather than the latest production image then you should specify this using a GitHub label. Add a label use-finrem-cos-pr-number replacing number with the value required.

GitHub will have the main URL for a PR deployment. e.g. https://finrem-ccd-definitions-pr-<number>.preview.platform.hmcts.net/

This can be found be clicking 'View Deployment' in the conversation tab of the PR. However, this URL in itself is not very useful.

To access a PR deployment via the UI for testing it must be persisted once the Jenkins build pipeline has finished.

This is achieved by adding the label enable_keep_helm to the PR before it builds.

The following URLs will then be available. Replace <number> with the value of your PR.

Application	URL
Manage Cases	https://xui-finrem-ccd-definitions-pr-<number>.preview.platform.hmcts.net/
Manage Organisation	https://xui-mo-finrem-ccd-definitions-pr-<number>.preview.platform.hmcts.net/
CCD Admin Web	https://admin-web-finrem-ccd-definitions-pr-<number>.preview.platform.hmcts.net/

• Login with an authorised AAT user listed here

See also:

• https://tools.hmcts.net/confluence/display/RSE/Divorce+Local+Environment+Set+up+using+Preview
• https://tools.hmcts.net/confluence/display/RSE/Debugging+a+service+in+Preview+Cluster+via+Telepresence

GitHub Action to Create a Preview Environment

A GitHub Action is available called Create Preview Environment.

This provides a workflow to create a preview environment for testing a change that only includes Java code updates and no CCD configuration changes.

The workflow creates a new branch and a draft pull request with the required labels needed to create a preview environment.

The workflow is run manually. From the action's workflow page, select the Run workflow button and enter the following inputs:

• Use workflow from - Select Branch: master
• Jira DFR- - The Jira ticket number for the change e.g. 1234
• finrem-cos PR # - The PR number for the finrem-cos change e.g. 5678
• PR Title - (optional) The title of the pull request to be created. If left blank then a default title will be used
• Branch name - (optional) The name of the branch to be created. If left blank then a default will be used

The draft pull request that is created will include a link to the Jira ticket and also to Manage Cases, Manage Organisation and CCD Admin Web applications in the preview environment.

Deploying CCD Config Changes to Demo or ITHC

Config changes are now uploaded to AAT when a PR branch is merged to master. When we want to release config changes to Demo/ITHC:

1. Excel files for the Consented or Contested Journey can be found in the Artifacts tab of the Jenkins build on merge to master
2. Login to the CCD Admin Web Portal for the relevant environment
3. Go to "Import Case Definition" and upload the appropriate Excel file and verify it uploaded successfully

Release To Production

Jenkins now generates the config ready to release to PROD, this can be found in the Artifacts tab of the Jenkins build on merge to master.

NOTE: Jenkins will populate Judge details in the PROD configs that is not available locally, so PROD configs should never be used when generated locally and instead should always be taken from Jenkins.

Judge Data in FixedLists

To update judge data in FixedLists for Production, see here.

Precommit checks

Husky handles pre-commit checks.

This is the file that determines the precommit checks that are run.

./husky/pre-commit

The file runs yarn lint, see the Scipts section in in package.json. If you get a message to say the pre-commit hook was ignored, register the hook with:

yarn setup-precommit

The pre-commit hook is automatically set on in the setup step.