CCM-12590 - Update failure reason code to string

docs/assets/diagrams/types.md

@@ -13,7 +13,7 @@ erDiagram
         string status "enum: PENDING, ACCEPTED, REJECTED, PRINTED, ENCLOSED, CANCELLED, DISPATCHED, FAILED, RETURNED, FORWARDED, DELIVERED"
         string specificationId
         string groupId
-        number reasonCode
+        string reasonCode
         string reasonText
         string supplierId
         string url "url"

internal/datastore/src/__test__/letter-repository.test.ts

@@ -111,14 +111,14 @@ describe('LetterRepository', () => {
       id: 'letter1',
       supplierId: 'supplier1',
       status: 'REJECTED',
-      reasonCode: 1,
+      reasonCode: 'R01',
       reasonText: 'Reason text'
     };
     await letterRepository.updateLetterStatus(letterDto);
 
     const updatedLetter = await letterRepository.getLetterById('supplier1', 'letter1');
     expect(updatedLetter.status).toBe('REJECTED');
-    expect(updatedLetter.reasonCode).toBe(1);
+    expect(updatedLetter.reasonCode).toBe('R01');
     expect(updatedLetter.reasonText).toBe('Reason text');
   });
 

internal/datastore/src/types.md

@@ -13,7 +13,7 @@ erDiagram
         string status "enum: PENDING, ACCEPTED, REJECTED, PRINTED, ENCLOSED, CANCELLED, DISPATCHED, FAILED, RETURNED, FORWARDED, DELIVERED"
         string specificationId
         string groupId
-        number reasonCode
+        string reasonCode
         string reasonText
         string supplierId
         string url "url"

internal/datastore/src/types.ts

@@ -24,7 +24,7 @@ export const LetterSchemaBase = z.object({
   status: LetterStatus,
   specificationId: z.string(),
   groupId: z.string(),
-  reasonCode: z.number().optional(),
+  reasonCode: z.string().optional(),
   reasonText: z.string().optional()
 });
 

lambdas/api-handler/src/contracts/letters.ts

@@ -7,7 +7,7 @@ export type LetterDto = {
   supplierId: string,
   specificationId?: string,
   groupId?: string,
-  reasonCode?: number,
+  reasonCode?: string,
   reasonText?: string
 };
 
@@ -30,7 +30,7 @@ export const PatchLetterRequestResourceSchema = z.object({
   type: z.literal('Letter'),
   attributes: z.object({
     status: LetterStatusSchema,
-    reasonCode: z.number().optional(),
+    reasonCode: z.string().optional(),
     reasonText: z.string().optional(),
   }).strict()
 }).strict();
@@ -42,7 +42,7 @@ export const GetLetterResponseResourceSchema = z.object({
     status: LetterStatusSchema,
     specificationId: z.string(),
     groupId: z.string().optional(),
-    reasonCode: z.number().optional(),
+    reasonCode: z.string().optional(),
     reasonText: z.string().optional(),
   }).strict()
 }).strict();

lambdas/api-handler/src/handlers/__tests__/get-letter.test.ts

@@ -78,7 +78,7 @@ describe('API Lambda handler', () => {
       specificationId: 'spec1',
       groupId: 'group1',
       status: 'FAILED',
-      reasonCode: 100,
+      reasonCode: 'R01',
       reasonText: 'failed validation'
     });
 
@@ -97,7 +97,7 @@ describe('API Lambda handler', () => {
           status: 'FAILED',
           specificationId: 'spec1',
           groupId: 'group1',
-          reasonCode: 100,
+          reasonCode: 'R01',
           reasonText: 'failed validation'
         }
       }

lambdas/api-handler/src/handlers/__tests__/get-letters.test.ts

@@ -65,7 +65,7 @@ describe('API Lambda handler', () => {
         specificationId: 's1',
         groupId: 'g1',
         status: 'PENDING',
-        reasonCode: 123, // shouldn't be returned if present
+        reasonCode: 'R02', // shouldn't be returned if present
         reasonText: 'Reason text' // shouldn't be returned if present
       },
     ]);

lambdas/api-handler/src/handlers/__tests__/patch-letter.test.ts

@@ -32,7 +32,7 @@ const updateLetterStatusRequest : PatchLetterRequest = {
       type: 'Letter',
       attributes: {
         status: 'REJECTED',
-        reasonCode: 123,
+        reasonCode: 'R01',
         reasonText: 'Reason text',
       }
     }
