API-Nutzungsbeispiel: Schätzung von Workflow-Abschlussdaten

Anwendungsfall

Nehmen wir an, wir wollen:

• Daten über unsere Workflow-Läufe aus der öffentlichen API von Pneumatic extrahieren;
• Die resultierenden Daten in Google Sheets speichern;
• Und die exportierten Daten bearbeiten, um einen ansprechenden individuellen Bericht zu erstellen.

Pneumatic ermöglicht es Ihnen, für jede Aufgabe in einer Workflow-Vorlage einen ‘Fälligkeitswert’ einzugeben. Theoretisch können wir, wenn wir für alle Schritte Fälligkeitswerte eingeben, dann Abschlussdaten für alle Workflow-Instanzen schätzen.

Angenommen, unser Unternehmen verwendet einen einfachen Skripterstellungsprozess, der aus folgenden Schritten besteht:

1. Anforderungen analysieren
2. Ein Skript erstellen (ein einfaches Softwarestück)
3. und dann veröffentlichen

Wir können Fälligkeitswerte für alle Schritte in unserem Prozess eingeben und jetzt, da wir unsere Skripterstellung Workflow-Vorlage haben, können wir mehrere Workflow-Instanzen daraus ausführen:

Wie könnten wir herausfinden, wann jeder dieser Workflows abgeschlossen sein wird?

API zur Rettung

Erstellen wir eine Google Sheets-Tabelle, in die wir die Daten eingeben, die wir benötigen, um auf die API von Pneumatic zuzugreifen und die Daten zu sammeln, die wir von ihr erhalten - Beispiel zur Schätzung von Abschlussdaten.

Halten wir es einfach, wir brauchen irgendwo Platz für unseren API-Schlüssel, den wir von unserer Integrationsseite erhalten:

Dann benötigen wir auch die ID unserer Vorlage, die wir aus der URL unserer Vorlage erhalten können:

Und was die Namen unserer Spalten angeht, geben wir sie einfach manuell als Anleitung ein, welche Informationen wir von Pneumatic erhalten möchten:

Jetzt müssen wir zu Erweiterungen —> AppScript gehen, um die Codes zu erstellen, die auf die API von Pneumatic zugreifen und von dort die Daten holen, die wir wollen:

Berechtigungen

Wenn Sie versuchen, eines der Skripte in der Tabelle auszuführen, wird Google Sie um Erlaubnis bitten, diese auszuführen. Geben Sie die Erlaubnis durch Klicken auf Erlauben.

Die Codes

Pneumatic hat eine detaillierte API-Dokumentation, die Sie hier finden können, aber in diesem Leitfaden werden wir es einfach halten, naja, relativ einfach. Die am Anfang dieses Dokuments geteilte Tabelle enthält bereits alle Funktionen, die Sie benötigen, um Ihre Schätzungen der Abschlussdaten bereit zu haben (für unser Beispiel).

In der oberen Leiste können Sie auswählen, welche Funktion ausgeführt wird, wenn Sie auf Ausführen klicken.

Die Funktion, die wir benötigen, ist 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; //die Zeile, in der wir anfangen, Daten zu schreiben
  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("Aufgabe "+workflow.current_task+" von " +workflow.tasks_count);
      //console.log(workflow.task);
      sheet.getRange(row, 4).setValue(addDays(today, daysLeft(workflow.current_task, templateData.tasks, workflow.task)));
      row +=1;
  } 
}

Diese Funktion ist ziemlich einfach:

• Zuerst erhält sie die Zugangsdaten zur Pneumatic API, die wir zuvor in die Tabelle eingegeben haben (den API-Schlüssel und die Vorlagen-ID).
• Dann erstellt sie den Pneumatic-Endpunkt, den wir benötigen, um unsere Workflows zu erhalten.
• Sie erstellt ein Konfigurationsobjekt, um den API-Schlüssel hineinzugeben, und holt dann die Workflow-Informationen, indem sie die Fetch-Methode auf das UrlFetchApp-Objekt ausführt.
• Schließlich iteriert sie über die Workflows und füllt die Zellen in unserer Tabelle mit den Informationen, die wir wollen.

Wenn Sie auf Ausführen klicken und dann wieder in die Tabelle gehen, stellen Sie fest, dass sie mit Daten gefüllt wurde:

Es gibt einige versteckte Komplexität. Sie können sehen, dass unsere Funktion einige andere Funktionen nutzt. Sie erhält unsere Workflow-Vorlagendaten, weil wir diese Informationen benötigen, um auf die von uns in der Vorlage eingegebenen Fälligkeitswerte zuzugreifen:

const templateData = getTemplateById(apiKey, templateId)

