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

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'
  }
  ...
}

Route prefix config

DPR routes are prefixed with /dpr by default. e.g.

/dpr/async/:type/:reportId/:id/request

This should adequate for your integration, however you can replace this prefix by adding your own to the config.ts file:

export default {
  ...
  apis: {
    ...
  }
  dpr: {
    ...
    routePrefix: '/my-prefix'
  }
  ...
}

This will adjust the routes accordingly. e.g.

/my-prefix/async/:type/:reportId/:id/request

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)

Get the current User ID

The user ID of the currently logged in user is the primary key used in the report config store, to retrieve and store report information against a specific user.

A users report data will be stored using this key structure:

`dprReportStoreUser:${ uuid }`

The integration assumes that users uuid is located in the res object at res.locals.user.uuid.

In the HMPPS template this is set in at server/middleware/setUpCurrentUser.ts

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

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

  DprEmbeddedAsyncReports({
    router,
    services,
    layoutPath: 'path/to/layout.njk',
    config: config.dpr
  })
}

This step will enable the page routes documented here

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 DprAsyncReportsRoutes from '@ministryofjustice/hmpps-digital-prison-reporting-frontend/dpr/routes/asyncReports'

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
DprAsyncReportsRoutes({
  router: app,
  services,
  layoutPath: 'path/to/layout.njk',
  config: config.dpr
})