Publisher example - new event template (draft)

Provide an elaboration of the summary - most publishers will use the summary as their opening sentence in the overview. 

Use the pattern below to set out what the user needs to know:

• Publisher: <insert the service, including short name, and link to API spec>
• Event name: <insert the name of your event>
• Delivery mechanism: Multicast Notification Service
• Payload type: <insert payload type>
• Data retrieval: <insert data retrieval method>

For general guidance on using MNS, refer to the MNS service page.

A brief sentence on the status of your event, with a link to the reference guide/statuses, for example:

This event is currently in private beta.

Provide bullet points of when to use this event - consider the use cases to help with the bullets.

You may want to also have a sub-section on when subscribers should not use this event - again as bullets - this sub-section is optional.

Provide example use cases as a further sub-section - simple one line bullet points to list the use cases will suffice.

This event notifies subscribers when to use the event.

Use this event if your system:

• <insert criteria specific to the service and use case>

Example use cases

• <insert example use cases>

Do not subscribe this event if:

• <insert criteria where the event is not suitable>

Diagrams

Create a diagram using Draw.io to visually describe how the event works. Take inspiration from other event pages who have incorporated this pattern.

The diagram will have its master copy stored on Confluence. Create a new draw.io diagram by clicking on the + icon and selecting draw.io Diagram. You can now create a new diagram from scratch or use an existing diagram as a starting template.

To create a new diagram, select Blank, and then select Create. To add the NHS England library, select + More Shapes at bottom left. Scroll down and select NHS England Digital Services.xml, then Apply. The icons should appear in the left panel. You can drag and drop icons to the canvas on the right.  

To use an existing diagram, find a similar one in the Confluence folder and open the diagram in draw.io using a new browser window. Click the pencil icon to edit it, select all objects of the existing diagram with your mouse, then copy (Ctrl+C) and paste (Ctrl+V) this into your new diagram.

Event patterns

Use the pattern below to describe how the event works:

This event follows a notification and retrieval pattern:

1. A <event trigger> is created or updated in <name of your API>.

2. An event is published.

3. The event is delivered to a subscribed system via MNS.

4. Your system receives the event.

5. Your system retrieves the latest record using <how the event is retrieved - for example, with NHS number>.

6. Your system applies the latest data.

State whether your event is using FHIR, CloudEvent or both and use the most relevant bullet(s) from the points below:

• FHIR events are accessible to both internal and external subscribers.
• CloudEvents format can be accessed by internal subscribers only.

Replicate the table as used in other event pages - ensure the content is relevant to your event rather than cutting, pasting and assuming all information is accurate.

You may need to add a description which is more relevant to your event.

The columns of your table should be set out as:

If your event uses filters, describe them in more detail in this section.

If your event does not use filters, state this in one sentence in this section.

Use a table to describe your filters with the following headings:

Use the PDS change event subscription filter layout for an example.

Provide example of your subscriptions using inline code to set out the filter.

Use the following generic text to set out what a subscriber will need to do to onboard to your event:

To subscribe to this event, you will need to:

• complete onboarding to <insert the name of your API and hyperlink to it > (if data retrieval is required)
• complete onboarding for MNS

• use the Subscription API to create a subscription

• configure an endpoint to receive event notifications

Refer to Subscribe to Multicast Notification Service for further guidance.

If this is the only version of your event, then say so using the sentence below:

<insert the name of your event> is the only version of this event.

Talk about how you would like subscribers to test the event. Start the paragraph with the following sentence:

These events are available in the Path to Live environments (PTL).

Provide the preferred contact method that subscribers should use, should they have any queries with onboarding to your event. This could be:

• a named individual - an onboarding lead (use their email address)
• service desk
• developer community

The contact details should be your contact, not the contact details of the MNS team.