Getting Started
- Mutual Transport Layer Security (mTLS) Authentication
- Registering a Component
- Example Requests
- Sending a Message to the Simulator
- Sending Multiple Messages within the Same Request
- Receiving Messages from the DIP Simulator
- Test Run Logging
- Outbound Information
- Message Signing
- X-API-KEY Header
- DIP Connection Provider Information
- Request Size Limit
- Further Information
1. Mutual Transport Layer Security (mTLS) Authentication
mTLS is a type of mutual authentication, in which two parties at either end of a network connection authenticate each other using digital certificates. The DIP specification mandates that all network communication must be secured using mTLS.
When mTLS is enabled, Programme participants will need to download their 'Participant' certificate and use that certificate when making requests to the DIP Simulator.
Please follow these steps to download and use your certificate:
- Navigate to the Participant Configuration page and download the certificate with the 'Download Certificate' button.
- Once the certificate has been downloaded attach it to the Postman requests by following this guide*
2. Registering a Component
To use the DIP Simulator, you must register a Component which can be used to send requests to the DIP Simulator.
Follow these steps to register a Component:
- Go to Registered Components page in the drop-down menu under DIP Simulator in the navigation bar above
- On the top right-hand corner, click on 'New Component'
- Enter a name for the Component and select the Role(s) you wish it to have
- Click 'Create'
- You will then be redirected back to the Registered Components page, where you will see your new Component with a newly generated DIP ID
3. Example Requests
The DIP Simulator uses the Postman API platform for building and using Application Programming Interfaces (APIs). To use Postman, please sign up for free at www.postman.com.
You can download a suite of example Postman requests and environment exports from the Example Requests page, found under 'Information' in the navigation bar above.
Follow these steps to import the Postman collection file into Postman:
- Click on the Postman collection file from the Example Requests page. This will download the Postman collection file
- Open Postman. If you have not signed up to Postman yet, please do so using the link above
- On the top left pane of Postman, look for 'My Workspace'
- Click 'Import' and select the Postman collection file you downloaded
In Postman, you should see the collection called 'MHHS DipSim Interfaces' containing the imported requests. There will also be a folder called 'Example Requests', which contains successful messages, and another folder called 'Tests' that demonstrates DIP Simulator responses to any messages containing errors.
The Example Requests page also contains an exported Postman environment file. This file contains variables that simplify using the request collection with different environments. Follow these steps to import the Production environment into Postman:
- Click on the Production environment file from the Example Requests page. This will download the file
- Open Postman. In Postman, click ‘Environments’ in the navigation sidebar on the left
- Click ‘Import’ and select the Production environment file you downloaded
- Change the environment dropdown option in the upper right-hand corner of Postman from 'No Environment' to 'Production'
If the {{hostname}} must be changed to a different URL, please follow these steps:
- Click the collection called 'MHHS DipSim Interfaces' and click the 'Variables' tab in the middle pane
- On the 'Variables' section, change the hostname's initial and current value to the desired URL
4. Sending a Message to the Simulator
Once a Component is registered with the DIP Simulator, it can be used to send requests to the DIP Simulator.
Follow these steps to send requests to the DIP Simulator:
- Open a request in the Postman collection. Your Component must be registered with the Role required to send the selected message (see "Register a Component" above)
- In the request body, replace 'SenderDipId' in the S1 payload block with the DIP ID of your registered Component
- Click 'Send' to send the message to the DIP Simulator and view the response from the DIP Simulator
5. Sending Multiple Messages within the Same Request
Each request message that is sent to the DIP Simulator should contain at least one payload; however, multiple messages can be sent in a single request. To do this, add additional message payloads into the array of the request body that is being sent to the DIP Simulator. There are many examples of how to do this in the Postman example request collection.
Please note there is a 100K limit on the POST request which can be sent with Postman due to an issue with TLS renegotiation and web applications hosted in Azure.
6. Receiving Messages from the DIP Simulator
To receive messages from the DIP Simulator, you will need to connect a Component. This can be done by sending a ‘dip-channel/{id}/pubconfig’ request to the DIP Simulator with the Component's DIP ID, and a callback URL for the messages to be sent to. Connected Components can be viewed on the Connected Components page of the DIP Simulator, which is found in the drop-down menu under DIP Simulator in the navigation bar above.
To connect a Component, follow the instructions below:
For this example, we use a web-based webhook site (see Further Information below) and our callback URL is https://webhook.site/f8032d3f-197d-4f67-af90-7b6e64428c33.
- Go to the Registered Components page to get the DIP ID for the Component that you want to connect
- Prepare a callback URL that the DIP Simulator can send the messages to
- Send a Publication Configuration request to the DIP Simulator with the DIP ID and callback URL, there are examples of calling dip-channel/{id}/pubconfig in the Postman collection on the Example Requests page
- Now the Component will appear on the Connected Components page and will start receiving messages that have the Component's Roles as part of the interface's routing
7. Test Run Logging
Test Run Logging is a feature of the DIP Simulator which enables the generation of a report based on the result of sending a set of messages from a registered Component to the Simulator. This report can be used by the PIT teams to inform their decision on the acceptance of a Participant Component into PIT.
Please follow these steps to create a new Test Run:
- Register a Component to use for the Test Run. Follow the instructions under Registering a Component
- Go to the Test Runs page in the drop-down menu under 'DIP Simulator' in the navigation bar. This will only be visible when signed in
- Click 'New Test Run'
- Enter a name for the Test Run and select the Component you would like to create the Test Run for
- Click 'Create'
- You will be redirected back to the Test Runs page, where you will see your new Test Run
- The new Test Run will have the status of 'In Progress'
- Open the Test Run Report by clicking the icon next to the Test Run
Add whatever messages you like from your Component to the Test Run by following the steps below:
- Open a request in the Postman
- In the request body, replace 'SenderDipId' in the S1 payload block with the 'Component Id' from the Test Run Report
- In the request headers, add the header 'X-Test-Run-Key' and add the value of 'Test Run Key' from the Test Run Report
- Click 'Send' to send the message to the DIP Simulator and to log the response from the DIP Simulator to the Test Run Report
- You should see the result from the message you have just run in the 'Message Results' section of the Test Run Report
Once you have added all desired messages to the Test Run, you can complete the Test Run by clicking the 'Finish Test' button on the Test Run Report page. If all the messages succeeded the result of the Test Run will be updated to 'Pass', otherwise the result will be 'Fail'. Once the Test Run is completed you cannot add further messages. You can share this report with any member of the MHHS programme by simply sending them the url.
8. Outbound Information
All the registered webhooks for The DIP Simulator will be received from one of its' outbound addresses:
51.143.182.89, 51.143.182.117, 51.143.182.96, 51.143.182.211, 51.140.146.130
9. Message Signing
Message signing header validation for inbound request and generation of signing headers for outbound requests have been added to the DIP Simulator in accordance with the instructions set out in the MHHS-DEL1197 Interface Code of Connection v1.3.
Message signing is mandatory, all requests are required to have the following headers included with the message.
- X-DIP-Signature-Certificate
- X-DIP-Signature
- X-DIP-Signature-Date
- X-DIP-Content-Hash
The Postman collection available from the Example Requests page contains a pre-request script that can populate these headers for you. This script is controlled by the 'SigningClientCertPEM' and 'SigningClientPrivateKeyPEM' variables in the Postman environment. These variables should be set to the public and private key from your Simulator participant certificate. This is the same certificate that is used for mTLS.
You can extract your certificate keys using the following openssl command.
openssl pkcs12 -in your_certificate.pfx -nodes -passin pass:your_certificate_password
Copy certificate including -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- to the 'SigningClientCertPEM' Postman environment variable.
Copy private key including -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- to the 'SigningClientPrivateKeyPEM' Postman environment variable.
When copying the keys into the environment variables ensure you remove any newlines or trailing whitespace.
In all cases outbound messages from the DIP Simulator include the headers generated by message signing.
10. X-API-KEY Header
A requirement for a header with the key 'X-API-KEY' has been added to the DIP Simulator. The value of the header can be a dummy string value when connecting to the DIP Simulator, however for connection to the DIP please refer to the MHHS-DEL1197 Interface Code of Connection v1.2.
This header is mandatory for all requests.
11. DIP Connection Provider Information
The DIP Simulator has the ability to receive messages from Participants that are using a DIP Connection Provider to send their messages.
When a message is received the DIP Simulator will validate the mTLS certificate and the message signing certificate against the DIPIDs for the Components provided in the 'SenderDipId' and 'DipConnectionProviderId' fields of the S1 block.
These are the validation rules that are applied to the S1 block values, mTLS certificate and message signing certificate:
- The mTLS certificate will be validated against the 'S1.DipConnectionProviderId' if provided, otherwise against the 'S1.SenderDipId'.
- The message signing certificate will be validated against 'S1.SenderDipId' if message signing headers have been provided.
- If no 'S1.DipConnectionProviderId' is provided then the mTLS and message signing certificates will be validated against the 'S1.SenderDipId'.
12. Request Size Limit
Due to an issue with TLS renegotiation it has been identified that requests exceeding 100K will fail with a 403 error. This is with Azure Web Applications which use TLS renegotiation. The only workaround which is not a requirement of the DIP is to use Expect: 100-Continue. This involves not just adding the Expect header, but also correctly handling the Expect: 100-Continue behavior, which requires the client to pause transmission after sending headers and wait for an interim HTTP/1.1 100 Continue response from the server before sending the request body. This behaviour is not supported with Postman and therefore Postman cannot be used to send requests over 100K to the Simulator.
13. Further Information
For further information on how to use the DIP Simulator, a recording of the "MHHS Webinar: DIP Simulator Demo", is available here.
We suggest using Webhook.site*, a free site that allows you to test and automate incoming HTTP requests.
*The MHHS Programme is not responsible for the content of external sites.