Guide de mise en œuvre de l’API eOrientation HL7 FHIR

• Pour configurer les identifiants OAuth2 dans le Portail Ocean, vous devez disposer de la clé de chiffrement partagée (SEK) du site (voir l’étape 2 dans l’article suivant : Guide de configuration de l’intégration HL7 FHIR eOrientation). Si vous ne l’avez pas déjà, l’administrateur du site Ocean peut vous la fournir ou elle peut être récupérée à partir de Connexion Cloud. Consultez le guide suivant pour de l’information supplémentaire Récupérer une clé de chiffrement partagée perdue ou oubliée

• L’URL pour la demande de jeton porteur OAuth2 dans l’environnement de test d’Ocean est

  https://test.cognisantmd.com/svc/oauth2/token

  (la documentation du serveur d’autorisation OAuth 2.0 fait référence à l’environnement de production).

• Ocean retourne les codes d’erreur standard 401/403 de réponse pour les erreurs d’autorisation liées à l’accès à nos points de terminaison sécurisés via OAuth2.
• Si vous êtes verrouillé lors de l’échange de jetons OAuth2, cela peut être réinitialisé par l’administrateur du site. Il peut accéder à la page Admin du site > Identifiants du site > Identifiants OAuth et cliquer sur l’icône de cadenas.

Guide de mise en œuvre de l’eOrientation de l’Ontario :

• Les API FHIR d’eOrientation d’Ocean sont conformes à la version v0.10.0 du Guide de mise en œuvre de l’eOrientation de l’Ontario.
• Il existe une version plus récente (v0.10.1) qui introduit des « changements majeurs » (c’est-à-dire non rétrocompatibles) dans l’ensemble de valeurs MessageEventCode, qui ne sont pas pris en charge par Ocean pour le moment.

Section Profils et opérations :

• Le guide de mise en œuvre de l’eOrientation de l’Ontario comprend une section Profils et opérations qui contient des liens vers la documentation de profilage spécifique pour chaque ressource FHIR utilisée dans la spécification.
• Chaque profil indique pour chaque champ s’il est requis, la cardinalité requise, les valeurs d’énumération acceptées le cas échéant, les invariants spécifiques et toute autre information pertinente associée.
  • Exemple : Le champ telecom de la ressource Patient est requis, et les sous-champs system, value et use sont requis, mais pas les sous-champs rank ou period.

Extension FHIR d’Ocean

• La mise en œuvre d’Ocean utilise trois extensions FHIR.
  1. « http://ehealthontario.ca/fhir/StructureDefinition/ext-id-message-header » dans la ressource MessageHeader
  2. « http://ehealthontario.ca/fhir/StructureDefinition/ext-id-health-card-version-code » dans la ressource Patient
     • Les deux premières sont spécifiées dans le profilage des ressources v0.10.0.
  3. « https://ocean.cognisantmd.com/svc/fhir/v1/CodeSystem/ontario-clinical-wait-time-codes » dans la ressource Rendez-vous du message notify-add-appointment et notify-update-appointment. 
     • La troisième (pour les temps d’attente) a été ajoutée pour répondre aux besoins du Programme de services électroniques de l’Ontario.

Calcul du temps d’attente :

• Ocean calcule les temps d’attente pour chaque Liste d’annuaire de référence et les affiche dans l’Ocean Healthmap.
• L’extension FHIR pour les temps d’attente doit être envoyée dans la ressource Rendez-vous pour qu’Ocean mette à jour le temps d’attente en conséquence.
  • Exemple : Lorsqu’une date du rendez-vous est soumise avec l’extension définie à « wait-1 », Ocean utilisera cette date comme la date de la première consultation avec le fournisseur de services de santé dans le calcul du temps d’attente.
    • L’extension doit être définie à « wait-1a » si le rendez-vous est l’évaluation de dépistage initiale plutôt que la consultation réelle.

Gestion des réponses/erreurs

