• Introduction
• Architecture de la Solution
• Pré-requis
• Étape 1 : Configurer le Back-end
  • Installation des pré-requis système
  • Initialisation de l'environnement applicatif
  • Écriture du code source (main.py)
  • Démarrage du service
  • Test de fonctionnement
• Étape 2 : Configuration du Front-end
• Étape 3 : Configuration Nginx
• Étape 4 : Test de fonctionnement
• Félicitations !

Introduction

Dans ce tutoriel, nous allons configurer une architecture complète (back-end et front-end) pour utiliser des flux (graphiques) DigDash en embarqué via la librairie Javascript.

Pour cela, nous allons mettre en œuvre un back-end léger en Python FastAPI. Ce composant permet de générer des jetons d'impersonnalisation (newAuthTokenAs) à l'aide d'une clé d'API, tout en masquant cette clé critique aux yeux des utilisateurs finaux (front-end). Il sera ensuite nécessaire de modifier notre reverse proxy. Puis, pour finir, nous allons créer une page HTML avec du Javascript pour faire appel à cette API.

Architecture de la Solution

Pour des raisons de sécurité, la clé d'API DigDash ne doit jamais transiter sur le navigateur du client. Le flux d'authentification s'organise donc ainsi :

• Le Front-end (Javascript) appelle une route sécurisée sur le serveur web (/generate-user-token).
• Nginx relaie cette requête en local vers le serveur FastAPI.
• FastAPI interroge directement DigDash en injectant la clé d'API et les en-têtes requis, puis extrait le jeton.
• Le jeton est renvoyé à notre Front-end qui va pouvoir le consommer pour s’authentifier et afficher les flux (graphiques).

Pré-requis

Pour ce tutoriel et afin de pouvoir utiliser la méthode newAuthTokenAs il est nécessaire d’activer l’emprunt d’identité. Pour cela, nous vous invitons à suivre le paragraphe Avancé : Emprunt d’identité sur la page Anonymisation des Urls.

Dans cet exemple d’implémentation, nous utilisons une clé d’API pour l’authentification de l’administrateur au prêt de DigDash. Il est donc nécessaire de créer une clé que l’on utilisera dans notre API back-end. Pour cela, nous vous invitons à suivre la procédure Créer une clé d'API.

Étape 1 : Configurer le Back-end

Installation des pré-requis système

Connectez-vous à votre serveur en SSH et exécutez les commandes suivantes pour installer Python 3 et le gestionnaire d'environnement virtuel. Python sera la technologie socle pour notre back-end.

Initialisation de l'environnement applicatif

Créez et placez-vous dans le répertoire de votre choix (par exemple, /var/www/embedded/) pour initialiser l'application :

Écriture du code source (main.py)

1. Créez un fichier nommé main.py dans le répertoire précédemment initialisé
   sudo vi main.py
2. Puis ajoutez-y le code suivant :

   ⚠ Modifiez la variable API_KEY et l'en-tête "DIGDASH_DOMAIN" avec vos propres paramètres.

   from fastapi import FastAPI, HTTPException
   import httpx
   
   app = FastAPI(title="DigDash Token API")
   
   # Configuration locale : FastAPI communique directement avec Tomcat sur le port 8080
   DIGDASH_LOCAL_URL = "http://127.0.0.1:8080"
   
   # CONFIGURATION A COMPLETER
   API_KEY = "<VOTRE_CLE_API_DIGDASH>"
   DIGDASH_DOMAIN = "<VOTRE_DOMAINE_PUBLIC_EX_client.digdash.com>"
   
   @app.get("/generate-user-token")
   async def generate_user_token(target_user: str):
      """
       Génère un jeton d'authentification pour un utilisateur cible (newAuthTokenAs).
       """
      # Construction explicite de l'URL pour DigDash
       url = f"{DIGDASH_LOCAL_URL}/ddenterpriseapi/DDEnterpriseServlet?method=newAuthTokenAs&userId={target_user}"
      
      # En-têtes requis pour identifier l'environnement DigDash et communiquer l'API Key
       headers = {
          "X-API-KEY": API_KEY,
          "Accept": "application/json",
          "Host": DIGDASH_DOMAIN
       }
   
       async with httpx.AsyncClient() as client:
          try:
               response = await client.get(url, headers=headers)
   
              # Si Tomcat renvoie une erreur (401, 404, 500, etc.)
              if response.status_code != 200:
                  raise HTTPException(
                       status_code=response.status_code,
                       detail=f"Erreur DigDash Backend: {response.text}"
                   )
   
              # La servlet renvoie le token que l'on transfert au front-end
               raw_token = response.text
              return {"token": raw_token}
   
          except httpx.RequestError as exc:
              raise HTTPException(
                   status_code=500,
                   detail=f"Erreur de communication interne avec Tomcat: {str(exc)}"
               )
   
   if __name__ == "__main__":
      import uvicorn
      # Lancement du serveur en local sur le port 8000
       uvicorn.run(app, host="127.0.0.1", port=8000)

   💡 Pour une industrialisation, il est recommandé d’utiliser des fichiers “.env” pour ne pas avoir la clé codée directement dans le fichier python.
   La mise en place de logs est également fortement recommandée pour tracer les usages de l’API et débugger. 

