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

  1. Generate Key (Example): openssl genrsa -out company.qaeu.server.key 2048

  2. 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

  1. 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"
		}
	}]
}