• Les messages réussis retourneront un code de réponse 200, indiquant qu’Ocean a bien reçu et traité l’orientation.
• Les messages qu’Ocean ne peut pas traiter pour quelque raison que ce soit (données incorrectes, données manquantes, JSON non analysable, etc.) retourneront un code de réponse 40X/50X avec une ressource FHIR OperationOutcome comme corps qui contiendra une description de l’erreur.  Elle comprend une section « issues » où le serveur présentera des informations de débogage lisibles par l’humain pour aider à déterminer la raison de l’erreur.
  • Cette information peut être n’importe quoi, des erreurs d’analyse JSON, des erreurs de validation de la spécification (champs requis manquants ou utilisation de mauvais types de données), des erreurs de logique métier (par exemple, tenter de mettre à jour une orientation qui n’existe pas) et des exceptions de traitement interne de notre côté (généralement des bogues).
  • Avec cette information et la réponse d’erreur, il y a généralement assez d’éléments pour tenter de trouver efficacement la cause sous-jacente.

Ressource Task :

• Ocean n’envoie pas de ressource Task dans aucun de ses messages.   La ressource Task n’est envoyée que par le système cible RMS pour indiquer comment la demande de service originale a été traitée par RMS Target.  La documentation de l’API inclut des exemples de la ressource Task dans les événements de message entrants envoyés à Ocean par RMS Target.

Champs démographiques :

• Ocean ignorera tout champ démographique vide envoyé dans le message « update-service-request » du RMS Target (plutôt que d’écraser/supprimer la valeur existante).

Adresses du patient :

• Si le RMS Target envoie à Ocean deux adresses Patient FHIR, Ocean stockera les deux mais n’affichera que la première dans la charge utile.
• Si plus de deux adresses sont envoyées, Ocean ignorera toutes sauf les deux premières.

Jeton OAuth2 :

• Le jeton OAuth2 envoyé par le RMS Target fournit à Ocean l’information nécessaire pour déterminer à quel site appartient le message (puisque chaque modèle de jeton est spécifique au site). C’est pourquoi l’identificateur du site Ocean n’a pas besoin d’être transmis dans la charge utile.

RefID :

• Le RefID est utilisé par Ocean pour déterminer à quelle eOrientation spécifique la charge utile fait référence dans le site Ocean.

Ressources PractitionerRole :

• Le bundle contiendra deux ressources PractitionerRole, l’une décrivant le demandeur et l’autre décrivant le fournisseur de services.
• Les liens dans ServiceRequest/MessageHeader établissent quelle ressource est reliée à chaque praticien.
• Les identificateurs de numéro de facturation basés sur notre modèle de données Clinicien ont été intégrés dans nos ressources FHIR Practitioner dans les API sortantes. Pour assurer une solution complète, cette mise à jour a maintenant été étendue au traitement des API entrantes. Par conséquent, la définition des numéros de facturation sur les objets clinicien lors de l’arrivée de praticiens FHIR est maintenant prise en charge de façon transparente.

• Certains renvois et consultations Ocean impliquent un autre acteur (par exemple, secrétaire médicale, résident) qui soumet la demande au nom du clinicien. Dans ce cas, il y a un autorisateur de la demande et un soumissionnaire de la demande. La charge utile FHIR inclura une troisième ressource Practitioner et PractitionerRole dans le bundle pour le soumissionnaire (ainsi que l’autorisateur et le spécialiste). Voici des exemples de la façon dont les informations du soumissionnaire et de l’autorisateur seront renseignées dans la charge utile :

  	MessageHeader.sender	ServiceRequest.requester	MessageHeader.author
  Assistant du médecin PA envoyant une orientation sous le médecin Dr D	PA	Dr D	Dr D
  Résident R envoyant une orientation sous le médecin Dr D	R	Dr D	Dr D
  Infirmière praticienne IP envoyant une orientation (commandant une IRM) sous le médecin autorisant Dr Digley	IP	Dr D	Dr D
  Secrétaire médicale MOA envoyant une orientation comme déléguée sous Dr D	MOA	Dr D	Dr D

Identificateur du référent :

• L’identificateur du référent n’est pas garanti unique. Cela s’explique par le fait que le référent peut avoir créé l’orientation sans se connecter à un compte utilisateur Ocean (par exemple, directement à partir de l’Ocean Healthmap), de sorte qu’Ocean peut ne pas être en mesure d’assigner un identificateur unique.

DocumentReference :

