feat(GIFT-3546): add endpoint to fetch customer data

.env.sample

@@ -30,6 +30,14 @@ DATABASE_CEDAR_NAME=
 # CIS
 DATABASE_CIS_NAME=
 
+# ODS
+DATABASE_ODS_HOST=
+DATABASE_ODS_PORT=
+DATABASE_ODS_CLIENT_ID=
+DATABASE_ODS_TENANT_ID=
+DATABASE_ODS_CLIENT_SECRET=
+DATABASE_ODS_NAME=
+
 # API
 API_KEY=
 

.github/workflows/deployment.yml

@@ -135,6 +135,12 @@ jobs:
             "DATABASE_NUMBER_GENERATOR_NAME=${{ secrets.DATABASE_NUMBER_GENERATOR_NAME }}" \
             "DATABASE_CEDAR_NAME=${{ secrets.DATABASE_CEDAR_NAME }}" \
             "DATABASE_CIS_NAME=${{ secrets.DATABASE_CIS_NAME }}" \
+            "DATABASE_ODS_HOST=${{ secrets.DATABASE_ODS_HOST }}" \
+            "DATABASE_ODS_PORT=${{ secrets.DATABASE_ODS_PORT }}" \
+            "DATABASE_ODS_CLIENT_ID=${{ secrets.DATABASE_ODS_CLIENT_ID }}" \
+            "DATABASE_ODS_TENANT_ID=${{ secrets.DATABASE_ODS_TENANT_ID }}" \
+            "DATABASE_ODS_CLIENT_SECRET=${{ secrets.DATABASE_ODS_CLIENT_SECRET }}" \
+            "DATABASE_ODS_NAME=${{ secrets.DATABASE_ODS_NAME }}" \
             "APIM_INFORMATICA_URL=${{ secrets.APIM_INFORMATICA_URL }}" \
             "APIM_INFORMATICA_USERNAME=${{ secrets.APIM_INFORMATICA_USERNAME }}" \
             "APIM_INFORMATICA_PASSWORD=${{ secrets.APIM_INFORMATICA_PASSWORD }}" \

.github/workflows/test.yml

@@ -10,7 +10,7 @@ run-name: Executing test QA on ${{ github.repository }} 🚀
 
 on:
   pull_request:
-    branches: [main]
+    branches: [main, feat/FN-3543/integrate-with-ods]
     paths:
       - "**"
 

docker-compose.yml

@@ -28,6 +28,12 @@ services:
       DATABASE_NUMBER_GENERATOR_NAME:
       DATABASE_CEDAR_NAME:
       DATABASE_CIS_NAME:
+      DATABASE_ODS_HOST:
+      DATABASE_ODS_PORT:
+      DATABASE_ODS_CLIENT_ID:
+      DATABASE_ODS_TENANT_ID:
+      DATABASE_ODS_CLIENT_SECRET:
+      DATABASE_ODS_NAME:
       APIM_INFORMATICA_URL:
       APIM_INFORMATICA_USERNAME:
       APIM_INFORMATICA_PASSWORD:

src/config/database.config.ts

@@ -32,5 +32,13 @@ export default registerAs(
       password: process.env.DATABASE_PASSWORD,
       name: process.env.DATABASE_CIS_NAME,
     },
+    mssql_ods: {
+      host: process.env.DATABASE_ODS_HOST,
+      port: +process.env.DATABASE_ODS_PORT,
+      client_id: process.env.DATABASE_ODS_CLIENT_ID,
+      tenant_id: process.env.DATABASE_ODS_TENANT_ID,
+      client_secret: process.env.DATABASE_ODS_CLIENT_SECRET,
+      name: process.env.DATABASE_ODS_NAME,
+    },
   }),
 );

src/constants/database-name.constant.ts

@@ -3,4 +3,5 @@ export const DATABASE = {
   MDM: 'mssql-mdm',
   CIS: 'mssql-cis',
   NUMBER_GENERATOR: 'mssql-number-generator',
+  ODS: 'mssql-ods',
 };

src/modules/database/database.module.ts

@@ -4,9 +4,10 @@ import { MsSqlCedarDatabaseModule } from './mssql-cedar-database.module';
 import { MsSqlCisDatabaseModule } from './mssql-cis-database.module';
 import { MsSqlMdmDatabaseModule } from './mssql-mdm-database.module';
 import { MsSqlNumberGeneratorDatabaseModule } from './mssql-number-generator-database.module';
