Documentation de l’outil de rapprochement des centres¶

L’outil de rapprochement des centres est un produit de sources ouvertes et basé sur des normes ouvertes utilisé pour comparer les listes de centres à partir de différentes sources de données. L’outil prend en charge le téléchargement de fichiers CSV et la connexion aux serveurs FHIR et DHIS2.

L’outil peut être utilisé comme application indépendante avec sa propre authentification ou sous forme d’appli DHIS2 facile d’installation qui utilise DHIS2 pour l’authentification prenant en charge l’outil en arrière-plan.

Si vous apprenez tout juste à connaître ces outils, veuillez essayer les démarrages rapides !

Pour obtenir de l’aide, veuillez consulter ce guide, y compris la section FAQ.

Pour consulter les annonces ou discussions, inscrivez-vous sur le Groupe Google de registres d’installations <https://groups.google.com/forum/#!forum/facility-registry>`_.
Pour participer à des discussions mensuelles au sujet des registres d’installations, inscrivez-vous à la « Communauté de registre d’installations OpenHIE »<https://wiki.ohie.org/display/SUB/Facility+Registry+Community>`_.
Créez une question sur le repositoire GitHub GitHub Repository.

Démarrages rapides.¶

Données d’exemple¶

Téléchargez les données d’exemple¶

Consultez la fiche exemple pour les données du Centre de soins de Fauxpays.
Il y a deux fiches de travail à l’intérieur (cf. onglets au bas), une pour la Source ONG 1 et une pour la Source 2 DHIS2. Il s’agit de données fictives à utiliser avec l’outil.
Téléchargez chaque onglet comme fichier CSV séparé sur votre ordinateur en cliquant sur le menu Fichier et en choisissant Télécharger comme; valeurs séparées par des virgules
Sauvegardez les fichiers sur votre ordinnateur dans un dossier facile d’accès.

_images/get_example_data.png

Téléchargez les données.¶

Accédez à l’outil de rapprochement à partir du site : http://facility.org et cliquez sur DEMO. Vous verrez un avis de non-responsabilité. Si vous l’acceptez, veuillez cliquer sur continuer.
Dans la version hébergée, connectez-vous en utilisant demo:demo pour utilisateur:motdepasse.
Sur le site, choisissez Ajouter une source en haut de la page au centre et sélectionnez Télécharger CVS.

_images/upload_csv.png

Donnez le nom de votre choix au téléchargement et cliquez sur Téléchargement CSV. Sélectionnez le fichier Centres de soins de Fauxpays - Source 1 ONG là où vous l’avez sauvegardé sur votre ordinateur.
Cliquez pour continuer. Les données seront téléchargées dans le système.

_images/upload_dialog.png

Vous vous trouverez dans une nouvelle fenêtre de dialogue qui vous demande d’affecter des entêtes pour le nom du centre, le code identifiant du centre et les niveaux administratifs. Veuillez sélectionner les entêtes qui conviennent dans le menu déroulant comme indiqué sur la capture d’écran ci-dessous.

_images/upload_select_columns.png

Cliquez sur le bouton bleu de téléchargement.
Procédez à nouveau aux étapes ci-dessus pour télécharger les données mais cette fois-ci donnez le nom de DHIS2 au téléchargement et choisissez le fichier Centre de soins de Fauxpays - Source 2 DHIS2 sur votre ordinnateur.
Vous devriez maintenant avoir deux sources de données.

_images/data_sources_list.png

Mise en correspondance des données¶

Le couplage des listes de centres consiste tout d’abord à créer une paire de sources de données et puis de procéder au rapprochement en commençant par le niveau le plus élevé et en descendant dans la hiérarchie jusqu’au dernier niveau.

Couplage des données¶

Cliquez sur l’onglet de rapprochement et choisissez Créer et gérer une paire de sources de données. Sélectionnez les deux sources de données. La source de données qui vous choisissez comme Source 1 est la vérité. La source de données que vous sélectionnez comme Source 2 est celle que vous souhaitez corriger.
Choisissez DHIS2 comme Source 1 et ONG commes Source 2.

_images/pair_data.png

Cliquez sur Sauvegarder et vous serez envoyé sur la page de rapprochement.

N.B. : Après la sauvegarde, la paire devrait être active. Si ce n’est pas le cas, choisissez, « Active sous paires de données existantes », puis cliquez sur « Activer la paire ».

Rapprochement¶

Il n’existe que deux régions (le niveau administratif le plus élevé des données de Fauxpays). Elles seront automatiquement mises en correspondance. L’indicateur de statut intitulé COUPLÉ indique que 2 des 2 régions ont été couplées. Dans la partie inférieure de la capture d’écran ci-dessous, vous pouvez également voir que pour le Niveau 1, la correspondance est de 100 %, dans la mesure où les deux emplacements de la Source 1 correspondent aux deux emplacements de la Source 2.
En bas à gauche, cliquez sur District pour continuer.

_images/level_1.png

Au Niveau 2, les districts seront automatiquement mis en correspondance. Cliquez sur Accès au centre pour continuer.

_images/level_2.png

Cliquez sur Passer au Niveau 3.
Au Niveau 3, certains centres ne seront pas couplés.
Une liste de centres sans centre correspondant se trouve dans la boîte de dialogue vert clair pour la Source 1.

_images/level_3_before.png

Sélectionnez un des centres, tel que l’Hôpital de référence générale.
Une fenêtre de dialogue pop-up vous permettra de choisir le centre qui lui correspond.

_images/level_3_match_hospital.png

Sélectionnez le couplage le mieux adapté, dans ce cas-ci, il s’agit de l’hôpital de référence, et cliquez sur Sauvegarder couplage.
Passez en revue les centres non couplés sous Source 1, sélectionnez et sauvegardez les meilleurs couplages. Une fois que vous aurez fini, vous verrez :

_images/level_3.png

Le Statut de rapprochement de la Source 1, dans la boîte de statut en haut à gauche, doit indiquer 100 %.

Exporter le rapport de rapprochement¶

En haut à gauche de l’onglet de rapprochement, se trouve une option pour la production d’un rapport des ensembles de données rapprochées basé sur FHIR ou d’un fichier CSV de ce qui correspond et ce qui ne correspond pas dans chacun des ensembles de données. Choisissez Exporter CSV. Vous serez alors en mesure de choisir trois fichiers de correspondances et non correspondances.