• Chaque bundle ServiceRequest inclura un DocumentReference pour récupérer une copie PDF de l’eOrientation Ocean.
• Si le demandeur inclut des pièces jointes dans l’eOrientation, celles-ci seront ajoutées au bundle comme ressources DocumentReference distinctes. Dans ce cas, la copie PDF de l’eOrientation sera toujours la première ressource DocumentResource incluse dans le bundle.

Type de contenu de la pièce jointe :

• Selon la spécification HL7 FHIR eOrientation, il n’est pas obligatoire de spécifier le type de contenu/MIME d’une pièce jointe à l’eOrientation.

• Ocean le fournira si connu, mais les systèmes récepteurs ne doivent pas supposer qu’il sera toujours disponible ou qu’il s’agira d’un type de contenu spécifique (par exemple, PDF), puisque les demandeurs peuvent inclure d’autres pièces jointes (par exemple, images).

Récupération du résumé de l’orientation et des pièces jointes :

• Il existe deux méthodes pour récupérer le résumé de l’orientation et les pièces jointes originales à partir d’Ocean :
  1. Le résumé de l’orientation peut être récupéré à l’aide du point de terminaison décrit ci-dessous : https://ocean.cognisantmd.com/public/fhirApiDocs.html#operation/referralReferenceLetter_1 et les pièces jointes individuelles peuvent être récupérées à partir du point de terminaison décrit ci-dessous : https://ocean.cognisantmd.com/public/fhirApiDocs.html#operation/documentReferenceBinary_1

  2. Un PDF consolidé avec le résumé de l’orientation et toutes les pièces jointes peut être récupéré en ajoutant

     ?attachments=true au point de terminaison du résumé de l’orientation  https://ocean.cognisantmd.com/public/fhirApiDocs.html#operation/referralReferenceLetter_1 

Limites de taille des pièces jointes :

• Les API d’Ocean acceptent des tailles de fichier/pièce jointe allant jusqu’à 10 Mo par fichier et jusqu’à un maximum de 50 Mo de pièces jointes à une orientation.
• Ocean renverra une réponse d’erreur au point de terminaison d’envoi si les pièces jointes dépassent ces limites.
• Les systèmes intégrateurs sont responsables d’aviser leurs utilisateurs si une erreur survient (par exemple, afficher un avertissement à l’utilisateur que les pièces jointes ont dépassé les limites acceptables).

Mode test :

• Les cibles d’orientation Ocean ont la possibilité de définir leur liste d’annuaire (sous l’onglet « Activation » de la liste) en « Mode test ». Cela signifie que toutes les orientations envoyées à cette liste seront traitées comme des patients fictifs.
• Pour indiquer qu’une charge utile FHIR correspond à une orientation de test, Ocean ajoutera la propriété  meta.security = HTEST à chaque ressource du bundle.

Données démographiques obligatoires pour les eOrientations dans Ocean :

•  
  •  
    • Ocean envoie les données démographiques de base suivantes du fournisseur pour chaque eOrientation :

• Les données démographiques suivantes sont obligatoires pour soumettre une eOrientation dans Ocean et doivent être présentes dans la ressource Patient :
  • Prénom(s)
  • Nom de famille (Nom de famille)
  • Date de naissance (DDN)
  • Adresse (champ rue)
  • Ville
  • Un champ de contact téléphonique (mobile, fax ou professionnel).

Gestion des valeurs nulles :

• Ocean n’envoie pas de « valeur nulle » lorsque le champ n’a pas été rempli.

Champ Sexe :

• L’objet Patient du standard FHIR R4 prend en charge les quatre valeurs AdministrativeGender suivantes pour sa valeur « sexe » : « masculin », « féminin », « autre » et « inconnu ». Par conséquent, Ocean utilise « inconnu » lorsque la valeur fournie dans la section « Sexe » est laissée vide, « masculin » et « féminin » lorsque ces choix sont sélectionnés, et « autre » lorsque toute autre valeur est fournie. Les fournisseurs de services peuvent inclure des valeurs plus flexibles ou spécifiques selon les besoins cliniques à l’aide du corps du formulaire de demande de service.

Champ Assurance maladie-Province et Identificateur Assurance maladie :

