Added logic for creation, mangemnet and display of case links by aschalew-at · Pull Request #1527 · hmcts/pcs-api

aschalew-at · 2026-03-18T12:09:37Z

Jira link

See [HDPI-4510](https://tools.hmcts.net/jira/browse/HDPI-4510)
[HDPI-4509](https://tools.hmcts.net/jira/browse/HDPI-4509)
[HDPI-4512](https://tools.hmcts.net/jira/browse/HDPI-4512)

Change description

This is about case linking which is linking of cases based on certain reasons.The PR includes changes for creation, managing and displaying of cases links.

Testing done

Security Vulnerability Assessment

CVE Suppression: Are there any CVEs present in the codebase (either newly introduced or pre-existing) that are being intentionally suppressed or ignored by this commit?

Yes
No

Checklist

commit messages are meaningful and follow good commit message guidelines
README and other documentation has been updated / added (if needed)
tests have been updated / new tests has been added (if needed)
Does this PR introduce a breaking change

github-actions · 2026-03-18T12:12:56Z

CCD diff summary

👉 Full report: https://github.com/hmcts/pcs-api/actions/runs/23739028491?check_suite_focus=true

AuthorisationCaseState.json

UserRole	CaseStateID	CRUD
+caseworker-pcs	+AWAITING_SUBMISSION_TO_HMCTS	+R
+caseworker-pcs	+PENDING_CASE_ISSUED	+R

CaseField.json

RegularExpression	Max	Searchable	Min	FieldTypeParameter	HintText	Label	ID	FieldType
+	+	+	+	+	+	+Component Launcher (for displaying Linked Cases data)	+LinkedCasesComponentLauncher	+ComponentLauncher
+	+	+	+	+CaseLink	+	+Linked cases	+caseLinks	+Collection

AuthorisationCaseEvent/AuthorisationCaseEvent.json

UserRole	CaseEventID	CRUD
+caseworker-pcs	+createCaseLink	+R
+caseworker-pcs-solicitor	+createCaseLink	+CRU
+caseworker-pcs	+maintainCaseLink	+R
+caseworker-pcs-solicitor	+maintainCaseLink	+CRUD

AuthorisationCaseField/caseworker-pcs.json

UserRole	CaseFieldID	CRUD
+caseworker-pcs	+LinkedCasesComponentLauncher	+R
+caseworker-pcs	+caseHistory	+CRU
+caseworker-pcs	+caseLinks	+R
+caseworker-pcs	+caseTitleMarkdown	+R
+caseworker-pcs	+nextStepsMarkdown	+R
+caseworker-pcs	+nextStepsMarkdownLabel	+R
+caseworker-pcs	+propertyAddress	+R
+caseworker-pcs	+waysToPay	+R

AuthorisationCaseField/caseworker-pcs-solicitor.json

UserRole	CaseFieldID	CRUD
+caseworker-pcs-solicitor	+LinkedCasesComponentLauncher	+CRUD
+caseworker-pcs-solicitor	+caseLinks	+CRUD

CaseEvent/maintainCaseLink.json

Description	EndButtonLabel	ID	Name	PostConditionState	PreConditionState(s)	Publish	ShowEventNotes	ShowSummary
+To manage link related cases	+Save and continue	+maintainCaseLink	+Manage case links	+*	+*	+N	+N	+N

CaseEvent/createCaseLink.json

Description	EndButtonLabel	ID	Name	PostConditionState	PreConditionState(s)	Publish	ShowEventNotes	ShowSummary
+To link related cases	+Save and continue	+createCaseLink	+Link cases	+*	+*	+N	+N	+N

CaseEventToFields/maintainCaseLink.json

CaseEventID

CaseFieldID

DisplayContext

DisplayContextParameter

PageColumnNumber

PageDisplayOrder

PageFieldDisplayOrder

PageID

PageLabel

ShowSummaryChangeOption

+maintainCaseLink

+LinkedCasesComponentLauncher

+OPTIONAL

+#ARGUMENT(UPDATE,LinkedCases)

+1

+1

+2

+maintainCaseLink

+Case Link

+Y

+maintainCaseLink

+caseLinks

+OPTIONAL

+LinkedCasesComponentLauncher = "DONOTSHOW"

+1

+1

+1

+maintainCaseLink

+Case Link

+Y

+Y

CaseEventToFields/createCaseLink.json

CaseEventID

CaseFieldID

DisplayContext

DisplayContextParameter

PageColumnNumber

PageDisplayOrder

PageFieldDisplayOrder

PageID

PageLabel

ShowSummaryChangeOption

+createCaseLink

+LinkedCasesComponentLauncher

+OPTIONAL

+#ARGUMENT(CREATE,LinkedCases)

+1

+1

+2

+createCaseLink

+Case Link

+Y

+createCaseLink

+caseLinks

+OPTIONAL

+LinkedCasesComponentLauncher = "DONOTSHOW"

+1

+1

+1

+createCaseLink

+Case Link

+Y

+Y

CaseTypeTab/6_caseLinkscaseworker-pcs-solicitor.json

CaseFieldID

Channel

DisplayContextParameter

TabDisplayOrder

TabFieldDisplayOrder

TabID

TabLabel

UserRole

+LinkedCasesComponentLauncher

+CaseWorker

+#ARGUMENT(LinkedCases)

+6

+1

+caseLinkscaseworker-pcs-solicitor

+Linked cases

+caseworker-pcs-solicitor

+caseLinks

+CaseWorker

+#ARGUMENT(LinkedCases)

+LinkedCasesComponentLauncher!=""

+6

+2

+caseLinkscaseworker-pcs-solicitor

+Linked cases

…cases

scottstewart-sl · 2026-03-23T11:44:14Z

src/main/java/uk/gov/hmcts/reform/pcs/ccd/entity/PcsCaseEntity.java

        defendantResponse.setPcsCase(this);
    }
+
+    public void mergeCaseLinks(List<ListValue<CaseLink>> incomingLinkedCases) {


scottstewart-sl · 2026-03-23T11:48:16Z

src/main/java/uk/gov/hmcts/reform/pcs/ccd/event/MaintainLinkCase.java

+                            .decentralisedEvent(EventId.maintainCaseLink.name(), this::submit)
+                            .forAllStates()
+                            .name("Manage case links")
+                            .description("To Manage link related cases")


Minor - small M on "manage". Also it might read better as "To manage linked cases" or something like that. (Is that actually displayed anywhere btw?)

"To manage linked cases" will be the tool tip on the event "Manage case links".

scottstewart-sl · 2026-03-23T11:50:14Z

src/main/java/uk/gov/hmcts/reform/pcs/ccd/service/PcsCaseService.java

            .orElseThrow(() -> new CaseNotFoundException(caseReference));
    }

+    public void patchCase(long caseReference, PCSCase pcsCase) {


This method name isn't clear on what it is doing. We used to have a single patchCase method that would handle all updates if they weren't null but that has since been changed to have specific methods to only update specific fields. So can you rename this to something like patchCaseLinks ?

scottstewart-sl · 2026-03-23T11:51:40Z

src/main/java/uk/gov/hmcts/reform/pcs/ccd/service/PcsCaseService.java

+            pcsCaseEntity.mergeCaseLinks(pcsCase.getCaseLinks());
+        }
+
+        pcsCaseRepository.save(pcsCaseEntity);


You shouldn't need to save the pcsCaseEntity as it is already managed in this scenario.

scottstewart-sl · 2026-03-23T11:55:40Z

src/main/java/uk/gov/hmcts/reform/pcs/ccd/PCSCaseView.java

            .collect(Collectors.toList());
    }

+    private List<ListValue<CaseLink>> mapAndWrapCaseLinks(PcsCaseEntity pcsCaseEntity) {


Can you move this logic into a separate class please? Otherwise this PCSCaseView will get quite large. See ClaimView as an example - you can implement a class with the same setCaseFields(...) method signature and call it in the same way as the other *View instance are called, (https://github.com/hmcts/pcs-api/blob/master/src/main/java/uk/gov/hmcts/reform/pcs/ccd/PCSCaseView.java#L117-L127)

scottstewart-sl · 2026-03-23T11:56:11Z

src/main/resources/db/migration/V071__create_case_link_and_link_reason_tables.sql

+-- ============================================
+-- ============================================
+-- PCS CASE LINK + LINK REASONS
+-- ============================================


This comment is repeated 🙂

scottstewart-sl · 2026-03-23T11:57:42Z

src/main/resources/db/migration/V071__create_case_link_and_link_reason_tables.sql

+DROP TABLE IF EXISTS case_link_reason CASCADE;
+
+-- Drop case_link table
+DROP TABLE IF EXISTS case_link CASCADE;


Are these DROP statements actually needed, given that Flyway will be applying the migrations in the correct order so the tables and indexes shouldn't exist when this migration script is run.

scottstewart-sl · 2026-03-23T11:59:02Z

src/main/resources/db/migration/V071__create_case_link_and_link_reason_tables.sql

+
+-- Table: case_link
+CREATE TABLE case_link (
+     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),


Minor - we rely on the ORM to assign these, so for consistency with the other table definitions could you remove the default?

scottstewart-sl · 2026-03-23T11:59:41Z

src/main/resources/db/migration/V071__create_case_link_and_link_reason_tables.sql

+CREATE TABLE case_link (
+     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+     case_id UUID NOT NULL REFERENCES pcs_case(id) ON DELETE CASCADE,   -- Source case
+     linked_case_id BIGINT NOT NULL,  -- Linked case number (BIGINT)


I would argue that these comments are not needed - the column definition is clear enough.

scottstewart-sl · 2026-03-23T12:02:08Z

build.gradle

      "**/uk/gov/hmcts/reform/pcs/ccd/page/**/*.java," +
      "**/uk/gov/hmcts/reform/pcs/ccd/entity/**/*.java," +
+      "**/uk/gov/hmcts/reform/pcs/ccd/event/**/*.java," +
+      "**/uk/gov/hmcts/reform/pcs/ccd/service/**/*.java," +


Can you revert these changes please? We should have code coverage on those packages.

…cases

scottstewart-sl · 2026-03-27T10:05:50Z

src/main/resources/db/migration/V072__create_case_link_and_link_reason_tables.sql

+-- ============================================
+CREATE TABLE case_link (
+     id UUID PRIMARY KEY,
+     case_link_reference UUID NOT NULL REFERENCES pcs_case(id) ON DELETE CASCADE,


This FK is called case_id in all other tables that have it, so it would be better to be consistent with the existing naming convention.

Renamed case_link_reference to case_id and linked_case_id to linked_case_reference.

scottstewart-sl · 2026-03-27T10:11:51Z

src/main/java/uk/gov/hmcts/reform/pcs/ccd/entity/PcsCaseEntity.java

+        if (incomingLinkedCases == null) {
+            this.caseLinks.clear();
+            return;
+        }


Why should an empty incoming list remove the existing ones, if this is a merge operation?

The whole if block can be removed, as incomingLinkedCases can never be null, as this is being checked in the calling method (patchCaseLinks())

scottstewart-sl · 2026-03-27T10:13:36Z

src/main/java/uk/gov/hmcts/reform/pcs/ccd/entity/PcsCaseEntity.java

+                    caseLinkReasonEntities.add(caseLinkReasonEntity);
+                }
+                caseLinkEntity.getReasons().clear();
+                caseLinkEntity.getReasons().addAll(caseLinkReasonEntities);


Better to have a setReasons method on the caseLinkEntity rather than fetching the collection and manipulating it, since you don't know whether it is immutable or not.

As the reasons field in in CaseLinkEntity is annotated with @onetomany with orphanRemoval set to true, Hibernate tracks the original collection instance and expects the same collection to be mutated and not swapped out.

scottstewart-sl · 2026-03-27T10:14:32Z

src/main/java/uk/gov/hmcts/reform/pcs/ccd/entity/PcsCaseEntity.java

+        }
+
+        this.caseLinks.clear();
+        this.caseLinks.addAll(result);


Is there a reason for not just assigning result, (which could have a better name btw), to this.caseLinks ?

Same as above. The caseLinks field in PcsCaseEntity is annotated with @onetomany with orphanRemoval set to true, Hibernate tracks the original collection instance and expects the same collection to be mutated and not swapped out. result renamed to mergedCaseLinkEntities.

…cases

guygrewal77 · 2026-03-27T17:35:24Z

src/main/java/uk/gov/hmcts/reform/pcs/ccd/accesscontrol/CaseLinkingAccess.java

+    @Override
+    public SetMultimap<HasRole, Permission> getGrants() {
+        SetMultimap<HasRole, Permission> grants = HashMultimap.create();
+        grants.putAll(PCS_SOLICITOR, Permission.CRU);


Is the Delete missing for permissions ? In the event - CreateCaseLink class, solicitor has full CRUD access.

The access profile in CaseLinkinAccess is applied to the fields in PCSCase (for updating cases) do not need the Delete permission in association with the events CreateCaseLink and MaintainLinkCase. In the event class CreateCaseLink, we only need the permissions CRU, whereas in the event class MaintainLinkCase, we need the Delete permission as well. Hence I will remove the Delete permission in CreateCaseLink and keep it in MaintainLinkCase. I will keep CRU in CaseLinkinAccess class

…cases

…n for solicitor in CreateCaseLink

tvr-hmcts

Some comments for consideration

tvr-hmcts · 2026-03-30T12:55:07Z

src/main/java/uk/gov/hmcts/reform/pcs/ccd/service/CaseLinkService.java

+                        .build();
+                    caseLinkReasonEntities.add(caseLinkReasonEntity);
+                }
+                caseLinkEntity.getReasons().clear();


Is this call needed again here?

tvr-hmcts · 2026-03-30T13:00:31Z

src/test/java/uk/gov/hmcts/reform/pcs/ccd/entity/CaseLinkEntityTest.java

+    }
+
+    @Test
+    void shouldAddCaseLinkReason() {


This is just testing a setter no? Guess I am not understanding the value.

tvr-hmcts · 2026-03-30T13:04:11Z

src/main/java/uk/gov/hmcts/reform/pcs/ccd/service/CaseLinkService.java

+
+            if (dto.getReasonForLink() != null) {
+                List<CaseLinkReasonEntity> caseLinkReasonEntities = new ArrayList<>();
+                for (ListValue<LinkReason> incomingLinkReason : dto.getReasonForLink()) {


This can just be streamed into the reasons collection within the entity rather than create this new arraylist.

tvr-hmcts · 2026-03-30T13:06:54Z

src/main/java/uk/gov/hmcts/reform/pcs/ccd/view/CaseLinkView.java

+@Component
+public class CaseLinkView {
+
+    public void setCaseFields(PCSCase pcsCase, PcsCaseEntity pcsCaseEntity) {


Not understanding the point in this wrapper. The same check is made within the other method also. So the other can just be public

tvr-hmcts · 2026-03-30T13:07:28Z

src/main/java/uk/gov/hmcts/reform/pcs/ccd/event/CreateCaseLink.java

+
+    private final PcsCaseService pcsCaseService;
+
+


Extra space

tvr-hmcts · 2026-03-30T13:10:13Z

src/test/java/uk/gov/hmcts/reform/pcs/ccd/service/PcsCaseServiceTest.java

    }

+    @Test
+    void shouldPatchCaseData() {


Need another test for when the pcsCase.getCaseLinks() != null

tvr-hmcts · 2026-03-30T13:13:32Z

src/test/java/uk/gov/hmcts/reform/pcs/ccd/service/PcsCaseServiceTest.java

+        // Given
+        PcsCaseEntity pcsCaseEntity =  mock(PcsCaseEntity.class);
+        PCSCase caseData = PCSCase.builder().build();
+        when(pcsCaseRepository.findByCaseReference(CASE_REFERENCE)).thenReturn(java.util.Optional.of(pcsCaseEntity));


import java.util.Optional

tvr-hmcts · 2026-03-30T13:14:16Z

src/test/java/uk/gov/hmcts/reform/pcs/ccd/service/PcsCaseServiceTest.java

+        underTest.patchCaseLinks(CASE_REFERENCE, caseData);
+
+        // Then
+        verify(caseLinkService, atLeastOnce()).mergeCaseLinks(caseData.getCaseLinks(), pcsCaseEntity);


The number of times can be asserted more strictly here.

tvr-hmcts · 2026-03-30T13:15:34Z

src/test/java/uk/gov/hmcts/reform/pcs/ccd/event/MaintainLinkCaseTest.java

+    }
+
+    @Test
+    void shouldModifyCaseLinksInSubmitCallback() {


The logic in here is a duplication of the other test CreateCaseLinkTest

tvr-hmcts · 2026-03-30T13:17:56Z

src/test/java/uk/gov/hmcts/reform/pcs/ccd/view/CaseLinkViewTest.java

+        // Then
+        List<ListValue<CaseLink>> mappedCaseLinks = pcsCase.getCaseLinks();
+        assertThat(mappedCaseLinks).hasSize(1);
+        assertThat(mappedCaseLinks.getFirst().getValue().getCaseReference()).isEqualTo("1234");


mappedCaseLinks.getFirst().getValue() can be extracted and the variable used in the other asserts rather than call the same chain each time.

aschalew added 2 commits March 18, 2026 11:22

Added logic for creation, mangemnet and display of case links

6d15c22

Reverted AUthMode back to Local

e0a2d81

aschalew-at requested a review from a team as a code owner March 18, 2026 12:09

aschalew-at requested review from saurabhvalsangkar-hmcts and scottstewart-sl March 18, 2026 12:09

Merge branch 'master' into HDPI-4510-create-and-view-proposed-linked-…

931e7ea

…cases

hmcts-jenkins-j-to-z bot requested a deployment to preview March 18, 2026 12:22 Abandoned

Renamed sql script for case linking from V063 to V067

645a043

hmcts-jenkins-j-to-z bot requested a deployment to preview March 18, 2026 14:10 Abandoned

Renamed epims_id back to empimsid

e84bdcd

hmcts-jenkins-j-to-z bot requested a deployment to preview March 18, 2026 16:31 Abandoned

hmcts-jenkins-j-to-z bot requested a deployment to preview March 19, 2026 10:00 Abandoned

Updated Unit tests to remove some code smells

0f64f6a

aschalew-at requested a review from a team as a code owner March 19, 2026 10:46

aschalew-at requested review from AmandaRichards and arun-hmcts March 19, 2026 10:46

hmcts-jenkins-j-to-z bot requested a deployment to preview March 19, 2026 11:02 Abandoned

hmcts-jenkins-j-to-z bot requested a deployment to preview March 19, 2026 15:30 Abandoned

Renamed epimsid to epims_id

9519c00

hmcts-jenkins-j-to-z bot requested a deployment to preview March 19, 2026 17:19 Abandoned

Renamed epims_id back to epimsid

67afd9e

hmcts-jenkins-j-to-z bot requested a deployment to preview March 20, 2026 07:32 Abandoned

aschalew added 2 commits March 20, 2026 09:10

Resolved merge conflicts

a925e2f

Renamed V067 to V070 after merging master

aeddb7a

hmcts-jenkins-j-to-z bot requested a deployment to preview March 20, 2026 09:32 Abandoned

hmcts-jenkins-j-to-z bot requested a deployment to preview March 20, 2026 11:01 Abandoned

Update V002.1__postcode_test_data.sql

4d49560

hmcts-jenkins-j-to-z bot deployed to preview March 20, 2026 11:23 View deployment

hmcts-jenkins-j-to-z bot added the ns:pcs label Mar 20, 2026

hmcts-jenkins-j-to-z bot deployed to preview March 25, 2026 16:54 View deployment

scottstewart-sl reviewed Mar 26, 2026

View reviewed changes

aschalew added 2 commits March 26, 2026 10:05

Merge branch 'master' into HDPI-4510-create-and-view-proposed-linked-…

ac43cd0

…cases

Updated code for PR comments

3922036

hmcts-jenkins-j-to-z bot deployed to preview March 26, 2026 14:26 View deployment

aschalew-at requested review from adusumillipraveen and scottstewart-sl March 26, 2026 15:50

aschalew added 2 commits March 27, 2026 08:25

Merge branch 'master' into HDPI-4510-create-and-view-proposed-linked-…

cbdee92

…cases

Fixed a code smell from Sonar cube

ce7a640

hmcts-jenkins-j-to-z bot deployed to preview March 27, 2026 08:55 View deployment

scottstewart-sl reviewed Mar 27, 2026

View reviewed changes

aschalew added 2 commits March 27, 2026 13:22

Updated PK names in case_link table from PR review comment

26e23f7

Merge branch 'master' into HDPI-4510-create-and-view-proposed-linked-…

b011d5a

…cases

hmcts-jenkins-j-to-z bot deployed to preview March 27, 2026 13:35 View deployment

aschalew added 2 commits March 27, 2026 15:29

Moved mergeCaseLinks() method into CaseLinkService class

1139553

Updated CaseLinkServiceTest

f8d4e88

hmcts-jenkins-j-to-z bot deployed to preview March 27, 2026 16:24 View deployment

scottstewart-sl approved these changes Mar 27, 2026

View reviewed changes

aschalew-at requested a review from scottstewart-sl March 27, 2026 16:49

guygrewal77 reviewed Mar 27, 2026

View reviewed changes

aschalew-at requested a review from guygrewal77 March 30, 2026 06:35

hmcts-jenkins-j-to-z bot deployed to preview March 30, 2026 08:21 View deployment

aschalew added 2 commits March 30, 2026 10:10

Merge branch 'master' into HDPI-4510-create-and-view-proposed-linked-…

354c908

…cases

Removed reasonText field from CaseLinkReasonEntity, updated permissio…

05939c7

…n for solicitor in CreateCaseLink

hmcts-jenkins-j-to-z bot deployed to preview March 30, 2026 10:23 View deployment

guygrewal77 approved these changes Mar 30, 2026

View reviewed changes

tvr-hmcts reviewed Mar 30, 2026

View reviewed changes

Conversation

aschalew-at commented Mar 18, 2026

Jira link

Change description

Testing done

Security Vulnerability Assessment

Checklist

Uh oh!

github-actions bot commented Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CCD diff summary

AuthorisationCaseState.json

CaseField.json

AuthorisationCaseEvent/AuthorisationCaseEvent.json

AuthorisationCaseField/caseworker-pcs.json

AuthorisationCaseField/caseworker-pcs-solicitor.json

CaseEvent/maintainCaseLink.json

CaseEvent/createCaseLink.json

CaseEventToFields/maintainCaseLink.json

CaseEventToFields/createCaseLink.json

CaseTypeTab/6_caseLinkscaseworker-pcs-solicitor.json

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

guygrewal77 Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tvr-hmcts left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

github-actions bot commented Mar 18, 2026 •

edited

Loading

guygrewal77 Mar 27, 2026 •

edited

Loading