@@ -81,7 +81,7 @@ describe('patchLetter API Handler', () => {
             status: 'REJECTED',
             specificationId: 'spec1',
             groupId: 'group1',
-            reasonCode: 123,
+            reasonCode: 'R01',
             reasonText: 'Reason text',
           }
         }

lambdas/api-handler/src/mappers/__tests__/letter-mapper.test.ts

@@ -46,7 +46,7 @@ describe('letter-mapper', () => {
       supplierStatus: 'supplier1#PENDING',
       supplierStatusSk: Date.now().toString(),
       ttl: 123,
-      reasonCode: 123,
+      reasonCode: 'R01',
       reasonText: 'Reason text'
     };
 
@@ -60,7 +60,7 @@ describe('letter-mapper', () => {
           specificationId: 'spec123',
           status: 'PENDING',
           groupId: 'group123',
-          reasonCode: 123,
+          reasonCode: 'R01',
           reasonText: 'Reason text',
         }
       }
@@ -111,7 +111,7 @@ describe('letter-mapper', () => {
       supplierStatus: 'supplier1#PENDING',
       supplierStatusSk: Date.now().toString(),
       ttl: 123,
-      reasonCode: 123,
+      reasonCode: 'R01',
       reasonText: 'Reason text'
     };
 
@@ -125,7 +125,7 @@ describe('letter-mapper', () => {
           specificationId: 'spec123',
           status: 'PENDING',
           groupId: 'group123',
-          reasonCode: 123,
+          reasonCode: 'R01',
           reasonText: 'Reason text',
         }
       }
@@ -145,7 +145,7 @@ describe('letter-mapper', () => {
       supplierStatus: 'supplier1#PENDING',
       supplierStatusSk: Date.now().toString(),
       ttl: 123,
-      reasonCode: 123,
+      reasonCode: 'R01',
       reasonText: 'Reason text'
     };
 

lambdas/api-handler/src/services/__tests__/letter-operations.test.ts

@@ -102,7 +102,7 @@ describe('patchLetterStatus function', () => {
     id: 'letter1',
     supplierId: 'supplier1',
     status: 'REJECTED',
-    reasonCode: 123,
+    reasonCode: 'R01',
     reasonText: 'Reason text'
   };
 
@@ -223,7 +223,7 @@ function makeLetter(id: string, status: Letter['status']) : Letter {
       supplierStatus: `supplier1#${status}`,
       supplierStatusSk: Date.now().toString(),
       ttl: 123,
-      reasonCode: 123,
+      reasonCode: 'R01',
       reasonText: "Reason text"
   };
 }

postman/Sandbox.postman_collection.json

@@ -754,7 +754,7 @@
                           "language": "json"
                         }
                       },
-                      "raw": "\n{\n  \"data\": {\n    \"attributes\": {\n      \"reasonCode\": 100,\n      \"reasonText\": \"failed validation\",\n      \"status\": \"CANCELLED\"\n    },\n    \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n    \"type\": \"Letter\"\n  }\n}"
+                      "raw": "\n{\n  \"data\": {\n    \"attributes\": {\n      \"reasonCode\": 'R01',\n      \"reasonText\": \"failed validation\",\n      \"status\": \"CANCELLED\"\n    },\n    \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n    \"type\": \"Letter\"\n  }\n}"
                     },
                     "header": [
                       {
@@ -1014,7 +1014,7 @@
                           "language": "json"
                         }
                       },
-                      "raw": "{\n  \"data\": {\n    \"attributes\": {\n      \"reasonCode\": 100,\n      \"reasonText\": \"failed validation\",\n      \"status\": \"FAILED\"\n    },\n    \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n    \"type\": \"Letter\"\n  }\n}"
+                      "raw": "{\n  \"data\": {\n    \"attributes\": {\n      \"reasonCode\": 'R01',\n      \"reasonText\": \"failed validation\",\n      \"status\": \"FAILED\"\n    },\n    \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n    \"type\": \"Letter\"\n  }\n}"
                     },
                     "header": [
                       {
@@ -1451,7 +1451,7 @@
                       "language": "json"
                     }
                   },
