Integration Guides Integrating the platform

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

Pre-requisites

• Integrate the DPR FE Library

Integration steps

---

Add DPR configuration

API config

Add DPR API configuration to your config.ts file.

export default {
  ...
  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))),
    }
  }
  ...
}

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 default {
  ...
  apis: {
    ...
  }
  ...
  dpr {
    dataProductDefinitionsPath: 'definitions/prisons/dps/yourServiceName'
  }
  ...
}

---

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/dpr/data/dprReportingClient'
import { createRedisClient } from './redisClient'
import config from '../config'

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

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

---

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/dpr/utils/ReportStoreServiceUtils'

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

  ...
  const dprServices = createDprServices({ reportingClient, dashboardClient, reportDataStore })

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

Enable/disable features

You can disable certain features by adding extra config to the createDprServices method:

const featureConfig = {
  bookmarking: false    // Disables bookmarking feature 
  download: false       // Disables download feature
}

const dprServices = createDprServices({ reportingClient, dashboardClient, reportDataStore }, featureConfig)

---

Setup the DPR user in locals

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

// 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 setUpDprResources from '@ministryofjustice/hmpps-digital-prison-reporting-frontend/dpr/middleware/setUpDprResources'
import config from './config'

...

app.use(setUpDprResources(services, config.dpr))

---

Initialise routes

Import the async routes in to your routes file which will give you access to the async reporting paths.

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

import dprPlatformRoutes from '@ministryofjustice/hmpps-digital-prison-reporting-frontend/dpr/routes'

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

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

---

Summary

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/dpr/data/dprReportingClient'
// services
import createDprServices from '@ministryofjustice/hmpps-digital-prison-reporting-frontend/dpr/utils/ReportStoreServiceUtils'
// middleware
import setUpDprResources from '@ministryofjustice/hmpps-digital-prison-reporting-frontend/dpr/middleware/setUpDprResources'
// Routes
import dprPlatformRoutes from '@ministryofjustice/hmpps-digital-prison-reporting-frontend/dpr/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. Add middleware
app.use(setUpDprResources(services, config.dpr))

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