Exemple d'utilisation de l'API : Estimation des dates de fin du flux de travail

Cas d’utilisation

Supposons que nous voulons:

• Extraire des données sur l’exécution de notre flux de travail à partir de l’API publique de Pneumatic;
• Stocker les données résultantes dans la feuille Google;
• Et traiter les données exportées pour obtenir un rapport personnalisé agréable à regarder.

Pneumatic vous permet d’entrer une valeur de due in pour chaque tâche dans un modèle de flux de travail. Théoriquement, si nous entrons des due-ins pour toutes les étapes, nous pouvons alors estimer les dates de réalisation de toutes les instances du flux de travail.

Supposons que notre entreprise utilise un processus simple de création de script comprenant:

1. Analyser les besoins
2. Créer un script (un simple morceau de logiciel)
3. et ensuite le publier

Nous pouvons entrer des due-ins pour toutes les étapes de notre processus et maintenant que nous avons notre modèle de flux de travail de création de script, nous pouvons exécuter plusieurs instances du flux de travail à partir de celui-ci:

Comment pourrions-nous découvrir quand chacun de ces flux de travail sera terminé ?

API à la rescousse

Créons une feuille de calcul Google où nous allons saisir les données dont nous avons besoin pour accéder à l’API de Pneumatic et collecter les données que nous en obtenons — Exemple d’estimation des dates de fin

Soyons simples, nous avons besoin d’un endroit pour mettre notre clé API, que nous obtenons de notre page d’intégrations :

Ensuite, nous aurons également besoin de l’ID de notre modèle, que nous pouvons obtenir à partir de l’URL de notre modèle :

Et en ce qui concerne les noms de nos colonnes, entrons-les manuellement comme guide pour les informations que nous voulons obtenir de Pneumatic :

Maintenant, nous devons aller dans Extensions —> AppScript pour créer les codes qui accèderont à l’API de Pneumatic et obtiendront de là les données que nous voulons :

Autorisations

Si vous essayez d’exécuter l’un des scripts dans la feuille de calcul, Google vous demandera l’autorisation de les exécuter, donnez l’autorisation en cliquant sur Autoriser.

Les Codes

Pneumatic propose une documentation détaillée de l’API que vous pouvez trouver ici, mais dans ce guide nous allons le simplifier, enfin, relativement. La feuille de calcul partagée au début de ce document contient déjà toutes les fonctions dont vous avez besoin pour préparer vos estimations de dates de fin (pour notre exemple).

Dans le panneau en haut, vous pouvez sélectionner quelle fonction sera exécutée si vous cliquez sur Exécuter.

La fonction dont nous avons besoin est getCompletionDateEstimates:

function getCompletionDateEstimates() {
  
  let end_point = 'https://api.pneumatic.app/workflows';
  const sheet = SpreadsheetApp.getActiveSheet();
  const apiKey = sheet.getRange(1,2).getValue();
  const templateId = sheet.getRange(2,2).getValue();
  end_point = end_point +'?template_id='+templateId;
  
  let config = {
    muteHttpExceptions:true,
    method: "get",
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  }
  
  const templateData = getTemplateById(apiKey, templateId)
  
  const response = UrlFetchApp.fetch(end_point, config);
  const json = response.getContentText();
  const workflowData = JSON.parse(json);
  const workflows = workflowData.results;
  const today = new Date();
  //console.log(workflows)
  let row = 5; //the row where we start writing data
  for (let workflow of workflows) {
      sheet.getRange(row,1).setValue(workflow.name);
      sheet.getRange(row, 2).setValue(workflow.task.name);
      sheet.getRange(row, 3).setValue("Tâche "+workflow.current_task+" sur " +workflow.tasks_count);
      //console.log(workflow.task);
      sheet.getRange(row, 4).setValue(addDays(today, daysLeft(workflow.current_task, templateData.tasks, workflow.task)));
      row +=1;
  } 
}

Cette fonction est assez simple :

• Elle récupère d’abord les entrées d’accès à l’API de Pneumatic que nous avons saisies dans la feuille de calcul plus tôt (la clé API et l’ID du modèle).
• Ensuite elle crée le point de terminaison Pneumatic dont nous avons besoin pour obtenir nos flux de travail.
• Elle crée un objet de configuration pour y mettre la clé API et ensuite obtient les informations sur les flux de travail en exécutant la méthode fetch sur l’objet UrlFetchApp.
• Enfin, elle itère sur les flux de travail et remplit les cellules de notre tableau avec les informations que nous voulons.

Si vous cliquez sur Exécuter et que vous revenez à la feuille de calcul, vous constaterez qu’elle a été remplie de données :

Il y a une certaine complexité cachée là-dedans. Vous pouvez voir que notre fonction utilise d’autres fonctions. Elle récupère les données de notre modèle de flux de travail car nous avons besoin de ces informations pour accéder aux due-ins que nous avons saisis dans le modèle :

const templateData = getTemplateById(apiKey, templateId)

La fonction getTemplateById est définie ici même dans le même script ci-dessus :

function getTemplateById(apiKey, templateId){
  
  const end_point = 'https://api.pneumatic.app/templates/'+templateId;
  let config = {
    muteHttpExceptions:true,
    method: "get",
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  }
  let response = UrlFetchApp.fetch(end_point, config);
  const json = response.getContentText();
  const templateData = JSON.parse(json);
  return templateData;
}

Elle utilise un point de terminaison différent pour obtenir le modèle souhaité et renvoie simplement les données du modèle. Ensuite à l’intérieur de la boucle, nous appelons deux autres fonctions, addDays et daysLeft. addDays() ajoute simplement des jours à une date pour obtenir une autre date :

    function addDays(date, days) {
      let ret = new Date(date);
      ret.setDate(ret.getDate() + days);
      return ret;
    }

Pendant ce temps, daysLeft est la fonction qui fait tout le travail d’estimation et fait toutes sortes d’hypothèses :

function daysLeft(currentTask, tasks, taskInWorkflow) {
  
    let ret = 0;
    ret += extraDays(currentTask, tasks, taskInWorkflow);//ajoute des jours supplémentaires pour les tâches qui n'ont pas encore été terminées
    // aucun jour supplémentaire n'est ajouté pour les tâches en retard;
    
    for (let i = currentTask; i < tasks.length; i++){
      let task = tasks[i];
      if (task.due_in !== null) {
        let splitDueIn = task.due_in.split(" ");
        let splitTime = [];
        if (splitDueIn.length > 1) {
          ret += parseInt(splitDueIn[0]);
          splitTime = splitDueIn[1].split(":");
        }else {
          splitTime = splitDueIn[0].split(":");
        }
        if (parseInt(splitTime[0])>12) {
          ret +=1; //ajouter un jour supplémentaire s'il y a plus de 12 heures dans le délai imparti
        }
        
      }else{
        ret += 1; //supposons que s'il n'y a pas de délai imparti, la tâche prend 1 jour
      }
      return ret;
    }
}

Tout d’abord, elle appelle la fonction extraDays qui regarde essentiellement si la tâche en cours est en retard et si c’est le cas, elle renvoie zéro. Si ce n’est pas en retard, elle renvoie la différence entre la date estimée de fin et maintenant :