+import { MsSqlOdsDatabaseModule } from './mssql-ods-database.module';
 
 @Module({
-  imports: [MsSqlMdmDatabaseModule, MsSqlCedarDatabaseModule, MsSqlCisDatabaseModule, MsSqlNumberGeneratorDatabaseModule],
-  exports: [MsSqlMdmDatabaseModule, MsSqlCedarDatabaseModule, MsSqlCisDatabaseModule, MsSqlNumberGeneratorDatabaseModule],
+  imports: [MsSqlMdmDatabaseModule, MsSqlCedarDatabaseModule, MsSqlCisDatabaseModule, MsSqlNumberGeneratorDatabaseModule, MsSqlOdsDatabaseModule],
+  exports: [MsSqlMdmDatabaseModule, MsSqlCedarDatabaseModule, MsSqlCisDatabaseModule, MsSqlNumberGeneratorDatabaseModule, MsSqlOdsDatabaseModule],
 })
 export class DatabaseModule {}

src/modules/database/mssql-ods-database.module.ts

@@ -0,0 +1,37 @@
+import { Module } from '@nestjs/common';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { DATABASE } from '@ukef/constants';
+
+@Module({
+  imports: [
+    TypeOrmModule.forRootAsync({
+      name: DATABASE.ODS,
+      imports: [ConfigModule],
+      inject: [ConfigService],
+      useFactory: (configService: ConfigService) => ({
+        name: DATABASE.ODS,
+        host: configService.get<string>('database.mssql_ods.host'),
+        port: configService.get<number>('database.mssql_ods.port'),
+        database: configService.get<string>('database.mssql_ods.name'),
+        type: 'mssql',
+        authentication: {
+          type: 'azure-active-directory-service-principal-secret',
+          options: {
+            clientId: configService.get<string>('database.mssql_ods.client_id'),
+            clientSecret: configService.get<string>('database.mssql_ods.client_secret'),
+            tenantId: configService.get<string>('database.mssql_ods.tenant_id'),
+          },
+        },
+        extra: {
+          options: {
+            encrypt: true,
+            trustServerCertificate: true,
+            useUTC: true,
+          },
+        },
+      }),
+    }),
+  ],
+})
+export class MsSqlOdsDatabaseModule {}

src/modules/mdm.module.ts

@@ -14,6 +14,7 @@ import { NumbersModule } from '@ukef/modules/numbers/numbers.module';
 import { PremiumSchedulesModule } from '@ukef/modules/premium-schedules/premium-schedules.module';
 import { SectorIndustriesModule } from '@ukef/modules/sector-industries/sector-industries.module';
 import { YieldRatesModule } from '@ukef/modules/yield-rates/yield-rates.module';
