Filter enrichment in your MNS event
How to add filtering enrichment to events published to the Multicast Notification Service (MNS).
Overview
This page summarises the steps required to achieve enriched filtering when subscribing to a publishing service's events using Multicast Notification Service (MNS).
Before approaching MNS to assist with filter enrichment, publishers will need to:
- determine whether you can meet the requirements of the subscriber
- look at alternative options to assist
- discuss with the MNS team to determine whether we enrich the subscriber's filtering needs
Subscribers will need to:
- discuss your filtering requirements with the publishing service
- determine whether your requirements meet the needs of your use case
MNS can provide filter enrichment to a publisher's event in most use cases. However, as we are not owners of the business logic required as an additional filter, it is often more beneficial for the subscriber and publisher to agree the filtering requirements between them.
Filtering
A subscriber can subscribe to all the events of a given type. However, often, they will only be interested in a subset of those events.
MNS supports a filtering object in the event to accommodate this requirement.
The event publisher should work with subscribers to ascertain what filters the subscriber needs in order to only receive the specific events they are interested in.
The event publisher can then add these filters to the filtering object in the event.
Subscribers are then able to add criteria in their subscription which match on the filtering object.
The events then sent to subscribers exclude the filtering object.
Filter enrichment
If the publisher is unable to provide the filtering the subscriber requires, MNS can use some provided filters and enrich further ones from them.
MNS currently recognises and supports the following enrichments:
| Enrichment | Format value (used in filter schema) |
Type |
|---|---|---|
The patient's registered GP ODS code:
|
nhsnumber | Patient NHS number |
The GP software supplier ODS code (for example, TPP, EMIS):
|
odscode |
GP ODS Code |
|
Address details retrieved from the Office of National Statistics (ONS):
|
postcode | Postcode |
How it works
When an event publisher onboards to MNS, the MNS team will create a filter schema linked to the event type.
This is a JSON schema that defines the fields in the filtering object. Examples include the type of the field - for example, string and integer. Also, it will define if it is mandatory or matches a range of values.
However, each field can also support a "format" which matches up with "Format value" in the table above.
As an example, if the publisher passes in a field called "nhs_number", which is defined with a format of "nhsnumber", then that resolves to the type Patient NHS number in the table. When that event is processed by MNS, two extra filtering fields are added. One named "generalpractitioner" of type GP ODS Code and another named "postcode" of type Postcode.
Subsequently, the GP ODS code will then be enriched itself and a GP software supplier ODS code will be added with the field name "generalpractitioner_manufacturer_org". The Postcode field will also be enriched which will add the following fields: "postcode_country_code", "postcode_icb_sub_location_code" and "postcode_local_authority_ods_code".
Sub-enrichment is optional and is at the discretion of the publisher.
The subscriber is then free to subscribe using criteria from the enriched filtering object.
Example data supporting enrichment
Example filter schema defining an enriched nhs_number field
{
"type": "object",
"properties": {
"resource_type": {
"type": [
"string"
],
"minLength": 1
},
"resource_action": {
"type": [
"string"
],
"enum": [
"Create",
"Update"
]
},
"product_ids": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"minItems": 1,
"uniqueItems": true,
"x-format": "list"
},
"nhs_number": {
"type": [
"string",
"null"
],
"format": "nhsnumber",
"minLength": 1
}
},
"required": [
"resource_type",
"resource_action",
"product_ids"
],
"additionalProperties": false
}
Example event from a publisher
{
"specversion": "1.0",
"id": "236a1d4a-5d69-4fa9-9c7f-e72bf505aa5b",
"source": "uk.nhs.vaccinations-data-flow-management",
"type": "imms-vaccinations-1",
"time": "2020-06-01T13:00:00Z",
"dataref": "https://api.service.nhs.uk/immunisation-fhir-api/Immunization/29dc4e84-7e72-11ee-b962-0242ac120002",
"filtering": {
"resource_type": "A",
"resource_action": "Create",
"product_ids": ["B","C"],
"nhs_number": "9730676240",
},
"subject": "9730676240",
"versionid": "12"
}
Example of an enriched event
{
"specversion": "1.0",
"id": "236a1d4a-5d69-4fa9-9c7f-e72bf505aa5b",
"source": "uk.nhs.vaccinations-data-flow-management",
"type": "imms-vaccinations-1",
"time": "2020-06-01T13:00:00Z",
"dataref": "https://api.service.nhs.uk/immunisation-fhir-api/Immunization/29dc4e84-7e72-11ee-b962-0242ac120002",
"filtering": {
"resource_type": "A",
"resource_action": "Create",
"product_ids": ["B","C"],
"nhs_number": "9730676240",
"generalpractitioner": "Y12345",
"generalpractitioner_manufacturer_org": "ABC123",
},
"subject": "1234567890",
"versionid": "12"
}
Example of sub-enrichment
"nhs_number_limited_sub_enrichment": {
"type": [
"string",
"null"
],
"format": "nhsnumber",
"minLength": 1,
"x-allowed-subenrichments": [
"odscode"
]
},
Example subscription with criteria matching filters
{
"resourceType": "Subscription",
"status": "requested",
"end": "2028-04-05T17:31:00.000Z",
"reason": "Business process A",
"criteria": "eventType='imms-vaccinations-1' AND resource_type='A' AND generalpractitioner='Y12345' AND 'B' IN product_ids AND generalpractitioner_manufacturer_org = 'ABC123'",
"channel": {
"type": "message",
"endpoint": "arn:aws:sqs:eu-west-2:123456789012:queue2",
"payload": "application/fhir+json"
}
}
New enrichment requests
If your use case requires new enrichment capabilities, please discuss them with the MNS team.
Last edited: 8 July 2026 11:38 am