Logik und Automatisierung

Die App zeigt bereits Daten und lässt sie bearbeiten. Es fehlt der Teil, der allein arbeitet: ein Skript, das jeden Morgen auf die Pipeline schaut, zählt, was offen ist, und die für die Woche erwarteten Abschlüsse festhält.

In dieser Etappe schreiben Sie dieses Skript in Python, führen es von Hand aus, um das Ergebnis zu sehen, und legen ihm eine Uhrzeit fest — jeden Tag um 07:00.

#Was das Skript tun wird

Das atualizar_indicadores beantwortet drei Fragen und gibt sie in einem Ergebnis zurück, das in der Historie bleibt:

Frage	Was es zurückgibt
Wie viele Verkaufschancen sind offen?	oportunidades_abertas
Wie viel ist die Pipeline wert?	valor_pipeline
Wie viele Abschlüsse sind für die nächsten 7 Tage erwartet?	fechos_proximos_7_dias

Zusätzlich zum Ergebnis schreibt es Logs — eine Zeile pro Abschluss der Woche —, damit derjenige, der die Historie öffnet, ohne Rechnen versteht, was an jenem Tag anstand.

#Das Skript erstellen

1. Wählen Sie in der Seitenleiste das Panel Code.
2. Klicken Sie in der Zeile Skripte auf das + (Neues Skript). Es öffnet sich der Dialog Neues Skript — „Wählen Sie die Runtime und erstellen Sie es — den Code bearbeiten Sie danach, mit dem Vertrag im Blick.“
3. Schreiben Sie in Name atualizar_indicadores. Der Name identifiziert das Skript überall — in den Zeitplänen, in den Schritten von APIs, in den Abhängigkeiten anderer Skripte.
4. Runtime steht fest auf Python.
5. Schreiben Sie in Beschreibung Berechnet die Vertriebskennzahlen neu und meldet, wenn es Abschlüsse für diese Woche gibt.
6. Lassen Sie bei Zeitlimit 1 Minute stehen. Das ist die Obergrenze der Ausführung: Nach dieser Zeit bricht die Plattform ab.
7. Klicken Sie auf Skript erstellen. Der Editor öffnet sich mit der fertigen main.py.

#Die main.py schreiben

Der Vertrag eines Skripts ist kurz: eine Funktion main(input), die etwas zurückgibt. Was Sie zurückgeben, bleibt in der Historie der Ausführungen und ist, wenn das Skript von einer API aufgerufen wird, deren Antwort.

Schreiben Sie das in den Editor:

from datetime import date, timedelta

from api_manager import db, log


def main(input):
    """Berechnet die Kennzahlen des Vertriebspanels neu.

    Läuft jeden Tag um 7:00 Uhr (Zeitplan "Tägliche Kennzahlen") und gibt
    die Zusammenfassung zurück — die Historie der Ausführungen behält so
    pro Tag einen lesbaren Eintrag.
    """
    crm = db("Dados CRM")

    abertas = crm.query(
        "select count(*) as n, coalesce(sum(valor), 0) as total "
        "from oportunidades where fase not in ('fechada_ganha', 'fechada_perdida')"
    )[0]

    limite = (date.today() + timedelta(days=7)).isoformat()
    fechos_semana = crm.query(
        "select titulo, data_fecho from oportunidades "
        "where fase not in ('fechada_ganha', 'fechada_perdida') "
        "and data_fecho <= ? order by data_fecho",
        [limite],
    )

    log("Pipeline:", abertas["n"], "Verkaufschancen /", abertas["total"], "EUR")
    for op in fechos_semana:
        log("Abschluss diese Woche:", op["titulo"], "(", op["data_fecho"], ")")

    return {
        "oportunidades_abertas": abertas["n"],
        "valor_pipeline": abertas["total"],
        "fechos_proximos_7_dias": len(fechos_semana),
    }

Vier Dinge, die man sich aus diesem Code merken sollte:

Zeile	Was sie tut
from api_manager import db, log	Der Zugang der Plattform: db öffnet Datenbanken, log schreibt in die Historie.
db("Dados CRM")	Die Datenbank über den Internen Namen der Datenquelle — denselben, den Sie in der Etappe des Modells registriert haben. Ändern Sie den Namen dort, und diese Zeile funktioniert nicht mehr.
crm.query(sql, [valores])	Parametrisierte Abfrage. Die Werte gehen immer getrennt von der Query — nie an den Text geklebt.
return { … }	Das Ergebnis der Ausführung. Es bleibt in der Historie und ist das, was eine API zurückgeben würde.

Das input, das die Funktion erhält, bringt die Argumente der Ausführung mit — die einer API, die eines Zeitplans oder die, die Sie gleich von Hand schreiben. Hier verwenden wir keines.

#Das Skript von Hand ausführen

1. Klicken Sie oben im Editor auf Jetzt ausführen.
2. Es öffnet sich der Dialog — „Legen Sie die Argumente dieser Ausführung fest (optional). Die Werte kommen als Text beim Skript an.“ Wir brauchen keines.
3. Klicken Sie auf Ausführen.

Das Panel Ergebnis der Ausführung unten füllt sich: das Siegel Erfolg mit der Dauer, der zurückgegebene Wert als JSON und der Block Logs mit den Zeilen, die das log() geschrieben hat.

#Die Historie der Ausführungen

Das Ergebnis im Editor ist nur das der aktuellen Sitzung. Die vollständige Historie steckt im Button Ausführungen, neben dem Jetzt ausführen:

