Paramètres et configuration¶

Paramètres du système¶

Vous pouvez manipuler les paramètres du système en interagissant avec la ressource systemSettings. Un paramètre système est une simple paire clé-valeur, où la clé et la valeur sont des chaînes de texte en clair. Pour enregistrer ou mettre à jour un paramètre système, vous pouvez envoyer une requête POST à l'URL suivante :

/api/33/systemSettings/my-key?value=my-val

Vous pouvez également soumettre la valeur du paramètre dans le corps de la requête, où le type de contenu est défini sur "texte/clair". Par exemple, vous pouvez utiliser curl comme suit :

curl "play.dhis2.org/demo/api/33/systemSettings/my-key" -d "My long value"
  -H "Content-Type: text/plain" -u admin:district

Pour définir les paramètres du système en bloc, vous pouvez envoyer un objet JSON avec une propriété et une valeur pour chaque paire clé-valeur de paramètre du système à l'aide d'une requête POST :

{
  "notification de l'application clé" : "Bienvenue",
  "intro de l'application clé": "DHIS2",
  "pied de page de l'application clé" : "En savoir plus sur dhis2.org"
}

Les traductions pour les clés de paramétrage traduisibles peuvent être définies en spécifiant le paramètre local comme paramètre de requête et la valeur traduite qui peut être spécifiée soit comme paramètre de requête, soit dans la charge utile du corps. Voir un exemple d'URL :

/api/33/systemSettings/<my-key>?locale=<my-locale>&value=<my-translated-value>

Vous devez remplacer my-key par votre clé réelle et my-val par votre valeur réelle. Pour récupérer la valeur d'une clé donnée (en JSON ou en texte brut) vous pouvez envoyer une requête GET à l'URL suivante :

/api/33/systemSettings/my-key

Alternativement, vous pouvez spécifier la clé en tant que paramètre de requête :

/api/33/systemSettings?key=my-key

Si une clé n'est pas retrouvée ou marquée comme confidentielle, une réponse 404 sera renvoyée comme suit :

{
    "httpStatus": "Not Found",
    "httpStatusCode": 404,
    "status": "ERROR",
    "message": "Setting does not exist or is marked as confidential",
    "errorCode": "E1005"
}

Vous pouvez récupérer des paramètres système spécifiques sous forme de JSON en répétant la clé paramètre de la requête :

curl "play.dhis2.org/demo/api/33/systemSettings?key=keyApplicationNotification&key=keyApplicationIntro"
  -u admin:district

Vous pouvez récupérer tous les paramètres du système à l'aide d'une requête GET :

/api/33/systemSettings

Pour récupérer une traduction spécifique pour une clé traduisible donnée, vous pouvez spécifier un paramètre local comme paramètre de requête :

/api/33/systemSettings/<my-key>?locale=<my-locale>

Si elle est présente, la traduction pour le paramètre local donné est renvoyée. Sinon, une valeur est renvoyée. Si aucun paramètre local n'est spécifié pour la clé traduisible, le paramètre local par défaut de l'interface utilisateur est utilisé pour obtenir la traduction correcte. Si la traduction donnée n'est pas présente, la valeur par défaut est renvoyée.

La priorité pour les clés traduisibles est la suivante :

locale spécifiée > UI local par défaut de l'utilisateur > valeur par défaut

Pour supprimer un paramètre du système, vous pouvez envoyer une requête DELETE à l'URL similaire à celle utilisée ci-dessus pour la récupération. Si une clé traduisible est utilisée, toutes les traductions présentes seront également supprimées.

Pour supprimer uniquement une traduction spécifique d'une clé traduisible, il convient d'utiliser la même URL que pour l'ajout d'une traduction et la valeur vide doit être fournie :

/api/33/systemSettings/<my-key>?locale=<my-locale>&value=

Les paramètres système disponibles sont énumérés ci-dessous.

Tableau : Paramètres du système

Paramètres de l'utilisateur¶

Vous pouvez manipuler les paramètres de l'utilisateur en interagissant avec la ressource userSettings. Un paramètre utilisateur est une simple paire clé-valeur, où la clé et la valeur sont des chaînes de texte en clair. Le paramètre utilisateur sera lié à l'utilisateur authentifié pour la requête de l'API Web. Pour obtenir une liste de tous les paramètres utilisateur, vous pouvez envoyer une requête GET à l'URL suivante :

/api/33/userSettings

Les paramètres non définis par l'utilisateur seront remplacés par les paramètres équivalents du système. Pour ne renvoyer que les valeurs définies explicitement par l'utilisateur, vous pouvez ajouter ?useFallback=false à l'URL ci-dessus, comme ceci :

/api/33/userSettings?useFallback=false

Pour enregistrer ou mettre à jour un paramètre pour l'utilisateur actuellement authentifié, vous pouvez envoyer une requête POST à l'URL suivante :

