hmpps-connect-dps-components

hmpps-connect-dps-components is a Node.js client library to simplify the process of incorporating global components within DPS applications. We welcome feedback on this README here in order to improve it.

Contents

1. Using the library
2. For library developers

Using the library

Prerequisites

The package assumes adherance to the standard hmpps-template-typescript project. It requires:

• a user object to be available on res.locals containing a token, displayName, and authSource.
• nunjucks to be setup
• to be run AFTER helmet middleware
• API configs defined for the following:
  • Component API
  • (If using the caseload data middleware) - Prison API
  • (If using the allocation job responsibilities middleware) - Allocations API config
• IF you are using the retrieveAllocationJobResponsibilities middleware you will need the @ministryofjustice/hmpps-auth-clients package to be installed and setup so that you are able to create AuthenticationClient objects.

Installation

To install the package, run the following command:

npm install @ministryofjustice/hmpps-connect-dps-components

Usage

Currently, the package provides the header and the footer component.

Automatic installation

You can use this script to attempt to automatically install DPS components. It is designed to work with the latest hmpps-template-typescript file layout.

npx @ministryofjustice/hmpps-connect-dps-components

Do take care to check the diff carefully, in case your repository has diverged from the template.

Manual installation

To incorporate, use the middleware for appropriate routes within your Express application:

    import { getFrontendComponents } from '@ministryofjustice/hmpps-connect-dps-components'

    ...

    app.use(getFrontendComponents({
      logger,
      componentApiConfig: config.apis.componentApi,
      dpsUrl: config.serviceUrls.digitalPrison,
      requestOptions: { includeSharedData: true },
    }))

However, please 🙏 consider carefully whether you need the components for EVERY request.

It may be sufficient for you app to only request components for GET requests for example, in which case

    app.get('*', getFrontendComponents({
      logger,
      componentApiConfig: config.apis.componentApi,
      dpsUrl: config.serviceUrls.digitalPrison,
      requestOptions: { includeSharedData: true },
    })
  )

may be more appropriate, especially if you use the PRG pattern to handle form submission. This will help us to reduce the load on the micro frontend components API. You may wish to go even further, for example avoiding routes that don't need components - the Prisoner Profile does something like this to avoid the component API call for the following routes: /api (provides prisoner images) and / (a redirect only route).

    app.get(
      /^(?!\/api|^\/$).*/,
      getFrontendComponents({
        logger,
        componentApiConfig: config.apis.componentApi,
        dpsUrl: config.serviceUrls.digitalPrison,
      }),
      (req, res) => {
        res.render('prisonerProfile')
      },
    )

There are a number of options available depending on your requirements.

Add the hmpps-connect-dps-components path to the nunjucksSetup.ts file to enable css to be loaded:

const njkEnv = nunjucks.configure(
  [
    path.join(__dirname, '../../server/views'),
    'node_modules/govuk-frontend/dist/',
    'node_modules/govuk-frontend/dist/components/',
    'node_modules/@ministryofjustice/frontend/',
    'node_modules/@ministryofjustice/frontend/moj/components/',
    'node_modules/@ministryofjustice/hmpps-connect-dps-components/dist/assets/',
  ],
  {
    autoescape: true,
    express: app,
  },
)

Include the package scss within the all.scss file

@import '@ministryofjustice/hmpps-connect-dps-components/dist/assets/footer';
@import '@ministryofjustice/hmpps-connect-dps-components/dist/assets/header-bar';

Include reference to the components in your layout.njk file:

{% for js in feComponents.jsIncludes %}
    <script src="{{ js }}" nonce="{{ cspNonce }}"></script>
{% endfor %}

{% for css in feComponents.cssIncludes %}
    <link href="{{ css }}" nonce="{{ cspNonce }}" rel="stylesheet" />
{% endfor %}

{% block header %}
  {{ feComponents.header | safe }}
{% endblock %}

{% block footer %}
    {{ feComponents.footer | safe }}
{% endblock %}

Extra calls

It may be that you need to add some extra requests for the page components for pages that do not fit the normal flow of routes. e.g. in setUpAuthentication.ts on the /autherror path:

     router.get(
      '/autherror',
      getFrontendComponents({
        logger,
        componentApiConfig: config.apis.componentApi,
        dpsUrl: config.serviceUrls.digitalPrison,
        requestOptions: { includeSharedData: true },
      }),
      (req, res) => {
        res.status(401)
        return res.render('autherror')
      },
    )

