Display purposes in view licence page summary tab

app/models/licence-version-purpose.model.js

@@ -0,0 +1,31 @@
+'use strict'
+
+/**
+ * Model for LicenceVersionPurposes (water.licence_version_purposes)
+ * @module LicenceVersionPurposes
+ */
+
+const { Model } = require('objection')
+
+const BaseModel = require('./base.model.js')
+
+class LicenceVersionPurposes extends BaseModel {
+  static get tableName () {
+    return 'licenceVersionPurposes'
+  }
+
+  static get relationMappings () {
+    return {
+      licenceVersion: {
+        relation: Model.BelongsToOneRelation,
+        modelClass: 'licence-version.model',
+        join: {
+          from: 'licenceVersionPurposes.licenceVersionId',
+          to: 'licenceVersions.id'
+        }
+      }
+    }
+  }
+}
+
+module.exports = LicenceVersionPurposes

app/models/licence-version.model.js

@@ -23,6 +23,18 @@ class LicenceVersionModel extends BaseModel {
           from: 'licenceVersions.licenceId',
           to: 'licences.id'
         }
+      },
+      purposes: {
+        relation: Model.ManyToManyRelation,
+        modelClass: 'purpose.model',
+        join: {
+          from: 'licenceVersions.id',
+          through: {
+            from: 'licenceVersionPurposes.licenceVersionId',
+            to: 'licenceVersionPurposes.purposeId'
+          },
+          to: 'purposes.id'
+        }
       }
     }
   }

app/presenters/licences/view-licence.presenter.js

