Requesting an Integration Service
Hello! If you are building a digital service in HMPPS that needs to interact with probation case data in NDelius, then you are in the right place.
This guide outlines how the Probation Integration team works with client teams like yours to build secure, reliable, and domain-focused integrations.
How we integrate
A probation integration service typically acts as an anti-corruption layer that connects your HMPPS digital or domain service to the NDelius probation case management system. Adding this layer helps define a meaningful domain and responsibility boundary - allowing us to hide the complexity of NDelius and provide a stable, well-defined interface for your service to interact with the data it needs.
Most integrations involve a combination of the following capabilities:
- Reading Data: Providing REST API endpoints to read existing probation data in the format your service needs.
- Writing Data: Consuming HMPPS Domain Event messages to map and write data back asynchronously.
Every digital service will get their own dedicated integration - they are not shared between clients. This allows us to build integrations that are tailored to the specific needs of each team.
Roadmap
Here is the typical roadmap for working with us, from discussion to production. Timescales vary depending on the complexity of the integration, but we aim to move as quickly as possible.
1. Requirements
Everything starts with a conversation. We’ll meet to understand your use case, data requirements, and timelines. This helps us align our teams and set expectations early.
At this stage, we may need a few follow-up sessions to clarify details. We may also need to include other teams (e.g. the National Delius Service Team) to confirm what’s possible.
2. Ongoing communication
We believe in close collaboration - for asking questions, sharing updates, and resolving issues quickly. Here are the main channels we use:
- Slack: We will create a shared Slack channel (e.g.,
#topic-pi-<your-project>) for day-to-day questions and dev support. - Weekly Catch-up (Optional): During the active design and development phases, we can schedule a weekly catch-up to discuss changes to requirements, unblock any issues and track progress.
3. Design
Before writing code, we agree on the contracts:
- APIs: We define the endpoints, request parameters, and response structures for any data you need to read.
- Events: You define the domain event type that your service will publish. You may also need to define a “detail” API to enable sharing of sensitive data - see Handling sensitive data.
Once the design has been agreed, we will add stories to our Jira board under a single epic.
4. Development
We will build the integration service and deploy it to the dev and preprod environments -
see Environments.
Once it’s ready for you to start testing against, we will share an update on Slack.
At this point you can start hooking up your dev service and start testing. If you spot any issues, or need any changes, get in touch on Slack - we are happy to help!
5. Testing
At this point, we will add an automated test to validate the end-to-end user journey - setting up cases in NDelius, completing the required steps in your service, and verifying data is flowing correctly. See End-to-end testing.
To support this, we may ask you to grant permissions to our test user accounts in the dev environment.
Depending on the scope of your service, the National Delius Service Team (NDST) may also need to do some manual testing to validate the impact on the NDelius system.
6. Go Live
Once an end-to-end test is in place and passing, the integration service will be deployed to production. Then it’s up to you to start using it 🚀
Support
Our partnership doesn’t end at “Go Live”. For ongoing questions, troubleshooting, or future enhancements, you can always reach us in your dedicated Slack channel or our general support channel: #probation-integration-tech.
Monitoring
We continuously monitor the integration services and will be alerted of any exceptions. We will proactively investigate and resolve issues, keeping you informed of any significant incidents.
If you notice any issues from your side, please reach out on Slack.
Responsibility
Responsibility is split between the two teams as follows:
Probation Integration Team:
- Providing guidance on integration and data domain modelling best practices.
- Building and maintaining the APIs and Domain Event consumers.
- Defining the authorisation roles required to access the APIs.
- Managing the connection to the NDelius data stores (Database, LDAP server, Alfresco).
Client Team:
- Researching user needs and validating the use case.
- Defining the domain and product requirements.
- Consuming the APIs provided.
- Publishing the agreed domain events.
- Assistance with testing and validation of data.
- Ownership of any data stored in your service.