Logiikka ja automaatio

Sovellus näyttää jo dataa ja antaa muokata sitä. Puuttuu osa, joka työskentelee itsekseen: skripti, joka joka aamu katsoo pipelinea, laskee mikä on auki ja kirjaa viikolle ennustetut päätökset.

Tässä vaiheessa kirjoitat skriptin Pythonilla, ajat sen käsin nähdäksesi tuloksen ja sovit sille kellonajan — joka päivä klo 07.00.

#Mitä skripti tekee

atualizar_indicadores vastaa kolmeen kysymykseen ja palauttaa ne tuloksena, joka jää historiaan:

Kysymys	Mitä se palauttaa
Montako myyntimahdollisuutta on auki?	oportunidades_abertas
Minkä arvoinen pipeline on?	valor_pipeline
Montako päätöstä on ennustettu seuraaville 7 päivälle?	fechos_proximos_7_dias

Tuloksen lisäksi se kirjoittaa lokeja — yhden rivin viikon jokaista päätöstä kohden — jotta historian avaava ymmärtää laskematta, mitä sinä päivänä oli sovittuna.

#Skriptin luominen

1. Valitse sivupalkista paneeli Koodi.
2. Napsauta rivillä Skriptit painiketta + (Uusi skripti). Avautuu valintaikkuna Uusi skripti — ”Valitse runtime ja luo — koodia muokataan seuraavaksi, sopimus näkyvissä.”
3. Kirjoita kohtaan Nimi teksti atualizar_indicadores. Nimi yksilöi skriptin kaikkialla — ajastuksissa, API-vaiheissa, toisten skriptien riippuvuuksissa.
4. Runtime on kiinteästi Python.
5. Kirjoita kohtaan Kuvaus teksti Laskee myynnin tunnusluvut uudelleen ja ilmoittaa, kun tälle viikolle on päätöksiä.
6. Jätä kohtaan Aikaraja arvo 1 minuutti. Se on suorituksen katto: sen ajan kuluttua alusta katkaisee.
7. Napsauta Luo skripti. Editori avautuu main.py valmiina.

#main.py:n kirjoittaminen

Skriptin sopimus on lyhyt: funktio main(input), joka palauttaa jotakin. Palauttamasi jää suoritushistoriaan ja, jos skriptiä kutsuu API, se on API:n vastaus.

Kirjoita editoriin tämä:

from datetime import date, timedelta

from api_manager import db, log


def main(input):
    """Laskee myyntipaneelin tunnusluvut uudelleen.

    Ajetaan joka päivä klo 7.00 (ajastus "Indicadores diários") ja
    palautetaan yhteenveto — suoritushistoriaan jää luettava merkintä
    joka päivältä.
    """
    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"], "myyntimahdollisuutta /", abertas["total"], "EUR")
    for op in fechos_semana:
        log("päätös tällä viikolla:", op["titulo"], "(", op["data_fecho"], ")")

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

Neljä asiaa, jotka tästä koodista kannattaa muistaa:

Rivi	Mitä se tekee
from api_manager import db, log	Alustan pääsy: db avaa tietokantoja, log kirjoittaa historiaan.
db("Dados CRM")	Tietokanta tietolähteen sisäisellä nimellä — samalla, jonka rekisteröit mallivaiheessa. Muuta nimeä siellä, ja tämä rivi lakkaa toimimasta.
crm.query(sql, [valores])	Parametroitu kysely. Arvot menevät aina kyselystä erillään — ei koskaan liimattuina tekstiin.
return { … }	Suorituksen tulos. Se jää historiaan ja on se, minkä API palauttaisi.

Funktion saama input tuo suorituksen argumentit — API:n, ajastuksen tai ne, jotka kohta kirjoitat käsin. Täällä emme käytä yhtäkään.

#Skriptin ajaminen käsin

1. Napsauta editorin yläreunassa Suorita nyt.
2. Valintaikkuna avautuu — ”Määritä tämän suorituksen argumentit (valinnainen). Arvot saapuvat skriptille tekstinä.” Emme tarvitse yhtäkään.
3. Napsauta Suorita.

Alhaalla paneeli Suorituksen tulos täyttyy: merkki Onnistui kestoineen, palautettu arvo JSON-muodossa ja lohko Lokit riveineen, jotka log() kirjoitti.

#Suoritushistoria

Editorin tulos on vain nykyisen istunnon. Koko historia on painikkeen Suoritukset takana, Suorita nyt -painikkeen vieressä:

Jokainen rivi kertoo kohdat Alkoi, Alkuperä (Manuaalinen, kun se olit sinä; Ajastus, kun kyseessä oli sovittu aika), Tila ja Kesto, ja linkki Tiedot avaa suorituksen: argumentit, palautetun tuloksen ja juuri sen ajon lokit. Tätä kautta ymmärretään kolme viikkoa myöhemmin, mitä skripti näki sinä aamuna, jona kukaan ei ollut katsomassa.