Consultez le statut du rapprochement¶

Sélectionnez Statut du rapprochement et voyez le statut global.

_images/reconciliation_status.png

Ajouter une source DHIS2¶

Cet exemple utilise le terrain de jeu DHIS2 (Playground) qui contient déjà des données fictives, toutefois réalistes, sur un centre.

Configurer une source de données DHIS2¶

Pour vous connecter à tout système DHIS2, vous aurez besoin d’un nom d’utilisateur, d’un mot de passe et de l’URL (adresse Internet) du système DHIS2. Cet exemple utilise le nom d’utilisateur et le mot de passe fournis par le terrain de jeu de démonstration.

Tout serveur DHIS2 peut être utilisé comme source pour laquelle l’utilisateur peut s’authentifier et est autorisé à accéder au centre et à la hiérarchie.

L’URL de base est le site Web du système DHIS2. L’URL donnée en exemple dans le terrain de jeu peut prêter à confusion quelque peu parce qu’il contient /2.31.3, la raison étant que le terrain de jeu héberge de nombreuses versions du système DHIS2 à la même adresse tels que /2.32, etc. Dans d’autres systèmes DHIS2, il n’y aura pas de /version.

Ouvrez l’outil de rapprochement des données sur les centres. Sélectionnez « Sources de données ».

_images/dhis2_datasources.png

Sélectionnez la source à distance
Dans le formulaire d’ajout de nouvelle source à distance, procédez ainsi :

Field	Entry	Notes
Source Type	DHIS2	This configures the form for DHIS2.
Source Name	DHIS2 play	Any name is acceptable.
Base URL	https://play.dhis2.org/2.31.3/	DHIS2 playground for version 2.31. Other DHIS2 do not have /version.
Username	admin	This is the username for the playground.
Password	district	This is the password for 'admin' user of the playground.

_images/dhis2_remotesourceform.png

Cliquez sur Ajouter.

Synchro¶

Sélectionnez Voir sources de données dans l’onglat Sources de données.

Les données ne seront extraites de DHIS2 à moins que vous ne procédiez à une synchrnisation forcée ou à une mise à jour de la syncrhonisation.

Cliquez à côté de la source DHIS que vous avez ajoutée pour la sélectionner.
Cliquez sur Mise à jour de la synchronisation.

_images/dhis2_added.png

L’outil de rapprochement sera maintenant ajouté aux données de la source DHIS2. Pour continuer, ajoutez une autre source de données ou s’il y en a déjà une que vous souhaitez utiliser, créez une paire de données.

Guide de l’utilisateur¶

Sources de données¶

Veuillez noter que vous trouverez dans la présente documentation un démarrage rapide sur la manière de télécharger un fichier CSV.

L’outil prend en charge le fichier CSV comme fichier source, ainsi que toute connexion à distance aux serveurs DHIS2 et FHIR.

Data Fields	Required	Optional	Notes
CSV	facility name, ID	administrative levels, longitude and latitude	Column names in the first row, UTF-8 encoding
FHIR server	location name, ID	`partOf` locations (administrative levels)
DHIS2 instance	org unit name, ID	org units (administrative levels)

Télécharger un fichier CSV¶

Le nom des colonnes doit figuré sur la première rangée du fichier CSV. Les rangées vides doivent être supprimées. Le fichier CSV doit être encodé en format Unicode (utf-8) dans la mesure où c’est ce qui est utilisé en interne en backend. Si certaines entités sont encodées en format autre, alors les couplages qui semblent être identiques risquent de ne pas l’être comme escompté.

Les colonnes de latitude et de longitude sont facultatives. Si elles sont incluses, elles seront utilisées pour faciliter le rapprochement manuel mais elles ne seront pas utilisées ni requises en mode automatique.

Une fois téléchargées, dans l’onglet de visualisation, les saisies CSV peuvent être modifiées. Aucune modification ne peut changer la source de données d’origine mais les modifications seront exportées après le rapprochement.

Sélectionner les niveaux¶

Les utilisateurs peuvent choisir d’inclure tout niveau de leur hiérarchie mais ils doivent être classés avec le niveau le plus élevé d’abord.

Il est également possible de sélectionner aucun niveau pour coupler une liste plate sans hiérarchie. Pour ce faire, ne sélectionnez aucun niveau.

Serveurs à distance – DHIS2 ou FHIR¶

L’outil prend en charge les sources à distance. Tout serveur DHIS2 ou FHIR peut être utilisé comme source si l’utilisateur est habilité à y avoir accès.

Aucun test approfondi de compatibilité n’a été réalisé mais les versions de DHIS2 >=2.22 devraient être prises en charge. Veuillez contacter le service chargé de la maintenance en cas de problème.

FHIR est pris en charge pour STU3 et la prise en charge de R4 est anticipée. D’autres serveurs FHIR peuvent être ajoutés à des versions ultérieures de l’outil, tels que le serveur HAPI FHIR.

Couplage¶

Veuillez noter qu’il existe, sur la chaîne YouTube Open HIE, un tutoriel vidéo sur la manière de coupler, ainsi qu’un démarrage rapide dans la présente documentation.

Le rapprochement des sources de données implique le choix d’une paire de sources avec lesquelles travailler, puis le lancement de l’outil de couplage automatique ou manuel. Tout couplage peut être défait.

Couplage de sources¶

Sous l’onglet de rapprochement sur la page de création et de gestion des sources de données. Sous l’onglet des paires, sélectionnez une source à gauche et une source à droite, la source de gauche (la source 1) est la source leader, celle de la vérité. La source de droite est la source suiveuse, celle qui est doit être nettoyée.

_images/pairpage.png

Dans le cadre du processus de couplage, il est possible de partager la paire avec un autre utilisateur susceptible de contribuer à l’exercice de rapprochement, par exemple, lorsqu’il s’agit d’une personne qui connaît bien le lieu.

Couplage automatique¶

Lorsque le processus de rapprochement démarre, il utilise le couplage automatique. Le couplage se fait ainsi :

Le premier niveau rapproche les noms des zones administratives les plus élevées (intitulées régions pour les besoins de cet outil) à l’aide de la distance de Levenshtein.
Le couplage au deuxième niveau se fait sur la base du premier niveau, ainsi que de la distance de Levenshtein pour les noms de deuxième niveau, appelés districts pour les besoins de l’outil.
Les couplages de derniers niveaux sont basés sur ceux du deuxième niveau (qui se basaient déjà sur le niveau supérieur) ainsi que sur la distance de Levenshtein.