Démarrage du service

Pour tester le fonctionnement, vous pouvez lancer le processus via uvicorn. Cela va monopoliser votre terminal, il sera nécessaire d’en ouvrir un nouveau pour les prochaines étapes.

Si cette commande se déroule bien, vous devriez voir apparaître le message suivant : 

INFO:     Application startup complete.

Test de fonctionnement

Afin de valider le fonctionnement de notre back-end, il est possible de réaliser un curl en local sur notre serveur DigDash.

Étape 2 : Configuration du Front-end

Pour notre architecture côté client, nous allons créer un fichier index.html dans notre répertoire /var/www/embedded/. L’appel à l'API se fait de manière transparente via l’utilisation de fetch. 

1. Créez un fichier index.html.
   sudo vi index.html

2. Puis ajoutez-y le code HTML/CSS/JavaScript suivant :

   ⚠ Modifiez la variable myUser et les identifiants de flux (ici c74b5ca3 et ee54be60) avec vos propres paramètres.

   <!DOCTYPE html>
   <html lang="fr">
   <head>
       <meta charset="UTF-8">
       <title>Dashboard Embarqué</title>
       <script src="/digdash_dashboard/digdash.dashboard.js"></script>
       <style>
    .dashboard-container { display: flex; flex-wrap: wrap; gap: 20px; padding: 20px; }
           .chart-box { border: 1px solid #ccc; width: 45%; height: 400px; background: #f9f9f9; }
       </style>
   </head>
   <body>
       <div class="dashboard-container">
           <div id="chart-1" class="chart-box"></div>
           <div id="chart-2" class="chart-box"></div>
       </div>
   
       <script>
             // Fonction d'initialisation de DigDash
    async function init() {
     const myUser = 'Utilisateur1';
     const response = await fetch('/generate-user-token?target_user='+myUser, {
       method: 'GET'
      });
   
     if (!response.ok) throw new Error("Erreur lors de la récupération du token");
     
     const data = await response.json();
     const authToken = data.token;
      console.log("Token récupéré avec succès :", authToken);
   
      console.log("Parent: Initialisation de DigDash...");
      DigDash.init({
      "url": "/digdash_dashboard", // Utilisation du chemin relatif via Nginx
      "user": myUser,
      "authToken": authToken
      });
     }
   
    function renderChildChart(containerId, flowId) {
      console.log(`Enfant [${containerId}]: Attente de l'initialisation...`);
     // Fonction permettant d'attendre l'initialisation de DigDash
                  function waitForInit(callback) {
      if (DigDash.parameters && DigDash.parameters.size > 0) {
       callback();
       } else {
       setTimeout(() => waitForInit(callback), 100);
       }
      }
   
      waitForInit(() => {
      console.log(`Enfant [${containerId}]: Dessin du flux ${flowId}`);
      DigDash.drawPortlet(containerId, {
      "type": "flow",
      "flowId": flowId
       })
      });
     }
   
           init();
   
           renderChildChart("chart-1", "c74b5ca3");
           renderChildChart("chart-2", "ee54be60");
       </script>
   </body>
   </html>

Étape 3 : Configuration Nginx

Pour rendre cette API et ce site accessible depuis l'extérieur sans ouvrir de port supplémentaire sur votre pare-feu, vous devez ajouter deux règles de routage dans votre fichier de configuration Nginx existant. 

1. Ouvrez votre fichier de configuration Nginx (généralement /etc/nginx/sites-available/001-digdash.com.conf) : 
   sudo vi /etc/nginx/sites-available/001-digdash.com.conf
2. Localisez le bloc server qui écoute sur le port 443 ssl.
3. Insérez les deux directives location suivante à l'intérieur de ce bloc et à la suite des autres location :
       # Routage vers le proxy d'authentification FastAPI
      location /generate-user-token {
           proxy_pass http://127.0.0.1:8000;
           include proxy_params;
          
          # Désactivation impérative de l'interception des erreurs Nginx
          # pour laisser FastAPI transmettre ses messages d'erreur propres au client
          proxy_intercept_errors off;
      }
   
     # Routage vers notre index.html
     location /embedded/ {
          alias /var/www/embedded/;
           index index.html;
           try_files $uri $uri/ =404;
      }
4. Testez la syntaxe de la configuration et rechargez Nginx : 
   # Vérification de la configuration Nginx
   sudo nginx -t
   
   # Si le test est positif, rechargement à chaud de la configuration
   sudo systemctl reload nginx

Étape 4 : Test de fonctionnement

Pour finir ce tutoriel, vous pouvez tester l'accès à votre page web via l’url suivante :

https://VOTRE_DOMAINE.digdash.com/embedded/index.html

La page affichée doit contenir deux flux (graphiques) côte à côte, par exemple :

Félicitations !

Vous avez réussi à mettre en place vos premiers graphiques DigDash en mode embarqué.
Il ne vous reste plus qu’à appliquer ce principe aux graphiques que vous souhaitez intégrer à vos pages web !