#Ajastaminen joka aamuun

Skripti, joka ajaa vain kun joku painaa nappia, ei ole automaatiota. On aika sopia sille kellonaika.

1. Laajenna paneelin Koodi puussa skriptin atualizar_indicadores solmu. Näkyviin tulee kolme osiota: Tiedostot, Riippuvuudet ja Ajastukset.
2. Vie hiiri osion Ajastukset päälle ja napsauta + (Uusi ajastus).
3. Anna sille nimi Indicadores diários ja luo. Ajastuksen editori avautuu välilehteen.
4. Valitse kohdassa Toistuvuus kortti Määrättyinä hetkinä — ”Tiettyyn kellonaikaan valitseminasi päivinä.”
5. Valitse kohdassa Toistuu vaihtoehto Joka päivä (valittuina päivinä).
6. Kirjoita kohtaan Kello aika 07:00.
7. Jätä kohdassa Päivät kaikki seitsemän valituiksi (tai napsauta Arkipäivät, jos viikonloppu ei kiinnosta).
8. Valitse kohdassa Aikavyöhyke vyöhyke Europe/Lisbon. Vyöhyke päättää, mitä ”seitsemän aamulla” tarkoittaa — ilman sitä oikea aika muuttuisi kellonsiirtojen mukana.
9. Valitse kohdassa Jos ajo jää väliin vaihtoehto Ohita.
10. Varmista, että kytkin Aktiivinen on päällä, ja napsauta Tallenna.

#Kolme toistuvuutta

Toistuvuus	Milloin käyttää
Toista	N minuutin tai tunnin välein, tauotta. Synkronoinnit, kyselyt.
Määrättyinä hetkinä	Tiettyyn kellonaikaan, valittuina päivinä. Meidän tapauksemme — ja yleisin.
Vahtimisikkuna	Tarkistaa N minuutin välein kahden kellonajan välillä ja pysähtyy, kun päivän työ on tehty. Sen tiedoston odottamiseen, joka saapuu ”aamulla, vaihtelevaan aikaan”.

Se, joka kirjoittaa ajastuslausekkeen mieluummin käsin, löytää linkin Kirjoita lauseke käsin kolmen vaihtoehdon alta.

#Mitä tehdä väliin jääneille

Palvelin oli nurin seitsemältä aamulla. Kun se palaa, mitä tapahtuu väliin jääneelle kerralle? Sen päättää Jos ajo jää väliin:

Vaihtoehto	Mitä se tekee
Ohita	Ei jälkisuorita. Kirjataan, että kerta menetettiin.
Vain viimeisin	Jälkisuorittaa viimeisen tekemättä jääneen; aiemmat kirjataan menetetyiksi.
Kaikki	Jälkisuorittaa kaikki tekemättä jääneet siinä järjestyksessä, jossa ne oli sovittu.

Päivittäiselle yhteenvedolle Ohita on oikea valinta: tiistain yhteenvedon ajaminen torstaina ei palvele ketään. Kuukausilaskutukselle Kaikki on täysin järkevä.

#Ajastuksen suorituspaneeli

Editorin oikealla puolella on paneeli Suoritukset, jossa ovat suunnitellut ajat ja se, mitä kullekin tapahtui: Tehty, Tekemättä, Menetetty tai Ohitettu.

#Entä seuraavaksi?

Skripti on valmis muuhunkin kuin sovittuun aikaan: se voi olla API:n vaihe (jotta yhteenveto lasketaan pyynnöstä), se voi kutsua toisia skriptejä riippuvuutena ja se voi asentaa tarvitsemiaan Python-paketteja. Luku Skriptit käy tämän kaiken läpi, ja skriptien SDK dokumentoi api_manager-moduulin — tietokanta, tiedostot, salaisuudet, ilmoitukset ja HTTP-kutsut.

#Miksi ei…?

• Miksi skripti epäonnistuu virheellä ”tietolähdettä ei löydy”? Nimen kohdassa db("…") on oltava täsmälleen tietolähteen Sisäinen nimi, isot kirjaimet mukaan lukien.
• Miksi en näe painiketta Suorita nyt? Skripti on ei-aktiivinen — kytke yläreunan kytkin päälle.
• Miksi suoritus katkaistiin kesken? Se osui Aikarajaan. Joko skripti todella kestää, ja kasvatat rajaa, tai se tekee liikaa työtä siihen paikkaan nähden, josta sitä kutsutaan.
• Miksi ajastus ei koskaan ajanut? Tarkista järjestyksessä: onko ajastus Aktiivinen? Onko skripti Aktiivinen? Onko ajastin käynnissä tässä asennuksessa? Ja onko Aikavyöhyke se, mikä luulet sen olevan?

CRM on valmis. Se pitää vielä saada ilmoille: julkaisu ja käyttö.