-                  "raw": "{\n  \"data\": [\n    {\n      \"attributes\": {\n        \"status\": \"PENDING\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"status\": \"ACCEPTED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"status\": \"PRINTED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"status\": \"ENCLOSED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"status\": \"DISPATCHED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"status\": \"DELIVERED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"reasonCode\": 100,\n        \"reasonText\": \"failed validation\",\n        \"status\": \"RETURNED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"reasonCode\": 100,\n        \"reasonText\": \"failed validation\",\n        \"status\": \"CANCELLED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"reasonCode\": 100,\n        \"reasonText\": \"failed validation\",\n        \"status\": \"FAILED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"reasonCode\": 100,\n        \"reasonText\": \"failed validation\",\n        \"status\": \"RETURNED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    }\n  ]\n}"
+                  "raw": "{\n  \"data\": [\n    {\n      \"attributes\": {\n        \"status\": \"PENDING\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"status\": \"ACCEPTED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"status\": \"PRINTED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"status\": \"ENCLOSED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"status\": \"DISPATCHED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"status\": \"DELIVERED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"reasonCode\": 'R01',\n        \"reasonText\": \"failed validation\",\n        \"status\": \"RETURNED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"reasonCode\": 'R01',\n        \"reasonText\": \"failed validation\",\n        \"status\": \"CANCELLED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"reasonCode\": 'R01',\n        \"reasonText\": \"failed validation\",\n        \"status\": \"FAILED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"reasonCode\": 'R01',\n        \"reasonText\": \"failed validation\",\n        \"status\": \"RETURNED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    }\n  ]\n}"
                 },
                 "header": [
                   {

sandbox/data/examples/patchLetter/requests/patchLetter_CANCELLED.json

@@ -1,8 +1,8 @@
 {
   "data": {
     "attributes": {
-      "reasonCode": "R01",
-      "reasonText": "failed validation",
+      "reasonCode": "R10",
+      "reasonText": "Miscellaneous",
       "status": "CANCELLED"
     },
     "id": "2WL5eYSWGzCHlGmzNxuqVusPxDg",

sandbox/data/examples/patchLetter/requests/patchLetter_FAILED.json

@@ -1,8 +1,8 @@
 {
   "data": {
     "attributes": {
-      "reasonCode": "R01",
-      "reasonText": "failed validation",
+      "reasonCode": "R10",
+      "reasonText": "Miscellaneous",
       "status": "FAILED"
     },
     "id": "2WL5eYSWGzCHlGmzNxuqVusPxDg",

sandbox/data/examples/patchLetter/requests/patchLetter_REJECTED.json

@@ -1,8 +1,8 @@
 {
   "data": {
     "attributes": {
-      "reasonCode": "R01",
-      "reasonText": "failed validation",
+      "reasonCode": "R07",
+      "reasonText": "No such address",
       "status": "REJECTED"
     },
     "id": "2WL5eYSWGzCHlGmzNxuqVusPxDg",

sandbox/data/examples/patchLetter/requests/patchLetter_RETURNED.json

@@ -2,7 +2,7 @@
   "data": {
     "attributes": {
       "reasonCode": "R01",
-      "reasonText": "failed validation",
+      "reasonText": "Addressee gone away",
       "status": "REJECTED"
     },
     "id": "2WL5eYSWGzCHlGmzNxuqVusPxDg",

sandbox/data/examples/patchLetter/responses/patchLetter_CANCELLED.json

@@ -1,8 +1,8 @@
 {
   "data": {
     "attributes": {
-      "reasonCode": "R01",
-      "reasonText": "failed validation",
+      "reasonCode": "R10",
+      "reasonText": "Miscellaneous",
       "specificationId": "2WL5eYSWGzCHlGmzNxuqVusPxDg",
       "status": "CANCELLED"
     },

sandbox/data/examples/patchLetter/responses/patchLetter_FAILED.json

@@ -1,8 +1,8 @@
 {
   "data": {
     "attributes": {
-      "reasonCode": "R01",
-      "reasonText": "failed validation",
+      "reasonCode": "R10",
+      "reasonText": "Miscellaneous",
       "specificationId": "2WL5eYSWGzCHlGmzNxuqVusPxDg",
       "status": "FAILED"
     },

sandbox/data/examples/patchLetter/responses/patchLetter_REJECTED.json

@@ -1,8 +1,8 @@
 {
   "data": {
     "attributes": {
-      "reasonCode": "R01",
-      "reasonText": "failed validation",
+      "reasonCode": "R07",
+      "reasonText": "No such address",
       "specificationId": "2WL5eYSWGzCHlGmzNxuqVusPxDg",
       "status": "REJECTED"
     },

sandbox/data/examples/patchLetter/responses/patchLetter_RETURNED.json

@@ -2,7 +2,7 @@
   "data": {
     "attributes": {
       "reasonCode": "R01",
-      "reasonText": "failed validation",
+      "reasonText": "Addressee gone away",
       "specificationId": "2WL5eYSWGzCHlGmzNxuqVusPxDg",
       "status": "RETURNED"
     },

specification/api/components/documentation/getLetterStatus.md

@@ -20,3 +20,20 @@ You can test the following scenarios in our sandbox environment
 | Retrieve a CANCELLED letter status      | `2XL5eYSWGzCHlGmzNxuqVusPxDg`|
 | Retrieve a FAILED letter status         | `2YL5eYSWGzCHlGmzNxuqVusPxDg`|
 | Retrieve a RETURNED letter status       | `2ZL5eYSWGzCHlGmzNxuqVusPxDg`|
+
+### Example Error Codes
+
+Examples of reason codes and text that may be returned include (but are not limited to)
+
+| Reason Code | Reason Text                |
+|-------------|----------------------------|
+|R01          |Addressee gone away         |
+|R02          |Address incomplete          |
+|R03          |Address inaccessible        |
+|R04          |Addressee unknown           |
+|R05          |Addressee gone away/Refused |
+|R06          |Not called for              |
+|R07          |No such address             |
+|R08          |No reason given             |
+|R09          |Deceased                    |
+|R10          |Miscellaneous               |

specification/api/components/documentation/patchLetter.md

@@ -24,3 +24,20 @@ Allowed `status` values that can be used to are:
 It is not possible to update a letter to status of `PENDING`.
 
 Optionally a `reasonCode` and `reasonText` explaining the status (for example, validation failures) can be included in the request body.
+
+### Example Error Codes
+
+Examples of reason codes and text that may be returned include (but are not limited to)
+
+| Reason Code | Reason Text                |
+|-------------|----------------------------|
+|R01          |Addressee gone away         |
+|R02          |Address incomplete          |
+|R03          |Address inaccessible        |
+|R04          |Addressee unknown           |
+|R05          |Addressee gone away/Refused |
+|R06          |Not called for              |
+|R07          |No such address             |
+|R08          |No reason given             |
+|R09          |Deceased                    |
+|R10          |Miscellaneous               |

specification/api/components/documentation/postLetters.md

@@ -26,3 +26,20 @@ Allowed `status` values that can be used to are:
 It is not possible to update a letter to status of `PENDING`.
 
 Optionally a `reasonCode` and `reasonText` explaining the status (for example, validation failures) can be included in the request body for each update.
+
+### Example Error Codes
+
+Examples of reason codes and text that may be returned include (but are not limited to)
+
+| Reason Code | Reason Text                |
+|-------------|----------------------------|
+|R01          |Addressee gone away         |
+|R02          |Address incomplete          |
+|R03          |Address inaccessible        |
+|R04          |Addressee unknown           |
+|R05          |Addressee gone away/Refused |
+|R06          |Not called for              |
+|R07          |No such address             |
+|R08          |No reason given             |
+|R09          |Deceased                    |
+|R10          |Miscellaneous               |

tests/component-tests/apiGateway-tests/testCases/UpdateLetterStatus.ts

@@ -8,7 +8,7 @@ export type PatchMessageRequestBody = {
     type: string;
     id: string;
     attributes: {
-      reasonCode?: string | number;
+      reasonCode?: string;
       reasonText?: string;
       status: string;
     };
@@ -20,7 +20,7 @@ export type PatchMessageResponseBody = {
     type: string;
     id: string;
     attributes: {
-      reasonCode?: number;
+      reasonCode?: string;
       reasonText?: string;
       status: string;
       specificationId:string;
@@ -64,7 +64,7 @@ export function patchFailureRequestBody (id: string, status: string) : PatchMess
     data: {
         attributes: {
           status: status,
-          reasonCode: 123,
+          reasonCode: 'R01',
           reasonText: 'Test Reason'
       },
       type: 'Letter',