/api/33/userSettings/my-key?value=my-val

Vous pouvez spécifier explicitement l'utilisateur pour lequel le paramètre doit être sauvegardé en utilisant cette syntaxe :

/api/33/userSettings/my-key?user=username&value=my-val

Vous pouvez également soumettre la valeur du paramètre dans le corps de la requête, où le type de contenu est défini sur "texte/clair". Par exemple, vous pouvez utiliser curl comme suit :

curl "https://play.dhis2.org/demo/api/33/userSettings/my-key" -d "My long value"
  -H "Content-Type: text/plain" -u admin:district

Par exemple, pour définir les paramètres linguistiques de l'interface utilisateur de l'utilisateur actuel en français, vous pouvez utiliser la commande suivante.

curl "https://play.dhis2.org/demo/api/33/userSettings/keyUiLocale?value=fr"
  -X POST -u admin:district

Vous devez remplacer my-key par votre véritable clé et my-val par votre valeur réelle. Pour récupérer la valeur d'une clé donnée en texte brut, vous pouvez envoyer une requête GET à l'URL suivante :

/api/33/userSettings/my-key

Pour supprimer un paramètre utilisateur, vous pouvez envoyer une requête DELETE à l'URL similaire à celle utilisée ci-dessus pour la récupération.

Les paramètres système disponibles sont énumérés ci-dessous.

Tableau : Paramètres de l'utilisateur

Configuration¶

Pour accéder à la configuration, vous pouvez interagir avec la ressource configuration. Vous pouvez obtenir des réponses XML et JSON via l'en-tête Accepter ou en utilisant les extensions .json ou .xml. Vous pouvez OBTENIR toutes les propriétés de la configuration depuis :

/api/33/configuration

Vous pouvez envoyer des requêtes GET et POST aux ressources spécifiques suivantes :

GET /api/33/configuration/systemId

GET POST DELETE /api/configuration/feedbackRecipients

GET POST DELETE /api/configuration/offlineOrganisationUnitLevel

GET POST /api/configuration/infrastructuralDataElements

GET POST /api/configuration/infrastructuralIndicators

GET POST /api/configuration/infrastructuralPeriodType

GET POST DELETE /api/configuration/selfRegistrationRole

GET POST DELETE /api/configuration/selfRegistrationOrgUnit

GET POST /api/facilityOrgUnitGroupSet

GET POST /api/facilityOrgUnitLevel

Pour la configuration de la liste d'autorisations CORS, vous pouvez effectuer une requête POST avec un tableau d'URLs vers la liste d'autorisations comme charge utile en utilisant "application/json" comme type de contenu, par exemple :

["www.google.com", "www.dhis2.org", "www.who.int"]

GET POST /api/33/configuration/corsAllowlist

Pour les requêtes POST, la valeur de configuration doit être envoyée sous forme de texte dans la charge utile de la requête. Le tableau suivant indique les valeurs de configuration appropriées pour chaque propriété.

Tableau : Valeurs de configuration

Par exemple, pour définir le groupe d'utilisateurs des destinataires du retour d'information, vous pouvez invoquer la commande curl suivante :

curl "localhost/api/33/configuration/feedbackRecipients" -d "wl5cDMuUhmF"
  -H "Content-Type:text/plain"-u admin:district

Jetons¶

La ressource tokens fournit des jetons d'accès à différents services.

Compte Google Service¶

Vous pouvez récupérer un jeton d'accès OAuth 2.0 du compte de service Google à l'aide d'une requête GET vers la ressource suivante.

GET /api/tokens/google

Le jeton est valable pendant un certain temps, après quoi un autre jeton doit être demandé à cette ressource. La réponse contient un en-tête de contrôle de cache qui correspond à l'expiration du jeton. La réponse contiendra les propriétés suivantes au format JSON.

Tableau : Réponse du jeton

Cela suppose qu'un compte de service Google a été créé et configuré pour DHIS2. Veuillez consulter le guide d'installation pour plus d'informations.

Contenu statique¶

La ressource staticContent vous permet de télécharger et d'extraire des logos personnalisés utilisés dans DHIS2. La ressource permet à l'utilisateur de télécharger un fichier avec une clé associée, qui peut ensuite être extraite à l'aide de la clé. Seuls les fichiers PNG sont pris en charge et ne peuvent être téléchargés que vers les clés logo_banner et logo_front.

/api/33/staticContent

Tableau : Clés de contenu statique

Pour télécharger un fichier, envoyez-le avec une requête POST à :

POST /api/33/staticContent/<key>

Exemple de requête pour télécharger logo.png dans la clé logo_front :

curl -F "file=@logo.png;type=image/png" "https://play.dhis2.org/demo/api/33/staticContent/logo_front"
  -X POST -H "Content-Type: multipart/form-data" -u admin:district

