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

• Pour définir les informations d'identification OAuth2 dans l'Ocean Portail, vous devez avoir 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 Cloud Connect. Consultez le guide suivant pour des informations supplémentaires Récupération d'une clé de chiffrement partagée perdue / 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 se réfère à l'environnement de production).
• Ocean renvoie les codes d'erreur de réponse standard 401/403 pour les erreurs liées à l'autorisation lors de l'accès à nos points de terminaison sécurisés via OAuth2.
• Si vous êtes bloqué lors de l'échange de jetons OAuth2, cela peut être réinitialisé par l'administrateur du site. Ils peuvent accéder à la page Admin du site > Informations d'identification du site > Page des informations d'identification OAuth et cliquer sur l'icône de cadenas.

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

• Les API FHIR de l'eOrientation d'Ocean sont conformes à la version v0.10.0 du Guide de mise en œuvre de l'eOrientation en 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 en Ontario comprend une section Profils et Opérations qui inclut 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 enum acceptées si applicable, les invariants spécifiques, et toute autre information pertinente associée.
  • Exemple : Le champ telecom sur 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

• L'implémentation 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 premiers sont spécifiés 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 Appointment des messages notify-add-appointment et notify-update-appointment. 
     • Le troisième (pour les temps d'attente) a été ajouté 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 Directory Listing d'orientation et les affiche dans l'Ocean Healthmap.
• L'extension FHIR pour les temps d'attente doit être envoyée dans la ressource Appointment pour qu'Ocean mette à jour le temps d'attente en conséquence.
  • Exemple : Lorsqu'une date de rendez-vous est soumise avec l'extension définie sur "wait-1", Ocean utilisera cette date comme la date de la première consultation avec le fournisseur de services de santé dans les calculs de temps d'attente.
  • L'extension doit être définie sur "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 renverront un code de réponse 200, indiquant qu'Ocean a bien reçue et traitée 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.) renverront un code de réponse 40X/50X avec une Ressource FHIR OperationOutcome comme corps qui contiendra une description de l'erreur. Il inclut une section 'issues' où le serveur présentera des informations de débogage lisibles par l'homme pour aider à déterminer la raison pour laquelle l'erreur a été émise.
  • Ces informations peuvent être n'importe quoi, des erreurs d'analyse JSON, des erreurs de validation de spécification (champs requis manquants ou utilisation de mauvais types de données), des erreurs de logique métier (par exemple, essayer 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 ces informations et la réponse d'erreur, il y a généralement suffisamment d'éléments pour essayer de trouver efficacement le problème sous-jacent.

Ressource de Tâche :

• Ocean n'envoie pas de ressource de Tâche dans aucun de ses messages. La ressource de Tâche est uniquement envoyée 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 de Tâche dans les événements de message entrants envoyés à Ocean par le RMS Target.

Champs Démographiques :

• Ocean ignorera tous les champs démographiques vides envoyés dans le message 'mise à jour-demande-de-service' du RMS Target (plutôt que de remplacer/supprimer la valeur existante).

Adresses des Patients :

• Si le RMS Target envoie à Ocean deux adresses FHIR de Patient, 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 les informations nécessaires pour déterminer à quel site appartient le message (puisque chaque modèle de jeton est spécifique à un site). C'est pourquoi l'ID 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 se réfère la charge utile au sein du site Ocean.

Ressources de Rôle de Praticien :

• Le lot contiendra deux ressources PractitionerRole, l'une décrivant le demandeur et l'autre décrivant le fournisseur de services.
• Les liens dans le ServiceRequest/MessageHeader établissent quelle ressource est connecté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 au sein des API sortantes. Pour garantir une solution complète, cette mise à jour a maintenant été étendue au traitement des API entrantes. En conséquence, la définition des numéros de facturation sur les objets cliniciens lors de l'arrivée des praticiens FHIR est désormais prise en charge de manière transparente.
• Certaines orientations et consultations Ocean impliquent un autre acteur (par exemple, secrétaire médical, résident) qui soumet la demande au nom du clinicien. Dans ce cas, il y a un autorisateur de demande et un soumetteur de demande. La charge utile FHIR inclura une troisième ressource Practitioner et PractitionerRole dans le lot pour le soumetteur, (ainsi que l'autorisateur et le spécialiste). Voici des exemples de la façon dont les informations du soumetteur et de l'autorisateur seront renseignées dans la charge utile :

  	MessageHeader.sender	ServiceRequest.requester	MessageHeader.author
  Assistant 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édical MOA envoyant une orientation en tant que délégué sous Dr. D	MOA	Dr. D	Dr. D

Identificateur du référent :

• L'identificateur du référent n'est pas garanti d'être unique. Cela est dû au fait que le référent peut avoir créé l'orientation sans se connecter à un compte utilisateur Ocean (par exemple, directement depuis le Ocean Healthmap), donc Ocean peut ne pas être en mesure d'assigner un identificateur unique.

DocumentReference :

• Chaque lot 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 lot en tant que ressources DocumentReference distinctes. Dans ce cas, la copie PDF de l'eOrientation sera toujours la première ressource DocumentResource incluse dans le lot.

Type de contenu de la pièce jointe :

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

• Ocean le fournira si c'est 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), car les demandeurs peuvent inclure d'autres pièces jointes (par exemple, des 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é à partir 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 d'intégration sont responsables de notifier leurs utilisateurs en cas d'erreur (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 directory listing (sous l'onglet 'Activation' de la liste) en 'Mode Test'. Cela signifie que toutes les orientations définies sur 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 lot.

Démographie obligatoire pour les eOrientations dans Ocean :

• Ocean envoie les données démographiques de base des fournisseurs 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 (DOB)
  • Adresse (champ de rue)
  • Ville
  • Un champ de contact basé sur le téléphone (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 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 en utilisant le corps du formulaire de demande de service.

Champ HN-Province et Identificateur HN :

• Ocean vérifie si le champ HN-province est rempli avec un code alpha provincial standard à deux lettres (par exemple 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 d'utilisation sur l'identificateur sera défini sur OFFICIEL.

Saisie des systèmes d'identificateurs :

• Les utilisateurs sont invités à entrer le nom du système d'identificateurs dans le champ province lorsqu'ils soumettent un numéro d'identification autre qu'un numéro d'assurance maladie provincial. Par exemple, ils entreront "ID militaire" dans le champ HN-province et le numéro d'identification dans le champ assurance maladie. Ocean fournira la valeur entrée dans le champ HN-province comme identificateur de santé secondaire et définira le champ d'utilisation de l'identificateur JHN avec SECONDAIRE.
• Ocean ne valide pas que le numéro d'identification soumis appartient au système d'identification (par exemple, il ne vérifie pas la somme de contrôle des 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 directory listing sont mappées à SNOMED CT et LOINC.
• Une liste maîtresse des catégories et des mappages est disponible en bas de cet article (fournie en PDF et .xlsx).

Données du formulaire d'orientation :

• Le corps du formulaire d'orientation (par exemple, Allergies, Antécédents médicaux, et toute question que le fournisseur de services cliniques ajoute à son formulaire d'orientation Ocean) sera envoyé dans la ressource QuestionnaireResponse en tant que paire clé-valeur de nom.
• Ocean ne contrôle ni ne contraint les noms de clés créés par le fournisseur de services. Par conséquent, si vous avez l'intention de mapper les réponses de champs spécifiques du formulaire d'orientation dans les champs cibles RMS, vous devrez vous coordonner avec le fournisseur de services sur les noms de clés.   (Cela est défini dans le champ de légende de la question, qui est décrit dans l'onglet Général de l'article suivant : Guide de l'éditeur de formulaire électronique - 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 le RMS Target à Ocean et l'état interne correspondant de l'eOrientation Ocean. 

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

Ressource Patient :

• Une ressource Patient qui inclut l'adresse email du patient doit être envoyée dans le message d'événement entrant à Ocean afin de déclencher des notifications par email au patient. 
• L'onglet Patient du guide de support suivant : Où sont envoyés les emails de notification de consultation électronique et/ou d'eOrientation ? liste les moments où les changements d'état dans Ocean enverront un email (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 devrait 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 > Directory Listings > Informations sur la liste > section Détails du service) peut être configurée par l'Admin du site pour ajouter des étiquettes supplémentaires à partir des valeurs suivantes : rendez-vous 1 - 5, date de consultation, date de suivi, date de première visite, date de procédure, date de chirurgie.
• Il est fortement recommandé que seules ces valeurs soient utilisées 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.
• De plus, pour des raisons sémantiques, les seules étiquettes Ocean qui peuvent être utilisées pour stocker l'attente 2 sont Date de procédure et Date de chirurgie.

État de réservation dans Ocean :

• La référence est mise à jour à un état "Réservé" dans Ocean (ce qui correspond au dossier 'Réservé Non Confirmé' dans l'Ocean Portail) une fois qu'elle reçoit les données de rendez-vous du RMS dans l'événement de message 'add-notify-appointment'.
• La référence peut être déplacée directement à l'état 'Confirmé' dans Ocean (ce qui correspond au dossier 'Réservation Confirmée' dans l'Ocean Portail) si une ressource Patient est référencée dans le champ Appointment.participant.actor et que le appointment.participant.status est réglé sur accepté . 
  • Note : Si une référence passe directement de l'état Nouveau ou Accepté à l'état Réservation Confirmée, Ocean n'enverra pas un courriel au patient lui demandant de confirmer son rendez-vous.

Instructions pour le courriel de rendez-vous du patient :

• Les instructions pour le courriel de notification de rendez-vous du patient (par exemple, les instructions de préparation) peuvent être incluses dans le champ Appointment.patientInstruction de l'événement de message 'notify-add-appointment'.

Spécification du moyen de rendez-vous :

• Le moyen de rendez-vous (vidéo, téléphone) peut être spécifié dans le champ Location.type qui est référencé par le champ Appointment.participant.actor :
  • Si le moyen est inconnu/non spécifié ou connu pour être en personne :
    Inclure un participant contenant un acteur avec le code "LOC", affichage "Emplacement de la clinique" et une référence à la ressource Location de l'annonce.
  • Si le rendez-vous est basé sur le 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" à un emplacement avec l'ID X dans le Bundle. Régler les télécommunications de l'emplacement pour correspondre au numéro de téléphone de l'annonce.
  • Si le rendez-vous est une visite à domicile :
    Inclure un participant contenant un acteur avec le code "HH", affichage "Emplacement du Patient" et une référence "Location/X" à un emplacement avec l'ID X dans le Bundle. Régler l'adresse de l'emplacement pour correspondre à l'adresse du patient si elle est disponible.
  • Si le rendez-vous est à un emplacement alternatif :
    Inclure un participant contenant un acteur avec le code "LOC", affichage "Emplacement Alternatif de la Clinique" et une référence "Location/X" à un emplacement avec l'ID X dans le Bundle.  La ressource Location doit contenir une adresse et sa description doit correspondre à la description de l'emplacement alternatif (par exemple, "Emplacement de Visite de Clinique Alternative : ___"   (NOTE : l'exemple de ressource Location fourni dans le fichier zip en bas de la page sera mis à 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 référence 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 référence 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 référence, l'API renverra 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 de mise à jour de l'état de notification est utilisé pour transmettre à Ocean les valeurs d'état de référence suivantes dans le champ Task.status : Accepté, Refusé, Confirmé, Annulé, Terminé, Imprimé, Incomplet, Envoyé.
• Le champ est facultatif et ne doit être rempli par le système tiers que lorsque la valeur de l'état de la référence est différente de la mise à jour précédente envoyée à Ocean.
• Ocean renverra une erreur de "La référence 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 de référence du système tiers est plus granulaire que celui d'Ocean, les mises à jour de référence doivent contenir les informations mises à jour pertinentes sans valeur d'état à moins qu'elle ne modifie l'état de la référence Ocean. 
• Lors de l'envoi de la ressource Task pour mettre à jour l'état de la référence, une raison explicative du changement d'état (par exemple, pourquoi la référence a été refusée) peut être ajoutée en utilisant la propriété Task.businessStatus.text.

ID de Service Externe :

• L'"ID de service externe" dans le listing du répertoire (onglet 'Enablement') est utilisé comme "id" unique pour le HealthcareService. L'administrateur du site peut définir l'ID de Service Externe comme un ensemble unique de chiffres pouvant être utilisé pour identifier le listing dans l'intégration.

• Ocean prend en charge à la fois IPv4 et IPv6
• Ocean enverra l'ensemble du bundle/ressources ServiceRequest chaque fois qu'il y a une mise à jour de l'un des champs de l'orientation. La liste des modifications est fournie dans le MessageHeader.reason qui peut servir d'« indices » pour que la cible RMS évalue ce qui a changé. Il appartient à 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ûr d'ignorer les notifications avec le 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çu avec succès. La prochaine mise à jour d'état asynchrone envoyée à Ocean peut fournir un état plus spécifique pour l'orientation lorsqu'elle est traitée par la cible RMS.
• Si vous utilisez un seul point de terminaison pour recevoir des bundles ServiceRequest pour plusieurs sites Ocean, vous pouvez identifier qui est le destinataire prévu en examinant le ServiceRequest / Performer / PractitionerRole / Identificateur, qui contiendra l'ID du site.  
• L'ID du ServiceRequest doit être renseigné dans la section meta->profile du MessageHeader. Cela est requis pour qu'Ocean puisse identifier les messages entrants comme conformes à la spécification Ontario HL7 FHIR eReferral 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, toutes les orientations électroniques préexistantes qui existent dans le site Ocean ne seront pas envoyées à la cible RMS tant qu'elles ne seront pas mises à jour (ce qui déclenchera Ocean pour envoyer une notification webhook).
• 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 l'Ocean Portail.

• À mesure qu'une orientation est mise à jour dans Ocean, elle se déplacera entre divers 'dossiers' dans le tableau de bord eOrientation. C'est une façon de voir que la mise à jour de l'état envoyée à Ocean a été traitée.
• Le journal des événements pour chaque orientation peut être consulté en ouvrant le record de l'orientation et en sélectionnant 'Voir le journal des événements' à partir du 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, elles désactiveront automatiquement l'API. Elle peut être réactivée en retournant dans Menu Admin > Intégrations, en ouvrant la configuration d'intégration pertinente et en l'enregistrant.
• Les sites d'orientation Ocean peuvent offrir aux patients un formulaire de site web d'auto-orientation ainsi que la liste eOrientation dans l'Ocean Healthmap.
• Si cela est activé, ces auto-orientations déclencheront une notification webhook avec un ensemble ServiceRequest.
• Ils peuvent être distingués des orientations initiées par le 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 le fournisseur de services (par exemple, peuvent-ils créer une nouvelle orientation dans le RMS Target/POS ou devraient-ils seulement le faire une fois qu'elles ont été 'acceptées' dans l'Ocean Portail).