Integration Guides Integrating the FE platform

This integration quide describes the steps required to use DPR's FE Platform into your service, using the HMPPS TS template

The FE platform provides means for services to integrate DPR reporting processes and features.

NOTE: These steps are not required if you are only using DPRs embedded sync report handlers.

Outcome

By following this guide and integrating successfully you have and use of a set of predefined routes to help you manage, view and request reports. See reporting routes for more information about what routes are available.

Pre-requisites

• Integrate the DPR FE Library

Integration steps

---

Add DPR configuration

API config

Add DPR API configuration to your config.ts file.

export const apis = {
  ...
  dpr: {
    url: get('DPR_API_URL', 'http://127.0.0.1:3002', requiredInProduction),
    timeout: {
      response: Number(get('DPR_API_TIMEOUT_RESPONSE', 60000)),
      deadline: Number(get('DPR_API_TIMEOUT_DEADLINE', 60000)),
    },
    agent: new AgentConfig(Number(get('DPR_API_TIMEOUT_RESPONSE', 60000))),
  }
}
export default {
  apis
}

See DPR Environments for API base urls

DPD path config

The DPD path is location in the definitions repo where your DPDs are stored. The path commonly follows this pattern:

definitions/prisons/dps/${yourServiceName}

Add your DPD path to the config.ts file:

export const apis = {
  ...
}
...
export const dpr = {
  dataProductDefinitionsPath: 'definitions/prisons/dps/yourServiceName'
}
export default {
  apis,
  dpr,
}

---

Initialise Redis Client

An initialised Redis client is a dependency DPR's reporting platform. Redis is used to store report request config to keep track of the state of a requested report, and enable features such as bookmarking and downloading.

See next section (Initialise data clients) for details on how the redis client is used.

---

Initialise data clients

Initialise DPR data clients within your app setup to point to DPR's API endpoint.

This setup is commonly done in the server/data/index.ts file of the HMPPS template

import { initDprReportingClients } from '@ministryofjustice/hmpps-digital-prison-reporting-frontend/initDprReportingClients'
import { createRedisClient } from './redisClient'
import config from '../config'

const {
  reportingClient,
  dashboardClient,
  reportDataStore,
  productCollectionClient,
  missingReportClient,
  featureFlagService,
} = initDprReportingClients(config.apis.dpr, createRedisClient())

export const dataAccess = () => ({
  ...reportingClient,
  dashboardClient,
  reportDataStore,
  productCollectionClient,
  missingReportClient,
  featureFlagService,
})

---

Create services

This setup is commonly done in the server/services/index.ts file of the HMPPS template

import { createDprServices } from '@ministryofjustice/hmpps-digital-prison-reporting-frontend/createDprServices'

export const services = (): Services => {
  const {
    reportingClient,
    dashboardClient,
    reportDataStore,
    featureFlagService,
    ...
  } = dataAccess()

  const dprClients = {
    reportingClient,
    dashboardClient,
    reportDataStore,
    featureFlagService,
  }
  ...

  const dprServices = createDprServices(dprClients)

  return {
    ...,
    ...dprServices
  }
}

Enable features

You can enable certain features by adding optional config to the createDprServices method:

const featureConfig = {
  /** Enable/disable bookmarking
   *  - Bookmark links/buttons will be hidden
   *  - Bookmark service will be disabled
   */
  bookmarking: true

  /** Enable/disable download
   *  - Download links/buttons will be hidden
   */
  download: true

    /** Enable/disable feedbackOnDownload
   *  - If disabled, the download functionality will be available immediately
   *  - If enabled, users are required to fill out feedback to gain access to download
   */
  feedbackOnDownload: true,

   /** Enable/disable collections
   *  - collections dropdown will be hidden
   *  - collections service will be disabled
   */
  collections: true,

  /** Enable/disable Missing reports
   *  - Missing reports will be hidden in the report catalogue
   *  - Bookmark service will be disabled
   */
  missingReports: true,

  /** Enable/disable Save defaults
   *  - Save defaults button will be hidden in report filters
   *  - Save defaults service will be disabled
   */
  saveDefaults: true,
}

const dprServices = createDprServices(dprClients, featureConfig)

By default all features are set to false

---

Setup the DPR user in locals

In your populateCurrentUser middleware, ensure you have dprUser defined in your res.locals

import { DprUser } from '@ministryofjustice/hmpps-digital-prison-reporting-frontend/dprUser'

// example using manage user api
const user = await this.hmppsManageUsersClient.getUser(token)

const dprUser = new DprUser()
// required
dprUser.token = res.locals.user.token
dprUser.id = user.uuid
// optional
dprUser.activeCaseLoadId = user.activeCaseLoadId
dprUser.emailAddress = user.email
dprUser.displayName = user.displayName
dprUser.staffId = user.staffId

res.locals.dprUser = dprUser

---

Initialise middleware

This setup is commonly done in the server/app.ts file of the HMPPS template

import { setupResources } from '@ministryofjustice/hmpps-digital-prison-reporting-frontend/setUpDprResources'
import config from './config'

...
const env = nunjucksSetup(app, applicationInfo)
app.use(setupResources(services, 'path/to/layout.njk', env, config.dpr))

---

Initialise routes

Import the async routes in to your routes file. See reporting routes.

This setup is commonly done in the server/routes/index.ts file of the HMPPS template

import { routes as dprRoutes } from '@ministryofjustice/hmpps-digital-prison-reporting-frontend/routes'

export function routes(services: Services): Router {
  const router = Router()
  ...

  router.use('/', dprRoutes({ services, layoutPath: 'path/to/layout.njk'}))
}

export default routes

---

Quick start guide

This summary represents a simple view of the steps required for integrating the platform and should not be used in production. Please follow these integration steps to integrate using best practices of the HMPPS template

// Clients
import { initDprReportingClients } from '@ministryofjustice/hmpps-digital-prison-reporting-frontend/initDprReportingClients'
// services
import { createDprServices } from '@ministryofjustice/hmpps-digital-prison-reporting-frontend/createDprServices'
// middleware
import { setupResources } from '@ministryofjustice/hmpps-digital-prison-reporting-frontend/setUpDprResources'
// Routes
import { routes as dprRoutes } from '@ministryofjustice/hmpps-digital-prison-reporting-frontend/routes'

import { createRedisClient } from './redisClient'
import config from '../config'

// 1. Init Data clients
const clients = initDprReportingClients(config.apis.dpr, createRedisClient())

// 2. Create services
const services = {
  ...createDprServices(clients),
}

// 3. Init DPR user in populateCurrentUser. See "Setup the DPR user in locals" section of guide

// 4. Add middleware
const env = nunjucksSetup(app, applicationInfo)
app.use(setupResources(services, 'path/to/layout.njk', env, config.dpr))

// 5. Initialise routes
router.use('/', dprRoutes({ services, layoutPath: 'path/to/layout.njk' }))