Le téléchargement de plusieurs fichiers avec la même clé écrasera le fichier existant. Ainsi, la recherche d'un fichier pour une clé donnée ne renverra que le dernier fichier téléchargé.

Pour récupérer un logo, vous pouvez OBTENIR ce qui suit :

GET /api/33/staticContent/<key>

Exemple de requêtes pour récupérer le fichier stocké pour logo_front :

• Ajout de « Accepter : text/html » à l'en-tête HTTP.*__ Dans ce cas, le point d'extrémité renverra une image par défaut si rien n'est défini. Il renvoie un flux d'images lorsqu'une image personnalisée ou par défaut est trouvée.

curl "https://play.dhis2.org/demo/api/33/staticContent/logo_front"
  -H "Accept: text/html" -L -u admin:district

• Ajout de « Accepter : application/json » à l'en-tête HTTP.*__ Avec ce paramètre, le point d'extrémité ne renverra jamais d'image par défaut si le logo personnalisé n'est pas trouvé. Au lieu de cela, un message d'erreur sera renvoyé. Lorsque l'image personnalisée est trouvée, ce point d'extrémité renvoie une réponse JSON contenant le chemin/URL de l'image correspondante.

curl "https://play.dhis2.org/demo/api/33/staticContent/logo_front"
  -H "Accept: application/json" -L -u admin:district

Les messages de succès et d'erreur se présentent comme suit :

{
  "images": {
    "png": "http://localhost:8080/dhis/api/staticContent/logo_front"
  }
}

{
  "httpStatus": "Non trouvé",
  "httpStatusCode": 404,
  "statut": "ERREUR",
  "message": "Aucun fichier personnalisé n'a été trouvé."
}

Pour utiliser des logos personnalisés, vous devez activer les paramètres système correspondants en leur attribuant la valeur vrai. Si le paramètre correspondant est faux, le logo par défaut sera utilisé.

Paramétrage de l'IU¶

Pour parametrer l'interface utilisateur de l'application DHIS2, vous pouvez insérer des styles JavaScript et CSS personnalisés via la ressource files.

POST GET DELETE /api/33/files/script
POST GET DELETE /api/33/files/style

Le contenu JavaScript et CSS inséré par le biais de cette ressource sera chargé par l'application web DHIS2. Cela peut être particulièrement utile dans certaines situations :

• Remplacer les styles CSS de l'application DHIS2, tels que la page de connexion ou la page principale.

• Définir des fonctions JavaScript communes à plusieurs formulaires de saisie de données personnalisés et à des rapports basés sur HTML.

• Y compris les styles CSS utilisés dans les formulaires de saisie de données personnalisés et les rapports basés sur HTML.

Paramétrage de l'application de connexion¶

L'application Paramètres permet aux utilisateurs de définir une variété d'éléments (texte, logo, drapeau) qui peuvent être utilisés pour paramétrer la page de connexion de DHIS2. En outre, il est possible de choisir entre deux présentations préconfigurées (la présentation par défaut et une présentation avec barre latérale).

Au besoin, le style et la présentation de l'application de connexion peuvent être personnalisés en téléchargeant un modèle HTML (également définissable dans l'application de configuration). Ce modèle HTML remplace certains éléments (basés sur l'ID) ; les ID en réserve sont listés dans le tableau ci-dessous. Il est donc possible de combiner un style personnalisé (à l'aide de css) et une mise en page personnalisée (à l'aide de HTML) pour modifier l'apparence de l'application de connexion. Le modèle personnalisé ne prend pas en charge les scripts personnalisés, et les balises de script seront supprimées de tout modèle téléchargé.

Pour créer un modèle personnalisé, il est recommandé de commencer par l'un des modèles existants (ceux-ci peuvent être téléchargés à partir de l'application de connexion à l'extension dhis-web-login/#download).

L'apparence de la boîte de dialogue de connexion peut également être modifiée en définissant des variables css dans le modèle HTML. Les variables css suivantes sont disponibles pour le paramétrage :

--form-container-margin-block-start
--form-container-margin-block-end
--form-container-margin-inline-start, auto
--form-container-margin-inline-end
--form-container-default-width
--form-container-padding
--form-container-background-color
--form-container-box-border-radius
--form-container-box-shadow
--form-container-font-color
--form-title-font-size
--form-title-font-weight
--form-container-title-color

You can reset the login page theme using the API by making a POST request to /api/41/systemSettings/loginPageLayout including the loginPageLayout DEFAULT or SIDEBAR value in the request body, where content type is set to "text/plain". As an example, you can use curl like this:

curl "play.im.dhis2.org/stable-2-41-0/api/41/systemSettings/loginPageLayout" -d "DEFAULT" -H "Content-Type: text/plain" -u admin:district