@@ -15,7 +15,17 @@ const { formatLongDate } = require('../base.presenter.js')
  * @returns {Object} The data formatted for the view template
  */
 function go (licence) {
-  const { ends, expiredDate, id, licenceDocumentHeader, licenceHolder, licenceRef, region, startDate } = licence
+  const {
+    ends,
+    expiredDate,
+    id,
+    licenceDocumentHeader,
+    licenceHolder,
+    licenceRef,
+    licenceVersions,
+    region,
+    startDate
+  } = licence
 
   return {
     id,
@@ -24,6 +34,7 @@ function go (licence) {
     licenceHolder: _generateLicenceHolder(licenceHolder),
     licenceRef,
     pageTitle: `Licence ${licenceRef}`,
+    purposes: _generatePurposes(licenceVersions),
     region: region.displayName,
     startDate: formatLongDate(startDate),
     warning: _generateWarningMessage(ends)
@@ -46,6 +57,22 @@ function _generateLicenceHolder (licenceHolder) {
   return licenceHolder
 }
 
+function _generatePurposes (licenceVersions) {
+  if (!licenceVersions || licenceVersions.length === 0 || licenceVersions[0]?.purposes.length === 0) {
+    return null
+  }
+  const allPurposeDescriptions = licenceVersions[0].purposes.map((item) => {
+    return item.description
+  })
+
+  const uniquePurposes = [...new Set(allPurposeDescriptions)]
+
+  return {
+    caption: uniquePurposes.length === 1 ? 'Purpose' : 'Purposes',
+    data: uniquePurposes
+  }
+}
+
 function _generateWarningMessage (ends) {
   if (!ends) {
     return null

app/services/licences/fetch-licence.service.js

@@ -55,6 +55,7 @@ async function _fetchLicence (id) {
         'id'
       ])
     })
+    .withGraphFetched('licenceVersions.[purposes]')
     .modify('licenceHolder')
 
   return result

app/views/licences/tabs/summary.njk

@@ -4,7 +4,7 @@
 <h2 class="govuk-heading-l">Summary</h2>
 
 <dl class="govuk-summary-list">
-    <div class="govuk-summary-list__row">
+<div class="govuk-summary-list__row">
         <dt class="govuk-summary-list__key">Licence Holder</dt>
         <dd class="govuk-summary-list__value">
             <span class="govuk-form-group">{{ licenceHolder }}</span>
@@ -23,13 +23,28 @@
     {% endif %}
 
     <div class="govuk-summary-list__row">
-        <dt class="govuk-summary-list__key">
-            Billing region
-        </dt>
-        <dd class="govuk-summary-list__value">
-            {{ region }}
-        </dd>
+        <dt class="govuk-summary-list__key">Billing region</dt>
+        <dd class="govuk-summary-list__value">{{ region }}</dd>
     </div>
+
+    {% if purposes %}
+        <div class="govuk-summary-list__row">
+            <dt class="govuk-summary-list__key">{{ purposes.caption }}</dt>
+            <dd class="govuk-summary-list__value">
+                {% if purposes.data.length > 5 %}
+                    You have {{ purposes.data.length }} purposes
+                {% elseif purposes.data.length > 1 %}
+                    <ul class="govuk-list">
+                        {% for purpose in purposes.data %}
+                            <li>{{ purpose }}</li>
+                        {% endfor %}
+                    </ul>
+                {% else %}
+                    {{ purposes.data[0] }}
+                {% endif %}
+            </dd>
+        </div>
+    {% endif %}
 </dl>
 
 <div class="govuk-grid-row">

db/migrations/legacy/20240129145658_create-licence-version-purposes-table.js

@@ -0,0 +1,44 @@
+'use strict'
+
+const tableName = 'licence_version_purposes'
+
+exports.up = function (knex) {
+  return knex
+    .schema
+    .withSchema('water')
+    .createTable(tableName, (table) => {
+      // Primary Key
+      table.uuid('licence_version_purpose_id').primary().defaultTo(knex.raw('gen_random_uuid()'))
+
+      // Data
+      table.uuid('licence_version_id').notNullable()
+      table.uuid('purpose_primary_id').notNullable()
+      table.uuid('purpose_secondary_id').notNullable()
+      table.uuid('purpose_use_id').notNullable()
+      table.integer('abstraction_period_start_day').notNullable()
+      table.integer('abstraction_period_start_month').notNullable()
+      table.integer('abstraction_period_end_day').notNullable()
+      table.integer('abstraction_period_end_month').notNullable()
+      table.date('time_limited_start_date')
+      table.date('time_limited_end_date')
+      table.text('notes')
+      table.decimal('annual_quantity')
+      table.string('external_id')
+      table.boolean('is_test')
+
+      // Legacy timestamps
+      // NOTE: They are not automatically set
+      table.dateTime('date_created').notNullable()
+      table.dateTime('date_updated').notNullable()
+
+      // Constraints
+      table.unique(['external_id'], { useConstraint: true })
+    })
+}
+
+exports.down = function (knex) {
+  return knex
+    .schema
+    .withSchema('water')
+    .dropTableIfExists(tableName)
+}

db/migrations/public/20240129151549_create-licence-version-purposes-view.js

@@ -0,0 +1,36 @@
+'use strict'
+
+const viewName = 'licence_version_purposes'
+
+exports.up = function (knex) {
+  return knex
+    .schema
+    .createView(viewName, (view) => {
+      // NOTE: We have commented out unused columns from the source table
+      view.as(knex('licence_version_purposes').withSchema('water').select([
+        'licence_version_purpose_id AS id',
+        'licence_version_id',
+        'purpose_primary_id',
+        'purpose_secondary_id',
+        'purpose_use_id AS purpose_id',
+        'abstraction_period_start_day',
+        'abstraction_period_start_month',
+        'abstraction_period_end_day',
+        'abstraction_period_end_month',
+        'time_limited_start_date',
+        'time_limited_end_date',
+        'notes',
+        'annual_quantity',
+        'external_id',
+        // 'is_test ',
+        'date_created AS created_at',
+        'date_updated AS updated_at'
+      ]))
+    })
+}
+
+exports.down = function (knex) {
+  return knex
+    .schema
+    .dropViewIfExists(viewName)
+}

test/models/licence-version-purposes.model.test.js

@@ -0,0 +1,68 @@
+'use strict'
+
+// Test framework dependencies
+const Lab = require('@hapi/lab')
+const Code = require('@hapi/code')
+
+const { describe, it, beforeEach } = exports.lab = Lab.script()
+const { expect } = Code
+
+// Test helpers
+const DatabaseHelper = require('../support/helpers/database.helper.js')
+const LicenceVersionModel = require('../../app/models/licence-version.model.js')
+const LicenceVersionHelper = require('../support/helpers/licence-version.helper.js')
+const LicenceVersionPurposesHelper = require('../support/helpers/licence-version-purpose.helper.js')
+
+// Thing under test
+const LicenceVersionPurposeModel = require('../../app/models/licence-version-purpose.model.js')
+
+describe('Licence Version Purposes model', () => {
+  let testRecord
+
+  beforeEach(async () => {
+    await DatabaseHelper.clean()
+
+    testRecord = await LicenceVersionPurposesHelper.add()
+  })
+
+  describe('Basic query', () => {
+    it('can successfully run a basic query', async () => {
+      const result = await LicenceVersionPurposeModel.query().findById(testRecord.id)
+
+      expect(result).to.be.an.instanceOf(LicenceVersionPurposeModel)
+      expect(result.id).to.equal(testRecord.id)
+    })
+  })
+
+  describe('Relationships', () => {
+    describe('when linking to licence version purposes', () => {
+      let testLicenceVersion
+
+      beforeEach(async () => {
+        testLicenceVersion = await LicenceVersionHelper.add()
+
+        const { id } = testLicenceVersion
+        testRecord = await LicenceVersionPurposesHelper.add({ licenceVersionId: id })
+      })
+
+      it('can successfully run a related query', async () => {
+        const query = await LicenceVersionPurposeModel.query()
+          .innerJoinRelated('licenceVersion')
+
+        expect(query).to.exist()
+      })
+
+      it('can eager load the licence version', async () => {
+        const result = await LicenceVersionPurposeModel.query()
+          .findById(testRecord.id)
+          .withGraphFetched('licenceVersion')
+
+        expect(result).to.be.instanceOf(LicenceVersionPurposeModel)
+        expect(result.id).to.equal(testRecord.id)
+
+        expect(result.licenceVersion).to.be.an.instanceOf(LicenceVersionModel)
+        expect(result.licenceVersion.id).to.equal(testLicenceVersion.id)
+      })
+    })
+  })
+})

test/models/licence-version.model.test.js

@@ -12,6 +12,9 @@ const DatabaseHelper = require('../support/helpers/database.helper.js')
 const LicenceHelper = require('../support/helpers/licence.helper.js')
 const LicenceModel = require('../../app/models/licence.model.js')
 const LicenceVersionHelper = require('../support/helpers/licence-version.helper.js')
+const LicenceVersionPurposesHelper = require('../support/helpers/licence-version-purpose.helper.js')
+const PurposeHelper = require('../support/helpers/purpose.helper.js')
+const PurposeModel = require('../../app/models/purpose.model.js')
 
 // Thing under test
 const LicenceVersionModel = require('../../app/models/licence-version.model.js')
@@ -64,5 +67,39 @@ describe('Licence Version model', () => {
         expect(result.licence).to.equal(testLicence)
       })
     })
+
+    describe('when linking through licence version purposes to purposes', () => {
+      let purpose
+
+      beforeEach(async () => {
+        testRecord = await LicenceVersionHelper.add()
+        purpose = await PurposeHelper.add()
+
+        const { id } = testRecord
+        await LicenceVersionPurposesHelper.add({
+          licenceVersionId: id,
+          purposeId: purpose.id
+        })
+      })
+
+      it('can successfully run a related query', async () => {
+        const query = await LicenceVersionModel.query()
+          .innerJoinRelated('purposes')
+
+        expect(query).to.exist()
+      })
+
+      it('can eager load the purposes', async () => {
+        const result = await LicenceVersionModel.query()
+          .findById(testRecord.id)
+          .withGraphFetched('purposes')
+
+        expect(result).to.be.instanceOf(LicenceVersionModel)
+        expect(result.id).to.equal(testRecord.id)
+
+        expect(result.purposes[0]).to.be.an.instanceOf(PurposeModel)
+        expect(result.purposes).to.equal([purpose])
+      })
+    })
   })
 })