Recalculer les scores¶

Lors du processus de couplage à tout niveau, il est possible de demander à l’outil de coupler des entité non couplées à l’aide du bouton de recalcu des scores. Ce processus ne retire pas les paires.

_images/recalculatescores.png

Une des utilisations courantes de cela est le couplage manuel d’entités, quelles qu’elles soient, pour réexécuter le processus de couplage et incorporer les résultats. Cela peut également être utilisé lorsqu’une entité est libérée d’un couplage après avoir été préalablement signalée.

Couplage manuel¶

Le couplage manuel fait apparaître une fenêtre de dialogue pour le choix des options. Si les coordonnées géographiques (latitude et longitude) ont été fournies dans les sources de données, le couplage se base en outre sur la formule de haversine pour déterminer la distance la plus faible sur une sphère (distance géodésique) entre les points. Cette fonctionnalité n’est pas utilisée dans le cadre du couplage automatique mais elle est proposée pour le couplage manuel.

Tout couplage de domaines administratifs ou de centres peut être brisé. Si c’est ce que vous souhaitez, cliquez sur « Recalculer les scores afin de recréer l’index de score et coupler de manière manuelle ou indiquer ce que vous souhaitez.

Contraintes parents¶

Le processus par défaut consiste à coupler des centres entre des sources basées sur des hiérarchies uniquement. Cela signifie que tout centre se trouvant dans un niveau administratif imbriqué incorrect ne sera pas couplé.

Sous l’onglet de configuration du système, la contrainte parent peut être désactivée afin de permettre le couplage de tous les centres sur toutes les sources.

Rapprochement sans niveaux¶

Il est possible de coupler des centres à partir d’une liste plate sans hiérarchie.

Notifications¶

Lorsque les administrateurs partagent un ensemble de centres à coupler avec le responsable des données, ce dernier est averti par e-mail lorsque le couplage est terminé.

Signalement¶

Le signalement permet d’exporter les centres qui exigent un examen et des recherches plus approfondis. Lorsqu’un signalement est réalisé, l’utilisateur peut également inclure un commentaire.

Les signalements peuvent porter sur n’importe quelle entité. Par exemple, une unité organisationnelle ou un centre.

Pour voir les éléments signalés et les commentaires qui leur sont associés, cliquez sur l’onglet des signalements au bas du menu de rapprochement pour le niveau d’intérêt. Dans cet exemple, une unité organisationnelle a été signalée.

_images/flagged.png

Dans cet exemple, en outre, lorsqu’un centre ou une unité administrative ont été signalés, ils peuvent être libérés pour faire l’objet d’un couplage avec une autre entité ou le couplage signalé peut être confirmé.

Guide du développeur¶

Installation de l’appli DHIS2¶

DHIS2 est un HMIS de source ouverte basé sur des normes dans le domaine de la santé dans le monde. L’outil de rapprochement des centres peut être installé sous la forme de l’appli DHIS2 et configuré de manière convenable afin de restreindre les utilisateurs aux unités de l’organisation auxquelles ils ont besoin d’avoir accès.

_images/dhis2app_installed.png

Caractéristiques¶

L’appli de rapprochement des centres DHIS2 a la capacité de :

Authentifier uniquement à l’aide des utilisateurs DHIS2 et de leurs rôles.
Ajouter des utilisateurs DHIS2 aux sources de données et aux paires de données.
Restreindre les utilisateurs DHIS2 à une ou plusieurs paires de données particulières.
Restreindre les utilisateurs à des unités particulières de l’organisation dans DHIS2 et faire en sorte que cela soit reflété dans l’accès à l’outil de rapprochement des centres.

Installer l’appli DHIS2 sur le même serveur qui prend en charge DHIS2¶

Pour que l’outil de rapprochement des centres soit utilisé sous la forme de l’appli DHIS2, l’outil indépendant doit être installé. L’outil doit être installé sur le même serveur que DHIS2.

Clonez le repositaire GitHub.

git clone git@github.com:openhie/facility-recon.git
cd facility-recon

Accédez à DHIS2 comme administrateur avec la permission d’installer des applis. Ouvrez l’appli intitulée App Management (gestion des applis)

_images/dhis2app_appmanagement.png

Choisissez d’installer une appli à l’aide du bouton tout à droite.

_images/dhis2app_createnew.png

Une fenêtre de navigation des fichiers s’ouvrira. Choisissez le fichier .zip déjà empaqueté dans le repositaire le dossier GitHub dhis2App.

_images/dhis2app_gofrzip.png

Pour installer l’appli que le terrain de jeu de démo DHIS2, vous aurez besoin d’un autre paquet, cf. modifications ci-dessous.

Pour orienter l’appli vers un autre serveur pour le backend, vous aurez besoin d’un paquet différent, cf. modifications ci-dessous.

L’appli DHIS2 est maintenant installée. Confirmez :

Après avoir installé l’appli mais avant la configuration de l’authentification DHIS, réglez le rôle de l’utilisateur dans DHIS pour qu’il ait des permissions.

Ajoutez des permissions pour l’appli au rôle d’utilisateur¶

L’authentification externe fonctionne en associant un rôle d’utilisateur DHIS2. L’outil de rapprochement des centres doit connaître le rôle de l’utilisateur. Le rôle de l’utilisateur sélectionné pour gérer l’outil doit disposer de permissions ajoutées, sinon l’utilisateur sera bloqué.

Cliquez sur l’appli utilisateurs dans le menu déroulant de l’appli.

_images/dhis2app_usersapp.png

Dans le menu de l’appli des utilisateurs, sélectionnez rôle des utilisateurs.

_images/dhis2app_usersmenu.png

Sélectionnez le nom du rôle d’utilisateur que vous utiliserez pour prendre en charge l’appli de rapprochement des centres. Vous serez envoyer vers un affichage détaillé des autorités octroyées à ce rôle d’utilisateur.

Sous Applis, cochez la case à côté de l’appli de rapprochement des centres.

_images/dhis2app_userroleperms.png

Cliquez sur Sauvegarder au bas de la page pour soumettre la modification.

_images/dhis2share_confirmuserrole.png