+import { OdsModule } from './ods/ods.module';
 
 @Module({
   imports: [
@@ -27,6 +28,7 @@ import { YieldRatesModule } from '@ukef/modules/yield-rates/yield-rates.module';
     InterestRatesModule,
     MarketsModule,
     NumbersModule,
+    OdsModule,
     PremiumSchedulesModule,
     SectorIndustriesModule,
     YieldRatesModule,
@@ -44,6 +46,7 @@ import { YieldRatesModule } from '@ukef/modules/yield-rates/yield-rates.module';
     InterestRatesModule,
     MarketsModule,
     NumbersModule,
+    OdsModule,
     PremiumSchedulesModule,
     SectorIndustriesModule,
     YieldRatesModule,

src/modules/ods/dto/get-ods-customer-param.dto.ts

@@ -0,0 +1,15 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { CUSTOMERS, UKEFID } from '@ukef/constants';
+import { regexToString } from '@ukef/helpers/regex.helper';
+import { Matches } from 'class-validator';
+
+export class GetOdsCustomerParamDto {
+  @ApiProperty({
+    required: true,
+    example: CUSTOMERS.EXAMPLES.PARTYURN,
+    description: 'The unique UKEF id of the customer to search for.',
+    pattern: regexToString(UKEFID.PARTY_ID.REGEX),
+  })
+  @Matches(UKEFID.PARTY_ID.REGEX)
+  public urn: string;
+}

src/modules/ods/dto/get-ods-customer-response.dto.ts

@@ -0,0 +1,15 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export class GetOdsCustomerResponse {
+  @ApiProperty({
+    description: 'The unique UKEF id of the customer',
+    example: '00312345',
+  })
+  readonly urn: string;
+
+  @ApiProperty({
+    description: 'Customer name',
+    example: 'Test Company name',
+  })
+  readonly name: string;
+}

src/modules/ods/dto/ods-payloads.dto.ts

@@ -0,0 +1,36 @@
+// Customer Stored Procedure query params can be found here https://github.com/UK-Export-Finance/database-ods-datateam/blob/dev/t_apim/Stored%20Procedures/sp_ODS_get_customer.sql#L12
+export type OdsCustomerStoredProcedureQueryParams = {
+  customer_party_unique_reference_number: string;
+};
+
+export type OdsStoredProcedureQueryParams = OdsCustomerStoredProcedureQueryParams;
+
+// Stored Procedure input definition can be found here https://github.com/UK-Export-Finance/database-ods-datateam/blob/dev/t_apim/Stored%20Procedures/sp_ODS_query.sql#L10-L14
+export type OdsStoredProcedureInput = {
+  query_method: string;
+  query_object: OdsEntity;
+  query_page_size: number;
+  query_page_index: number;
+  query_parameters: OdsStoredProcedureQueryParams;
+};
+
+// The output of the stored procedure is in this format, returning a string that needs to be parsed
+// to JSON to give the OdsStoredProcedureOuputBody type
+export type OdsStoredProcedureOutput = {
+  output_body: string;
+}[];
+
+// Stored Procedure output definition can be found here https://github.com/UK-Export-Finance/database-ods-datateam/blob/dev/t_apim/Stored%20Procedures/sp_ODS_query.sql#L279-L286
+export type OdsStoredProcedureOuputBody = {
+  query_request_id: string;
+  message: string;
+  status: 'SUCCESS' | 'ERROR';
+  total_result_count: number;
+  results: Record<string, any>[];
+};
+
+export const ODS_ENTITIES = {
+  CUSTOMER: 'customer',
+} as const;
+
+export type OdsEntity = (typeof ODS_ENTITIES)[keyof typeof ODS_ENTITIES];

src/modules/ods/ods.controller.test.ts

@@ -0,0 +1,30 @@
+import { CUSTOMERS } from '@ukef/constants';
+import { when } from 'jest-when';
+import { OdsController } from './ods.controller';
+import { OdsService } from './ods.service';
+
+describe('OdsController', () => {
+  let odsServiceFindCustomer: jest.Mock;
+
+  let controller: OdsController;
+
+  beforeEach(() => {
+    const odsService = new OdsService(null, null);
+    odsServiceFindCustomer = jest.fn();
+    odsService.findCustomer = odsServiceFindCustomer;
+
+    controller = new OdsController(odsService);
+  });
+
+  describe('findCustomer', () => {
+    it('should return the customer when a valid customer URN is provided', async () => {
+      const mockCustomerDetails = { urn: CUSTOMERS.EXAMPLES.PARTYURN, name: 'Test name' };
+
+      when(odsServiceFindCustomer).calledWith(CUSTOMERS.EXAMPLES.PARTYURN).mockResolvedValueOnce(mockCustomerDetails);
+
+      const customers = await controller.findCustomer({ urn: CUSTOMERS.EXAMPLES.PARTYURN });
+
+      expect(customers).toEqual(mockCustomerDetails);
+    });
+  });
+});

src/modules/ods/ods.controller.ts

@@ -0,0 +1,30 @@
+import { Controller, Get, Param, Query } from '@nestjs/common';
+import { ApiNotFoundResponse, ApiOperation, ApiResponse, ApiTags, ApiBadRequestResponse } from '@nestjs/swagger';
+import { OdsService } from './ods.service';
+import { GetOdsCustomerParamDto } from './dto/get-ods-customer-param.dto';
+import { GetOdsCustomerResponse } from './dto/get-ods-customer-response.dto';
+
+@ApiTags('ods')
+@Controller('ods')
+export class OdsController {
+  constructor(private readonly odsService: OdsService) {}
+
+  @Get('customers/:customerUrn')
+  @ApiOperation({
+    summary: 'Get customers from ODS',
+  })
+  @ApiResponse({
+    status: 200,
+    description: 'Customers matching search parameters',
+    type: GetOdsCustomerResponse,
+  })
+  @ApiNotFoundResponse({
+    description: 'Customer not found.',
+  })
+  @ApiBadRequestResponse({
+    description: 'Invalid search parameters provided.',
+  })
+  findCustomer(@Param() param: GetOdsCustomerParamDto): Promise<GetOdsCustomerResponse> {
+    return this.odsService.findCustomer(param.urn);
+  }
+}

src/modules/ods/ods.module.ts

@@ -0,0 +1,11 @@
+import { Module } from '@nestjs/common';
+import { OdsController } from './ods.controller';
+import { OdsService } from './ods.service';
+import { MsSqlOdsDatabaseModule } from '../database/mssql-ods-database.module';
+
+@Module({
+  imports: [MsSqlOdsDatabaseModule],
+  controllers: [OdsController],
+  providers: [OdsService],
+})
+export class OdsModule {}

src/modules/ods/ods.service.test.ts

@@ -0,0 +1,107 @@
+import { OdsService } from './ods.service';
+import { ODS_ENTITIES, OdsStoredProcedureInput } from './dto/ods-payloads.dto';
+import { CUSTOMERS } from '@ukef/constants';
+import { DataSource, QueryRunner } from 'typeorm';
+
+describe('OdsService', () => {
+  let service: OdsService;
+  let mockQueryRunner: jest.Mocked<QueryRunner>;
+  let mockDataSource: jest.Mocked<DataSource>;
+
+  beforeEach(() => {
+    mockQueryRunner = {
+      query: jest.fn(),
+      release: jest.fn(),
+    } as unknown as jest.Mocked<QueryRunner>;
+
+    mockDataSource = {
+      createQueryRunner: jest.fn().mockReturnValue(mockQueryRunner),
+    } as unknown as jest.Mocked<DataSource>;
+
+    service = new OdsService(mockDataSource, null);
+  });
+
+  describe('callOdsStoredProcedure', () => {
+    it('should call the stored procedure with the query runner', async () => {
+      const mockInput: OdsStoredProcedureInput = service.createOdsStoredProcedureInput(ODS_ENTITIES.CUSTOMER, {
+        customer_party_unique_reference_number: CUSTOMERS.EXAMPLES.PARTYURN,
+      });
+
+      const mockResult = [{ output_body: JSON.stringify({ id: '123', name: 'Test Customer' }) }];
+      mockQueryRunner.query.mockResolvedValue(mockResult);
+
+      const result = await service.callOdsStoredProcedure(mockInput);
+
+      expect(mockDataSource.createQueryRunner).toHaveBeenCalled();
+      expect(mockQueryRunner.query).toHaveBeenCalledWith(
+        expect.stringMatching(
+          /DECLARE @output_body NVARCHAR\(MAX\);\s*EXEC t_apim\.sp_ODS_query @input_body=@0, @output_body=@output_body OUTPUT;\s*SELECT @output_body as output_body\s*/,
+        ),
+        [JSON.stringify(mockInput)],
+      );
+      expect(result).toEqual(mockResult);
+      expect(mockQueryRunner.release).toHaveBeenCalled();
+    });
+  });
+
+  describe('findCustomer', () => {
+    it('findCustomer should return a customer the customer urn and name when findCustomer is called', async () => {
+      const mockCustomer = { urn: CUSTOMERS.EXAMPLES.PARTYURN, name: 'Test Customer' };
+      const mockStoredProcedureOutput = [
+        {
+          output_body: `{
+            "query_request_id": "Test ID",
+            "message": "SUCCESS",
+            "status": "SUCCESS",
+            "total_result_count": 1,
+            "results": [
+              {
+                "customer_party_unique_reference_number": "${mockCustomer.urn}",
+                "customer_name": "${mockCustomer.name}",
+                "customer_companies_house_number": "12345678",
+                "customer_addresses": [
+                  {
+                    "customer_address_type": "Registered",
+                    "customer_address_street": "Test Street",
+                    "customer_address_postcode": "AA1 1BB",
+                    "customer_address_country": "United Kingdom",
+                    "customer_address_city": "Test City"
+                  }
+                ]
+              }
+            ]
+          }`,
+        },
+      ];
+      const mockInput: OdsStoredProcedureInput = service.createOdsStoredProcedureInput(ODS_ENTITIES.CUSTOMER, {
+        customer_party_unique_reference_number: mockCustomer.urn,
+      });
+
+      jest.spyOn(service, 'callOdsStoredProcedure').mockResolvedValue(mockStoredProcedureOutput);
+
+      const result = await service.findCustomer(mockCustomer.urn);
+
+      expect(service.callOdsStoredProcedure).toHaveBeenCalledWith(mockInput);
+      expect(result).toEqual(mockCustomer);
+    });
+  });
+
+  describe('createOdsStoredProcedureInput', () => {
+    it('should map the inputs to the stored procedure input format', async () => {
+      const exampleCustomerQueryParameters = {
+        customer_party_unique_reference_number: CUSTOMERS.EXAMPLES.PARTYURN,
+      };
+
+      const expected: OdsStoredProcedureInput = {
+        query_method: 'get',
+        query_object: ODS_ENTITIES.CUSTOMER,
+        query_page_size: 1,
+        query_page_index: 1,
+        query_parameters: exampleCustomerQueryParameters,
+      };
+      const result = service.createOdsStoredProcedureInput(ODS_ENTITIES.CUSTOMER, exampleCustomerQueryParameters);
+
+      expect(result).toEqual(expected);
+    });
+  });
+});