Jede Zeile nennt Start, Auslöser (Manuell, wenn Sie es waren; Cron, wenn es die festgelegte Uhrzeit war), Status und Dauer, und der Link Details öffnet die Ausführung: die Argumente, das zurückgegebene Ergebnis und die Logs genau dieses Laufs. Hier versteht man drei Wochen später, was das Skript an dem Morgen gesehen hat, an dem niemand hingeschaut hat.

#Für jeden Morgen einplanen

Ein Skript, das nur läuft, wenn jemand den Button drückt, ist keine Automatisierung. Es ist Zeit, ihm eine Uhrzeit zu geben.

1. Klappen Sie im Baum des Panels Code den Knoten des Skripts atualizar_indicadores auf. Es erscheinen drei Abschnitte: Dateien, Abhängigkeiten und Zeitpläne.
2. Fahren Sie mit der Maus über Zeitpläne und klicken Sie auf das + (Neuer Zeitplan).
3. Geben Sie ihm den Namen Tägliche Kennzahlen und erstellen Sie ihn. Der Editor des Zeitplans öffnet sich in einem Tab.
4. Wählen Sie unter Häufigkeit die Option Zu festen Zeitpunkten — „Zu einer Tageszeit, an den Tagen, die Sie wählen.“
5. Wählen Sie unter Wiederholt sich die Option Jeden Tag (an den gewählten Tagen).
6. Schreiben Sie unter Zur Uhrzeit 07:00.
7. Lassen Sie unter Tage alle sieben ausgewählt (oder klicken Sie auf Werktags, wenn das Wochenende nicht interessiert).
8. Wählen Sie unter Zeitzone Europe/Berlin. Es ist die Zeitzone, die entscheidet, was „sieben Uhr morgens“ ist — ohne sie verschiebt sich die richtige Uhrzeit mit der Zeitumstellung.
9. Wählen Sie unter Wenn ein Lauf ausfällt die Option Ignorieren.
10. Prüfen Sie, dass der Schalter Aktiv eingeschaltet ist, und klicken Sie auf Speichern.

#Die drei Häufigkeiten

Häufigkeit	Wann man sie nimmt
Wiederholen	Alle N Minuten oder Stunden, ohne Unterbrechung. Synchronisationen, Abfragen.
Zu festen Zeitpunkten	Zu einer Tageszeit, an den gewählten Tagen. Das ist unser Fall — und der häufigste.
Überwachungsfenster	Fragt alle N Minuten zwischen zwei Uhrzeiten ab und hört auf, sobald die Arbeit des Tages erledigt ist. Um auf eine Datei zu warten, die „morgens, zu wechselnden Zeiten“ ankommt.

Wer den Ausdruck des Zeitplans lieber selbst schreibt, hat unter den drei Optionen den Link Den Ausdruck von Hand schreiben.

#Was mit dem geschieht, was ausgefallen ist

Der Server war um sieben Uhr morgens unten. Wenn er zurückkommt, was passiert mit dem verpassten Termin? Genau das entscheidet Wenn ein Lauf ausfällt:

Option	Was sie tut
Ignorieren	Holt nichts nach. Es bleibt vermerkt, dass er verloren ging.
Nur den jüngsten	Holt den letzten ausgefallenen Lauf nach; die früheren werden als verpasst vermerkt.
Alle	Holt alle ausgefallenen Läufe nach, in der Reihenfolge, in der sie geplant waren.

Für eine tägliche Zusammenfassung ist Ignorieren das Richtige: die Zusammenfassung vom Dienstag am Donnerstag laufen zu lassen nützt niemandem. Für eine monatliche Abrechnung ergibt Alle dagegen jeden Sinn.

#Das Panel der Ausführungen des Zeitplans

Rechts im Editor liegt das Panel Ausführungen, mit den geplanten Uhrzeiten und dem, was mit jeder passiert ist: Erledigt, Ausstehend, Verpasst oder Übersprungen.

#Und danach?

Das Skript ist zu mehr bereit als zur festgelegten Uhrzeit: Es kann Schritt einer API sein (damit die Zusammenfassung auf Anfrage berechnet wird), es kann andere Skripte als Abhängigkeit aufrufen, und es kann Python-Pakete installieren, die es braucht. Das Kapitel Skripte geht das alles durch, und das SDK der Skripte dokumentiert das api_manager — Datenbank, Dateien, Secrets, Benachrichtigungen und HTTP-Aufrufe.

#Warum nicht…?

• Warum scheitert das Skript mit „Datenquelle nicht gefunden“? Der Name in db("…") muss exakt der Interne Name der Datenquelle sein, Großbuchstaben inklusive.
• Warum sehe ich den Button Jetzt ausführen nicht? Das Skript ist inaktiv — schalten Sie den Schalter oben ein.
• Warum wurde die Ausführung mittendrin abgeschnitten? Sie ist gegen das Zeitlimit gelaufen. Entweder dauert das Skript wirklich so lange und Sie erhöhen das Limit, oder es leistet zu viel Arbeit für den Ort, an dem es aufgerufen wird.
• Warum ist der Zeitplan nie gelaufen? Prüfen Sie der Reihe nach: Ist der Zeitplan Aktiv? Ist das Skript Aktiv? Läuft der Scheduler in dieser Installation? Und ist die Zeitzone die, für die Sie sie halten?

Das CRM ist vollständig. Es fehlt nur noch, es online zu stellen: veröffentlichen und nutzen.