Paramétrage de l’authentification DHIS¶

Dans le menu déroulant des applis, à nouveau, cliquez sur l’icône de l’appli de rapprochement des centres désormais installée afin de terminer la configuration et la paramétrage de l’authentification.

Sous Paramètres de configuration, activez l’authentification externe. Sélectionnez DHIS2 comme point d’authentification.

Sélectionnez le rôle de superutilisateur dans DHIS2 qui sera utilisé pour prendre en charge le rapprochement des centres.

_images/dhis2app_role.png

Puis, saisissez un nom d’utilisateur et un mot de passe que le backend pourra utiliser pour extraire des données auprès de DHIS2.

_images/dhis2app_userexternal.png

Sélectionnez Extraire pour alimenter l’appli en données. Cela est nécessaire au bon fonctionnement de la communication à deux sens entre l’appli et le backend du rapprochement.

_images/dhis2app_pull.png

Une fois que l’appli a terminé, elle réoriente vers l’affichage des sources de données pour une confirmation de la présence de la source de données DHIS2.

_images/dhis2app_pullconfirm.png

Installez l’appli DHIS2 sur le terrain de jeu DHIS2.¶

L’outil de rapprochement des centres doit être en marche. Une manière rapide de ce faire pour une démonstration consiste à utiliser Docker.

Consultez https://play.dhis2.org et sélectionnez une version de démonstration de DHIS2.

_images/dhis2app_playversion.png

Suivez les consignes ci-dessus mais utilisez la version précréée conçue pour le terrain de jeu DHIS2.

_images/dhis2app_demozip.png

Puis suivez le reste des consignes ci-dessus.

Installer un serveur backend différent¶

Si l’appli DHIS2 doit communiquer avec un backend qui se trouve sur un autre serveur, le paquet préconçu ne convient alors pas et doit être reconstitué avec l’adresse correcte.

Le fichier /facility-recon-gui/config/prod.env.js doit être modifié.

'use strict'
module.exports = {
  NODE_ENV: '"production"',
  BACKEND_SERVER: '"./"'
}

Modifiez la variable BACKEND_SERVER avec le serveur qui convient. Par exemple, pour localhost :

'use strict'
module.exports = {
  NODE_ENV: '"production"',
  BACKEND_SERVER: '"http://localhost:3000"'
}

Une fois que le fichier a été modifié et sauvegardé, constituez le gui.

cd facility-recon-gui
npm install
# there may be build warnings.
npm run build

La nouvelle appli est installée dans la racine sous /dhis2App/GOFR.zip. Cela est désormais intégré au serveur choisi lors de l’étape ci-dessus et peut être installé dans DHIS2.

Utilisateurs et partage de DHIS2¶

Avec DHIS2 comme couche d’authentification, les utilisateurs de DHIS2 peuvent se voir accorder l’accès à des sources et paires de données particulières, être restreints à certaines paires et faire en sorte que les restrictions de leurs unités organisationnelles se retrouvent également dans l’outil de rapprochement des centres.

Préalables¶

L’application de rapprochement des centres doit être en marche.
Ensuite, l’appli doit être installée. Cf. page du guide du développeur pour l’installation de l’appli DHIS2.
Une fois que DHIS2 est une couche d’authentification, les utilisateurs doivent exister dans DHIS2 pour pouvoir utiliser l’appli de rapprochement des centres.

À propos des utilisateurs DHIS2¶

Les éléments constitutifs de la gestion des utilisateurs dans DHIS2 sont les autorités, les utilisateurs, les rôles des utilisateurs et les groupes d’utilisateurs. Cf. la dernière documentation DHIS2 en date pour un aperçu qui est en partie reproduit dans le présent.

Types	Description
Authorities	Permissions to perform tasks like adding data sets, creating data elements, or viewing reports.
Users	An individual's account.
User roles	Required for each user. Roles may be used to assign particular data sets and authorities on the system to perform tasks.
User groups	Groups of users. User groups may be cross-cutting, so for example there may be a group of users who manage an HIV prevention program. They may have different user roles but they can also be in the same program group.

Options de configuration¶

Lorsque l’appli DHIS2 de rapprochement des centres est installée et que DHIS2 est sélectionné comme source d’authentification, un rôle de superutilisateur DHIS2 doit être sélectionné. Il existe plusieurs autres options.

_images/dhis2app_configure.png

Dans les paramètres par défaut :

Les utilisateurs seront en mesure de ne voir que les unités organisationnelles qu’ils ont la permission de voir dans DHIS2.
Les unités organisationnelles peuvent être intégrées à l’outil de rapprochement des centres dans un ensemble de données du nom de votre choix.
Les unités organisationnelles peuvent être partagées entre plusieurs utilisateurs et pas uniquement associées à l’utilisateur qui a configuré le système.

Les configurations par défaut peuvent être activées ou non, comme vous le souhaitez.

Options	Default (Y/N)	Description
Pull org units	Yes	Once selected, the user who sets up DHIS2 integration may choose to pull org units into the Facility Reconciliation app. Generally, the expectation is that if DHIS2 is the authentication source, then the user would prefer to pull org units from it as a data source. But, this switch allows for that assumption to be optional.
Share orgs with other users	Yes	This option allows for the DHIS2 organizational units data to be used by others rather than just the individual who configured the system.
Limit orgs sharing by orgid	Yes	This option allows org unit restrictions in DHIS2 to be respected in the Facility Reconciliation Tool. This means that if a user is confined to one org in DHIS2 that they will also be limited in the same way in the DHIS2 app.

Démarrage rapide avec Docker¶

La manière la plus rapide de démarrer est d’utiliser Docker Compose qui fait tourner toutes les composantes : appli, Redis, MongoDB et le serveur Hearth FHIR.

Clonez le repo et lancez les applis docker.

git clone https://github.com/openhie/facility-recon.git
cd facility-recon
docker-compose up

Consultez : http://localhost:3000

L’utilisateur admin par défaut est root@gofr.org et le pass est gofr. Les autres utilisateurs admin doivent immédiatement être créés, le défaut supprimé et les utilisateurs ordinaires ajoutés également.

Installation locale¶

Installation de Hearth (Serveur FHIR)¶

Assurez que mongo 3.6 ou une version ultérieure est installé et lancé avant de suivre les consignes suivantes

git clone https://github.com/intrahealth/hearth.git
cd hearth
npm install