• Ocean vérifie si le champ Assurance maladie-province est rempli avec un code alpha provincial standard à deux lettres (ex. ON, PE).  Si c’est le cas, l’identificateur JHN aura un système de nommage comme

  https://fhir.infoway-inforoute.ca/NamingSystem/ca-XX-patient-hcn où XX est le code alpha à deux lettres et le champ usage sur l’identificateur sera défini à OFFICIAL.

Saisie des systèmes d’identificateurs :

• Les utilisateurs sont invités à saisir le nom du système d’identificateur dans le champ province lorsqu’ils soumettent un numéro d’identification autre qu’un numéro d’assurance maladie provincial.  Par exemple, ils saisiront « ID militaire » dans le champ Assurance maladie-province et le numéro d’identification dans le champ assurance maladie.  Ocean fournira la valeur saisie dans le champ Assurance maladie-province comme identificateur de santé secondaire et définira le champ usage de l’identificateur JHN à SECONDARY.
• Ocean ne valide pas que le numéro d’identification soumis appartient au système d’identification (ex. il ne fait pas de somme de contrôle sur les numéros d’assurance maladie provinciaux).

Catégories de services de santé :

• Les catégories de services de santé utilisées pour identifier les services offerts pour chaque liste d’annuaire sont mappées à SNOMED CT et LOINC.
• Une liste maîtresse des catégories et des mappages est disponible au bas de cet article (PDF et .xlsx fournis).

Données du formulaire d’orientation :

• Le corps du formulaire d’orientation (ex. Allergies, Antécédents médicaux, et toute question ajoutée par le fournisseur de services cliniques à son formulaire d’orientation Ocean) sera envoyé dans la ressource QuestionnaireResponse comme une paire clé-valeur.
• Ocean ne contrôle ni ne contraint les noms de clés créés par le fournisseur de services. Par conséquent, si vous souhaitez mapper les réponses de champs spécifiques du formulaire d’orientation vers des champs cibles RMS, vous devrez vous coordonner avec le fournisseur de services sur les noms de clés.   (Ceci est défini dans le champ Légende de la question, qui est décrit dans l’onglet Général de l’article suivant : Guide de l’éditeur eForm - Ajouter un élément.) 

État du cycle de vie de l’eOrientation :

• Le tableau ci-dessous illustre les états du cycle de vie de l’eOrientation qui peuvent être communiqués par la cible RMS à Ocean et l’état interne correspondant de l’eOrientation dans Ocean. 

• L’état est communiqué par Ocean dans le champ État de la ressource ServiceRequest et est mis à jour par la cible RMS dans le champ État de la ressource Task.

Ressource Patient :

• Une ressource Patient qui inclut l’adresse courriel du patient doit être envoyée dans l’événement de message entrant à Ocean afin de déclencher les notifications courriel au patient. 
• L’onglet Patient du guide de soutien suivant : Où sont envoyés les courriels de notification eConsult et/ou eOrientation ? indique quand les changements d’état dans Ocean enverront un courriel (si reçu dans la ressource Patient).

Dates de rendez-vous :

