moj noms apvs 0106 nomis integration
Technical Spike to understand the NOMIS API being designed by the Prison Visit Booking team.
During the as-is caseworker claim assessment workflow there is no check performed on the NOMIS system to determine if the claimant exists on the Contact List of the Prisoner in the NOMIS system.
This check would establish if the claimant is a legitimate visitor of the specified prisoner.
Currently they user the prison number and prison location provided by the claimant on the paper form to confirm that the prisoner is valid.
The Prison-NOMIS system contains a 'Contact List' which lists the registered visitors for a prisoner.
The Prison Visit Booking service intends to use this information to validate the details submitted by applicants.
They will check the name and date of birth supplied against the list of registered visitors for the prisoner (identified by the Prisoner Id).
To enable this, the PvB team are in the process of designing an API which will expose data held within P-NOMIS to their (and other) services.
This technical spike examines the currently known details of this integration and assesses their viability to add a similar validation check against the Contact Log.
There are no service usage costs.
Assuming that the REST API for NOMIS can be made available to APVS as a client, and that an acceptable authentication scheme is provided, we will hide the details of this external integration by wrapping it in our own REST API endpoint.
This will be deployed as a seperate component comprised of the API which is accessible to internal APVS services and a client to the external NOMIS API.
New claims will create a NOMIS Check record with the details required by the external API and a status of Pending.
An async worker process will be developed for the internal web application which will process Pending NOMIS Check records.
The worker must first call the internal API endpoint with the Prisoner ID supplied by the claimant. This is used to return the Offender ID which must be provided to the call which retrieves the actual list of contacts. See API section below for the response format.
The worker will then call the internal API component with the Offender Id retrieved.
The API component will return a response which indicates:
- The Prisoner was not found for the specified Offender ID (404)
- An empty contact list if not visitor records are associated with the prisoner
- The list of Visitor records (See API section below for response format)
- Any other appropriate HTTP error codes
The worker process will update the status of the NOMIS check record in the database.
In the event that visitor contact records are returned, these will be inserted into a table associated with the claim.
This information will be used to display to the case worker on the Internal web application, specifically the detail screen for the claim in a format that allows matches and partial matches to be easily identified.
The two API methods which are currently relevant to the APVS solution are:
- Lookup an offender given a NOMS ID
- Fetch Visitor Contact List by Offender Id
Errors will be returned with appropriate HTTP response codes.
The usage of HTTP codes is currently not defined.
The PvB 2 API uses a few of the following design decisions, included at this stage for information only:
- 200: Their slots API returns this in error cases
- 404: Used as standard if record not found
- 422 (Unprocessable Entity): Used to indicate semantic errors
This gives an idea of the teams previous approach to API design.
No error codes will be used to represent errors; a human-readable message has been deemed sufficient. E.g.
{
"error": {
"message": "Blah is wrong"
}
}
The Benefit Check API component can be hosted as a separate container instance exposing the HTTP GET endpoint to the internal web application.
Logs from the worker should be exported to the log aggregator for monitoring.
APVS could potentially re-use this API to retrieve the visitors who are allowed to visit that prisoner, and therefore could present an opportunity to provide extra validation on the claim.
Whilst technically feasible, the uncertain time scales for live service availability and the actual level of benefit to the claim handling process make this an integration which we would recommend parking for the beginning of Beta.
The product owner of APVS has stated that this functionality should be part of the Prison Visit Booking service domain.
We feel that the ideal future state is that this integration remains within Prison Visit Booking and that in future we would receive data from Prison Visit Booking directly which would be predicated on all necessary NOMIS checks having been already completed successfully.