Skip to content

Send a document into the EHR

The EHR (DPI in french) is a software gathering the medical data of all patients of a healthcare facility. EHR providers usually support HPRIM, HL7, but they each have some specificities which can make it difficult to integrate documents into it. After years of exchange with many EHR providers, Lifen provides a reliable matching parser giving you the opportunity to easily integrate medical documents into the EHR of any hospital.

Access Control

You have to use the Access Token of an authenticated user with the BINARY_CREATE, DOCUMENTREFERENCE_CREATE, COMMUNICATIONREQUEST_CREATE, ENCOUNTER_CREATE, PATIENT_CREATE, and PATIENT_SEARCH permissions in the scope to access the FHIR API. For user authentication, take a look at the Connect Users Guide.

How does EHR integration work ?

First, make sure you have previously created a FHIR Patient and a FHIR Encounter on the API. (see paragraph below for more information)

Next, you have to upload the document on the FHIR Document API, add metadata to it, then create a request of communication.

Posting your CommunicationRequest will trigger several operations :

  • Gather all data about the patient (through the FHIR Patient and the FHIR Encounter resources)
  • Transform all FHIR information in HL7-ORU or HPRIM format
  • Post the document on a dedicated server
  • Create a Communication. The communication can have 2 status:
    • success: the document has been integrated into the DPI
    • entered-in-error: an error occurred during the integration.

Requested property on the Patient resource

Patients can be created by sending a POST to api.lifen.fr/fhir/v2/Patient with a JSON body following this example :

{
  "resourceType": "Patient",
  "meta": {
    "tag": [
      {
        "system": "https://www.lifen.fr/default",
        "code": "DEFAULT",
        "display": "Default tag"
      }
    ]
  },
  "identifier": [
    {
      "use": "official",
      "type": {
        "coding": [
          {
            "system": "http://interopsante.org/fhir/valueset/fr-patient-identifier-type",
            "version": "1.0",
            "code": "PI",
            "display": "PI"
          }
        ]
      },
      "system": "urn:oid:1.2.250.1.71.4.2.2.${custodian-idnat}",
      "value": "xxxxxxx"
    }
  ],
  "name": [
    {
      "family": "xxxxxxx",
      "given": [
        "xxxxxxxx"
      ]
    }
  ],
  "birthDate": "YYYY-MM-DD",
  "managingOrganization": {
    "reference": "Organization/xxxxxxx"
  }
}

Take care of the following attributes :

  • custodian-idnat is the national identifier of the healthcare facility where the EHR is.
  • value is the patient's IPP. This value is assigned to a patient when he comes for the first time in a hospital. This number is unique and will never change inside the same organization.
  • family name, given name, birthDate and managingOrganization are mandatory fields
  • managingOrganizationis the value of http://lifen.fr/userInfo.currentWorkspaceId from the user's ID token

Important: A patient cannot be created twice with the same IPP and ManagingOrganization. If it's the case, the FHIR API Patient will return an Error 412, and the Patient will have to be found first using the patient search documentation.

Requested property on the Encounter resource

Integrating a document into the EHR requires a Patient resource, and an Encounter resource attached to it.

An Encounter can be created by sending a POST to api.lifen.fr/fhir/v2/Encounter with a JSON body following this example :

{
  "resourceType": "Encounter",
  "status": "xxxxxxxxxx",
  "subject": {
    "reference": "Patient/xxxxxxxxxx"
  },
  "identifier": [
    {
      "use": "official",
      "type": {
        "coding": [
          {
            "system": "http://www.interopsante.org/fhir/valueset/fr-encounter-identifier-type",
            "version": "3.0.1",
            "code": "VN",
            "display": "Visit Number"
          }
        ]
      },
      "system": "urn:oid:1.2.250.1.71.4.2.2.${custodian-idnat}",
      "value": "${visit-number-value}",
      "assigner": {
        "reference": "Organization/xxxxxxxx"
      }
    }
  ],
  "period": {
    "start": "YYYY-MM-DDThh:mm:ss+00:00",
    "end": "YYYY-MM-DDThh:mm:ss+00:00"
  },
  "serviceProvider": {
    "reference": "Organization/xxxxxxxxxx"
  }
 }

Take care of the following attributes :

  • custodian-idnat : the national identifier of the healthcare facility
  • visit-number-value : the value of the visit number
  • status: planned | arrived | triaged | in-progress | onleave | finished | cancelled
  • subject: the patient present at the encounter (previously created or searched)
  • period: start and end of the encounter (year - month - day and hour in UTC). At least one property is mandatory.
  • serviceProvider and assigner: the custodian organization of this Encounter record. It is the managingOrganization present on the Patient.

