File availability notification
The EMR middleware needs to implement a service to receive notification of new data available to be consumed. This notification service is relevant to improve performance in the client application preventing continuous calls to get data.
As introduced in the Health data sharing and Clinical document sharing technical implementation guidance, we offer two distinct options to facilitate seamless data retrieval from the S3 bucket:
- Option 1: Using a Secure Token Service (STS) Authorization token
- Option 2: Using pre-signed URLs
Option 1: Using a Secure Token Service (STS) Authorization token
Notification Message Definition
| field | description |
|---|---|
| EmrOid | Emr Org ID |
| MessageId | Each message receives a system-assigned message ID |
| MessageType | Message Type ("Clinical Report" for CDA, "Clinical Data" for FHIR file) |
| MessageCreatedAt | Message creation date |
| MessageReference | Consists of accesspoint and objectKey |
| MessageReceiptHandle | To be used in the commit request |
Example request:
{
"EmrOid": "2.16.724.4.2",
"MessageId": "e6950ef2-3c66-4d00-9aba-205fde0d3199",
"MessageType": "Clinical Report",
"MessageCreatedAt": "1603778420307",
"MessageReference":
{ "accesspoint": "arn:aws:s3:us-east-1:019364481091:accesspoint/2291405",
"objectKey": "delivery/2291405/cda/xxx.xml"
}
"MessageReceiptHandle": "abc"
}
Notification Message Header Definition
| field | description |
|---|---|
| x-operation-id | A unique ID to track end-to-end flow of messages between Roche D.I and EMR Middleware. This unique ID should be returned back to Roche D.I. in header value of Notification ACK Service via the header parameter x-operation-id |
Option 2: Using pre-signed URLs
Notification Message Definition
| field | description |
|---|---|
| EmrOid | Emr Org ID |
| MessageId | Each message receives a system-assigned message ID |
| MessageType | Message Type ("Clinical Report" for CDA, "Clinical Data" for FHIR file) |
| MessageCreatedAt | Message creation date |
| MessageReference | Consists of accesspoint containing pre-signed URL and objectKey set as null |
| MessageReceiptHandle | To be used in the commit request |
Example request:
{
"EmrOid": "2.16.724.4.2",
"MessageId": "e6950ef2-3c66-4d00-9aba-205fde0d3200",
"MessageType": "Clinical Report",
"MessageCreatedAt": "1603778420307",
"MessageReference": {
"accesspoint": "https://{env}-emr-integration-data-store-s3.s3.amazonaws.com/delivery/2291405/cda/xxx.xml?X-Amz-Security-Token=yyy"
},
"MessageReceiptHandle": "abc"
}
Notification Message Header Definition
| field | description |
|---|---|
| x-operation-id | A unique ID to track end-to-end flow of messages between Roche D.I and EMR Middleware. This unique ID should be returned back to Roche D.I. in header value of Notification ACK Service via the header parameter x-operation-id |
Notification Service Authentication
Basic Authentication (HTTPS)
Notification interface should use HTTP Basic Authentication. EMR middleware, acting as a server, needs to provide username and password to client application (Roche)
### Server certificate for EMR Middleware For the server certificate, the **Certificate Authority** is **Roche** and not an external 3rd party CA. Roche sign certificates used in HTTPS so it is responsible for generating and sharing the server certificate based on the Certificate Signing Request (CSR) provided by EMR middleware.
EMR middleware is responsible for generating a Private Key, maintaining in a Private Keystore and providing to Roche the CSR in order to issue the certificate.
Generate Server Certificate Signing Request
Generate Key (Example): openssl genrsa -out company.qaeu.server.key 2048
Generate Server Certificate Signing Request (Example): openssl req -new -sha256 -key company.qaeu.server.key -subj "/C=Country/ST=State or Province/L=Locality/O=Organization/CN=DOMAIN_FQDN" -out company.qaeu.server.req.pem
Subject Fields
C = Country ST = Test State or Province L = Test Locality O = Organization Name OU = Organizational Unit Name CN = DOMAIN_FQDN
- Provide *.csr file to Roche DC (and NOT the private key)
OpenAPI Specification
{
"openapi": "3.0.0",
"info": {
"title": "Noitification API",
"version": "1.0.0",
"description": "Notification API"
},
"servers": [{
"url": "https://test.emr.com"
}],
"paths": {
"/measures/notification": {
"post": {
"responses": {
"200": {
"description": "Successful processed request"
},
"400": {
"description": "Invalid message"
}
},
"tags": [
"Notification"
],
"operationId": "sendNotification",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotificationMessageRequest"
}
}
},
"required": true
},
"parameters": [{
"name": "Authorization",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
}],
"security": [{
"map_auth": [
"write:message",
"read:message"
]
}],
"summary": "Add a new mapping"
}
}
},
"components": {
"schemas": {
"NotificationMessageRequest": {
"xml": {
"name": "NotificationMessageRequest"
},
"type": "object",
"properties": {
"EmrOid": {
"example": "2.16.724.4.2",
"type": "string"
},
"MessageId": {
"example": "5fea7756-0ea4-451a-a703-a558b933e274",
"type": "string"
},
"MessageType": {
"example": "Clinical report",
"type": "string"
},
"MessageCreatedAt": {
"example": "1606748230567",
"type": "string"
},
"MessageReference": {
"type": "object",
"example": {
"accesspoint": "arn:aws:s3:us-east-1:019364481091:accesspoint/2291405",
"objectKey": "delivery/2291405/cda/xxx.xml"
}
},
"MessageReceiptHandle": {
"description": "Message receipt handle is required to be sent once notification is processed in order to remove message.",
"example": "MbZj6wDWli%2BJvwwJaBV%2B3dcjk2YW2vA3%2BSTFFljTM8tJJg6HRG6PYSasuWXPJB%2BCw%0D%0A++++++++Lj1FjgXUv1uSj1gUPAWV66FU%2FWeR4mq2OKpEGYWbnLmpRCJVAyeMjeU5ZBdtcQ%2BQE%0D%0A++++++++auMZc8ZRv37sIW2iJKq3M9MFx1YvV11A2x%2FKSbkJ0%3D",
"type": "string"
}
},
"required": [
"EmrOid",
"MessageId",
"MessageType",
"MessageCreatedAt",
"MessageReference",
"MessageReceiptHandle"
]
},
"ApiResponse": {
"type": "object",
"properties": {
"Result": {
"type": "string"
},
"Description": {
"type": "string"
}
},
"required": [
"code",
"type",
"message"
]
}
},
"responses": {},
"parameters": {},
"examples": {},
"requestBodies": {},
"headers": {},
"securitySchemes": {
"map_auth": {
"type": "oauth2",
"flows": {
"implicit": {
"authorizationUrl": "http://notification.swagger.io/oauth/dialog",
"scopes": {
"write:message": "",
"read:message": ""
}
}
}
},
"api_key": {
"type": "apiKey",
"in": "header",
"name": "api_key"
}
},
"links": {},
"callbacks": {}
},
"tags": [{
"name": "Notification",
"description": "Notify EMRs about new messages",
"externalDocs": {
"url": "https://confluence.rochedc.accentureanalytics.com",
"description": "Find out more"
}
}]
}