Ouvrez le fichier de config situé sous config/default.json et désactivez l’authentification en configurant le type d’authenfication en mode désactivé, c’est-à-dire « authentication »: { « type »: « disabled »}

Démarrez Hearth

npm run dev:start

Backend¶

Téléchargez le repo.

git clone https://github.com/openhie/facility-recon.git

cd facility-recon/facility-recon-backend
npm install

Installez et lancez Redis

wget http://download.redis.io/redis-stable.tar.gz
tar xvzf redis-stable.tar.gz
cd redis-stable
make
redis-server

Faites tourner backend

cd ~/facility-recon/facility-recon-backend
node lib/index.js

Frontend¶

cd facility-recon/facility-recon-gui
npm install
npm run build

Appli DHIS2 (facultative)¶

Veuillez noter que l’appli DHIS2 n’est pas requise pour le fonctionnement de l’outil dans la mesure où il peut fonctionner indépendemment du GUI.

Copiez les contenus constitués sur le frontend de facility-recon/facility-recon-gui/dist à facility-recon/dhis2App/ puis zippez le contenu de dhis2App

cp -r facility-recon/facility-recon-gui/dist/* facility-reco/dhis2App/
cd facility-recon/dhis2App
rm GOFR.zip
zip GOFR.zip ./*

Connectez-vous à DHIS2 et installez le fichier zippé (GOFR.zip)

Vagrant¶

Installer¶

Il s’agit d’un exemple qui utilise Vagrant pour une mémoire virtuelle Ubuntu ou CentOS pour le test du début à la fin de la reconnaissance des centres.

Pour utiliser l’outil, changez simplement le répertoire dans OS (CentOS ou Ubuntu) que vous souhaitez utiliser et démarrez-le.

cd ubuntu
vagrant up

Résoudre les problème¶

Pour le nettoyage, veuillez noter que les boîtes Vagrant sont stockées dans ~/.vagrant.d/boxes.
[macOS] En cas d’erreur due à un conflit de ports pour ssh, dégagez l’entrée de transmission du port pour 2222 dans /Library/Preferences/VMwareFusion/networking et /Library/Preferences/VMwareFusion/vmnet8/nat.conf

Considérations relatives à la production¶

Ressources système¶

Les planificateurs des systèmes doivent procéder à des tests au niveau local avec les plus grandes sources de données qui représenteraient leur cas d’utilisation. Sans intéraction avec des utilisateurs, le serveur de démo utilise ~740Mo de RAM (mongo : 200Mo, redis : 10Mo, hearth : 250Mo, backend : 250Mo).

La version de démo utilise deux unités centrales de traitement, 4Go de RAM et 20Go SSD sur un VPS hébergé sur le nuage. Pour les cas d’utilisation avec des sources de données plus larges, tels que des centres de 10k, attendez-vous à accroître l’allocation de RAM.

DNS¶

DNS peut être configuré de toutes sortes de manières pour l’hébergement. Une des méthodes consiste à créer un enregistrement DNS pour le domaine et à ajouter ensuite un enregistrement A sous le domaine racine pour le serveur de l’application.

Inversez Proxy et HTTPS¶

Pour héberger l’outil derrière un proxy inverse tel que nginx, configurez-le de manière à ce qu’il transmette les requêtes au serveur nodejs qui fait tourner l’application sur le port 3000.

Une recette complète pour l’inversement proxy et SSL se trouve à l’adresse suivante : https://www.linode.com/docs/web-servers/nginx/use-nginx-reverse-proxy/

Si vous utilisez Ubuntu avec Nginx, vous risquez de devoir désactiver Apache.

sudo update-rc.d apache2 disable

Ansible¶

Ces étapes s’appliquent à l’installation directe sur un serveur OS et exige une expérience en configuration à distance.

Pour utiliser Ansible, votre clé SSH publique doit être dans .ssh/authorized_keys sur l’hébergement à distance et vous devez également créer un /etc/ansible/hosts ou semblable avec l’adresse IP ou le nom de l’hébergement à distance. Un fichier Ansible/hébergement qui dispose d’une entrée pour l’hébergement local et un serveur doit être :

[local]
localhost ansible_connection=local

[servers]
172.16.174.137

Installation SSH¶

Un modèle de playbook est fourni pour vous montrer comment créer un utilisateur fr doté de permissions sudo à l’aide d’Ansible à utiliser avec la mémoire virtuelle. Cf. /packaging pour Terraform (Digital Ocean) et Vagrant (CentOS 7 et Ubuntu 18) pour des exemples qui fonctionnent.

Créez une mémoire virtuelle. Assurez-vous d’inclure une clé ssh publique pour l’utilisateur qui installera les prérequis.

Créez un utilisateur fr et octroyez-lui un accès sudo :

ansible-playbook -i /usr/local/etc/ansible/hosts user.yaml

En fonction des besoins, ajoutez des clés ssh pour l’utilisateur fr. (Assurez-vous que la clé publique de l’utilisateur est disponible sur github, c’est-à-dire https://github.com/citizenrich.keys) :

ansible-playbook -i /usr/local/etc/ansible/hosts keys.yaml

Installation¶

Prérequis : git, redis, mongo, nodejs, paquets de construction natives pour nœud :

# for centos
ansible-playbook -i /usr/local/etc/ansible/hosts prep_centos.yaml
# for ubuntu
ansible-playbook -i /usr/local/etc/ansible/hosts prep_ubuntu.yaml

Installez les services, chargez-les et démarrez-les dans le système :

# prepare hearth and the app
ansible-playbook -i /usr/local/etc/ansible/hosts install.yaml
# install into systemd and begin the hearth and backend services
ansible-playbook -i /usr/local/etc/ansible/hosts services.yaml

Résolution de problème¶

Vérifiez que tous les process tournent ainsi que le dernier statut en date pour hearth et backend :

ansible-playbook -i /usr/local/etc/ansible/hosts troubleshoot.yaml

Mises à niveau¶

Relancez l’installation des mises à jour de playbook intrahealth/hearth et appli repos sur le serveur à distance. Relancez les services de mise à jour de playbook services. yaml. Les services sont réinitialisés (pas simplement retéléchargés).

Le playbook install.yaml utilise :

Utilisez git pull pour obtenir les dernières mises à jour en date pour la branche master.
Installation npm pour la mise à jour des packages.

Statut de base¶

# on centos, use `mongod`
systemctl status mongod.service
# on ubuntu,use `mongodb`
systemctl status mongodb.service
systemctl status redis.service
systemctl status facility-recon.service
systemctl status hearth.service

Connexions¶

# on centos, use `mongod`
journalctl -u mongod.service -b
# on ubuntu,use `mongodb`
journalctl -u mongodb.service -b
journalctl -u facility-recon.service -b
journalctl -u hearth.service -b
journalctl -u redis.service -b

Redémarrage des services¶

sudo systemctl restart facility-recon.service
sudo systemctl restart hearth.service

Redémarrez les bases de données¶

# on centos, use `mongod`
sudo systemctl restart mongod.service
# on ubuntu,use `mongodb`
sudo systemctl restart mongodb.service
sudo systemctl restart redis.service

Mise en réseau¶

Assurez-vous que les process écoutent sur les ports qui conviennent : cf. https://serverfault.com/questions/725262/what-causes-the-connection-refused-message

# gui: 8080, backend: 3000, hearth: 3447, mongo: 27017, redis: 6379
sudo netstat -tnlp | grep :8080
sudo netstat -tnlp | grep :3000
sudo netstat -tnlp | grep :3447
sudo netstat -tnlp | grep :27017
sudo netstat -tnlp | grep :6379

Vérifiez qu’il n’y ait pas de blocage de pare-feu. Relancez le gui et :

sudo tcpdump -n icmp 

Terraform¶

Il s’agit d’un exemple d’installation de Terraform à distance sur une mémoire virtuelle fournie par Digital Ocean. Cf. répertoir /packaging/terraform pour l’exemple de configuration.

Créer un compte
Exporter une variable DIGITALOCEAN-TOKEN avec votre jeton API.
Obtenez l’empreinte de hachage que DO a générée pour votre clé SSH (dépend de DO).

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer $DO_TOKEN" "https://api.digitalocean.com/v2/account/keys"

Exportez une variable TF_VAR_fingerprint avec le hachage.
Prenez connaissance des instances et de la taille des dernières gouttelettes, il faudra que le super parseur jq pour JSON soit installé.

curl -X GET --silent "https://api.digitalocean.com/v2/images?per_page=999" -H "Authorization: Bearer $DO_TOKEN" > droplets.json
curl --silent -X GET "https://api.digitalocean.com/v2/sizes" -H "Authorization: Bearer $DO_TOKEN" | jq '.sizes[].slug' > sizes.json

Ajuster la configuration
Profitez-en !

terraform init
terraform apply
terraform state pull | jq --raw-output

Vous devriez pouvoir utiliser ssh comme racine si la clé a été configurée correctement (configuration par défaut de DO).

Nettoyer.

terraform destroy

Contribuer¶

L’outil de rapprochement est distribué sous licence Apache 2.0. La communauté se réjouit de toute contribution !

Pour les fonctionnalités de substance, veuillez envisager de vous impliquer dans la commauntauté avant tout et soyez prêts à ce que l’on vous demande de préparer une document de conception. Un document de conception peut être un bref Google Doc sur lequel la communauté peut apporter un retour d’informations.
Pour les fonctionalités de moindre taille, veuillez soumettre une question sur GitHub ou la poser à la communauté en vous enquérant d’emblée de l’approche.

Veuillez-vous joindre à la Communauté de registre des centres OpenHIE pour démarrer des conversations mensuelles et au Groupe Google de registre des centres pour recevoir des annonces et participer à des discussions.

Mettre à jour et constituer la documentation¶

Ces documents sont hébergés sur https://readthedocs.io. La documentation est constituée à l’aide de Sphinx, le soutien Markdown étant activé. Pour traduire, la documentation doit avant tout être en langue de base (anglais). Une fois la création réussie, les fichiers traduisibles (.pot) sont envoyés sur Transifex. Les fichiers pot doivent être synchronisés avec Transifex pour que les éditeurs puissent les utiliser.

Construction simple¶

Installez les prérequis (cf. ci-dessous). Puis procédez à une création.

make html

Extensions Sphinx¶

Les extensions Python sont requises pour la constitution de docs, y compris sphinx_markdown_tables pour les tables à traduire. Le fichier .readthedocs. yaml dans la racine du repo détermine la version de Python (3.7) et l’emplacement du fichier requis dans docs/requirements.txt.

Pour davantage de renseignements sur la manière dont les tableaux markdown peuvent traduire correctement, cf. : https://pypi.org/project/sphinx-markdown-tables/

Mise à jour des sources de traduction¶

Cela provient des docs rtd avec des changements mineurs pour les noms de dossiers.

Cela doit être fait si le contenu change dans la documentation de la langue de base.

Créez les fichiers .pot.

cd docs
sphinx-build -b gettext source build/gettext -l fr
sphinx-intl update -p build/gettext -l fr

If a page is created it needs to be added to .tx/config by using tx init mapping and then pushed to Transifex. For example

# try
tx config mapping --resource facility-recon.docs_build_gettext_dev_dhis2users \
--source-lang en --type PO --source-file docs/build/gettext/dev/dhis2users.pot \
--expression 'docs/source/locales/<lang>/LC_MESSAGES/dev/dhis2users.po'
# add --execute to do it if all looks well
tx config mapping --resource facility-recon.docs_build_gettext_dev_dhis2users \
--source-lang en --type PO --source-file docs/build/gettext/dev/dhis2users.pot \
--expression 'docs/source/locales/<lang>/LC_MESSAGES/dev/dhis2users.po' --execute

Envoyez les fichiers sur Transifex.

tx push -tl fr

Constituer la documentation pour de nouvelles traductions¶

tx pull -l fr

Puis ajoutez, engagez git, soumettez les changements à la branche master du repositaire. Puis reconstituez les projets anglais et français sur readthedocs.org.

Mise à jour de la documentation de base (en anglais)¶

N.B. : Python 3.x est escompté dans le Makefile.

Installation des prérequis :

pip install sphinx
pip install recommonmark
pip install sphinx_rtd_theme
pip install sphinx-intl
pip install transifex-client
pip install sphinx_markdown_tables

Clonez le référentiel, créez une branche et saisissez le répertoire des docs. (Si vous n’êtes pas l’éditeur, veuillez procéder à l’autoclonage, à l’embrachement et ensuite envoyez une demande d’extraction).

git clone https://github.com/openhie/facility-recon.git
cd facility-recon/docs

Établissez la documentation. Il n’est pas nécessaire d’engager la constitution de la documentation. Le .gitignore inclut la constitution de documentation, ainsi les documents construits ne seront pas engagés par défaut. redthedocs constitue la documentation hébergé lui-même.

Créez les docs en langue par défaut (anglais).

make html

Les documents développés iront dans le répertoire /docs/build. Ouvrez /docs/build/index.html dans un navigateur pour voir les documents.

Installation de Transifex¶

Transifex offre une interface accessible qui permet aux contributeurs de saisir et corriger les traductions. Le flux de travail est expliqué sur readthedocs.

Créez un compte sur transifex.com. Soyez ajouté à l’organisation OpenHIE pour le projet facility-recon. Obtenez un jeton dans les configurations de l’utilisateur et initialisez le client de ligne de commande transifex. Vous n’avez pas besoin de tx init directemment, dans la mesure où la version de .tx/config devrez avoir été contrôlée. Installez l’environnement variable $TFX_TOKEN pour vous-même.

Créer des fichiers de traduction intermédiaires pour de nouvelles langues¶

Dans le répertoire /docs, creéz les fichiers de paramètres locaux. Utilisez le paramètre local qui convient. Veuillez noter que Sphinx prend en charge moins de paramètres locaux que Transifex.

sphinx-intl update -p build/gettext -l es

La manière dont la localisation a été faite (à ne pas reproduire)¶

Ne répétez pas ce process. Il a pour but de documenter la manière dont il se fait en premier en lieu. Toute répétition supprimerait les traductions, les modifierait ou les effacerait.

Installez Sphinx pour le projet. Activez le soutien Markdown. Installez readthedocs.org. Activez le point d’accueil Web pour enclencher la constitution.
Créez les documents dans la langue source.
Créez des projets dans readthedocs.org pour la langue source (facility-recon - sans préfixe ni suffixe) et le nouveau fichier (facility-recon-fr)
Affectez les langues qui conviennent aux deux projets.
Affectez le projet -fr comme traduction de la source. Vous devez avoir deux projets.

La création d’une source gettest dir. est requise dans la mesure om le fichier conf.py ne se trouve pas dans le répertoire de documents.

sphinx-build -b gettext source build/gettext

Créez des fichiers .pot pour le français. Cela met un répertoire local dans /docs/source/ et crée des fichiers pour chaque fichier .md et .rst.

cd docs
sphinx-intl update -p build/gettext -l fr

Init soutien Transifex pour le repo. Faites-le à partir de la racine repo, et non pas des docs. Ajoutez une var env jeton API Transifex pou ce faire.

# must be in repo root
cd ../
tx init --token $TFX_TOKEN --no-interactive

Mappez tous les documents. Cela doit être fait dans la racine du repo.

# must be in repo root
tx config mapping-bulk --project facility-recon --file-extension '.pot' --source-file-dir docs/build/gettext \
    --source-lang en --type PO --expression 'docs/source/locales/<lang>/LC_MESSAGES/{filepath}/{filename}.po' --execute

Procédez au lancement initial des documents de langue source sur Transifex.

tx push --source

Testez en traduisant et en révisant quelques fichiers sur Transifex. Extrayez de Transifex.

tx pull -l fr

Vérifiez de manière manuelle les fichiers .po traduits pour confirmer les modifications.

Développez localement pour vérifier. (Pour information, les fichiers .mo sont placés dans le repo et ils pourraient donc potentiellement être gitignorés ou supprimés).

cd docs
sphinx-build -b html -D language=fr ./source build/html/fr

…puis ouvrez le fichier index.html dans les fichiers pour le français pour confirmer.

readthedocs.io doit être reconstitué sur la base du poitn d’accueil Web existant.

FAQ¶

Existe-t-il une API ?¶

L’outil utilise un serveur FHIR, Hearth pour un stockage persistant. Hearth utilise MongoDB comme couche de stockage.

Pour obtenir des sources de données et procéder au rapprochement, les utilisateurs ayant accès à la pile sous-jacente peuvent interroger MongoDB ou l’API REST basée sur FHIR pour Hearth. Aucune authentification n’est nécessaire pour l’accès brut de cette manière.

Cet outil peut-il être utilisé dans les secteurs éducatif et agricole ?¶

Oui ! Cet outil a été créé pour le secteur de la santé et utilise la norme FHIR basée sur le profil mCSD IHE.

Toute liste d’emplacements hiérarchiques peut être potentiellement prise en charge. La représentation dorsale peut être exportée en format CSV et d’autres peuvent être ajoutées en fonction des cas d’utilisation.

L’outil nettoye-t-il les données sources ?¶

Non. Cet outil prend une paire de sources et utilise des méthodes automatiques et manuelles afin d’identifier des correspondances. Si des corrections sont nécessaires, l’outil peut exporter un CSV ou une représentation FHIR de ce qui est couplé et ce qui ne l’est pas. Ces sources de données doivent être nettoyées à l’extérieur de l’outil.

Si cette caractéristique s’applique à votre cas d’utilisation, veuillez nous contacter.

Puis-je utiliser l’outil sur mon propre ordinateur personnel ?¶

Cet outil compte quatre composantes : l’application à proprement parler, Redis, une base de données mémoire pour la performance, le serveur FHIR Hearth et MongoDB qui est utilisé aussi bien par Hearth pour le stockage des ressources que par l’application pour la gestion

Cet outil est conçu de manière à être hébergé sur un serveur local ou sur le nuage. Cet outil prend en charge la gestion des utilisateurs et est censé être mis à la disposition de nombreux utilisateurs pour leur permettre de collaborer sur le rapprochement des listes des centres. L’installation serveur est recommandée pour le déploiement de l’outil.

Docker n’est pas recommandé par défaut dans la mesure où il ne permettra pas aux données de persister, ce qui veut dire que lorsque vous arrêtez Docker, vous perdez vos données. Cela peut être modifié par la création d’un volume pour stocker les données. Mais l’outil est censé être utilisé comme plateforme permettant à de multiples utilisateurs de collaborer sur le couplage. Il peut être déployé sur un serveur à l’aide de Docker mais l’administrateur doit prendre garde de créer un volume pour assurer la persistance des données.

Les développeurs peuvent installer les piles directement mais cela ne s’applique pas à la production.

Feuille de route¶

Les caractéristiques proposées sont prises en charge par un Google Doc publiquement visionnable et pris en charge par GitHub.

Version : 0.1.0¶

Calendrier : février 2018 à juillet 2018, statut : terminé

Caractéristiques :¶

Couplage réalisé sur la base d’une source de données téléchargée.
L’autre source de données est une instance DHIS2 (GeoAlign).
Authentification préliminaire DHIS2.
Exportations préliminaires de centres couplés et non couplés.

Version : 0.2.0¶

Calendrier : août 2018 à octobre 2018, statut : terminé

Caractéristiques :¶

Confirgurable par l’utilisateur à toute paire de données.
Toute instance DHIS2 à laquelle l’utilisateur a accès.

N.B. : la version 0.2.0 a été testée en production de manière approfondie dans près de 80 000 centres.

Version : 0.3.0¶

Calendrier : novembre 2018 à décembre 2018, statut : terminé

Caractéristiques :¶

Remaniement de l’interface utilisateur.

Version : 0.4.0¶

Calendrier : janvier 2019 à février 2019, statut : terminé

Caractéristiques :¶

Containerisation.
Hébergement des scripts et des logiciels utilitaires.

N.B. : la version 0.3.0 a été testée lors d’ateliers de conception axés sur les utilisateurs avec une instance hébergée sur le nuage.

Version : 0.5.0¶

Calendrier : mars 2019 à avril 2019, statut : terminé

Caractéristiques :¶

Documentation sur facility-recon.readthedocs.org.
Exportation améliorée pour montrer tous les éléments appariés et non appariés.
Couplage activé sur les identifiants des centres et leurs coordonnées géographiques.

Version : 0.6.0¶

Calendrier : mai 2019 à juin 2019, statut : terminé

Caractéristiques :¶

Options d’authentification externe (DHIS2, iHRIS)
Partage des sources de données DHIS2.
Partage des paires DHIS2.
Appli DHIS2 facile à installer.
Couplage configurable, basé sur une contrainte parent pouvant être désactivée

Version : 0.7.0¶

Calendrier : à déterminer, statut : en cours

Caractéristiques :¶

Préparation du lancement de 1.0.
Test approfondi de bout en bout.
Bugs réglés.
Version de FHIR mise à jour.
Passage à HAPI FHIR envisagé.

À propros de¶

L’outil a été conçu par la communauté de développement internationale pour le premier cas d’utilisation de prise en charge d’une plateforme de suivi et d’évaluation pour de multiples pays. Cet outil est le premier créé dans le cadre .NET.

Cette version de l’outil a été créée dans un cadre ouvert de manière à créer une communauté plus large autour d’elle et d’assurer des contributions sur le long terme de la part de la communauté ainsi que l’ajout de nouvelles fonctionnalités.

Les cas d’utilisation initiaux sont centrés sur le secteur de la santé. L’outil est conçu à l’aide de la norme FHIR émergente basée sur le profile mCSD IHE. Le backend est un serveur FHIR, ce qui signifie qu’une API conforme à la norme FHIR est disponible sur le serveur pour la prise en charge des opérations. Toutes les sources de données sont converties en ressources d’emplacement FHIR. Cela signifie que les requêtes ordinaires FHIR REST API peuvent être interrogées sur le serveur backend.

À l’avenir, il se peut que l’outil soit en mesure de prendre en charge toutes les données hiérarchiques ou plates, aussi bien dans le secteur médical que dans d’autres secteurs. Le couplage d’algorithmes, de nouvelles sources données et de formats d’exportation peut être créé de manière à satisfaire une variété de cas d’utilisation en fonction des besoins de la communauté.

Documentation de l’outil de rapprochement des centres¶

Démarrages rapides.¶

Données d’exemple¶

Téléchargez les données d’exemple¶

Téléchargez les données.¶

Mise en correspondance des données¶

Couplage des données¶

Rapprochement¶

Exporter le rapport de rapprochement¶

Consultez le statut du rapprochement¶

Ajouter une source DHIS2¶

Configurer une source de données DHIS2¶

Synchro¶

Guide de l’utilisateur¶

Sources de données¶

Télécharger un fichier CSV¶

Sélectionner les niveaux¶

Serveurs à distance – DHIS2 ou FHIR¶

Couplage¶

Couplage de sources¶

Couplage automatique¶

Recalculer les scores¶

Couplage manuel¶

Contraintes parents¶

Rapprochement sans niveaux¶

Notifications¶

Signalement¶

Utilisateurs et partage¶

Rôles¶

Auto-inscription¶

Partager une source de données¶

Ajouter à une paire¶

Modifier le mot de passe¶

Guide du développeur¶

Installation de l’appli DHIS2¶

Caractéristiques¶

Installer l’appli DHIS2 sur le même serveur qui prend en charge DHIS2¶

Ajoutez des permissions pour l’appli au rôle d’utilisateur¶

Paramétrage de l’authentification DHIS¶

Installez l’appli DHIS2 sur le terrain de jeu DHIS2.¶

Installer un serveur backend différent¶

Utilisateurs et partage de DHIS2¶

Préalables¶

À propos des utilisateurs DHIS2¶

Options de configuration¶

Partager des sources de données¶

Partager des paires de données¶

Démarrage rapide avec Docker¶

Installation locale¶

Installation de Hearth (Serveur FHIR)¶

Backend¶

Frontend¶

Appli DHIS2 (facultative)¶

Vagrant¶

Installer¶

Résoudre les problème¶

Considérations relatives à la production¶

Ressources système¶

DNS¶

Inversez Proxy et HTTPS¶

Ansible¶

Installation SSH¶

Installation¶

Résolution de problème¶

Mises à niveau¶

Statut de base¶

Connexions¶

Redémarrage des services¶

Redémarrez les bases de données¶

Mise en réseau¶

Terraform¶

Contribuer¶

Mettre à jour et constituer la documentation¶

Construction simple¶

Extensions Sphinx¶

Mise à jour des sources de traduction¶

Constituer la documentation pour de nouvelles traductions¶

Mise à jour de la documentation de base (en anglais)¶

Installation de Transifex¶

Créer des fichiers de traduction intermédiaires pour de nouvelles langues¶