Create a Binary resource to upload a PDF report

How to create a Binary

Create a DocumentReference resource containing the document's metadata

How to create a DocumentReference

Create a CommunicationRequest resource

Send a POST api.lifen.fr/fhir/v2/CommunicationRequest with a JSON body referencing the previously created DocumentReference, the sender, the requester, the recipient and the subject of the document.

Example :

{
  "resourceType": "CommunicationRequest",
  "meta": {
    "tag": [
      {
        "system": "http://lifen.fr/fhir/tag/processing/mode",
        "code": "IMMEDIATE_MODE",
        "display": "request should be treated in immediate mode"
      }
    ]
  },
  "status": "active",
  "priority": "routine",
    "extension": [
        {
          "url": "http://lifen.fr/fhir/StructureDefinition/communicationrequest-active-devices",
          "valueReference": {
            "reference": "Device/xxxxxxx"
          }
        }
      ],
  "category": [
    {
      "coding": [
        {
          "system": "http://lifen.fr/fhir/ValueSet/communication-category",
          "code": "MEDICAL_REPORT"
        }
      ]
    }
  ],
  "payload": [
    {
      "contentReference": {
        "reference": "DocumentReference/xxxxxxx"
      }
    }
  ],
    "subject": {
    "reference": "Patient/xxxxxxx"
  },
    "topic": [
    {
      "reference": "Patient/xxxxxxx"
    }
  ],
  "context": {
    "reference": "Encounter/xxxxxxx"
  },
  "sender": {
    "reference": "Practitioner/xxxxxxx"
  },
  "requester": {
    "agent": {
      "reference": "Organization/xxxxxxx"
    }
  },
"recipient": [
    {
      "reference": "Device/xxxxxxx"
    }
  ]
}

Take care of the following attributes :

  • device : a value provided by Lifen
  • sender :
    • User token : one of the identities to choose in the http://lifen.fr/userInfo.identities array from the user's ID token
    • Application token : ask our solution architect at Lifen for the Organization FHIR reference corresponding to healthcare organization you are connected to
  • requester :
    • User token : the value of http://lifen.fr/userInfo.currentWorkspaceId from the user's ID token
    • Application token : ask our solution architect at Lifen for the Organization FHIR reference corresponding to your application
  • subjectand topic : the value of the ID for the previously created Patient resource
  • context : the value of the Encounter ID previously created or fetched

After that, the CommunicationRequest will be integrated into Lifen's sending flow to add other information and eventually send the document to the DPI.

Check the status of the document sent to the EHR

After posting the CommunicationRequest, Lifen creates a Communication resource per recipient. In the case of a document sent to the EHR, the recipient is a Device. To know if the document has been successfully sent into the EHR, you have to check the status of the Communication generated by Lifen.

Send a GET request on api.lifen.fr/fhir/v2/Communication?based-on=CommunicationRequest/xxxx with reference id of the CommunicationRequest previously created

Check the status field on the Communication (Status documentation) to know if the integration is successful.

If the status is entered-in-error, then check the notDoneReason field to know the detailed reason of the failure (notDoneReason documentation)

Example :

{
  "resourceType": "Communication",
  "status": "entered-in-error",
  "notDone": true,
  "notDoneReason": {
    "coding": [
      {
        "system": "http://lifen.fr/fhir/ValueSet/communication-status-reason",
        "code": "missing-info",
        "display": "Informations manquantes pour la génération du document."
      }
    ]
  },
  ...
}

Check the body of HL7 ORU message send sent to DPI in the value of the extension with system http://lifen. fr/fhir/internal/StructureDefinition/communication-body

Example :

{
  "resourceType": "Communication",
  "extension": [
    {
      "url": "http://lifen.fr/fhir/internal/StructureDefinition/communication-body",
      "valueString": "MSH|^~\\&|LIFEN|LIFEN|OX|OX|20190828153104||ORU^R01^ORU_R01|11355081566999064230|P|2.
      5|||AL||FRA|UTF-8\rPID|1||10000030^^^^PI||SMITH^TESTUN^^^^^D||19620201|U||||||||||||||||||||||\rPV1||O|||||||||||||||||19001001
      ||||||||||||||||||||||||||||||||V|\rOBR|1||1135481|CR hospitalisation|||20190828|||||||||||||||||||||||||\rOBX|1|RP||11493-4|test.
      pdf||||||F|||20190828152818||10003730115^DR Didier Brassier^^^^^^^^^^^RPPS"
    },
    ...
  ],
  ...
}