Die Funktion getTemplateById ist direkt hier im gleichen Skript oben definiert:

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;
}

Sie verwendet einen anderen Endpunkt, um die gewünschte Vorlage zu erhalten, und gibt einfach die Vorlagendaten zurück. Dann rufen wir innerhalb der Schleife zwei weitere Funktionen auf, addDays und daysLeft addDays() fügt einfach Tage zu einem Datum hinzu, um ein anderes Datum zu erhalten:

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

In der Zwischenzeit ist daysLeft die Funktion, die die schwere Arbeit unserer Schätzung leistet und alle Arten von Annahmen macht:

function daysLeft(currentTask, tasks, taskInWorkflow) {
  
    let ret = 0;
    ret += extraDays(currentTask, tasks, taskInWorkflow);//add extra days for tasks that have not been completed yet
    // no extra days get added for overdue tasks;
    
    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; //add an extra day if there's more than 12 hours in the due in
        }
        
      }else{
        ret += 1; //assume that if there is no due in the task takes 1 day
      }
      return ret;
    }
}

Zuerst ruft sie die Funktion extraDays auf, die im Grunde genommen prüft, ob die aktuelle Aufgabe überfällig ist oder nicht, und wenn sie es ist, gibt sie null zurück. Wenn sie nicht überfällig ist, gibt sie die Differenz zwischen dem geschätzten Fälligkeitsdatum und jetzt zurück:

function extraDays(currentTask, tasks, taskInWorkflow){
  //const dateStarted = new Date(taskInWorkflow.date_started);
  const estimatedEndDate = new  Date(taskInWorkflow.estimated_end_date);
  const now = new Date();
  if (estimatedEndDate < now) {
    //console.log(Math.round((now - estimatedEndDate)/(1000 * 60 * 60 * 24)));
    return 0;
  }else {
    extra = Math.round((estimatedEndDate - now)/(1000 * 60 * 60 * 24));
    //estimating the difference in days by rounding days to integers
    console.log(extra);
    return extra;
  }
}

Intern stellt JS Tage als die Anzahl der Millisekunden seit dem Start der ersten Unix-Maschine oder so dar, daher der (1000 x 60 x 60 x 24) Quatsch, um Millisekunden in Tage umzurechnen.

Hier haben wir unsere erste große Wahl darüber, wie wir Daten schätzen: Wir runden die Tage einfach ab, so dass 1,5 Tage = 2 Tage und 1,3 Tage = 1 Tag.

Jetzt zurück zu daysLeft():

   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; //add an extra day if there's more than 12 hours in the due in
       }
       
     }else{
       ret += 1; //assume that if there is no due in the task takes 1 day
     }
     return ret;
   }

Hier gehen wir die verbleibenden Aufgaben durch und prüfen, ob eine Aufgabe einen Fälligkeitsparameter hat, wenn sie keinen hat, gehen wir einfach davon aus, dass die Aufgabe genau einen Tag dauern wird. Wenn sie jedoch einen hat, müssen wir den Fälligkeitsparameter zerlegen.

Wir prüfen, ob die Aufgabe in 1 Tag oder später fällig ist und fügen die Anzahl der Tage zu unserem Rückgabewert hinzu. Und dann schauen wir, wie viele Stunden die Aufgabe fällig ist und wenn es mehr als 12 Stunden sind, fügen wir einen weiteren Tag zu unserem Rückgabewert hinzu. Hier entscheiden wir uns dafür, bei unserer Schätzung etwas konservativ zu sein.

All diese Splits haben damit zu tun, wie Pneumatic die Fälligkeitsdaten intern speichert - sie werden als Strings gespeichert, daher müssen wir sie in Werte zerlegen, die wir in Ganzzahlen umwandeln können, daher all die String-Manipulationshoops, durch die wir springen müssen.

Die besten Dinge im Leben sind automatisierbar

Jetzt mag all dieser Code vielleicht ein bisschen einschüchternd aussehen, aber er ist wirklich nicht so schlimm und das Beste daran ist, dass er, einmal geschrieben, ad infinitum wiederverwendet werden kann.

Unabhängig davon, wie viele weitere Workflows Sie ausführen, können Sie Informationen über sie in diese Tabelle bekommen und sehen, wann jeder von ihnen abgeschlossen sein sollte, plus minus ein Tag (oder zwei).

Im Grunde genommen ermöglicht Ihnen die öffentliche API von Pneumatic also, die Automatisierungs-Nirvana zu erreichen, wo die Informationen, die Sie benötigen, nur einen Mausklick entfernt sind, genau in dem Format, in dem Sie sie sehen möchten.