Guide de mise en œuvre de l'API eRéférence HL7 FHIR

• Pour définir les informations d'identification OAuth2 dans le Portail Ocean, vous devez disposer de la Clé de chiffrement partagée du site (SEK) (voir l'étape 2 de l'article suivant : Guide de configuration de l'intégration HL7 FHIR eRéférence). Si vous ne l'avez pas déjà, l'administrateur du site Ocean peut vous la fournir ou vous pouvez la récupérer depuis Cloud Connect. Consultez le guide suivant pour plus d'informations Récupération d'une clé de chiffrement partagée perdue / oubliée
• L'URL pour la demande de jeton d'accès OAuth2 dans l'environnement de test d'Ocean est

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

  (le Documentation du serveur d'autorisation OAuth 2.0 fait référence à l'environnement de production).
• Ocean renvoie les codes d'erreur standard 401/403 en cas d'erreurs liées à l'autorisation pour l'accès à nos points de terminaison sécurisés via OAuth2.
• Si vous êtes bloqué dans l'échange de jetons OAuth2, cela peut être réinitialisé par l'administrateur du site. Ils peuvent accéder à Admin du site > Informations d'identification du site > page des informations d'identification OAuth et cliquer sur l'icône du cadenas.

Guide de mise en œuvre de l'eRéférence en Ontario :

