DHIS2 Version 41 Notes de mise à jour¶

Bienvenue aux notes de mise à jour pour DHIS2 version 41.

Il est important de se familiariser avec le contenu de ces notes avant de tenter une mise à niveau.

:Avertissement : Assurez-vous d'avoir également lu les notes de mise à jour de la VERSION PRÉCÉDENTE si vous effectuez une mise à jour à partir d'une version antérieure

Pour vous aider à parcourir le document, voici une table des matières détaillée.

Table des matières¶

• Prérequis
• Modifications apportées à l'API
  • Partage
  • Analyse
  • Tableaux non journalisés
  • Tableaux de ressources (ils peuvent faire cesser de fonctionner certains scripts existants)
  • Amélioration du script de mise à jour des attributs d'entités suivies
    • [Vérification des attributs qui seront affectés :] (#verifying-which-attributes-will-be-affected)
  • Tracker
  • Changements majeurs
  • ACL tracker export breaking changes
  • API obsolètes
    • Pagination
    • Point-virgule comme séparateur pour les identifiants (UID)
    • Appellation
    • Endpoints obsolètes
    • Clés obsolètes dans les réponses d'API
    • Suivi de la correction orthographique
  • Métadonnées
• Base de données
  • Tracker
  • Changements majeurs : tableaux et colonnes renommées
  • Tableaux renommés
  • Colonnes renommées
  • Référence Postgres
• Dépréciations et suppressions

Prérequis¶

Important

La version 41 de DHIS2 nécessite désormais l'environnement d'exécution Java 17.

Modifications apportées à l'API¶

Partage¶

• Les anciennes propriétés de partage sont supprimées : à partir de la version 2.36, une nouvelle propriété sharing a été introduite afin de remplacer les anciennes propriétés de partage userAccesses, userGroupAccesses, publicAccess, externalAccess. Afin de conserver la rétrocompatibilité de l'api web, nous avons pris en charge à la fois les nouvelles et les anciennes propriétés de notre api web et toutes les fonctionnalités associées. Cependant, afin d'apporter de nouvelles fonctionnalités et garder la base de code propre, nous devons supprimer l'ancien format dans la version 2.41. Ainsi, à partir de cette version, les propriétés suivantes ne seront plus renvoyées par notre api web :

userAccesses, userGroupAccesses, publicAccess, externalAccess

Elles seront tout de même accessibles dans les nouvelles propriétés sharing tel que documenté [ici] (https://docs.dhis2.org/en/develop/using-the-api/dhis-core-version-237/sharing.html#new-sharing-object).

• Changement majeur dans l'application Tableau de bord : dans la version 2.40 et les versions antérieures, les utilisateurs peuvent voir le contenu du tableau de bord même sans l'autorisation METADATA_READ (lecture des métadonnées) pour tous les objets de métadonnées liés aux éléments du tableau de bord. Cela est dû à une faille dans notre API web qui permet à tout utilisateur de voir les détails de tous les objets de métadonnées s'il connait l'uid. Cette faille a causé des problèmes pendant longtemps et a donc été supprimée dans la version 2.41. En conséquence, de nombreux utilisateurs ne pourrons pas visualiser les tableaux de bord parce qu'ils n'ont pas l'autorisation METADATA_READ requise pour accéder au contenu du tableau de bord. Pour résoudre ce problème, l'administrateur du système ou le propriétaire du tableau de bord peut utiliser la fonctionnalité [Partage en cascade pour le tableau de bord] (https://docs.dhis2.org/en/develop/using-the-api/dhis-core-version-237/sharing.html#cascade-sharing-for-dashboard) pour accorder les autorisations requises aux utilisateurs qui en besoin.

Analyse¶

Tableaux non journalisés¶

Les tableaux analytiques non journalisées sont maintenant activées (on) par défaut. Si cette option est activée, le processus d'exportation des tableaux analytiques pourrait être nettement amélioré. Mais cela a un coût : les tableaux "non journalisés" ne peuvent pas être répliqués. Cela signifie que le regroupement ne sera pas possible. De plus, les tableaux analytiques seront automatiquement tronqués si PostgreSQL est soudainement réinitialisé (réinitialisation brusque/crash). Si vous ne pouvez pas supporter les coûts mentionnés ci-dessus, vous devriez désactiver cette option (la mettre sur off). Cela se fait dans le fichier dhis.conf, c'est à dire : analytics.table.unlogged = off.

Tableaux de ressources (ils peuvent faire cesser de fonctionner certains scripts existants)¶

Auparavant, les tableaux de ressources analytiques étaient préfixés par un trait de soulignement (_). Mais dans cette version, cela a changé. Désormais, les tableaux de ressources seront préfixées par "analytics_rs_"... :

_categorystructure -> analytics_rs_categorystructure

Dans l'exemple ci-dessus, avant cette version, le tableau de ressources correspondant était nommée _categorystructure. À partir de cette version, elle sera nommée analytics_rs_categorystructure.

À cause de ce changement, certains scripts personnalisés qui dépendent de ces tableaux pourraient cesser de fonctionner. Il faut donc en tenir compte.

Amélioration du script de mise à jour des attributs d'entités suivies{ #tracked-entity-attribute-update-script-enhancement }¶

Dans cette version, un script Flyway a été introduit pour améliorer le système DHIS. Ce script est conçu pour mettre à jour le type de valeur de tous les attributs d'entités suivies (TEA) dont les valeurs sont incompatibles avec le type d'attribut déclaré.

Plus précisément, le script mettra à jour le type de ces attributs en "TEXT". Par exemple, si un TEA est déclaré comme NUMBER (numéro), mais que sa valeur est une chaîne de texte, le script modifiera le type de l'attribut en TEXT.

Cette amélioration garantit l'intégrité des données et l'alignement entre les types d'attributs et leurs valeurs réelles, ce qui est particulièrement nécessaire lors des analyses.

Vérification des attributs qui seront affectés :¶

La requête suivante peut être exécutée avant la mise à niveau pour vérifier quels TEA seront affectés.

La requête affichera également l'instruction de mise à jour

CREATE or replace FUNCTION can_be_casted(s text, type text) RETURNS bool AS
$$
BEGIN
    execute 'SELECT $1::' || type || ';' USING s;
    return true;
EXCEPTION
    WHEN OTHERS THEN
        RETURN false;
END;
$$ LANGUAGE plpgsql STRICT;

select uid,
    valuetype,
    description,
    'update trackedentityattribute set valuetype=''TEXT'' where uid = ''' || uid || ''';' as suggested_fix_statement
from (select tea.uid,
    tea.valuetype,
    tea.description,
    teav.value,
    case
        when tea.valuetype in ('NUMBER', 'UNIT_INTERVAL', 'PERCENTAGE') then can_be_casted(teav.value, 'double precision')
        when tea.valuetype like '%INTEGER%' then can_be_casted(teav.value, 'integer')
        when tea.valuetype in ('DATE', 'DATETIME', 'AGE') then can_be_casted(teav.value, 'timestamp')
    end as safe_to_cast
    from trackedentityattribute tea
    join trackedentityattributevalue teav on tea.trackedentityattributeid = teav.trackedentityattributeid) as t1
where safe_to_cast = false
group by uid, valuetype, description;

DROP function if exists can_be_casted(s text, type text);

Remarque Il n'est pas nécessaire d'exécuter soi-même la mise à jour puisque le système le fera automatiquement au prochain démarrage.

Remarque Vous pouvez également utiliser cette migration pour identifier les TEA que vous devez corriger si vous ne voulez pas que le type soit automatiquement modifié.

Important Au premier démarrage de la nouvelle version, le script sera automatiquement exécuté (le premier démarrage après la mise à niveau peut être légèrement plus lent en raison de l'exécution de ce script).

Tracker¶

Changements majeurs¶

Les paramètres de requête suivants ont été supprimés car on peut obtenir le même résultat en utilisant le paramètre filter.

• /tracker/trackedEntities?query
• /tracker/trackedEntities?attribute

Les paramètres de requête suivants ont été supprimés car ils induisaient en erreur et ne fournissaient pas d'informations utiles

• /tracker/trackedEntities?includeAllAttributes

Les paramètres de requête suivants ont été supprimés car ils n'ont jamais été implémentés et n'ont donc aucune incidence sur la réponse.

• /tracker/trackedEntities?attachment
• /tracker/events?attachment

Les paramètres suivants ont été supprimés car l'inclusion ou l'exclusion de champs dans la réponse JSON peut être réalisée en utilisant le paramètre de requête fields.

• /tracker/trackedEntities?skipMeta
• /tracker/events?skipMeta
• /tracker/events?skipEventId

Le champ index d'une entité dans le rapport d'une importation tracker a été supprimé.

Lors de l'importation d'entités de tracker à l'aide du endpoint POST /tracker, la réponse suit le format décrit [ici] (https://docs.dhis2.org/en/develop/using-the-api/dhis-core-version-master/tracker.html#import-summary-structure).

Le champ index a été supprimé du rapport objectsReport car les objets sont désormais ordonnés de la même manière que dans la requête.

Le champ orgUnitName a été supprimé des endpoints GET /tracker/enrollments et GET /tracker/events ; il n'est donc plus possible d'ordonner les objets sur ce champ.

Le champ trackedEntityType a été supprimé du endpoint GET /tracker/enrollments.

Le champ followup a été renommé followUp dans la réponse du endpoint CSV GET /tracker/events.

ACL tracker export breaking changes¶

Sauf indication contraire, les changements majeurs ultérieurs s'appliquent exclusivement aux versions 2.41 et suivantes.

1. Validité des requêtes /events et /tracker/events.

   • TECH-1630 : Une requête à /events et /tracker/events est désormais valide si l'unité d'organisation fournie est dans le champ de recherche de l'utilisateur, quel que soit le niveau d'accès au programme. Ceci correspond au comportement actuel des endpoints /tracker/trackedEntities et /tracker/enrollments. Dans les versions précédentes, le fait de spécifier un programme protégé ou fermé ou d'omettre le programme dans la requête, associé à une unité d'organisation hors du champ de saisie de l'utilisateur, entraînait une exception. Ce changement est effectif à partir de la version 2.38.
   • TECH-1663 : De plus, dans /events et /tracker/events, une requête utilisant le mode ACCESSIBLE sans spécification du programme renverra désormais tous les événements qui se trouvent dans le champ de recherche de l'utilisateur (dans les programmes OPEN ou AUDITED) et tous ceux qui se trouvent dans son champ de saisie (dans les programmes PROTECTED ou CLOSED). Auparavant, n'étaient renvoyés que les événements du champ de saisie de l'utilisateur. Ce changement est également effectif à partir de la version 2.38.

2. Requêtes d'API avec les modes d'unité d'organisation

   • TECH-1585 : Une requête d'API utilisant l'un des modes d'unité d'organisation (ALL, ACCESSIBLE, ou CAPTURE) obtiendra désormais une réponse 400|Bad Request (mauvaise requête) si une unité d'organisation supplémentaire est spécifiée dans la requête. Dans les versions précédentes, une telle requête tolérait la présence d'une unité d'organisation, même si elle n'était pas utilisée lors de la récupération des résultats de la base de données. La requête renvoyait tout de même une exception si l'unité d'organisation fournie ne faisait pas partie du champ d'application de l'utilisateur.

3. Modes d'unité d'organisation par défaut

   • TECH-1588 : Lorsque ni l'unité d'organisation ni le mode de l'unité d'organisation ne sont spécifiés dans la requête, le mode par défaut sera ACCESSIBLE. Les anciennes versions de /trackedEntities et /enrollments renvoyaient une exception si aucun des deux n'était spécifié. Le mode SELECTED reste le mode par défaut lorsqu'une unité d'organisation est spécifiée.

4. Autorisation pour le mode ALL (tous) de l'unité d'organisation

   • TECH-1589 : Dans /enrollments et /tracker/enrollments, le mode d'unité d'organisation ALL est désormais restreint aux utilisateurs qui ont l'autorité ALL ou F_TRACKED_ENTITY_INSTANCE_SEARCH_IN_ALL_ORGUNITS, ce qui est cohérent avec les deux autres endpoints. Auparavant, n'importe quel utilisateur pouvait utiliser le mode ALL, même si les résultats renvoyés ne correspondaient pas au champ d'application de l'utilisateur. Ce changement est effectif à partir de la version 2.38.

   • TECH-1634 TECH-1668 : Dans les trois endpoints, les superutilisateurs et les utilisateurs qui ont l'autorisation "Recherche d'instances d'entités suivies dans toutes les unités d'organisation" recevront des données sur l'ensemble du système, quelle que soit leur champ d'application. Les utilisateurs non autorisés recevront désormais 400|Bad Request. Jusqu'à présent, même les superutilisateurs ne recevaient que les données qui se trouvent dans leur champ d'application.

5. Réponses du endpoint l'Exportateur du Tracker

   • TECH-1630 : Une requête à /events et /tracker/events avec le mode d'unité d'organisation CHILDREN produira désormais une réponse qui contient les éléments de l'unité d'organisation objet de la requête et de ses subordonnées directes. Cet ajustement aligne le comportement avec celui des endpoints /tracker/trackedEntities et /tracker/enrollments. Auparavant, la réponse n'incluait pas les événements de l'unité d'organisation fournie, seuls ses subordonnées y figuraient. Ce changement est effectif à partir de la version 2.38.

   • TECH-1656 : Une requête à /tracker/trackedEntities aboutira désormais à 403|Forbidden si l'utilisateur n'a pas accès au programme demandé ou au type d'entité suivi. Avant, ce scénario déclenchait 409|Conflict.

   • TECH-1658 Les endpoints /tracker/trackedEntities et /tracker/enrollments renvoient désormais 400|Bad Request lorsqu'il y'a des paramètres incohérents qui impliquent le champ des programmes ou tout combinaison y afférant. Auparavant, ce scénario renvoyait 409|Conflict.

   • TECH-1589 : En accédant au endpoint /tracker/enrollments, un statut 403|Forbidden sera déclenché si l'utilisateur n'a pas d'autorisation pour le programme spécifié et le type d'entité suivie, ou pour le type d'entité suivi ou le type d'entité suivi du programme. Auparavant, le statut déclenché était 409|Conflict.

API obsolètes¶

Pagination¶

Dans les endpoints du Tracker

• /tracker/trackedEntities
• /tracker/enrollments
• /tracker/events
• /tracker/relationships
• /programNotificationInstances
• /programNotificationTemplates/filter
• /potentialDuplicates

les champs relatifs à la pagination

{
  "page": 3,
  "pageSize": 2,
  "total": 373570,
  "pageCount": 186785,
  "instances": [
  ]
}

ont été dépréciés (obsolètes) en faveur d'un objet pager. Les champs de pagination plats montrés ci-dessus et le pager imbriqué sont renvoyés à partir de la version 2.41 si la pagination est activée. Les champs plats seront supprimés dans une prochaine version.

{
  "pager": {
    "page": 3,    
    "pageSize": 2,
    "total": 373570,
    "pageCount": 186785,
  },
  "page": 3,
  "pageSize": 2,
  "total": 373570,
  "pageCount": 186785,
}

Les données précédemment renvoyées dans instances sont renvoyées dans une clé nommée suivant le pluriel de l'entité renvoyée elle-même. Par exemple, /tracker/trackedEntities renvoie les entités suivies dans la clé trackedEntities tandis que /potentialDuplicates renvoie les doublons potentiels dans la clé potentialDuplicates.

Le paramètre de requête paging remplace skipPaging. Vous devez savoir que paging est l'inverse de skipPaging. Cela signifie que si vous voulez désactiver la pagination, utilisez paging=false au lieu de skipPaging=true. La pagination reste activée par défaut.

Ceci permet d'aligner la pagination dans Tracker sur les autres endpoints de DHIS2.

Point-virgule comme séparateur pour les identifiants (UID)¶

Les champs ou les paramètres de requête qui acceptent plusieurs valeurs, cas des UID, sont désormais séparés par une virgule , au lieu d'un point-virgule ;. Cela permet de s'assurer que les UID soient systématiquement séparés par une virgule dans tous les endpoints de DHIS2.

Les champs suivants sont concernés * event.attributeCategoryOptions (ainsi qu'un événement renvoyé dans le cadre d'une relation `from/to)

Les paramètres de requête suivants qui acceptent un ou plusieurs UID séparés par des points-virgules sont dépréciés en faveur d'un paramètre qui accepte des UID séparés par des virgules. Les noms sont désormais utilisés au pluriel pour indiquer que plus d'un UID est autorisé.

Veuillez vous référer aux nouveaux paramètres lorsque vous travaillez avec l'API DHIS2 sur ces endpoints spécifiques.

Appellation¶

Les noms dans le Tracker ont changé au fil du temps. Afin de fournir une API cohérente, nous avons déprécié les paramètres de requête et les chemins suivants pour laisser place à de nouveaux paramètres qui utilisent de manière cohérente trackedEntity, enrollment et event.

Le tableau ci-dessous résume les changements de terminologie de l'API entre les anciens et les nouveaux noms de tracker :

Endpoints obsolètes¶

Clés obsolètes dans les réponses d'API{ #deprecated-keys-in-api-response-bodies }¶

Les utilisateurs sont invités à se familiariser avec la nouvelle terminologie afin de garantir la cohérence dans l'utilisation de l'API à l'avenir.

Suivi de la correction orthographique¶

Le champ followup est déprécié et la version camel case followUp est utilisée à la place dans les réponses d'API suivantes : * /tracker/events * /tracker/relations dans l'objet event.

Métadonnées¶

1. La propriété DataDimensionType est maintenant obligatoire pour CategoryOptionGroup et CategoryOptionGroupSet. Les enregistrements existants avec valeur null doivent être mis à jour manuellement avec DISAGGREGATION ou ATTRIBUTE.
2. Le paramètre mergeMode a été supprimé de l'application In Metadata Import Export et aussi du endpoint api/metadata. Cela signifie que lors de la mise à jour des objets, toutes les valeurs des propriétés existantes seront écrasées même si les nouvelles valeurs sont null. Utilisez JSON Patch API si vous voulez faire une mise à jour partielle d'un objet.

Base de données¶

Nous avons supprimé le préfixe dataelement des tableaux category et categoryoption afin d'améliorer la lisibilité.

Tracker¶

[Changements majeurs : tableaux et colonnes renommées]{ #breaking-changes-renamed-tables-and-columns }¶

Nous avons renommé certains tableaux et colonnes en suivant la nouvelle appellation du Tracker dans l'API.

Compte tenu des nouvelles conventions d'appellation des bases de données, si vous exécutez des scripts SQL personnalisés ou si vous avez créé des vues SQL, vous devrez peut-être vous adapter aux changements majeurs décrits dans la présente section.

Par conséquent, nous alignons les noms des bases de données avec les changements appliqués à trackedEntityInstance, programInstance, et programStageInstance.

De plus, nous avons également aligné trackedentitycomment et ses tableaux de base de données associés sur l'appellation de note de l'API.

Tableaux renommés¶

Colonnes renommées¶

Les colonnes suivantes relatives à programstageinstance ont été renommées

Les colonnes suivantes relatives à programminstance ont été renommées

Les colonnes suivantes relatives à trackedentityinstance ont été renommées

Les colonnes suivantes relatives à trackedentitycomment ont été renommées

Les colonnes de date suivantes pour enrollment ont été renommées

Les colonnes de date suivantes pour event ont été renommées

Référence Postgres¶

From Postgres docs for alter table

Les formulaires RENAME modifient le nom d'un tableau (ou d'un index, d'une séquence, d'une vue, d'une vue matérialisée ou d'un tableau étranger), le nom d'une colonne individuelle dans un tableau, ou le nom d'une contrainte du tableau. Lorsque l'on renomme une contrainte qui a un index sous-jacent, l'index est également renommé. Les données stockées ne sont pas affectées.

Renommer un tableau ou une colonne d'un tableau n'affecte pas les données. Par exemple, la reconstruction d'un index de clé primaire, qui peut s'avérer coûteuse pour les grands tableaux, ne doit pas se produire. Par conséquent, aucun temps d'arrêt n'est prévu après les migrations.

You can check that the index creation hasn't changed after the migration via the transaction commit.

select pg_xact_commit_timestamp(xmin)
from pg_class
where relname = 'programstageinstance_pkey';

Dépréciations et suppressions¶

Suppression des clés API de Google et Bing¶

Les clés API de Google et Bing Map ont été retirées du code. Pour configurer et utiliser une clé API de Bing Maps, consultez [ce guide] (https://docs.dhis2.org/en/topics/tutorials/google-earth-engine-sign-up.html#accessing-bing-maps-basemaps).