• Si le site permet plusieurs dates de rendez-vous pour une seule orientation, la liste d’orientation doit avoir plusieurs étiquettes configurées.
• Par défaut, Ocean n’active qu’une seule étiquette pour chaque liste nommée « Rendez-vous ».  Chaque liste d’orientation (Admin du site > Listes d'annuaires > Informations sur la liste > section Détails du service) peut être configurée par l’Admin du site pour ajouter des étiquettes supplémentaires parmi les valeurs suivantes : rendez-vous 1 - 5, date de consultation, date de suivi, date de visite initiale, date de procédure, date de chirurgie.
• Il est fortement recommandé de n’utiliser que ces valeurs dans le champ Appointment.appointmentType.text lors de la création et de la mise à jour d’un rendez-vous à l’aide des messages API.
• Aussi, pour des raisons sémantiques, les seules étiquettes Ocean pouvant être utilisées pour stocker l’attente 2 sont Date de procédure et Date de chirurgie.

État de réservation dans Ocean :

• L’orientation est mise à jour à l’état « Réservé » dans Ocean (ce qui correspond au dossier « Réservé non confirmé » dans le portail Ocean) dès qu’elle reçoit les données de rendez-vous du RMS dans l’événement de message « add-notify-appointment ».
• L’orientation peut être déplacée directement à l’état « Confirmé » dans Ocean (ce qui correspond au dossier « Réservation confirmée » dans le portail Ocean) si une ressource Patient est référencée dans le champ Appointment.participant.actor et que appointment.participant.status est défini à accepté . 
  • Note : Si une orientation passe directement de l’état Nouveau ou Accepté à l’état Réservation confirmée, Ocean enverra tout de même un courriel au patient avec les informations du rendez-vous, mais sans l’option de confirmer leur rendez-vous.

Instructions courriel de rendez-vous patient :

• Les instructions pour le courriel de notification de rendez-vous au patient (ex. instructions de préparation) peuvent être incluses dans le champ Appointment.patientInstruction de l’événement de message « notify-add-appointment ».

Spécification du mode de rendez-vous :

• Le mode de rendez-vous (vidéo, téléphone) peut être spécifié dans le champ Location.type référencé par le champ Appointment.participant.actor :
  • Si le mode est inconnu/non spécifié ou connu comme étant en personne :
    Inclure un participant contenant un acteur avec le code « LOC », affichage « Lieu de la clinique » et une référence à la ressource Location de la liste.
  • Si le rendez-vous est par téléphone :
    Inclure un participant contenant un acteur avec le code « LOC », affichage « Visite téléphonique » et une référence « Location/X » à une Location avec l’ID X dans le Bundle. Définir le champ telecom de Location pour correspondre au numéro de téléphone de la liste.
  • Si le rendez-vous est une visite à domicile :
    Inclure un participant contenant un acteur avec le code « HH », affichage « Lieu du patient » et une référence « Location/X » à une Location avec l’ID X dans le Bundle. Définir l’adresse de Location pour correspondre à l’adresse du patient si elle est disponible.
  • Si le rendez-vous est à un lieu alternatif :
    Inclure un participant contenant un acteur avec le code « LOC », affichage « Lieu de clinique alternatif » et une référence « Location/X » à une Location avec l’ID X dans le Bundle.  La ressource Location doit contenir une adresse et sa description doit correspondre à la description du lieu alternatif (ex. « Lieu de visite de clinique alternatif : ___ »   (REMARQUE : la ressource Location d’exemple fournie dans le fichier zip au bas de la page sera mise à jour pour inclure l’adresse alternative)

Appel API pour les données de rendez-vous :

• Si un appel API est envoyé avec des données de rendez-vous sans étiquette, alors Ocean assignera la première étiquette de rendez-vous qui n’a pas été utilisée dans cette orientation pour ce rendez-vous. Si un appel API est envoyé avec des données de rendez-vous sans étiquette, alors Ocean assignera la première étiquette de rendez-vous qui n’a pas été utilisée dans cette orientation pour ce rendez-vous.
• Si un deuxième rendez-vous est envoyé sans étiquette et que toutes les étiquettes de rendez-vous ont déjà été assignées pour cette orientation, l’API retournera une erreur.
• Alternativement, les données de rendez-vous peuvent être envoyées avec une étiquette de rendez-vous, mais elle doit correspondre à l’une des étiquettes configurées pour ce site.

Champ Task.status :

• Le message notify-update-status est utilisé pour transmettre à Ocean les valeurs d’état d’orientation suivantes dans le champ Task.status :  Accepté, Refusé, Confirmé, Annulé, Terminé, Imprimé, Incomplet, Envoyé.
• Le champ est optionnel et ne doit être rempli par le système tiers que lorsque la valeur d’état d’orientation est différente de la mise à jour précédente envoyée à Ocean.
• Ocean retournera une erreur « L’orientation est déjà dans l’état demandé » si deux mises à jour sont envoyées avec la même valeur d’état.   Ainsi, si l’ensemble interne des états d’orientation du système tiers est plus granulaire que celui d’Ocean, les mises à jour d’orientation doivent contenir l’information pertinente mise à jour sans valeur d’état à moins qu’elle ne change l’état de l’orientation Ocean. 
• Lors de l’envoi de la ressource Task pour mettre à jour l’état de l’orientation, une raison explicative du changement d’état (ex. pourquoi l’orientation a été refusée) peut être ajoutée à l’aide de la propriété Task.businessStatus.text.

ID de service externe :

• L’« ID de service externe » dans la liste d’annuaire (onglet « Activation ») est utilisé comme « id » unique pour le HealthcareService. L’Admin du site peut définir l’ID de service externe comme un ensemble unique de chiffres pouvant être utilisé pour identifier la liste dans l’intégration.

• Ocean prend en charge IPv4 et IPv6
• Ocean enverra l'ensemble du lot/ressources ServiceRequest chaque fois qu'il y a une mise à jour dans l'un des champs de l'eOrientation. La liste des changements est fournie dans le MessageHeader.reason, qui peut servir d’« indices » pour que la cible RMS évalue ce qui a changé. Il revient à la cible RMS de décider quelles mises à jour nécessitent une mise à jour interne et/ou une notification au fournisseur de services.
• Les événements de mise à jour sont suivis dans notre journal d’audit et déclencheront une notification de « mise à jour ». Il est sécuritaire d’ignorer les notifications avec MessageHeader.reason = EVENT_LOGGED.
• Il n'est pas nécessaire d'avoir une réponse synchrone à la transmission pour le message ServiceRequest entrant, autre qu'une réponse HTTP 200 pour indiquer que le message a été reçue avec succès. La prochaine mise à jour d’état asynchrone envoyée à Ocean peut fournir un état plus précis pour l’eOrientation lorsqu’elle est traitée par la cible RMS.
• Si vous utilisez un seul point de terminaison pour recevoir des lots ServiceRequest pour plusieurs sites Ocean, vous pouvez identifier le destinataire prévu en examinant le ServiceRequest / Performer / PractitionerRole / Identificateur, qui contiendra l’ID du site. 
• L’ID ServiceRequest doit être renseigné dans la section meta->profile du MessageHeader. Ceci est requis afin qu’Ocean puisse identifier les messages entrants comme étant conformes à la Spécification Ontario HL7 FHIR eOrientation v0.10.0 afin qu’ils puissent être traités en conséquence.

• De même, lorsque la cible RMS devient « active » avec l’intégration, toute eOrientation préexistante dans le site Ocean ne sera pas envoyée à la cible RMS tant qu’elle n’aura pas été mise à jour (ce qui déclenchera l’envoi d’une notification webhook par Ocean).
• Ocean maintient un journal de tous les envois de messages qui peut être utilisé pour déterminer quels messages ont été manqués. Ils peuvent être « forcés » manuellement à être renvoyés à la cible RMS en effectuant une mise à jour de l’orientation dans le Portail Ocean.

• Lorsqu’une orientation est mise à jour dans Ocean, elle passera entre différents « dossiers » dans le tableau de bord eOrientation. C’est une façon de voir que la mise à jour d’état envoyée à Ocean a été traitée.
• Le journal des événements pour chaque orientation peut être consulté en ouvrant le record d’orientation et en sélectionnant « Voir le journal des événements » dans le menu « Action » en haut à droite. Cela peut aider à déterminer si l’orientation est mise à jour comme prévu.
• Lorsque les API Ocean détectent un taux d’erreur d’appel de plus de 5 % lors des 20 premières tentatives, l’API sera automatiquement désactivée. Elle peut être réactivée en retournant dans Menu Admin > Intégrations, en ouvrant la configuration d’intégration concernée puis en l’enregistrant.
• Les sites d’orientation Ocean peuvent offrir aux patients un formulaire Web d’auto-orientation en plus de l’inscription eOrientation dans Ocean Healthmap.
• Si cette option est activée, ces auto-orientations déclencheront une notification webhook avec un lot ServiceRequest.
• Elles peuvent être distinguées des orientations initiées par un fournisseur de services, car ServiceRequest.requester fera référence à une ressource Patient plutôt qu’à une ressource PractitionerRole.
• Les intégrateurs devraient confirmer avec les parties prenantes commerciales du site s’ils souhaitent que les auto-orientations des patients soient traitées de la même manière que les orientations initiées par un fournisseur de services (par exemple, peuvent-ils créer une nouvelle orientation dans la cible RMS/POS ou doivent-ils le faire uniquement une fois qu’elles ont été « acceptées » dans le Portail Ocean).