• Les API FHIR de l'eRéférence d'Ocean sont conformes à la version 0.10.0 du Guide de mise en œuvre de l'eRéférence 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'eRéférence en Ontario comporte une section Profils et Opérations qui inclut des liens vers une documentation de profilage spécifique pour chaque ressource FHIR utilisée dans la spécification.
• Chaque profil liste pour chaque champ s'il est requis, la cardinalité requise, les valeurs énumérées acceptées le cas échéant, les invariants spécifiques et toute autre information pertinente qui y est associée.
  • Exemple : Le champ de télécommunication dans la ressource Patient est requis, et les sous-champs système, valeur et utilisation sont requis, mais pas les sous-champs rang ou période.

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 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 notify-add-appointment et notify-update-appointment messages. 
     • La troisième (pour les temps d'attente) a été ajoutée pour répondre aux besoins du Programme des services électroniques de l'Ontario.

Calcul des temps d'attente :

• Ocean calcule les temps d'attente pour chaque répertoire de référencement et les affiche dans la Healthmap d'Ocean.
• 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 de rendez-vous est soumise avec l'extension définie sur "wait-1", Ocean utilisera cette date comme date de la première consultation avec le fournisseur de services de santé dans les calculs de temps d'attente.
  • L'extension devrait être définie sur "wait-1a" si le rendez-vous est l'évaluation initiale de dépistage 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 reçu et traité avec succès la référence.
• Les messages qu'Ocean ne peut pas traiter pour une raison quelconque (mauvaises données, données manquantes, JSON non analysable, etc.) renverront un code de réponse 40X/50X avec une Ressource FHIR OperationOutcome comme corps qui aura une description de l'erreur. Il inclut une section "problèmes" 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 référence qui n'existe pas) et des exceptions de traitement interne de notre part (généralement des bogues).
  • Avec ces informations et la réponse d'erreur, il y a généralement assez 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 le système cible RMS. 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 système cible RMS.

Champs démographiques :

• Ocean ignorera tout champ démographique vide envoyé dans le message 'mise à jour de la demande de service' du système cible RMS (plutôt que de remplacer/supprimer la valeur existante).

Adresses des patients :

• Si le système cible RMS envoie à Ocean deux adresses de patient FHIR, Ocean les stockera toutes 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 système cible RMS fournit à Ocean les informations nécessaires pour déterminer à quel site appartient le message (puisque chaque modèle de jeton est spécifique au 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 eRéférence spécifique la charge utile se réfère dans le site Ocean.

Ressources de rôle de praticien :

• Le bundle contiendra deux ressources PractitionerRole, l'une décrivant le demandeur et l'autre décrivant le fournisseur de services.
• Les liens dans la demande de service/MessageHeader établissent quelle ressource est connectée à chaque praticien.
• Les identifiants de numéro de facturation basés sur notre modèle de données Clinician 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. Par conséquent, définir les numéros de facturation sur les objets cliniciens lors de l'arrivée des praticiens FHIR est désormais pris en charge de manière transparente.
• Certaines références et consultations Ocean impliquent un autre acteur (par exemple, un secrétaire médical, un résident) qui soumet la demande au nom du clinicien. Dans ce cas, il y a un autorisateur de la demande et un soumetteur de la demande. La charge utile FHIR inclura une troisième ressource Practitioner et PractitionerRole dans le bundle pour le soumetteur, (avec l'autorisateur et le destinataire). 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édical PA envoyant une référence sous la supervision du médecin Dr. D	PA	Dr. D	Dr. D
  Résident R envoyant une référence sous la supervision du médecin Dr. D	R	Dr. D	Dr. D
  Infirmière praticienne NP envoyant une référence (ordonnant une IRM) sous la supervision du médecin autorisant Dr. Digley	NP	Dr. D	Dr. D
  Secrétaire médical MOA envoyant une référence en tant que délégué sous la supervision du Dr. D	MOA	Dr. D	Dr. D

Identifiant du référent :

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

Document de référence :

• Chaque bundle de demande de service inclura un Document de référence pour récupérer une copie PDF de l'eRéférence Ocean.
• Si le demandeur inclut des pièces jointes dans l'eRéférence, celles-ci seront ajoutées au bundle en tant que ressources Document de référence distinctes. Dans ce cas, la copie PDF de l'eRéférence sera toujours la première ressource Document de référence incluse dans le bundle.

Type de contenu de la pièce jointe :

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

• Ocean fournira l'information si elle est connue, mais les systèmes récepteurs ne doivent pas supposer qu'elle 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 la référence et des pièces jointes :

• Il existe deux méthodes pour récupérer le résumé de la référence et les pièces jointes originales depuis Ocean :
  1. Le résumé de la référence 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 la référence et toutes les pièces jointes peut être récupéré en ajoutant

     ?attachments=true au point de terminaison du résumé de la référence  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 pièces jointes/fichiers allant jusqu'à 10 Mo par fichier et jusqu'à un maximum de 50 Mo de pièces jointes pour une référence.
• 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égrés sont responsables de notifier leurs utilisateurs en cas d'erreur (par exemple, afficher un avertissement à l'utilisateur indiquant que les pièces jointes ont dépassé les limites acceptables).

Mode Test :

• Les cibles de référence d'Ocean ont la possibilité de définir leur répertoire de listage (dans la section Avancé de la liste) en 'Mode Test eRéférence'. Cela signifie que toutes les références définies dans cette liste seront traitées comme des patients fictifs.
• Pour indiquer qu'une charge utile FHIR correspond à une référence de test, Ocean ajoutera la propriété  meta.security = HTEST à chaque ressource dans le bundle.

Démographie obligatoire pour les eRéférences dans Ocean :

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

• Les données démographiques suivantes sont obligatoires pour soumettre une eRéférence dans Ocean et doivent être présentes dans la ressource Patient :
  • Prénom(s)
  • Nom de famille
  • Date de naissance
  • Adresse (champ de 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é renseigné.

Champ de 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 renseigné 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 dénomination comme

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

Saisie des systèmes d'identificateurs :

• Les utilisateurs sont invités à saisir le nom du système d'identificateur dans le champ de 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 HN-province et le numéro d'identification dans le champ d'assurance maladie. Ocean fournira la valeur saisie dans le champ HN-province en tant qu'identificateur de santé secondaire et définira le champ d'utilisation de l'identificateur JHN sur SECONDAIRE.
• Ocean ne valide pas si 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 annonce répertoriée dans l'annuaire sont mappées à SNOMED CT et LOINC.
• Une liste principale des catégories et des mappages est disponible en bas de cet article (fournie en PDF et .xlsx).

Données du formulaire de référence :

• Le corps du formulaire de référence (par exemple, Allergies, Antécédents médicaux et toutes les questions ajoutées par le fournisseur de services cliniques à leur formulaire de référence Ocean) sera envoyé dans la ressource QuestionnaireResponse sous forme de paire clé-valeur.
• Ocean ne contrôle pas ni ne limite 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 de référence dans les champs cibles RMS, vous devrez 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'eRéférence :

• Le tableau ci-dessous illustre les états du cycle de vie de l'eRéférence qui peuvent être communiqués par le RMS Target à Ocean et l'état interne de l'eRéférence Ocean correspondant.

• 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 Tâche.

Ressource Patient :

• Une ressource Patient qui inclut l'adresse e-mail du patient doit être envoyée dans l'événement de message entrant à Ocean afin de déclencher des notifications par e-mail au patient.
• L'onglet Patient du guide de support suivant : Où les e-mails de notification d'eConseil et/ou d'eRéférence sont-ils envoyés ? liste quand les changements d'état dans Ocean enverront un e-mail (si reçus dans la ressource Patient).

Dates de Rendez-vous Multiples :

• Si le site permet plusieurs dates de rendez-vous pour une seule référence, la liste de références devrait avoir plusieurs étiquettes configurées.
• Par défaut, Ocean active uniquement une seule étiquette pour chaque liste nommée "Rendez-vous". Chaque liste de références (Administrateur du site > Répertoire des services > Section Détails du service) peut être configurée par l'administrateur du site pour ajouter des étiquettes supplémentaires parmi les 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é d'utiliser uniquement ces valeurs dans le champ textuel Appointment.appointmentType.text lors de la création et de la mise à jour d'un rendez-vous en utilisant les 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 :

• Le renvoi est mis à jour à un état "Réservé" dans Ocean (ce qui correspond au dossier 'Réservé non confirmé' dans le portail Ocean) une fois qu'il reçoit les données de rendez-vous du RMS dans l'événement de message 'ajouter-notifier-rendez-vous'.
• Le renvoi peut être directement déplacé à 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 le statut de l'acteur du rendez-vous est défini sur accepté . 
  • Note : Si un renvoi passe directement de l'état Nouveau ou Accepté à l'état Réservation confirmée, Ocean n'enverra pas d'e-mail au patient lui demandant de confirmer son rendez-vous.

Instructions par courriel de rendez-vous pour le patient :

• Les instructions pour le courriel de rendez-vous du patient (par ex., instructions de préparation) peuvent être incluses dans le champ Appointment.patientInstruction de l'événement de message 'notifier-ajouter-rendez-vous'.

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", afficher "Emplacement de la clinique" et une référence à la ressource Emplacement de l'inscription.
  • Si le rendez-vous est basé sur téléphone :
    Inclure un participant contenant un acteur avec le code "LOC", afficher "Visite téléphonique" et une référence "Emplacement/X" à un Emplacement avec l'ID X dans le Bundle. Définir le téléphone de l'Emplacement pour correspondre au numéro de téléphone de l'inscription.
  • Si le rendez-vous est une visite à domicile :
    Inclure un participant contenant un acteur avec le code "HH", afficher "Emplacement du patient" et une référence "Emplacement/X" à un Emplacement avec l'ID X dans le Bundle. Définir 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", afficher "Emplacement alternatif de la clinique" et une référence "Emplacement/X" à un Emplacement avec l'ID X dans le Bundle.  La ressource Emplacement doit contenir une adresse et sa description doit correspondre à la description de l'emplacement alternatif (par ex., "Emplacement de visite de clinique alternatif : ___"   (REMARQUE : la ressource Emplacement d'exemple fournie dans le fichier zip en 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 ce renvoi 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 ce renvoi 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 ce renvoi, 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 statut de la tâche :

• Le message de mise à jour de statut de notification est utilisé pour transmettre à Ocean les valeurs d'état de référence suivantes dans le champ État de la tâche : Accepté, Refusé, Confirmé, Annulé, Terminé, Imprimé, Incomplet, Envoyé.
• Le champ est facultatif et ne doit être renseigné que par le système tiers lorsque la valeur d'état de 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. Par conséquent, si l'ensemble interne de statuts de référence du système tiers est plus détaillé que celui d'Ocean, les mises à jour de référence doivent contenir les informations mises à jour pertinentes sans valeur d'état à moins que cela ne modifie l'état de référence d'Ocean.
• Lors de l'envoi de la ressource Tâche 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é texte de Task.businessStatus.

ID de service externe :

• L'"ID de service externe" dans la liste des répertoires est utilisé comme "id" unique pour le Service de santé. L'administrateur du site peut définir l'ID de service externe comme un ensemble unique de chiffres pouvant être utilisé pour identifier l'inscription dans l'intégration.

• Ocean prend en charge à la fois IPv4 et IPv6
• Ocean enverra l'ensemble des ressources/bundles de ServiceRequest à chaque mise à jour de l'un des champs de recommandation. La liste des modifications est fournie dans le MessageHeader.reason, qui peut servir de « 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 « mise à jour ». Il est sûr d'ignorer les notifications avec le MessageHeader.reason = ÉVÉNEMENT_ENREGISTRÉ.
• Il n'est pas nécessaire de fournir une réponse synchrone à la transmission du message de 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 la recommandation lorsqu'elle est traitée par la cible RMS.
• Si vous utilisez un seul point de terminaison pour recevoir des bundles de ServiceRequest pour plusieurs sites Ocean, vous pouvez identifier le destinataire prévu en examinant l'Identificateur de ServiceRequest / Performer / PractitionerRole / Identifier, qui contiendra l'ID du site.  
• L'Identificateur de 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 eRéférence HL7 FHIR de l'Ontario v0.10.0 afin qu'ils puissent être traités en conséquence.

• De même, lorsque la cible RMS devient « opérationnelle » avec l'intégration, les eRéférences 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 l'envoi d'une notification webhook par Ocean).
• Ocean conserve 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 » à être renvoyés à la cible RMS en apportant une mise à jour à la recommandation dans le Portail Ocean.

• À partir du moment où une référence est mise à jour dans Ocean, elle se déplacera entre différents 'dossiers' dans le tableau de bord eRéférence. C'est une façon de voir que la mise à jour de statut envoyée à Ocean a été traitée.
• Le journal des événements pour chaque référence peut être consulté en ouvrant le dossier de référence et en sélectionnant 'Voir le journal des événements' dans le menu 'Action' en haut à droite. Cela peut aider à déterminer si la référence est mise à jour comme prévu.
• Lorsque les API Ocean détectent un taux d'erreur d'appel de plus de 5% dans les 20 premières tentatives, elles désactivent automatiquement l'API. Elle peut être réactivée en retournant dans Menu Admin > Intégrations, en ouvrant la configuration d'intégration pertinente, puis en la sauvegardant.
• Les sites de référence Ocean peuvent offrir aux patients un formulaire de site web d'auto-référence ainsi que la liste eRéférence dans le Healthmap Ocean.
• Si cela est activé, ces auto-références déclencheront une notification webhook avec un bundle ServiceRequest.
• Elles peuvent être distinguées des références 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 veulent que les auto-références des patients soient traitées de la même manière que les références initiées par le fournisseur de services (par exemple, peuvent-elles créer une nouvelle référence dans la cible RMS/POS ou devraient-elles le faire uniquement une fois qu'elles ont été 'acceptées' dans le Portail Ocean).