ffc-pay-schemes 1.0.14 → 1.1.0

package/README.md

@@ -19,6 +19,8 @@ const {
   getAccountCodeMap,
   getBatchSequenceFromFileName,
   getJournalSourceFromPillar,
+  getPillarFromSchemeId,
+  getPillars,
   getReportingDataFilter,
   getSchemeBatchProperties,
   getSchemeFromBatchFileName,
@@ -44,6 +46,8 @@ const {
 - `getAccountCodeMap(schemeId)` returns the account code mapping used for a given `schemeId`.
 - `getBatchSequenceFromFileName(schemeId, fileName)` returns the sequence as identified in the supplied `fileName`, checking the correct position using the `schemeId`.
 - `getJournalSourceFromPillar(schemeId, source, pillar)` returns the appropriate manual source used in Payment journals for manual schemes, based on the supplied `pillar`. If `schemeId` is not the MANUAL scheme, or a match is not found, the supplied `source` will be returned.
+- `getPillarFromSchemeId(schemeId)` returns the pillar name for a given `schemeId`.
+- `getPillars()` returns all supported pillars.
 - `getReportingDataFilter(schemeId)` returns the fields which should be added to any data filters applied in reporting checks, for a given `schemeId`.
 - `getSchemeBatchProperties(schemeId)` returns the batch processing properties for a given `schemeId`.
 - `getSchemeFromBatchFileName(fileName)` returns the supported scheme details based on the expected file mask matching the supplied `fileName`.
@@ -95,12 +99,57 @@ The following services are intended to be used with the ffc-pay-schemes package:
 - ffc-pay-injection
 - ffc-pay-processing
 - ffc-pay-request-editor
+- ffc-pay-responses
 - ffc-pay-submission
 - ffc-pay-tracking
 - ffc-pay-web
 
 In the event a new payment scheme is added to the package, all of the above services must be bumped to the latest package version to ensure that Payment Hub can process associated payments.
 
+## Scheme onboarding process
+
+See the linked PR for an example of how to onboard a payment scheme with batch files to the ffc-pay-schemes package:
+
+<https://github.com/DEFRA/ffc-pay-schemes/pull/16>
+
+The below breakdown details all steps required for a general scheme onboarding:
+
+- Add the scheme's pillar name to `app/constants/pillars.js` - this allows the pillar to be recognised for manual payments in `ffc-pay-injection`
+- Add the manual source name for the scheme to `app/constants/manual-sources.js` - this defines the `source` name to use in D365 journals for manual payments for the scheme, created by `ffc-pay-submission`
+- Add the scheme batch properties to `app/constants/scheme-batch-properties.js` - this defines the naming convention for D365 journals for the scheme, created by `ffc-pay-submission`
+- Add the new scheme ID to `app/constants/scheme-ids.js` - this is the glue that holds payment processing together
+- Add the scheme name to `app/constants/scheme-names.js` - this is how the scheme will be referred to in all frontend services, and in system logs
+- Add the default scheme properties to `app/constants/schemes.js` - this is the primary driver for scheme defaults as read by `ffc-pay-enrichment`
+- Add the source system to `app/constants/source-systems.js` - this is how the scheme will be recognised by `ffc-pay-enrichment`, and allow the scheme ID to be determined
+- Add the scheme ID to the correct function in `app/create-invoice-number/index.js` - this is how the D365 formatted invoice number will be calculated in `ffc-pay-enrichment`
+- Add the scheme ID to the mapping in `app/get-account-code-map/index.js` - this is how account codes will be assigned to invoice lines with different description codes in `ffc-pay-processing` - this is only usually called for PPAs, but for good practice it should be determined for all schemes
+
+For all schemes supporting batch file ingestion:
+
+- Add details of the file mask to `app/constants/file-masks.js` - this should be the file mask as read by `ffc-pay-batch-processor`, and allows the service to recognise the file to be processed.
+- Add the file mask to the default scheme properties in `app/constants/schemes.js` - this is referenced by `ffc-pay-batch-processor`
+- Add the position of the sequence number within the payment file to `app/constants/sequence-positions.js` - as used by `ffc-pay-batch-processor` to determine the correct sequence number of the file for processing
+
+> Remember that ffc-pay-gateway must still be updated with the inbound file path, server name, and other configuration. See <https://github.com/DEFRA/ffc-pay-gateway/pull/78> for an example.
+
+For all schemes delivered via FRPS:
+
+- Add the scheme ID to `app/constants/frps-schemes.js` - this allows services to understand if it has been delivered by FRPS, helping with numerous helpers for FRPS specific behaviours
+
+For all schemes delivered via Siti Agri:
+
+- Add the scheme ID to `app/constants/siti-agri-schemes.js` - this allows services to understand if it has been delivered by Siti Agri, helping with numerous helpers for Siti Agri specific behaviours
+
+For all schemes which do not support PPAs:
+
+- Add the scheme ID to `app/constants/schemes-not-requiring-ppas.js` - this tells `ffc-pay-processing` not to calculate PPAs
+
+For all schemes which provide accounting values:
+
+- Add the scheme ID to `app/constants/schemes-providing-account-values.js` - this tells `ffc-pay-enrichment` to mark the payment request as providing accounting values, and enables correct value reporting in Payment Hub reports
+
+Completing all of these steps as required should allow Payment Hub to support payments for a new payment scheme, assuming there are no specific behaviours that differ from a general payment scheme.
+
 ## Licence
 
 THIS INFORMATION IS LICENSED UNDER THE CONDITIONS OF THE OPEN GOVERNMENT
@@ -122,4 +171,4 @@ public sector to license the use and re-use of their information under a common
 open licence.
 
 It is designed to encourage use and re-use of information freely and flexibly,
-with only a few conditions.
+with only a few conditions.

package/app/constants/file-masks.js

@@ -10,5 +10,6 @@ module.exports = {
   SFI23: /^SITISFIA\d{4}_AP_\d*.dat$/,
   DELINKED: /^SITIDP\d{4}_AP_\d*.dat$/,
   SFI_EXPANDED: /^ESFIO\d{4}_AP_\d*.dat$/,
-  COHT_CAPITAL: /^SITICOHTC\d{4}_AP_\d*.dat$/
+  COHT_CAPITAL: /^SITICOHTC\d{4}_AP_\d*.dat$/,
+  SFI26: /^SITISFI26\d{4}_AP_\d*.dat$/
 }

package/app/constants/manual-sources.js

@@ -35,7 +35,8 @@ const {
   COHT_CAPITAL,
   COHT_REVENUE,
   FPTT,
-  WMP
+  WMP,
+  SFI26
 } = require('./pillars')
 
 module.exports = {
@@ -75,5 +76,6 @@ module.exports = {
   [COHT_CAPITAL]: 'PMAN_COHTC',
   [COHT_REVENUE]: 'PMAN_COHTR',
   [FPTT]: 'PMAN_FPTT',
-  [WMP]: 'PMAN_WMP'
+  [WMP]: 'PMAN_WMP',
+  [SFI26]: 'PMAN_SFI26'
 }

package/app/constants/pillars.js

@@ -36,5 +36,6 @@ module.exports = {
   COHT_REVENUE: 'COHTR',
   COHT_CAPITAL: 'COHTC',
   FPTT: 'FPTT',
-  WMP: 'WMP'
+  WMP: 'WMP',
+  SFI26: 'SFI26'
 }

package/app/constants/scheme-batch-properties.js

@@ -102,5 +102,11 @@ module.exports = Object.freeze([
     prefix: 'FFCFALS_WMP',
     suffix: ' (FALS_WMP)',
     source: 'FALS_WMP'
+  },
+  {
+    schemeId: schemeIds.SFI26,
+    prefix: 'FFCSITISFI26',
+    suffix: ' (SITISFI26)',
+    source: 'SITISFI26'
   }
 ])

package/app/constants/scheme-ids.js

@@ -15,5 +15,6 @@ module.exports = {
   COHT_REVENUE: 15,
   COHT_CAPITAL: 16,
   FPTT: 17,
-  WMP: 18
+  WMP: 18,
+  SFI26: 19
 }

package/app/constants/scheme-names.js

@@ -1,19 +1,20 @@
 module.exports = {
-  SFI: 'Sustainable Farming Incentive 22',
-  SFI_PILOT: 'Sustainable Farming Incentive Pilot',
+  SFI: 'SFI-22',
+  SFI_PILOT: 'SFI-P',
   LUMP_SUMS: 'Lump Sums',
-  VET_VISITS: 'Annual Health and Welfare Review',
-  CS: 'Countryside Stewardship',
-  BPS: 'Basic Payment Scheme',
-  MANUAL: 'Manual Injection',
-  ES: 'Environmental Stewardship',
-  FC: 'Forestry Commission',
-  IMPS: 'Internal Market Payment Scheme',
-  SFI23: 'Sustainable Farming Incentive 23',
+  VET_VISITS: 'Vet Visits (AHWR)',
+  CS: 'CS',
+  BPS: 'BPS',
+  MANUAL: 'Manual Payments (Injection)',
+  ES: 'Genesis (ES)',
+  FC: 'GLOS (FC)',
+  IMPS: 'IMPS',
+  SFI23: 'SFI-23',
   DELINKED: 'Delinked Payments',
-  SFI_EXPANDED: 'Sustainable Farming Incentive Expanded Offer',
-  COHT_REVENUE: 'Combined Offer Higher Tier (Revenue)',
-  COHT_CAPITAL: 'Combined Offer Higher Tier (Capital)',
-  FPTT: 'Farm Payments Technical Test',
-  WMP: 'Woodland Management Plan'
+  SFI_EXPANDED: 'SFI-EO',
+  COHT_REVENUE: 'CS-HT (Revenue)',
+  COHT_CAPITAL: 'CS-HT (Capital)',
+  FPTT: 'FPTT',
+  WMP: 'WMP',
+  SFI26: 'SFI-26'
 }

package/app/constants/schemes.js

@@ -136,5 +136,13 @@ module.exports = Object.freeze([
     pillar: pillars.WMP,
     deliveryBody: RP10,
     fundCode: DRD10
+  },
+  {
+    schemeId: schemeIds.SFI26,
+    sourceSystem: sourceSystems.SFI26,
+    pillar: pillars.SFI26,
+    deliveryBody: RP00,
+    fundCode: DRD10,
+    fileMask: fileMasks.SFI26
   }
 ])

package/app/constants/sequence-positions.js

@@ -9,5 +9,6 @@ module.exports = {
   SFI23: 8,
   DELINKED: 6,
   SFI_EXPANDED: 5,
-  COHT_CAPITAL: 9
+  COHT_CAPITAL: 9,
+  SFI26: 9
 }

package/app/constants/siti-agri-schemes.js

@@ -1,3 +1,3 @@
-const { SFI, SFI_PILOT, LUMP_SUMS, CS, BPS, SFI23, DELINKED, SFI_EXPANDED, COHT_REVENUE, COHT_CAPITAL } = require('../constants/scheme-ids')
+const { SFI, SFI_PILOT, LUMP_SUMS, CS, BPS, SFI23, DELINKED, SFI_EXPANDED, COHT_REVENUE, COHT_CAPITAL, SFI26 } = require('../constants/scheme-ids')
 
-module.exports = [SFI, SFI_PILOT, LUMP_SUMS, CS, BPS, SFI23, DELINKED, SFI_EXPANDED, COHT_REVENUE, COHT_CAPITAL]
+module.exports = [SFI, SFI_PILOT, LUMP_SUMS, CS, BPS, SFI23, DELINKED, SFI_EXPANDED, COHT_REVENUE, COHT_CAPITAL, SFI26]

package/app/constants/source-systems.js

@@ -15,5 +15,6 @@ module.exports = {
   COHT_REVENUE: 'COHTR',
   COHT_CAPITAL: 'COHTC',
   FPTT: 'FPTT',
-  WMP: 'WMP'
+  WMP: 'WMP',
+  SFI26: 'SFI26'
 }

package/app/create-invoice-number/index.js

@@ -1,5 +1,5 @@
 const { MANUAL: MANUAL_SOURCE } = require('../constants/source-systems')
-const { MANUAL, FC, FPTT, WMP, DELINKED, SFI_EXPANDED, COHT_REVENUE, COHT_CAPITAL, SFI, SFI_PILOT, LUMP_SUMS, CS, BPS, SFI23, ES, IMPS } = require('../constants/scheme-ids')
+const { MANUAL, FC, FPTT, WMP, DELINKED, SFI_EXPANDED, COHT_REVENUE, COHT_CAPITAL, SFI, SFI_PILOT, LUMP_SUMS, CS, BPS, SFI23, ES, IMPS, SFI26 } = require('../constants/scheme-ids')
 const { createStandardSchemeInvoiceNumber } = require('./create-standard-scheme-invoice-number')
 const { createSitiAgriInvoiceNumber } = require('./create-siti-agri-invoice-number')
 const { createESInvoiceNumber } = require('./create-es-invoice-number')
@@ -12,7 +12,7 @@ const createInvoiceNumber = (paymentRequest) => {
     if (schemesWithAcceptedInvoiceNumbers.has(paymentRequest.schemeId) || paymentRequest?.sourceSystem === MANUAL_SOURCE) {
       return paymentRequest.invoiceNumber
     }
-    const standardSchemeInvoices = new Set([DELINKED, SFI_EXPANDED, COHT_REVENUE, COHT_CAPITAL])
+    const standardSchemeInvoices = new Set([DELINKED, SFI_EXPANDED, COHT_REVENUE, COHT_CAPITAL, SFI26])
     if (standardSchemeInvoices.has(paymentRequest.schemeId)) {
       return createStandardSchemeInvoiceNumber(paymentRequest)
     }

package/app/get-account-code-map/index.js

@@ -11,7 +11,8 @@ const {
   COHT_REVENUE,
   COHT_CAPITAL,
   FPTT,
-  WMP
+  WMP,
+  SFI26
 } = require('../constants/scheme-ids')
 
 const defaultMap = require('./default-map')
@@ -36,7 +37,8 @@ const schemeMap = new Map([
   [COHT_REVENUE, defaultMap],
   [COHT_CAPITAL, cohtcMap],
   [FPTT, sfiFrpsMap],
-  [WMP, sfiFrpsMap]
+  [WMP, sfiFrpsMap],
+  [SFI26, sfiFrpsMap]
 ])
 
 const getAccountCodeMap = (schemeId) => {

package/app/pillar/get-pillar-from-scheme-id.js

@@ -0,0 +1,11 @@
+const { UNKNOWN } = require('../constants/unknown')
+const { getSchemes } = require('../scheme-properties/get-schemes')
+
+const getPillarFromSchemeId = (schemeId) => {
+  const matchingScheme = getSchemes().find((scheme) => scheme.schemeId === schemeId)
+  return matchingScheme?.pillar ?? UNKNOWN
+}
+
+module.exports = {
+  getPillarFromSchemeId
+}

package/app/pillar/get-pillars.js

@@ -0,0 +1,9 @@
+const pillars = require('../constants/pillars')
+
+const getPillars = () => {
+  return pillars
+}
+
+module.exports = {
+  getPillars
+}

package/index.js

@@ -3,6 +3,8 @@ const { createSplitInvoiceNumber } = require('./app/create-split-invoice-number'
 const { getAccountCodeMap } = require('./app/get-account-code-map')
 const { getBatchSequenceFromFileName } = require('./app/helpers/get-batch-sequence-from-file-name')
 const { getJournalSourceFromPillar } = require('./app/helpers/get-journal-source-from-pillar')
+const { getPillarFromSchemeId } = require('./app/pillar/get-pillar-from-scheme-id')
+const { getPillars } = require('./app/pillar/get-pillars')
 const { getReportingDataFilter } = require('./app/helpers/get-reporting-data-filter')
 const { getSchemeBatchProperties } = require('./app/scheme-properties/get-scheme-batch-properties')
 const { getSchemeFromBatchFileName } = require('./app/scheme-properties/get-scheme-from-batch-file-name')
@@ -27,6 +29,8 @@ module.exports = {
   getAccountCodeMap,
   getBatchSequenceFromFileName,
   getJournalSourceFromPillar,
+  getPillarFromSchemeId,
+  getPillars,
   getReportingDataFilter,
   getSchemeBatchProperties,
   getSchemeFromBatchFileName,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffc-pay-schemes",
-  "version": "1.0.14",
+  "version": "1.1.0",
   "description": "Module for defining and providing details for the payment schemes supported by the Payment Hub.",
   "main": "index.js",
   "scripts": {

package/test/unit/pillar/get-pillar-from-scheme-id.test.js

@@ -0,0 +1,51 @@
+jest.mock('../../../app/scheme-properties/get-schemes', () => ({
+  getSchemes: jest.fn()
+}))
+
+const { UNKNOWN } = require('../../../app/constants/unknown')
+const { getSchemes } = require('../../../app/scheme-properties/get-schemes')
+const { getPillarFromSchemeId } = require('../../../app/pillar/get-pillar-from-scheme-id')
+
+describe('getPillarFromSchemeId', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  test('returns the pillar for a matching scheme ID', () => {
+    getSchemes.mockReturnValue([
+      {
+        schemeId: 1,
+        schemeName: 'Example Scheme',
+        pillar: 'Example Pillar'
+      }
+    ])
+
+    expect(getPillarFromSchemeId(1)).toBe('Example Pillar')
+  })
+
+  test('returns unknown when the scheme ID is not found', () => {
+    getSchemes.mockReturnValue([
+      {
+        schemeId: 1,
+        schemeName: 'Example Scheme',
+        pillar: 'Example Pillar'
+      }
+    ])
+
+    expect(getPillarFromSchemeId(2)).toBe(UNKNOWN)
+  })
+
+  test('returns unknown when no schemes are available', () => {
+    getSchemes.mockReturnValue([])
+
+    expect(getPillarFromSchemeId(2)).toBe(UNKNOWN)
+  })
+
+  test('gets schemes before searching for the pillar', () => {
+    getSchemes.mockReturnValue([])
+
+    getPillarFromSchemeId(2)
+
+    expect(getSchemes).toHaveBeenCalledTimes(1)
+  })
+})

package/test/unit/pillar/get-pillars.test.js

@@ -0,0 +1,8 @@
+const { getPillars } = require('../../../app/pillar/get-pillars')
+const pillars = require('../../../app/constants/pillars')
+
+describe('getPillars', () => {
+  test('returns all pillars', () => {
+    expect(getPillars()).toEqual(pillars)
+  })
+})