This will provide a stripped down header for if there is no user object on res.locals.

Content-Security-Policy

The package updates the Content-Security-Policy response header (often set by helmet middleware) to permit cross-domain/origin access to the FE components API. This package should be run after helmet and other security middleware to prevent this being overwritten.

There is a new parameter (which will become on by default in future) to use CSP directives as provided by the FE components API:

app.use(getFrontendComponents({
  logger,
  componentApiConfig: config.apis.componentApi,
  dpsUrl: config.serviceUrls.digitalPrison,
  requestOptions: { updateContentSecurityPolicy: true }, // ← updateContentSecurityPolicy is false by default
}))

Shared Data

An optional parameter includeSharedData: true can be passed into the get methods request options. Setting this will result in a sharedData object being added to res.locals.feComponents containing data the components have collected to render. This includes:

• activeCaseLoad (the active caseload of the user)
• caseLoads (all caseloads the user has access to)
• services (information on services the user has access to used for global navigation)
• allocationJobResponsibilities (the allocation policy codes the user has the associated job responsibility for. Allocation policy codes are: KEY_WORKER, meaning the user is a key worker and PERSONAL_OFFICER, meaning the user is a personal officer.)
• cspDirectives (Content-Security-Policy directives needed to use components from a different domain/origin)

This can be useful e.g. for when your service needs access to activeCaseLoad information to prevent extra calls to the api and takes advantage of the caching that the micro frontend api does.

Populating res.locals.user with the shared case load data

Many services typically add case load information to the user object on res.locals. This library provides some optional middleware which populates:

• res.locals.user.caseLoads with all case loads the user has access to
• res.locals.user.activeCaseLoad with the active case load of the user
• res.locals.user.activeCaseLoadId with the id of the active case load

It uses the sharedData object if it is present and caches in req.session so that any subsequent routes that do not use the component middleware can still use the data. If there is no data in the cache, it will fall back to making a call to Prison API to retrieve the data using the user token.

To enable this, add the middleware after the component middleware as follows:

import { retrieveCaseLoadData } from '@ministryofjustice/hmpps-connect-dps-components'

app.use(retrieveCaseLoadData({
    logger,
    prisonApiConfig: config.apis.prisonApi,
  }),
)

This middleware checks the res.locals.user.authSource so ensure that any mock auth data used in tests includes auth_source: 'nomis' in the response.

Populating res.locals.user with the shared allocation job responsibilities

This library also provides an optional middleware which populates:

• res.locals.user.allocationJobResponsibilities the allocation policy codes the user has the associated job responsibility for. Allocation policy codes are: KEY_WORKER, meaning the user is a key worker and PERSONAL_OFFICER, meaning the user is a personal officer.

Similar to shared case load data, it uses the sharedData object if it is present and caches in req.session so that any subsequent routes that do not use the component middleware can still use the data. If there is no data in the cache, it will fall back to making a call to Allocations API to retrieve the data using the user token.

To enable this, add the middleware after the component middleware as follows:

import { retrieveAllocationJobResponsibilities } from '@ministryofjustice/hmpps-connect-dps-components'
app.use(retrieveAllocationJobResponsibilities({
  logger,
  authenticationClient: new AuthenticationClient(config.apis.hmppsAuth, logger, services.dataAccess.tokenStore),
  allocationsApiConfig: config.apis.allocationsApi,
}))

This should go after retrieveCaseLoadData so that res.locals.user.activeCaseLoadId will be populated.

This middleware checks the res.locals.user.authSource so ensure that any mock auth data used in tests includes auth_source: 'nomis' in the response. It also checks the res.locals.user.activeCaseLoadId, which is required for retrieving allocation job responsibilities.

Your service will need to be set up with client credentials in order to use this middleware, although it currently does not need any specific role.

Note

In the event of a failure to retrieve the components, the package will populate the html fields with fallback components. The feComponents.sharedData will not be populated, but if you use the retrieveCaseLoadData middleware (see above) it will either take case load data from the cache or make a call to the Prison API to retrieve it.

For library developers:

1. Publishing to NPM