Merge pull request #901 from US-Trustee-Program/CAMS-282-auditable

Cams 282 auditable

backend/functions/lib/use-cases/case-assignment.ts

@@ -79,9 +79,9 @@ export class CaseAssignmentUseCase {
           role: CamsRole[role],
           assignedOn: currentDate,
         },
-        context.session,
-        { updatedOn: currentDate },
+        context.session?.user,
       );
+      assignment.updatedOn = currentDate;
       listOfAssignments.push(assignment);
     });
     const listOfAssignmentIdsCreated: string[] = [];
@@ -122,9 +122,9 @@ export class CaseAssignmentUseCase {
         before: existingAssignmentRecords,
         after: newAssignmentRecords,
       },
-      context.session,
-      { updatedOn: currentDate },
+      context.session?.user,
     );
+    history.updatedOn = currentDate;
     await this.casesRepository.createCaseHistory(context, history);
 
     context.logger.info(

backend/functions/lib/use-cases/orders/orders.ts

@@ -145,7 +145,7 @@ export class OrdersUseCase {
           before: initialOrder as TransferOrder,
           after: order,
         },
-        context.session,
+        context.session?.user,
       );
       await this.casesRepo.createCaseHistory(context, caseHistory);
     }
@@ -212,7 +212,7 @@ export class OrdersUseCase {
             before: null,
             after: order,
           },
-          context.session,
+          context.session?.user,
         );
         await this.casesRepo.createCaseHistory(context, caseHistory);
       }
@@ -238,7 +238,7 @@ export class OrdersUseCase {
           before: null,
           after: history,
         },
-        context.session,
+        context.session?.user,
       );
       await this.casesRepo.createCaseHistory(context, caseHistory);
     }
@@ -314,7 +314,7 @@ export class OrdersUseCase {
         before: isConsolidationHistory(before) ? before : null,
         after,
       },
-      context.session,
+      context.session?.user,
     );
   }
 

common/src/cams/auditable.ts

@@ -1,5 +1,5 @@
-import { CamsSession, getCamsUserReference } from './session';
 import { CamsUserReference } from './users';
+import { getCamsUserReference } from './session';
 
 export type Auditable = {
   updatedOn: string;
@@ -8,15 +8,20 @@ export type Auditable = {
 
 export const SYSTEM_USER_REFERENCE: CamsUserReference = { id: 'SYSTEM', name: 'SYSTEM' };
 
+/**
+ * Decorates the record with the Auditable properties. Any necessary overriding of the properties must be completed
+ * after or in lieu of calling this function.
+ * @param record T extends Auditable required The record to be decorated.
+ * @param camsUser CamsUserReference optional The user to be assigned to `updatedBy`. Defaults to the system user, so
+ * this parameter MUST be provided for user-initiated actions.
+ */
 export function createAuditRecord<T extends Auditable>(
   record: Omit<T, 'updatedOn' | 'updatedBy'>,
-  session?: CamsSession,
-  override?: Partial<Auditable>,
+  camsUser: CamsUserReference = SYSTEM_USER_REFERENCE,
 ): T {
   return {
-    updatedOn: new Date().toISOString(),
-    updatedBy: session ? getCamsUserReference(session.user) : SYSTEM_USER_REFERENCE,
     ...record,
-    ...override,
+    updatedOn: new Date().toISOString(),
+    updatedBy: getCamsUserReference(camsUser),
   } as T;
 }

docs/architecture/decision-records/Auditable.md

@@ -0,0 +1,38 @@
+# Auditable
+
+## Context
+
+A historical record needs to be kept related to certain data points in CAMS. This historical record involves tracking when a change was made, and by whom. We were previously managing this for orders and assignments in an ad hoc manner. To ensure consistency and to reduce boilerplate code, we need a way to provide this functionality through code common to all data types that require historical records.
+
+## Decision
+
+We have created the `Auditable` type which contains the common properties for history. We have also created the `createAuditRecord` function which provides default values for the properties. Overriding any of the properties of `Auditable` must be completed aside from calling this helper function but prior to persisting the record. This avoids issues with having two optional parameters.
+
+Consider the example type—`Foo`—as follows:
+
+```typescript
+type Foo = Auditable & {
+  prop1: string;
+  prop2: number;
+}
+```
+
+To create a historical record for an action initiated by a user, call the `createAuditRecord` as follows:
+
+```typescript
+createAuditRecord<Foo>(someFoo, context.session.user);
+```
+
+To create a historical record for an action initiated by the system, call the `createAuditRecord` as follows:
+
+```typescript
+createAuditRecord<Foo>(someFoo);
+```
+
+## Status
+
+Approved
+
+## Consequences
+
+Developers need to remember to make use of this type and the function, but it should reduce the amount of boilerplate/duplicate code we have to write to track history.