Questo si presta particolarmente bene per la realizzazione di giochi multiplayer, in cui la comunicazione dovrebbe essere continua e con la minor latenza possibile (il che esclude, per esempio, la comunicazione mediante http).

La tipica architettura prevede l'esistenza di un server centrale a cui i client si connettono: i client trasmettono ciascuno il proprio stato al server (ad esempio, la posizione del giocatore), e il server lo reinvia a tutti gli altri, che in questo modo possono restare sincronizzati.

In questo piccolo esperimento voglio provare a definire un semplice esempio di architettura client/server. Il server resta in ascolto della richiesta di connessione dei client, e una volta instaurata gestisce ciascuna connessione attraverso un diverso thread.

Il Server

Iniziamo con il server, che sarà tutto racchiuso in una classe. Per prima cosa vogliamo definire il metodo di inizializzazione della classe, che si occuperà di inizializzare il socket. Già che ci siamo definiamo come proprietà della classe un paio di dizionari per contenere i thread che andremo a creare e i relativi dati scambiati da ciascun client. Impostiamo con settimeout un timeout di connessione di mezzo secondo (il perchè è spiegato più avanti).

class ThreadedServer(object):

    clients_data = {}
    clients_list = {}

    def __init__(self, host, port):

        self.host = host
        self.port = port
        
        print(f"Apertura socket su porta {self.port}...")
        
        self.sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
        self.sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
        self.sock.settimeout(0.5)
        self.sock.bind((self.host, self.port))

Il metodo centrale di questa classe sarà quello che andrà ad ascoltare le richieste di connessione in ingresso e le passerà a un thread individuale.

    def listen(self):
                
        self.sock.listen(5)

        listening:bool = True
        print("attesa connessione...")

        while listening:

            try:
                
                client, address = self.sock.accept()
                client.settimeout(60)
                
                print("client connesso!")
                
                new_client_id = str(uuid.uuid4())
                new_thread = threading.Thread(
                    target = self.manage_client_connection, 
                    args = (client, address, new_client_id), 
                    daemon=True
                )
                new_thread.start()
                self.clients_list[new_client_id] = new_thread

            except socket.timeout:
                # print("Timeout")
                pass
            except KeyboardInterrupt:
                listening = False

        print("Thread principale terminato!")

Un paio di osservazioni:

• Il metodo listen inizializza il socket in ascolto. Il parametro è il numero massimo di connessioni contemporanee supportate (in questo caso 5).
• Il ciclo di attesa è un loop infinito. Usiamo una variabile booleana (listening) per sorvegliarne l'esecuzione.
• Il metodo accept è quello che effettivamente blocca il programma in attesa di connessione. Durante l'inizializzazione abbiamo impostato un timeout sulla fase di connessione (0,5 secondi), che ci consente di far avanzare il loop (sollevando una TimeoutException) anche in assenza di connessioni: in questo modo possiamo sorvegliare la nascita di un'eventuale eccezione di tipo KeyboardError. Questa eccezione avviene quando l'utente preme Control+C, e in questo caso mettiamo a False la variabile di ciclo e possiamo così chiudere il programma; in assenza di questo stratagemma il programma, in assenza di connessioni, rimarrebbe in eterno fermo in attesa e non sarebbe possibile terminarlo da tastiera. Naturalmente, le eccezioni dovute a timeout sono previste e quindi semplicemente ignorate: non è il metodo più efficiente o elegante ma ci accontentiamo.
• Quando viene accettata una connessione, viene generato un id casuale (per identificarla in maniera univoca) con il metodo uuid4. Viene poi costruito e avviato un thread attorno al metodo manage_client_connection, a cui viene passata la nuova connessione. A questo punto il programma principale può dimenticarsi di questa connessione, che sarà d'ora in avanti gestita dal thread, e rimettersi in ascolto della successiva.

A questo punto non ci resta che realizzare il metodo manage_client_connection, che fa il grosso del lavoro per ciascuno dei socket.

    def manage_client_connection(self, client:socket.socket, address, client_id:str):

        size = 1024

        # Handshake
        data = msgpack.unpackb(client.recv(size))
        print("Received handshake: ", data)
        handshake_reply = {
            "id": client_id
        }
        client.send(msgpack.packb(handshake_reply))

        while True:

            try:
                
                data = client.recv(size)

                if data:
                    
                    self.clients_data[client_id] = msgpack.unpackb(data)

                    client.send(msgpack.packb(self.clients_data))

                else:
                    raise Exception('Client disconnected')
                
            except Exception as e:

                print(e)
                client.close()
                del self.clients_data[client_id]
                return False

La comunicazione attraverso il socket è svolta usando la libreria msgpack, che consente di convertire in un formato binario dei flussi JSON. Questo fa si che la comunicazione sia estremamente più compatta e quindi efficiente (comunicare direttamente mediante stringhe JSON è ESTREMAMENTE poco efficiente).

Quando la connessione viene instaurata viene effettuato un handshake: si suppone che il client appena connesso ci mandi un pacchetto dati (che al momento è ignorato, ma è utile predisporlo per il futuro, un domani potrebbe contenere per esempio le credenziali dell'utente del client, o la versione, eccetera) a cui noi rispondiamo con un pacchetto dati contenente l'ID che abbiamo assegnato in precedenza a questa specifica connessione.

A questo punto inizia il loop infinito: il server resta in attesa di dati dal client, e quando li riceve li salva nel dizionario definito nella classe principale, indicizzandolo con l'uuid della connessione. Una volta ricevuto l'aggiornamento poi mandiamo al client i dati di TUTTI i client, in questo modo il client è sincronizzato con gli stati di tutti gli altri client connessi; ad esempio, possiamo immaginare che, nel caso di un gioco multiplayer, ogni client mandi al server la posizione (x,y) del proprio giocatore, e in cambio riceva le posizioni di tutti gli altri per poterli disegnare correttamente.

La classe del server è quindi terminata, e la possiamo avviare semplicemente così:

if __name__ == "__main__":
    ThreadedServer('', 12345).listen()

Il Client

Il client è un pò più complesso perchè deve contenere, oltre alla parte di networking, tutta la logica di gioco. In questo esempio ci focalizziamo solo sulla componente di networking, e il prototipo di gioco attorno lo lasciamo al prossimo post. Dentro il client quindi ci sarà una classe che si occuperà di gestire la comunicazione con il server.

La classe definisce una manciata di attributi, commentati qui sotto, e un metodo di inizializzazione che semplicemente imposta host e porta del server a cui connettersi.

class NetworkConnection:
   
  client_socket = None
  thread = None

  # Il client deve tentare di restare connesso
  _stay_connected = False

  # Stato connessione
  _is_connected = False

  # ID assegnato durante handshake
  player_id = None

  # Ultimo payload ricevuto dal server
  received_data = {}


  def __init__(self, host, port):
    self.host = host
    self.port = port
    self._stay_connected = False

Definiamo un metodo "connect", che verrà chiamato per attivare la connessione vera e propria, e un metodo "disconnect" che si spiega da solo. Il metodo connect si occupa semplicemente di creare un thread attorno al metodo "_worker", che gestisce le attività legate alla connessione in maniera autonoma. Viene inoltre garantito che il thread sia unico, se esiste già il "connect" lo distrugge prima di ricrearlo.

  def connect(self):
  
    self._is_connected = False
    
    # Si assicura che eventuale thread esistente sia chiuso
    if (self.thread != None and self.thread.is_alive()):
      self._stay_connected = False
      while(self.thread.is_alive()):
        time.sleep(.1)
  
    self._stay_connected = True
  
    self.thread = threading.Thread(target=self._worker, args=(), daemon=True)
    self.thread.start()
  
  
  def disconnect(self):
    self._stay_connected = False
    
  def is_connected(self):
    return self._is_connected

A questo punto dobbiamo solo definire il cuore della classe, il metodo "_worker". Questo metodo, che come abbiamo visto è eseguito in un thread, è costruito su due loop infiniti entrambi controllati dalla variabile "stay_connected".

Il loop interno è in ascolto sul canale di comunicazione, e ogni volta che riceve dati li salva nella variabile d'istanza self.received_data (accessibile dal resto del programma).

    while(self._stay_connected):
      
      ...
      
      while(self._stay_connected):

        data = self.client_socket.recv(1024)

        try:
          self.received_data = msgpack.unpackb(data)
        except Exception:
          _logger.exception("Errore durante socket recv")
          break

Il loop esterno, invece, entra in gioco all'avvio del thread e in tutte le eventuali situazioni in cui in loop interno dovesse morire a causa di errori di connessione o simili. Questo blocco si occupa di effettuare la connessione vera e propria al socket ed eseguire l'handshake (come già visto dal punto di vista del server).

    while(self._stay_connected):
      
      ...
      self._connect_socket()
      ...
      
      ...
      self._handshake()
      ...
      
      self._is_connected = True

      while(self._stay_connected):
        ...

In ogni caso, entrambi i loop terminano quando la variabile viene messa a un valore False. Mettendo attorno un pò di gestione di errori e l'implementazione dei metodi di connessione e handshake otteniamo questo codice:

  def _connect_socket(self):
    self.client_socket = socket.socket()
    self.client_socket.connect((self.host, self.port))


  def _handshake(self):

    _logger.debug("Effettuazione handshake...")

    handshake_payload = {
      "text": "hi"
    }
    
    self.client_socket.send(msgpack.packb(handshake_payload))
    handshake_recv = msgpack.unpackb(self.client_socket.recv(1024))
    self.player_id = handshake_recv['id']
    
    _logger.debug(f"Server assigned me this id: {self.player_id}")


  # Thread principale
  def _worker(self):

    while(self._stay_connected):
      
      try:
        self._connect_socket()
      except Exception:
        _logger.exception("Connessione fallita!")
        time.sleep(1)
        self.client_socket = None
        self.thread = None
        return

      try:
        self._handshake()
      except Exception:
        _logger.exception("Handshake fallito!")
        time.sleep(1)
        self.client_socket = None
        self.thread = None
        return
      
      self._is_connected = True

      while(self._stay_connected):

        data = self.client_socket.recv(1024)

        try:
          self.received_data = msgpack.unpackb(data)
        except Exception:
          _logger.exception("Errore durante socket recv")
          break

    try:
      self.client_socket.close()
    except Exception as _:
      pass
    
    self._is_connected = False

    self.client_socket = None
    self.thread = None

    _logger.debug("Client thread terminato")

Per completare la classe, creiamo anche un metodo che può essere richiamato dal programma principale per inviare dati (finora abbiamo visto solo la ricezione).

  def send(self, data:dict):

    if (self.thread == None or not self.thread.is_alive()):
      _logger.warning("send while thread not alive, reconnecting...")
      self.connect()

    if (self.client_socket):
      try:
        packed_data = msgpack.packb(data)
        self.client_socket.send(packed_data)
      except Exception:
        # _logger.exception("Impossibile trasmettere")
        pass

Il Test

A questo punto dovremmo avere tutto pronto per testare. Costruiamo un semplicissimo script che:

• inizializza la classe ed effettua la connessione
• chiede all'utente di inserire un messaggio
• invia un messaggio
• attende ulteriore conferma dall'utente (simula delay tra invio e ricezione)
• stampa client.received_data, in cui mi aspetto di trovare il messaggio che ho inviato in precedenza.

client = NetworkConnection(socket.gethostname(), 12345)
client.connect()

messaggio = input("Inserire messaggio:")

client.send(messaggio)

input("...")

print(client.received_data)

Per prima cosa avviamo il server:

Poi avviamo il client. Questo si connette immediatamente al server, effettua l'handshake e riceve un id univoco:

Inseriamo un messaggio qualunque nel client:

Premiamo ancora invio per superare il secondo input e vediamo che il nostro client ha ricevuto dal server il messaggio precedentemente inviato:

Il primo client è terminato e la sua connessione è quindi stata chiusa (come mostra l'errore nella finestra del server).

Conclusione

Il codice sopra è estremamente grezzo, con scarsa gestione degli errori e dei casi limite, e funzionicchia dignitosamente ma senza pretese. Diciamo che è un buon esempio accademico. Il prossimo passo sarà provare a inserirlo in un programma Pygame per provare a metterlo alla prova con qualcosa di più visivo.

Grazie per l'attenzione e alla prossima!

Fortunatamente ci sono in giro un sacco di soluzioni di monitoraggio liberamente accessibili e configurabili con poco sforzo, anche se non pensate esattamente per SAP, per cui ho voluto fare un esperimento. In questo post ho realizzato una bellissima dashboard per monitorare in un rapido colpo d'occhio alcuni parametri indicativi del funzionamento del sistema.

L'esperimento coinvolge Prometheus, uno scraper in grado autonomamente di prelevare metriche da sistemi esterni mediante chiamate http e registrarle in un archivio time-based; prevede inoltre la possibilità di eseguire query complesse su questi dati archiviati. L'esperimento coinvolge anche Grafana, un tool per la creazione di dashboard bellissime che si interfaccia direttamente con Prometheus. Più un paio di magheggi direttamente in SAP.

Esposizione delle metriche

Il primo passo da fare è esporre le metriche che ci interessano in un servizio http su SAP, dal quale poi Prometheus potrà andare a leggere (nota: c'è bisogno che Prometheus possa comunicare con SAP, quindi preparate una scatola di cioccolatini per il vostro IT di fiducia). Il modo più semplice per realizzare questo risultato è creare un nuovo servizio nella transazione SICF, esponendo un endpoint collegato a una classe ABAP che si occupa di creare l'output al momento dell'interrogazione.

Le metriche da esporre per Prometheus sono costituite da un semplice payload testuale, in cui ciascuna riga contiene il nome della metrica, un elenco facoltativo di label da associare alla misurazione, e il valore stesso. Supponendo di volere esporre una metrica con il conteggio dell'elenco completo degli IDOC presenti nel sistema divisi per tipo, stato e direzione, il mio output avrà una struttura del genere:

# TYPE total_idocs gauge
total_idocs { mestyp="CREMAS" status="03" direct="1" } 3
total_idocs { mestyp="CREMAS" status="26" direct="1" } 2
total_idocs { mestyp="DEBMAS" status="03" direct="1" } 12
total_idocs { mestyp="DEBMAS" status="09" direct="1" } 4
total_idocs { mestyp="DEBMAS" status="10" direct="1" } 1
total_idocs { mestyp="DEBMAS" status="29" direct="1" } 2
total_idocs { mestyp="DEBMAS" status="37" direct="1" } 2
total_idocs { mestyp="DESADV" status="26" direct="1" } 2
total_idocs { mestyp="DESADV" status="30" direct="1" } 13
total_idocs { mestyp="LOIPRO" status="03" direct="1" } 22
total_idocs { mestyp="LOIWCS" status="03" direct="1" } 8
total_idocs { mestyp="LOIWCS" status="29" direct="1" } 1
total_idocs { mestyp="MATMAS" status="03" direct="1" } 9
total_idocs { mestyp="MATMAS" status="26" direct="1" } 16
...

La prima riga, che inizia con #, è un commento per Prometheus che definisce il tipo di metrica (in questo caso "gauge"); esistono 4 tipi di metrica utilizzabili, questo è il più adatto a questo utilizzo. Ulteriori informazioni qui.

La classe indicata nel servizio SICF effettua una query sulla tabella che contiene le testate degli IDOC e produce un output conforme. Non prendete come esempio il codice qui sotto, ha bisogno di un pò di pulizia e ottimizzazione prima di andare in produzione :-)

CLASS zmp_idoc_monitor DEFINITION
  PUBLIC
  FINAL
  CREATE PUBLIC .
  PUBLIC SECTION.
    INTERFACES if_http_extension.
  PROTECTED SECTION.
  PRIVATE SECTION.
ENDCLASS.

CLASS ZMP_IDOC_MONITOR IMPLEMENTATION.

  METHOD if_http_extension~handle_request.

    server->response->set_status(
      code   = 200
      reason = 'ok'
    ).

    DATA: output TYPE string.

    " ----- IDOC per tipo/stato -------------------------------------

    TYPES: BEGIN OF ty_idoc_group,
             mestyp TYPE edidc-mestyp,
             status TYPE edidc-status,
             direct TYPE edidc-direct,
             count  TYPE i,
           END OF ty_idoc_group.
    TYPES: tyt_idoc_group TYPE TABLE OF ty_idoc_group.
    DATA: lt_idoc_group TYPE tyt_idoc_group.

    SELECT mestyp, status, direct, COUNT(*) AS count FROM edidc
    GROUP BY mestyp, status, direct
    INTO TABLE @lt_idoc_group.

    output = output && '# TYPE total_idocs gauge' && cl_abap_char_utilities=>newline.
    
    loop at lt_idoc_group into data(lv_idoc_group).
        output = output && |total_idocs \{ mestyp="{ lv_idoc_group-mestyp }" status="{ lv_idoc_group-status }" direct="{ lv_idoc_group-direct }" \} { lv_idoc_group-count }| && cl_abap_char_utilities=>newline.
    ENDLOOP.

    " ---------------------------------------------------------------

    server->response->set_cdata( output ).

    server->response->set_header_field(
      name  = 'Content-Type'
      value = 'text/plain'
    ).

  ENDMETHOD.
ENDCLASS.

A questo punto possiamo provare a effettuare una richiesta direttamente dal browser, inserendo l'indirizzo completo dell'endpoint, e vedremo il risultato.

Installazione Prometheus e Grafana

L'installazione è sempre semplice quando si usa Docker, per l'esattezza Docker Compose. Come unico accorgimento prima di procedere è necessario creare due cartelle, una per la configurazione di prometheus e una per i dati di grafana (più lo storage per prometheus, ma al momento non mi interessa conservare i dati tra un run e l'altro). Nella cartella dedicata a prometheus dobbiamo creare un file prometheus.yml con la configurazione, in cu inseriamo il puntamento al nostro server SAP con le relative credenziali utente.

global:
  scrape_interval:     15s

  external_labels:
    monitor: 'codelab-monitor'

scrape_configs:

  - job_name: my_idocs

    metrics_path: '/ztestidoc'

    basic_auth:
      username: 'my_sap_username'
      password: 'my_sap_pwd'

    static_configs:
      - targets: ['my_sap_url:port']

Si noti che è stata configurata una frequenza di scrape di 15 secondi, per questa applicazione probabilmente è fin troppo frequente (e occhio se il codice di estrazione diventa troppo pesante, meglio fare delle prove). Nel mio caso l'estrazione dal db dura complessivamente una decina di millisecondi quindi direi che problemi per ora non ce ne sono :-) .

A questo punto si può predisporre il file docker-compose.yml per l'avvio dei servizi. In questo caso ho deciso di esporre le porte di prometheus e grafana rispettivamente sulle porte 9010 e 9011 dell'host.

version: '3.3'

services:

   prometheus:
     image: prom/prometheus
     ports:
       - 9010:9090
     volumes:
       - my_prometheus_config:/etc/prometheus
     restart: always

   grafana:
     image: grafana/grafana-oss
     ports:
       - 9011:3000
     volumes:
       - my_grafana_storage:/var/lib/grafana
     restart: always
     # id -u
     user: "1001"

Nota: per qualche motivo grafana si arrabbia per problemi di permessi nella creazione delle sottocartelle sull'host, quindi è necessario indicare esplicitamente l'utente con cui eseguirlo (lo stesso con cui sono state create le cartelle). Per ottenere l'id dell'utente corrente è sufficiente usare il comando "id -u" da riga di comando (sotto linux).

Ora possiamo avviare entrambi i servizi con il solito comando:

docker-compose up -d

Configurazione Prometheus

..che poi non c'è nulla da configurare, abbiamo già fatto tutto nel file di configurazione.

Possiamo accedere all'interfaccia web di Prometheus alla porta 9010, dovrebbe essere già tutto configurato correttamente e nella schermata "Status->Targets" dovremmo vedere il nostro servizio up.

Nella schermata "Graph" possiamo effettuare una semplice query inserendo il nome del nostro datapoint (total_idocs), per vedere gli ultimi valori letti.

Configurazione Grafana

Per quanto riguarda Grafana invece non abbiamo ancora configurato nulla. Si poteva passare all'avvio un file di configurazione già fatto, ma dall'interfaccia si fa tutto in 10 secondi.

Si accede all'interfaccia usando la porta esposta da docker (nel nostro caso 9011). Le credenziali di default dell'amministratore sono admin - admin (viene chiesto di cambiare la password al primo accesso).

Da qui possiamo andare su "Connections -> Add new connection" e cercare il plugin per Prometheus.

Per il nostro setup è sufficiente compilare l'indirizzo della macchina. Ricordando che la macchina si trova già nella rete creata da docker-compose, possiamo utilizzare il nome del container e la porta "vera" (NON quella esposta sull'host).

Non sono necessari altri parametri, basta salvare e la connessione è già disponibile. A questo punto c'è "solo" da creare le dashboard per esporre i dati, e qui non c'è modo migliore di andare a tentativi come sto facendo io da qualche tempo :-)

Una volta che si è presa la mano, i risultati sono spettacolari.

Eccetera...

Alla prossima!

Vediamo un pò come si può fare.

Accesso

Il primo passo è configurare il proprio account Google per consentire l'accesso alle API. Sostanzialmente, quello che si deve fare è creare un nuovo progetto Google Cloud (un modo in cui Google possa identificare le nostre richieste), e abilitare su questo progetto le API GSheet.

Consiglio una lettura di questa guida, in cui sono spiegati tutti i passaggi.

Il risultato finale di questo percorso è l'ottenimento di un file credentials.json che contiene le informazioni necessarie alla libreria per accedere al nostro account (saranno comunque necessarie le credenziali, che verranno inserite in un secondo tempo).

Installazione librerie

Per l'accesso avremo bisogno di un pò di librerie python, che possiamo installare con le consuete modalità.

pip install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib

Autenticazione

Il primo passo da fare è chiedere l'autenticazione. L'autenticazione è effettuata con il proprio account Google. Durante la richiesta viene mostrata la consueta schermata di Google in cui si chiede di consentire l' uso del proprio account. Le informazioni scambiate sono poi salvate in un file locale token.json, in modo tale da restare disponibili per le successive esecuzioni senza richiedere ulteriori autorizzazioni.

import os
from google.oauth2.credentials import Credentials
from google.auth.transport.requests import Request
from google_auth_oauthlib.flow import InstalledAppFlow

creds = None
token_path = 'token.json', 
credentials_path = 'credentials.json'
scopes = ['https://www.googleapis.com/auth/spreadsheets'] #spreadsheets.readonly

# The file token.json stores the user's access and refresh tokens, and is
# created automatically when the authorization flow completes for the first
# time.

if os.path.exists(token_path):
    creds = Credentials.from_authorized_user_file(token_path, scopes)

# If there are no (valid) credentials available, let the user log in.

if not creds or not creds.valid:
    if creds and creds.expired and creds.refresh_token:
        creds.refresh(Request())
    else:
        flow = InstalledAppFlow.from_client_secrets_file(
            credentials_path, 
            scopes
        )
        creds = flow.run_local_server(port=0)

    # Save the credentials for the next run
    with open(token_path, 'w') as token:
        token.write(creds.to_json())
        
return creds

Si noti che in testa al codice abbiamo definito il percorso dei file sopracitati e l'array scopes, che contiene la lista dei permessi che stiamo richiedendo (nell'esempio è il permesso ad accedere in lettura/scrittura ai gsheet, possiamo usare l'alternativa spreadsheets.readonly per accedere in sola lettura e non rischiare modifiche indesiderate).

Inizializzazione servizio

A partire dall'oggetto autorizzativo costruito prima possiamo ora costruire l'oggetto che rappresenta il servizio, in questo caso il servizio "spreadsheets".

from googleapiclient.discovery import build

service = build('sheets', 'v4', credentials=creds)
sheet = service.spreadsheets()

Lettura dati

A questo punto abbiamo tutto quello che ci serve per leggere il contenuto di un gsheet.

SPREADSHEET_ID = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
SPREADSHEET_NAME = 'xxxxxxxxxxxxxxxxxxx'
RANGE = f'{SPREADSHEET_NAME}!A1:AQ'

result = sheet.values().get(
    spreadsheetId=SPREADSHEET_ID,
    range=RANGE
).execute()

values = result.get('values', [])

I parametri da fornire sono lo spreadsheet id (l'id unico dello sheet, visibile nell'url, come da immagine sotto), ...

...il nome della pagina all'interno della spreadsheet (case sensitive), ...

...e il range da leggere, nel formato nome_foglio!prima_cella:ultima_cella.

A questo punto nella variabile values è presente un array di array, che presenta i risultati letti dal gsheet organizzati per righe.

Se usiamo pandas possiamo comodamente convertire questi valori in un dataframe, usando la prima riga per determinare il nome delle colonne.

gsheet = pd.DataFrame(
    values[1:],
    columns=values[0]
)

Nota: la dimensione degli array dipende dai dati effettivamente presenti nel foglio, quindi bisogna prestare attenzione quando si leggono fogli parzialmente vuoti perché pandas potrebbe arrabbiarsi (tipo: ci sono 20 colonne ma gli array letti successivamente hanno solo 18 valori perché le ultime due colonne sono vuote). In questi casi bisogna bonificare gli array letti, ad esempio aggiungendo elementi vuoti fino a quando ciascuna riga ha lo stesso numero di elementi della riga di testata.

Lettura altre informazioni

Oltre al puro contenuto delle celle è possibile leggere informazioni aggiuntive, come ad esempio colori, formattazioni o un eventuale link associato alla cella stessa. Per fare questo si effettua un recupero dei dati aggiungendo il parametro "includeGridData".

response = sheet.get(
  spreadsheetId=SPREADSHEET_ID, 
  ranges=[f'{SPREADSHEET_NAME}!E4:I500'], 
  includeGridData=True
).execute()

A seguito di questo, le informazioni aggiuntive si possono trovare "scavando" nel nuovo oggetto restituito, di struttura non particolarmente user friendly :-). Nel mio caso, per recuperare i link dalla prima colonna del range, ho usato questo codice:

for rowdata in response['sheets'][0]['data'][0]['rowData']:
    first_cell = rowdata['values'][0]
    link = first_cell['hyperlink'] if 'hyperlink' in first_cell else ''

Update

Per modificare/scrivere valori nelle celle si effettua un update batch, quindi un'unica operazione di update composta da un certo numero di singoli aggiornamenti. Questi aggiornamenti specificano un range di celle, e un array di valori, uno per ciascuna cella da aggiornare. Alla fine l'update è eseguito chiamando la funzione "batchUpdate" sull'oggetto "values()" dello sheet.

updates = []

updates.append({
  'range': f'{SHEET_NAME}!A1:C1',
  'values': [[
    "prima cella",
    "seconda cella",
    "terza cella"
  ]]
})

# Batch update per valori
sheet.values().batchUpdate(
  spreadsheetId=SPREADSHEET_ID,
  body = {
    'value_input_option': 'USER_ENTERED',
    'data': updates
  }
).execute()

Esiste anche la possibilità di modificare altre informazioni relative alla pagina a parte i semplici valori, quali ad esempio i colori delle celle (utili per evidenziare valori particolari). Si procede in maniera simile, accodando una serie di update ad un'unica chiamata batch, ma con sintassi leggermente diverse.

Per esempio, per modificare il colore di un range di celle, si usa questo codice. Si noti che bisogna passare un range sia per le righe che per le colonne; occhio che il range parte da zero (la riga numero zero corrisponde alla prima riga nel gsheet, quindi quella con scritto 1) e l'estremo superiore è escluso. Si noti anche che nella sezione "values" dobbiamo passare esattamente un elemento per ciascuna delle celle da aggiornare.

requests = []

# Esempi di colori celle
WHITE = {"red": 1, "green": 1, "blue": 1}
RED = {"red": 1}
GREY = {"red": 0.8, "green": 0.8, "blue": 0.8}
LIGHTYELLOW = {"red": 1, "green": 0.95, "blue": 0.8}

requests.append({
  "updateCells": {
    #range 0-indexed, con estremo superiore escluso
    "range": {
      "sheetId": SHEET_ID,
      "startRowIndex": index-1,
      "endRowIndex": index,
      "startColumnIndex": 0,
      "endColumnIndex": 3
    },
    "rows": [
      {
      "values": [
          {"userEnteredFormat": {"backgroundColor": RED}},
          {"userEnteredFormat": {"backgroundColor": GREY}},
        ]
      }
    ],
    "fields": "userEnteredFormat.backgroundColor"
  }
})

sheet.batchUpdate(
  spreadsheetId=SPREADSHEET_ID, 
  body={
    "requests": requests
  }
).execute()

Voilà! Alla prossima!

Il problema è il seguente. Supponiamo di avere una serie di attività da svolgere in sequenza, una dopo l'altra. Ciascuna attività "costa" un tot di giornate di lavoro. Adesso supponiamo di avere a disposizione un tot di mesi, e per ciascuno di essi un certo numero di FTE (full time equivalent), ciascuno dei quali rappresenta il lavoro svolto da un programmatore impiegato full time (quindi se ho due programmatori full time sono 2 FTE, se ho 4 programmatori impiegati sul progetto al 50% sono.. ancora 2 FTE). Dobbiamo valutare indicativamente quando ciascuna fase del progetto inizia e finisce.

Una valutazione del genere si può fare semplicemente con carta&penna (o excel, se proprio ci vogliamo male). Supponiamo per esempio di avere nel primo mese 5 programmatori full time (5 FTE), che per 20 giorni lavorativi al mese fanno 100 giornate di lavoro. Se il primo task cuba 120 giorni di lavoro, il primo mese sarà tutto occupato e il task occuperà anche le prime 20 giornate del mese successivo. Poi inizia il secondo. E così via.

Ora proviamo a farlo con Python, che è più divertente che farlo con carta&penna. Useremo un notebook Jupyter (così possiamo vedere i risultati passo passo), pandas come libreria per l'elaborazione (non strettamente necessaria, potevamo anche fare senza) e pyplot per disegnare un bel gantt alla fine.

Per prima cosa importiamo le nostre dipendenze:

import pandas as pd
import plotly.express as px
import datetime
from calendar import monthrange

Prepariamo la nostra lista ordinata di task. Questo passo normalmente è il risultato finale di un'altra elaborazione, ad esempio per estrarre/sommare le stime da uno o più file excel, ma il risultato finale è questo: una lista di oggetti, ciascuno dei quali contiene la chiave "activity" con la descrizione del task e la chiave "total" con il numero di giorni necessari a completarlo.

tasks = [
    {'activity': '1', 'total': 200},
    {'activity': '2', 'total': 150},
    {'activity': '3', 'total': 40},
    {'activity': '4', 'total': 100},
    {'activity': '5', 'total': 80},
    {'activity': '6', 'total': 30},
    {'activity': '8', 'total': 70}
]

Adesso prepariamo la lista dei mesi su cui andremo a "spalmare" le giornate di lavoro. Nel nostro caso costruiremo un dataframe pandas, con alcuni valori compilati a manina e altri calcolati. In particolar modo, carichiamo a mano i mesi (si potrebbe automatizzare) e gli FTE disponibili per ciascun mese. Consideriamo un fisso di 20 giorni lavorativi al mese e un'efficienza dell' 80% e usiamo questi valori per calcolare il numero di giorni di lavoro effettivamente disponibili per ciascun mese.

months = pd.DataFrame(
    list(zip(
        ['2023-09', '2023-10', '2023-11', '2023-12', '2024-01', '2024-02', '2024-03', '2024-04', '2024-05'],
        [5, 6, 5, 6, 5, 6, 4, 7, 6]
    )),
    columns = ['month', 'fte']
)
months['days_month'] = 20
months['dev_efficiency'] = 0.8
months['days_avail_tot'] = months['days_month'] * months['fte'] * months['dev_efficiency']
months['days_avail'] = months['days_avail_tot']

Si noti che abbiamo predisposto due colonne con i giorni disponibili: una che rimarrà così com'è, come dato informativo, e l'altra da cui andremo a scalare man mano i giorni attribuiti ai diversi task.

Prima di proseguire, predisponiamo per ciascun task una colonna vuota (ci servirà per segnare i giorni allocati per quel mese e quel task).

for task in tasks:
    months[task['activity']] = 0

A questo punto arriva la parte divertente. Per ciascun mese, prendiamo ciascun task con giorni da allocare in sequenza, e per ciascuno cerchiamo di "consumare" la colonna "days_avail". Se finiscono i giorni disponibili vuol dire che per quel mese abbiamo finito e passiamo oltre; se invece finiscono i giorni del task passiamo a consumare il task successivo.

Siccome per qualche motivo stiamo usando un dataframe pandas, dobbiamo iterare sulle righe con iterrows(). Ad ogni iterazione facciamo una copia della riga, la modifichiamo con l'algoritmo e poi usiamo questa copia per rimpiazzare la riga originale.

Una cosa del genere:

for task in tasks:
    months[task['activity']] = 0

for index, row in months.iterrows():
    
    newrow = row.copy()
    
    for task in tasks:
    
        if (task['total'] != 0):

            if (newrow['days_avail'] < task['total']):
                newrow[task['activity']] = newrow['days_avail']
                task['total'] -= newrow['days_avail']
                newrow['days_avail'] = 0
            else:
                newrow[task['activity']] = task['total']
                newrow['days_avail'] -= task['total']
                task['total'] = 0
    
    
    months.iloc[index] = newrow

Funziona! Come si vede, il primo task occupa i primi due mesi per intero più 24 giorni nel terzo (quindi grossomodo un quarto), il secondo task 56 giorni nel terzo e quasi tutto il quarto, e così via.

Possiamo abbellire la tabella (e verificare le somme :-) ) aggiungendo manualmente una riga di totali. Con pandas posso calcolare i totali usando semplicemente il comando "sum" (numeric_only), ma questo mi calcola anche i totali sulle colonne dei giorni/mese e dell'efficienza, che non mi interessano. Fortunatamente posso grezzamente andare poi a sbiancare i totali che non voglio, così, tanto per complicarmi la vita.

months.loc['Total'] = months.sum(numeric_only=True, axis=0)

# Colonne di cui voglio mostrare il totale
columns_to_sum = []
for task in tasks:
    columns_to_sum.append(task['activity'])    
    
# Colonne da sbiancare (tutte quelle che non sono nella lista di prima)
columns_to_blank = []
for column in list(months.columns):
    if column not in columns_to_sum:
        columns_to_blank.append(column)        
for column in columns_to_blank:
    months.loc['Total', column] = ''

Disegnare il Gantt

A questo punto per rendere tutto più chiaro possiamo disegnare il nostro Gantt. Problema: per disegnare il grafico mi occorre stabilire delle date (approssimative) di inizio e fine di ciascun task, mentre ora ho solo il numero di giorni occupati. Devo fare un pò di ragionamenti.

Per cominciare, posso calcolare la frazione di mese che un task occupa: se in un mese ho 100 giornate disponibili, un task che in quel mese occupa 10 giorni va a riempire un decimo del mese. A questo punto, usando la funzione monthrange della libreria calendar, posso calcolare il numero di giorni contenuti in quel mese e fare la proporzione: il decimo di mese che ho calcolato prima, se un mese è di 28 giorni, vale circa 2,8 giorni. Naturalmente poi questi calcoli saranno tutti approssimativi, ma non importa.

Il mio obiettivo è costruire una lista di oggetti, uno per task. Ciascuno di questi oggetti deve contenere il nome del task, la data di inizio e la data di fine. Facciamo un bel loop sulla lista dei task, per ciascun task isoliamo dalla lista costruita in precedenza tutti i mesi che contengono attività per quel task, e di questa lista prendiamo il primo elemento (mese di inizio) e l'ultimo (mese di conclusione, che potrebbe anche coincidere col mese di inizio). Recuperiamo entrambi i mesi come oggetto datetime, e per ciascuno calcoliamo anche il numero di giorni contenuti.

dicts = []

for index, task in enumerate(tasks):

    records = months.loc[months[task['activity']] != 0]
    records = records.loc[~records.index.isin(['Total'])]

    if (records.empty):
        continue
        
    starting_month = datetime.datetime.strptime(records.iloc[0]['month'], '%Y-%m').date()
    starting_month_days = monthrange(starting_month.year, starting_month.month)[1]
    
    ending_month = datetime.datetime.strptime(records.iloc[-1]['month'], '%Y-%m').date()
    ending_month_days = monthrange(ending_month.year, ending_month.month)[1]

Per calcolare la data di inizio dobbiamo estrapolare i giorni occupati da eventuali task precedenti che hanno occupato giorni in quel mese, e poi riproporzionare sul numero di giorni effettivi del mese. Un bel +1 e abbiamo il giorno (approssimativo) di inizio del task nel mese.

    # Giorni occupati nel primo mese da attività precedenti
    
    preceding_days_in_month = sum([records.iloc[0][activity] for activity in [preceding_task['activity'] for preceding_task in tasks[0:index]] ])
    
    if (preceding_days_in_month == 0):
        starting_day = 1
    else:
        starting_day = int(starting_month_days * preceding_days_in_month / records.iloc[0]['days_avail_tot']) + 1
        
    starting_month = starting_month.replace(day=starting_day)

Per calcolare la data di fine procediamo a ritroso. In questo caso dobbiamo considerare i giorni occupati nel mese da task successivi, ed eventuali giorni rimasti inutilizzati (la colonna days_avail), il tutto poi sempre riproporzionato ai giorni da calendario del mese contro i giorni calcolati da FTE.

    # Giorni occupati nell'ultimo mese da attività successive
    
    following_days_in_month = sum([records.iloc[-1][activity] for activity in [preceding_task['activity'] for preceding_task in tasks[index+1:]] ])
    
    # Eventuali giorni in avanzo se mese non completamente occupato
    following_days_in_month += records.iloc[-1]['days_avail']
    
    if (following_days_in_month == 0):
        days_after = 0
    else:
        days_after = int(ending_month_days * following_days_in_month / records.iloc[-1]['days_avail_tot'])
        
    ending_day = ending_month_days - days_after
      
    ending_month = ending_month.replace(day=ending_day)

A questo punto aggiungiamo i dati di questo task al nostro dizionario di date, e chiudiamo il loop.

    dicts.append(dict(Task=task['activity'], Start=starting_month, Finish=ending_month))

Andiamo a stampare il risultato, e sarà qualcosa del genere:

[{'Task': '1', 'Start': datetime.date(2023, 9, 1), 'Finish': datetime.date(2023, 11, 9)}, {'Task': '2', 'Start': datetime.date(2023, 11, 10), 'Finish': datetime.date(2023, 12, 31)}, {'Task': '3', 'Start': datetime.date(2023, 12, 31), 'Finish': datetime.date(2024, 1, 15)}, {'Task': '4', 'Start': datetime.date(2024, 1, 15), 'Finish': datetime.date(2024, 2, 18)}, {'Task': '5', 'Start': datetime.date(2024, 2, 18), 'Finish': datetime.date(2024, 3, 21)}, {'Task': '6', 'Start': datetime.date(2024, 3, 21), 'Finish': datetime.date(2024, 4, 3)}, {'Task': '8', 'Start': datetime.date(2024, 4, 3), 'Finish': datetime.date(2024, 4, 21)}]

Non ci resta altro da fare che dare questo dizionario in pasto a plotly.

fig = px.timeline(dicts, x_start="Start", x_end="Finish", y="Task")
fig.update_yaxes(autorange="reversed") 
fig.show()

E voilà!

Alla prossima!

Perchè c'è un numero di task che posso gestire in un progetto prima di iniziare a maledire GSheet (e il corrispettivo su Teams). Quel numero è indicativamente compreso tra 9 e 11. Ed è arrivato. Ed è passato oltre. Ampiamente.

Redmine ha un sacco di funzionalità molto interessanti con cui sto sperimentando ultimamente, tra cui diversi tracker personalizzabili, gantt, news, wiki, forum, campi custom di diverse tipologie e per tutte le esigenze, una matrice di permessi ESTREMAMENTE flessibile, ottimo sistema di filtraggio/ricerca con query custom salvabili, notifiche via email e mille altre ancora, compresa una comoda api per caricamento/update delle issues a partire dai suddetti maledetti excel di cui si parlava poco fa.

Usando Docker (e docker-compose) è possibile tirare su una installazione di Redmine (e PostgreSQL) in un attimo, usando l'immagine ufficiale.

Un esempio di docker-compose.yml è più o meno così:

version: '3.3'

services:

   postgres:
     image: postgres:10
     volumes:
       - ./storage/postgresql-data:/var/lib/postgresql/data
     environment:
       POSTGRES_PASSWORD: "my_postgres_password"
       POSTGRES_DB: "redmine"
       PGDATA: "/var/lib/postgresql/data"
     restart: always

   redmine:
     image: redmine:5
     ports:
       - 2000:3000
     volumes:
       - ./storage/docker_redmine-plugins:/usr/src/redmine/plugins
       - ./storage/docker_redmine-themes:/usr/src/redmine/public/themes
       - ./storage/docker_redmine-data:/usr/src/redmine/files
       - type: bind
         source: ./storage/configuration.yml
         target: /usr/src/redmine/config/configuration.yml
     environment:
       REDMINE_DB_POSTGRES: "postgres"
       REDMINE_DB_USERNAME: "postgres"
       REDMINE_DB_PASSWORD: "my_postgres_password"
       REDMINE_DB_DATABASE: "redmine"
       REDMINE_SECRET_KEY_BASE: "secret_key_base"
     restart: always

La prima parte descrive il database postgres. Al primo avvio viene inizializzato con la password amministrativa e con il nome db specificati. La seconda parte è il server Redmine vero e proprio, corredato delle informazioni necessarie a collegarsi al database di cui sopra.

Come si vede sono stati esposti nel filesystem host una serie di volumi, tutti contenuti nella directory "storage". A parte quelli relativi ai dati (sia di redmine che di postgres) ho esposto anche le cartelle "plugins" e "themes" di Redmine, in cui posso copiare temi e plugin che saranno visibili dal prossimo riavvio.

A questo punto basta un:

docker-compose up -d

..e sulla porta 2000 abbiamo già la nostra installazione pronta per fare esperimenti.

HTTPS con Nginx

Già che ci siamo, possiamo usare il proxy Nginx per esporre il sito in https dal nostro server. Basta avere a disposizione la coppia di chiavi ssl valide per il proprio dominio (facili da ottenere e gratuite con LetsEncrypt), e aggiungere questa configurazione:

server{
        listen 6666 ssl;
        server_name my_beautiful_site.it 
        ssl_certificate /cert_path/fullchain.pem;
        ssl_certificate_key /cert_path/privkey.pem;
        location / {
                proxy_pass http://localhost:2000/;
        }
}

In questa configurazione stiamo esponendo la porta 2000 (quella che abbiamo aperto sul nostro container Redmine) sulla porta 6666 del nostro server, attraverso la connessione https con certificato. In questo caso naturalmente vogliamo anche assicurarci che la porta 9090 sia esposta mentre la 2000 no, ad esempio usando UFW (Uncomplicated FireWall). Per esporre la 6666 basta usare questi comandi:

ufw allow 6666
ufw reload

Bloccare la 2000 è meno immediato. In teoria UFW di default blocca qualunque porta che non sia esplicitamente esposta, ma Docker all'avvio di un container modifica per conto suo iptables (il firewall a basso livello di Linux), vanificando la protezione. La soluzione è esplicitare a Docker che la porta 2000 è accessibile solo dalla macchina locale, modificando la riga del docker-compose:

     ports:
       - 2000:3000

...così:

     ports:
       - 127.0.0.1:2000:3000

Adesso la porta 2000 non è più accessibile dall'esterno.

Configurazione email

Redmine supporta l'invio di email di notifica configurabili attraverso un server smtp. Configurare un server smtp proprio è divertente ma verrà subito bloccato per sospetto spam da qualunque altro server del pianeta, quindi conviene affidarsi a qualche servizio più professionale.

Nel mio caso ho voluto sperimentare con MailerSend, che offre un free-tier da 3000 email al mese che sono più che sufficienti per i miei esperimenti. Per accedere a questo servizio è necessario essere titolari di un dominio web, di cui si dovrà dimostrare il possesso modificando alcuni parametri DNS (accessibili dal pannello di controllo del servizio su cui si è registrato il suddetto dominio). La configurazione iniziale dell'account è un tantino macchinosa e non è un argomento particolarmente universale, quindi passerei oltre. Una volta superato l'ostacolo abbiamo a disposizione le credenziali per inviare mail dal nostro dominio attraverso il loro server SMTP.

Per configurare Redmine, dobbiamo predisporre dentro il container un file di configurazione denominato "config.yml", nel percorso /usr/src/redmine/config/.

Per assicurarci che il file persista ai riavvii del container, lo creiamo nel nostro host, ad esempio dentro la cartella "storage" che abbiamo predisposto in precedenza.

production:
  delivery_method: :smtp
  smtp_settings:
    address: [smtp server url]
    port: [smtp server port]
    domain: [miodominio.it]
    authentication: :login
    user_name: [smtp username]
    password: [smtp password]

..e poi creiamo il collegamento tra il file esterno e il percorso all'interno del container aggiungendo queste righe al nostro docker-compose, sotto la sezione "volumes":

       - type: bind
         source: ./storage/configuration.yml
         target: /usr/src/redmine/config/configuration.yml

A questo punto possiamo stoppare il nostro container e riavviarlo (prima di riavviarlo usiamo il comando "rm" per fare pulizia, non sarebbe necessario dopo il "down" ma male non fa, così siamo certi di partire da un nuovo container pulito).

docker-compose down
docker-compose rm -v
docker-compose up -d

Per assicurarci che la configurazione sia stata accettata da Redmine possiamo andare sotto il menù Administration->Settings->Email notifications, se NON vediamo un messaggio di errore vuol dire che finora tutto è andato per il verso giusto.

Si configura un indirizzo (qualunque, anche inesistente) di provenienza per le email seguendo le regole del servizio SMTP; nel caso di MailerSend è obbligatorio che l'indirizzo sia nel dominio con cui è stato configurato l'account. E si preme il pulsante "Send a test email" in basso a destra. Salvo sorprese dovremmo essere arrivati a destinazione.

Successo!

Spoiler della prossima puntata

In questo esperimento proverò ad accedere alla famosa Launch Library, una API che permette di recuperare informazioni su lanci spaziali. La libreria è a pagamento (eccetto un limite free di 15 chiamate al giorno), ma è disponibile un endpoint di test (https://lldev.thespacedevs.com) con dati non aggiornati ma senza limiti di chiamate. La documentazione è qui.

Cominciamo.

Per cominciare creiamo una classe nel nostro ambiente ABAP Cloud che erediti l'interfaccia IF_OO_ADT_CLASSRUN. Questa interfaccia richiede l'implementazione di un metodo, e questo metodo può poi essere chiamato semplicemente premendo F9 dalla schermata di Eclipse; è previsto anche un metodo out->write che consente di stampare messaggi sulla console.

CLASS zmp_space DEFINITION
  PUBLIC
  FINAL
  CREATE PUBLIC .
  PUBLIC SECTION.
    INTERFACES: if_oo_adt_classrun.
  PROTECTED SECTION.
  PRIVATE SECTION.
ENDCLASS.

CLASS zmp_space IMPLEMENTATION.
  METHOD if_oo_adt_classrun~main.
  ENDMETHOD.
ENDCLASS.

La lettura di un endpoint passa attraverso alcuni step:

• Predisposizione variabili (che è più elegante che dichiararle inline, a quanto dicono).

    DATA: lo_destination   TYPE REF TO if_http_destination,
          lo_client        TYPE REF TO if_web_http_client,
          lo_http_resp     TYPE REF TO if_web_http_response,
          lv_response_json TYPE string,
          lv_response_code TYPE i,
          cx               TYPE REF TO cx_root.

• Creazione destinazione. Nel nostro caso la creiamo a partire da un URL fisso, ma il metodo consente di usare anche destinations o communication agreements creati nella BTP con autenticazione eccetera (ovviamente NON disponibili nella trial :-| ).

lo_destination = cl_http_destination_provider=>create_by_url( 'https://lldev.thespacedevs.com/2.2.0/launch/?limit=10' ).

• Creazione dell'istanza client a partire dalla destinazione.

lo_client = cl_web_http_client_manager=>create_by_http_destination( lo_destination ).

• Esecuzione della chiamata (passando il metodo da usare, nel nostro caso GET).

lo_http_resp = lo_client->execute( if_web_http_client=>get ).

• Estrazione dell'esito HTTP e del testo contenuto nella risposta.

lv_response_code = lo_http_resp->get_status(  )-code.
lv_response_json = lo_http_resp->get_text(  ).

• Chiusura del client.

lo_client->close(  ).

• Eventuale verifica del buon esito della richiesta (codice 200).

IF ( lv_response_code NE 200 ).
  out->write( |Wrong response: { lv_response_code }| ).
  EXIT.
ENDIF.

• ...il tutto in un blocco try..catch che non fa mai male.

Il codice completo ha più o meno questo aspetto.

    DATA: lo_destination   TYPE REF TO if_http_destination,
          lo_client        TYPE REF TO if_web_http_client,
          lo_http_resp     TYPE REF TO if_web_http_response,
          lv_response_json TYPE string,
          lv_response_code TYPE i,
          cx               TYPE REF TO cx_root.

    TRY.

        lo_destination = cl_http_destination_provider=>create_by_url( 'https://lldev.thespacedevs.com/2.2.0/launch/?limit=10' ).
        lo_client = cl_web_http_client_manager=>create_by_http_destination( lo_destination ).
        lo_http_resp = lo_client->execute( if_web_http_client=>get ).
        lv_response_code = lo_http_resp->get_status(  )-code.
        lv_response_json = lo_http_resp->get_text(  ).
        lo_client->close(  ).

      CATCH cx_root INTO cx.
        out->write( cx->get_longtext(  ) ).

    ENDTRY.

    IF ( lv_response_code NE 200 ).
      out->write( |Wrong response: { lv_response_code }| ).
      EXIT.
    ENDIF.

Se le cose sono andate per il verso giusto adesso nella variabile lv_response_json abbiamo il contenuto della risposta in formato json, che dobbiamo andare ad esaminare. Ha un aspetto del genere:

{
    "count": 6874,
    "next": "https://ll.thespacedevs.com/2.2.0/launch/?limit=10&offset=10",
    "previous": null,
    "results": [
        {
            "id": "e3df2ecd-c239-472f-95e4-2b89b4f75800",
            "url": "https://ll.thespacedevs.com/2.2.0/launch/e3df2ecd-c239-472f-95e4-2b89b4f75800/",
            "slug": "sputnik-8k74ps-sputnik-1",
            "name": "Sputnik 8K74PS | Sputnik 1",
            "status": {
                "id": 3,
                "name": "Launch Successful",
                "abbrev": "Success",
                "description": "The launch vehicle successfully inserted its payload(s) into the target orbit(s)."
            },
            "last_updated": "2023-01-21T01:14:08Z",
            "net": "1957-10-04T19:28:34Z",
            "window_end": "1957-10-04T19:28:34Z",
            "window_start": "1957-10-04T19:28:34Z",
            "probability": null,
            "holdreason": null,
            "failreason": null,
            "hashtag": null,
            "launch_service_provider": {
                "id": 66,
                "url": "https://ll.thespacedevs.com/2.2.0/agencies/66/",
                "name": "Soviet Space Program",
                "type": "Government"
            },
            "rocket": {
                "id": 3003,
                "configuration": {
                    "id": 468,
                    "url": "https://ll.thespacedevs.com/2.2.0/config/launcher/468/",
                    "name": "Sputnik 8K74PS",
                    "family": "Sputnik",
                    "full_name": "Sputnik 8K74PS",
                    "variant": "8K74PS"
                }
            },
            "mission": {
                "id": 1430,
                "name": "Sputnik 1",
                "description": "First artificial satellite consisting of a 58 cm pressurized aluminium shell containing two 1 W transmitters for a total mass of 83.6 kg.",
                "launch_designator": null,
                
                .....

Come si vede, la risposta contiene un array "results" che contiene i singoli lanci. Di ogni istanza di lancio ci interessa l'id, il "net" (Not Earlier Than, che in caso di lanci già avvenuti immagino rappresenti il timestamp dell'effettuazione) e il nome "name". Inoltre ogni lancio contiene un oggetto "mission", che a sua volta contiene un "description" con la descrizione della missione. Nel nostro esempio semplificato ci accontentiamo di estrarre queste informazioni.

Per prima cosa dobbiamo costruire una struttura di tipi adatta a contenere queste informazioni. Quindi un tipo che rappresenta la missione (con una variabile "description"), un tipo che rappresenta il lancio (contenente "id", "net", "name" e la struttura che abbiamo costruito prima sotto il nome "mission"). Infine un tipo che rappresenta la risposta complessiva, con all'interno una tabella di "results" che rappresenta l'array nel json. Infine definiamo una variabile lv_result costruita su questo tipo, per contenere la nostra risposta una volta parsata.

Una cosa del genere:

    TYPES:

      BEGIN OF ty_mission,
        description TYPE string,
      END OF ty_mission,

      BEGIN OF ty_launch,
        id      TYPE c LENGTH 40,
        name    TYPE string,
        net     TYPE string,
        mission TYPE ty_mission,
      END OF ty_launch,

      BEGIN OF ty_launch_response,
        count    TYPE string,
        results  TYPE SORTED TABLE OF ty_launch WITH UNIQUE KEY id, 
      END OF ty_launch_response.

    DATA: lv_result TYPE ty_launch_response.

A questo punto non ci resta che utilizzare il magico metodo "/ui2/cl_json=>deserialize" per trasformare il JSON in una struttura abap:

    /ui2/cl_json=>deserialize(
      EXPORTING
         json             = lv_response_json
      CHANGING
        data             = lv_result
    ).

Dopo avere attivato il codice (Ctrl+F3), possiamo mettere un punto di debug a valle del parsing (doppio click sulla sinistra del codice in Eclipse, apparirà un punto blu) e vedere cosa succede quando eseguiamo il codice in modalità terminale con F9. Tip: per fare esperimenti al volo si può aggiungere una istruzione inutile a valle del punto che ci interessa e mettere il punto di debug su quella.

Come si vede i dati ci sono tutti. Vogliamo stamparli a console?

    LOOP AT lv_result-results INTO DATA(lv_item).
      out->write( |{ lv_item-net WIDTH = 22 ALIGN = LEFT } { lv_item-name WIDTH = 70 ALIGN = LEFT PAD = ' ' } { lv_item-mission-description }| ).
    ENDLOOP.

2022-05-05T02:38:00Z   Long March 2D | Jilin-1 Wideband-01C & High Resolution 03D-27 to 33    Earth observation satellites for the Jilin-1 commercial Earth observation satellites constellation.      
2022-04-29T19:55:22Z   Angara 1.2 | Kosmos 2555 (MKA-R)                                       Russian military radar satellite.  
2022-05-09T17:56:30Z   Long March 7  | Tianzhou-4                                             Third cargo delivery mission to the Chinese large modular space station.  
2022-05-06T09:42:00Z   Falcon 9 Block 5 | Starlink Group 4-17                                 A batch of 53 satellites for Starlink mega-constellation - SpaceX's project for space-based Internet communication system.  
2022-05-02T22:49:52Z   Electron | There and Back Again                                        Commercial rideshare mission including payloads for Alba Orbital, Astrix Astronautics, Aurora Propulsion Technologies, E-Space, Spaceflight Inc, Swarm Technologies and UNSEENLABS.  
2022-04-29T21:27:10Z   Falcon 9 Block 5 | Starlink Group 4-16                                 A batch of 53 satellites for Starlink mega-constellation - SpaceX's project for space-based Internet communication system.  
2022-05-13T07:09:00Z   Hyperbola-1 | Jilin-1 Mofang-01A(R)                                    New generation experimental Earth imaging satellite for the Jilin-1 constellation.

Voilà!

Bonus: e se volessimo salvare in una tabella sul db queste informazioni? Possiamo creare una tabella custom con i campi che ci interessano (i campi di testo libero sono CLOB, identificati come abap.string(0))...

@EndUserText.label : 'ZMP_TBL_LAUNCHES'
@AbapCatalog.enhancement.category : #NOT_EXTENSIBLE
@AbapCatalog.tableCategory : #TRANSPARENT
@AbapCatalog.deliveryClass : #A
@AbapCatalog.dataMaintenance : #RESTRICTED
define table zmp_tbl_launches {

  key client    : abap.clnt not null;
  key id        : abap.char(40) not null;
  name          : abap.string(0);
  net           : abap.string(0);
  description   : abap.string(0);

}

..e poi copiare il contenuto facendo un loop nei results. Per ciascuna iterazione copiamo i campi in una work area (una struttura costruita usando la tabella come modello) e usiamo il comando MODIFY, che crea la riga se non esiste e la aggiorna se esiste. Il controllo dell'esistenza è fatto sulla chiave della tabella (nel nostro caso id, oltre al solito client).

    DATA: wa_launch TYPE zmp_tbl_launches.

    LOOP AT lv_result-results INTO DATA(lv_launch_temp).

      CLEAR wa_launch.
      
      MOVE-CORRESPONDING lv_launch_temp TO wa_launch.

      wa_launch-description = lv_launch_temp-mission-description.

      MODIFY zmp_tbl_launches FROM @wa_launch.

    ENDLOOP.

Nell'esempio sopra abbiamo risparmiato un pò di fatica facendo un MOVE-CORRESPONDING, che copia i campi con nomi identici. Naturalmente non vale per "description", che si trova in una struttura all'interno di una colonna.

Dopo una esecuzione del programma la tabella contiene le informazioni.

Altro bonus: ABAP ha un timestamp standard strutturato come YYYYMMDDhhmmss, che è ovviamente diverso da quello restituito dall'API. Se vogliamo registrare il timestamp in un formato standard, per esempio per poter effettuare ricerche in range o ordinamenti, dobbiamo maltrattare la stringa restituita con un pò di string functions. Grezzamente farei una cosa del genere (sicuramente c'è un modo più elegante).

Aggiungiamo una colonna net_timestamp alla nostra tabella, con il tipo timestamp:

@EndUserText.label : 'ZMP_TBL_LAUNCHES'
@AbapCatalog.enhancement.category : #NOT_EXTENSIBLE
@AbapCatalog.tableCategory : #TRANSPARENT
@AbapCatalog.deliveryClass : #A
@AbapCatalog.dataMaintenance : #RESTRICTED
define table zmp_tbl_launches {

  key client    : abap.clnt not null;
  key id        : abap.char(40) not null;
  name          : abap.string(0);
  net           : abap.string(0);
  net_timestamp : timestamp;
  description   : abap.string(0);

}

Modifichiamo il loop di cui sopra per aggiungere la creazione del timestamp. Per creare il timestamp preleviamo le due parti relative a data e ora, e da ciascuna rimuoviamo i caratteri separatori. Concateniamo il risultato ed abbiamo il nostro dato.

Originale: 1958-02-01T03:47:56Z

Data: 1958-02-01 -> 19580201
Ora: 03:47:56Z -> 034756

Concatenando: 19580201034756

L'estrazione delle sottostringhe si fa con la tradizionale notazione STRINGA+OFFSET(LUNGHEZZA), e la sostituzione con la tradizionale REPLACE ALL OCCURRENCES. Si, esistono moderne funzioni equivalenti che fanno molto meno anni 80, ma vogliamo mettere la nostalgia del cobol che nasce sfogliando questi programmi?

    DATA: wa_launch TYPE zmp_tbl_launches.
    DATA: lv_tmp_date TYPE c LENGTH 10,
          lv_tmp_time TYPE c LENGTH 8,
          lv_net_ts type timestamp.

    DELETE FROM zmp_tbl_launches.
    LOOP AT lv_result-results INTO DATA(lv_launch_temp).

      CLEAR wa_launch.
      MOVE-CORRESPONDING lv_launch_temp TO wa_launch.

      wa_launch-description = lv_launch_temp-mission-description.

      lv_tmp_date = lv_launch_temp-net(10).
      REPLACE ALL OCCURRENCES OF '-' IN lv_tmp_date WITH ''.

      lv_tmp_time = lv_launch_temp-net+11(8).
      REPLACE ALL OCCURRENCES OF ':' IN lv_tmp_time WITH ''.

      lv_net_ts = |{ lv_tmp_date }{ lv_tmp_time }|.
      wa_launch-net_timestamp = lv_net_ts.

      MODIFY zmp_tbl_launches FROM @wa_launch.

    ENDLOOP.

Ed ecco il risultato:

Alla prossima!

Un encoder rotativo è sostanzialmente una manopola che trasmette al microcontrollore degli impulsi che descrivono la sua rotazione a passi discreti (un "click" alla volta). Rispetto ad un potenziometro ha il vantaggio di consentire la rotazione infinita in entrambe le direzioni, oltre al discorso dei passi discreti citato prima. E, come valore aggiunto, spesso gli encoder contengono anche un pulsante (pressione verticale sul perno).

L'obiettivo non mi è ancora del tutto chiaro, sto sperimentando. Un possibile utilizzo molto interessante è per lo scrolling: anziché premere le frecce su&giù per scorrere lungo un listato posso girare la manopola, e dietro le quinte arduino trasmette al computer l'equivalente delle frecce direzionali. Altri possibili utilizzi sono le funzioni multimediali (volume, più pausa/play sul pulsante).

A livello pratico, un encoder presenta due uscite (escludendo il pulsante).

Durante la rotazione, ad ogni click queste due uscite vengono messe a GND per alcuni millisecondi e poi riportate a flottanti (devono essere configurati i pullup su Arduino per fissare a VCC il valore a riposo). I segnali generati dai due pin sono sfasati, e la fase dipende dal verso di rotazione. Analizzando quindi l'evoluzione dei due segnali si può identificare l'effettuazione di un "click" e la sua direzione.

Fortunatamente non saremo costretti a gestire tutta la questione via software perché c'è già una comoda libreria per Arduino che gestisce l'interfaccia per noi: EncoderButton. La possiamo installare dal package manager di Arduino.

Di seguito un esempio di codice. Nella parte iniziale del programma importiamo la libreria, prepariamo le costanti usate per indicare i pin utilizzati e inizializziamo l'oggetto EncoderButton.

#include <EncoderButton.h>

// Encoder inputs
const byte ENC_A = 0;
const byte ENC_B = 1;
const byte ENC_BUTTON = 21;
EncoderButton eb1(ENC_A, ENC_B, ENC_BUTTON);
volatile int scrollSpeed;

Prima di proseguire predisponiamo i metodi di callback dei due eventi generati dal componente (rotazione e pressione pulsante). In questo esempio per ciascuna rotazione voglio inviare un certo numero di pressioni di freccia su o giù (a seconda del verso di rotazione) usando la libreria Keyboard già usata nella scorsa puntata, e alla pressione del pulsante voglio cambiare la velocità di scroll (ovvero il numero di pressioni di una freccia per ciascun "click" dell'encoder).

void onEb1Encoder(EncoderButton& eb) {
  if (eb.increment() > 0){
    for (int i = 0; i < scrollSpeed; i++){
      Keyboard.press(KEY_UP_ARROW);
      Keyboard.release(KEY_UP_ARROW);
    }
  }
  else {
    for (int i = 0; i < scrollSpeed; i++){
      Keyboard.press(KEY_DOWN_ARROW);
      Keyboard.release(KEY_DOWN_ARROW);
    }
  }
}

void onEncoderButtonClick(EncoderButton& eb){
  if (scrollSpeed == 1){
    scrollSpeed = 5;
  }
  else {
    scrollSpeed = 1;
  }
}

Nel setup configuriamo i pin come pullup e associamo le routine di callback al componente.

void setup(){
  ...
  pinMode(ENC_BUTTON, INPUT_PULLUP);
  pinMode(ENC_A, INPUT_PULLUP);
  pinMode(ENC_B, INPUT_PULLUP);  
  eb1.setEncoderHandler(onEb1Encoder);
  eb1.setClickHandler(onEncoderButtonClick);
  scrollSpeed = 1;
  ...
}

Nel loop principale dobbiamo solo chiamare un metodo per consentire l'aggiornamento continuo dello stato del componente e la chiamata agli eventuali eventi:

void loop(){
  ...
  eb1.update();
  ...
}

A questo punto non ci resta che collegare l'encoder all'Arduino aggiungendo 5 fili al groviglio, e tutto dovrebbe funzionare.

Alla prossima!

E ogni volta che si accede a un sistema bisogna cercarlo nella lista, aprirlo, poi andare a cercare le credenziali nel proprio password manager, poi copiaincollare le credenziali, verificare di avere impostato il giusto codice client e la giusta lingua, e poi finalmente ci siamo.

Salvo che non ho sbagliato a copiare la password e devo ricominciare da capo.

Scomodo.

Fortunatamente l'installazione standard della SAP GUI su Windows si porta appresso un misconosciuto programmino, "sapshcut", che consente di aprire una connessione direttamente con un comando da terminale:

start sapshcut -system="ABC" -desc="DESCRIZIONE" -client=123 -user="XXXX" -pw="XXXXX" -maxgui -language="EN"

E' sufficiente scrivere il nome della connessione così come è stata salvata nel SAP Logon (vedi sotto), le tre lettere del nome sistema, il client, le credenziali e la lingua desiderata per il login. L'opzione MAXGUI è facoltativa, serve ad aprire la GUI a schermo pieno.

E' già più comodo, ma non risolve la situazione. Dovrei tenermi una lista di comandi da qualche parte, e (peggio del peggio) ciascuno di questi dovrebbe contenere le credenziali in chiaro.

Non bellissimo.

Per fortuna viene in nostro aiuto Keepass 2,  un comodo password manager che lavora esclusivamente in locale (no cloud), open source e gratuito. Possiamo scriverci dentro le nostre credenziali, e proteggerle in un file criptato in locale con un'unica password globale. Le possiamo mettere in ordine in cartelle (magari per progetto) e gli possiamo dare una descrizione comoda. Possiamo perfino assegnare dei colori diversi (magari per distinguere dev da prod) e icone personalizzate.

Un'altra funzione molto comoda è la possibilità di salvare, per ciascuna credenziale, un url. E' possibile poi selezionare la voce dalla lista, premere Ctrl+U (o fare doppio click sulla colonna Url) per aprire direttamente l'indirizzo, tipicamente nel browser.

E' inoltre possibile usare un url del tipo "cmd://", per eseguire un qualunque comando. Possiamo quindi inserire nelle entry relative ai sistemi SAP un url per richiamare sapshcut, in questa maniera:

cmd://sapshcut -system={s:system} -desc="{s:desc}" -client={s:client} -user="{USERNAME}" -pw="{PASSWORD}" -maxgui -language="EN"

I campi tra parentesi graffe sono variabili interpretate da Keepass. USERNAME e PASSWORD corrispondono, ovviamente, alle credenziali inserite. Le altre, identificate come S:<nome>, sono impostate per ciascuna entry nel tab "Advanced":

Voilà. Possiamo selezionare una voce e premere Ctrl+U, e come per magia abbiamo la sessione aperta.

Alla prossima!

Il problema è che questi tcode sono tanti e hanno nomi assolutamente spassosi come me22n, se38, we05, se22, /opt/vim_wp eccetera. So bene che ricordarsi a memoria 800 codici è un punto di orgoglio importante per qualunque analista SAP, ma non sarebbe bello per quelli come me che non si ricordano cosa hanno mangiato a pranzo due ore prima avere un qualche programmino immediato da richiamare con il quale sia possibile cercare "idoc log" per ricordarsi della we05, o "manutenzione servizi" quando proprio "/iwfnd/maint_service" ce l'ho sulla punta della lingua ma non mi viene?

Del tipo:

Non mi ricordo come mostrare i log degli IDOC. Premo shift+F12 e mi appare la finestra di ricerca. Digito "idoc log" e nella lista mi appare in bella vista il codice WE05. Esclamo qualcosa del tipo "maccertoecchecca**olousoseicentovoltealgiorno"  facendo impensierire il mio vicino di scrivania (che pure ne ha viste di tutti i colori con me vicino), poi premo ESC e torno a lavorare.

Approfittando del fatto che avevo proprio voglia di fare qualche esperimento con TKinter, la libreria grafica nativa di Python, ho provato a realizzare qualcosa del genere.

Nel post che segue cerco di spiegare i singoli passaggi per la realizzazione dell'applicazione, cercando di seguire una specie di filo logico. Per ulteriori dettagli conviene sfogliare direttamente il codice disponibile qui: https://github.com/PicciMario/TCodeHelper.

Negli spezzoni di codice qui sotto, per facilitare la leggibilità, non mostro dettagli come la gestione degli errori o funzionalità meno interessanti. I vari "self" sono perchè nel codice completo tutto è dentro una classe, se riesco cerco di toglierli per rendere il codice più leggibile, ma può essermene scappato qualcuno. Non usate questo codice per cercare di farci qualcosa di utile, piuttosto guardate nel repository la versione completa.

Per prima cosa si deve creare una finestra Tkinter. Si importano un pò di librerie si chiama il costruttore Tk(). Già che ci siamo impostiamo una icona e il titolo.

window = tk.Tk()
window.title("TCode Helper - " + version)
window.geometry("400x400")

logo = Image.open(logo_filename)
app_icon = ImageTk.PhotoImage(logo)
window.wm_iconphoto(False, app_icon)

La parte più divertente in tkinter è come sempre la creazione dei componenti dell'interfaccia (e questa sotto è solo una piccola parte):

# Creazione componenti UI
small_info_image=logo.resize((12, 12))
small_info_image_tk = ImageTk.PhotoImage(small_info_image)
info_img = ttk.Button(window, image=small_info_image_tk, command=popup_about)
info_img.grid(row=0, column=1, sticky="nsew")

search_field = ttk.Entry(window, width=50)
[...]
search_field.bind("<KeyRelease>", _text_callback)
search_field.bind("<Tab>", focus_tree)

columns = ('code', 'descr')
tree = ttk.Treeview(window, columns=columns, show='headings')
[...]

tree.column("code", minwidth=0, width=100, stretch=tk.NO) 
[...]
tree.bind('<<TreeviewSelect>>', _selected_tcode)
tree.bind("<Tab>", focus_search)

descr_text = RichText(window, height=5, borderwidth=5, relief=tk.FLAT, wrap=tk.WORD)
[...]

E alla fine si mostra la finestra:

window.mainloop()

Come si vede ci sono diversi binding legati agli oggetti della UI. Per esempio, il campo di testo e la treeview hanno la pressione del tasto TAB collegati a metodi che effettuano l'uno il focus sull'altro; in questo modo è possibile passare rapidamente dal campo di ricerca alla lista con la pressione di un tasto. Nel caso di spostamento verso la lista si forza anche la selezione del primo elemento mostrato.

def focus_tree(self, event):
	if (tree.get_children()):
		child_id = tree.get_children()[0]
		tree.focus_set()
		tree.focus(child_id)
		tree.selection_set(child_id)
	return("break")

def focus_search(self, event):
	search_field.focus_set()
	search_field.selection_range(0, tk.END)
	return("break")

Infine, sulla lista si implementa un binding a una funzione che mostra nella casella in fondo il codice della transazione selezionata e la relativa descrizione (la casella è predisposta allo scopo di mostrare una descrizione estesa, ma non ho ancora avuto voglia di mettermi a scrivere un poema per ciascuna delle 80 transazioni nella lista che ho accumulato finora).

def _selected_tcode(self, event):

if (len(tree.selection()) > 0):

	selected_id = tree.selection()[0]
	selected_item = tree.item(selected_id)
		selected_tcode = next((x for x in self.tcodes if x['code'] == selected_item['values'][0]), "")

	descr_text.delete('1.0', tk.END)
	descr_text.insert("end", f"{selected_tcode['code']}\n", "bold")
	descr_text.insert("end", f"{selected_tcode['descr']}", "base")
	descr_text.insert("end", f"\n\nKeywords ({selected_tcode['score']}): {selected_tcode['keywords']}", "italic")

return("break")

Il binding più interessante è sul key release della casella di ricerca, che rigenera la lista dei codici trovati in base a quanto scritto e verrà descritto più avanti.

Prima di proseguire, abbiamo anche creato una manciata di binding legati direttamente alla finestra o globali.

Abbiamo creato un binding sulla chiusura della finestra. Quando la finestra viene chiusa (o quando premiamo ESC) non vogliamo che il programma termini, vogliamo solo che venga ridotto a icona nella tray bar di windows, e resti pronto per l'uso successivo. Per questa funzionalità usiamo la libreria "pystray". Nel menu contestuale dell'icona mettiamo due voci, una di default per mostrare la finestra e una per terminare l'applicazione.

window.protocol('WM_DELETE_WINDOW', withdraw_window)
window.bind('<Escape>', withdraw_window)

self.menu = (
	pystray.MenuItem('Mostra finestra', show_window, default=True),
	pystray.MenuItem('Termina applicazione', quit_window)
)
    
def withdraw_window():
	window.withdraw()
	icon = pystray.Icon("TCode Helper", logo, "TCode Helper", menu)

Il binding globale (quindi sempre attivo, anche mentre il programma non è visibile sullo schermo) serve a richiamare il programma in qualunque momento premento Shift+F12 (combinazione strategicamente scelta perchè, a quanto pare, non è catturata dai programmi che uso normalmente). Il metodo collegato elimina l'icona nella traybar e mostra la finestra, forzandola in primo piano e con il focus sulla casella di ricerca per poter iniziare a digitare immediatamente.

keyboard.add_hotkey('shift+F12', show_window)

def show_window(self):

	if (hasattr(self, 'icon')):
		self.icon.stop()

	window.withdraw()
	window.deiconify()
	window.lift()

	search_field.selection_range(0, tk.END)

	# Mette la finestra in primo piano, ma senza
	# lasciarla bloccata lì.
	window.attributes("-topmost", True)
	window.attributes("-topmost", False)

	window.focus_set()
	search_field.focus_set()	

Entrando nel vivo del programma, vediamo come all'avvio abbiamo caricato da un file JSON la lista dei codici.

with open(tcodes_filename, "r") as file:
	tcodes = json.load(file)

Per ogni TCODE è presente il tcode vero e proprio, la descrizione breve mostrata nell'interfaccia e una stringa di parole chiave. La ricerca viene effettuata su questa lista, che risulta più accurata perchè evita i match da parole presenti in ogni descrizione ("il", "la", "un", "modifica", "crea" eccetera) e consente di aggiungere più testo per ciascun codice senza obbligare a mostrarlo nella descrizione (per una transazione legata agli ordini di acquisto posso aggiungere parole chiave come "ordine", "acquisto", "oda", "purchase", "order" eccetera). La lista è fatta così:

[
	...
    {
        "code": "ME22N",
        "descr": "Modifica ordini di acquisto (OdA).",
        "keywords": "ordini acquisto OdA purchase order"
    },
    ...
]

(e al momento è un pò grezza, ci devo lavorare su e accetto volentieri pull request al riguardo...)

La funzione di ricerca, collegata al callback sulla scrittura nella casella di testo, segue questa logica: per ciascuna parola trovata nella ricerca, analizza la stringa delle parole chiave in ogni transazione e assegna un punteggio alla transazione stessa. Se trovo un match perfetto (quindi l'esatta parola cercata) assegno due punti alla transazione. Se trovo un match parziale un solo punto. Il match perfetto è individuato con una regexp, il match parziale con un semplice string find.

# Identifica parole chiave ricerca
keywords = [x for x in search.upper().split(' ') if len(x) > 1]

# Inizializza lista per punteggi ai tcodes
tcodes_points = [[x, 0] for x in self.tcodes]

# Calcola punteggi 
for keyword in keywords:
	for tcode in tcodes_points:

		pattern = keyword
		text = tcode[0]['keywords'].upper()

		if (re.search("(^| )" + pattern + "( |$)", text)):
			tcode[1] += 2
			print(pattern, tcode)
		elif tcode[0]['keywords'].upper().find(keyword) != -1:
			tcode[1] += 1

Alla fine mostro nell'albero i tcodes con almeno un punto, ordinati per punteggio decrescente.

# Ordina e ricostruisce lista tcodes con punteggio non nullo
tcodes_points.sort(key=lambda x: x[1], reverse=True)
for x in tcodes_points:
	x[0]['score'] = x[1] 
filtered_list = [x[0] for x in tcodes_points if x[1] > 0]

# Pulisce albero
for i in self.tree.get_children():
	self.tree.delete(i)

# Aggiunge record in albero
for item in filtered_list:
	self.tree.insert('', tk.END, values=(item['code'], item['descr']))

Il metodo è orribilmente poco efficiente, e richiede un mostruoso numero di check per ciascuna digitazione nella casella di ricerca, ma trattandosi di una lista di decine (al più centinaia) di codici al momento non vale la pena studiare ottimizzazioni esotiche, poichè il risultato è comunque immediato.

Bonus per chi è arrivato fino in fondo. Ho imparato a usare pyinstaller, una simpatica libreria python che consente di creare un programma eseguibile per windows (anche altre piattaforme, ma io ho solo windows) a partire da uno script python. Basta richiamarlo così:

pyinstaller -F --noconsole tcode_helper.py

Ho provveduto a rendere disponibile su github una release eseguibile del programma (a destra nella schermata di github, sotto "releases") se qualcuno ci vuole giocare senza doversi installare l'ambiente di sviluppo Python.

Alla prossima!

Requisiti

Per chiamare un modulo RFC da Python è necessario installare nel sistema la Netweawer RFC SDK. Questa libreria è scaricabile da qui, ma il download richiede un S-USER valido (no free trial) e che sia abilitato al download di risorse. Se il vostro S-USER non è abilitato (come accade di solito) dovete chiedere per piacere agli IT della vostra organizzazione.

Si installa e si prende nota della cartella di installazione.

Bisogna poi aggiungere la cartella "lib" della nostra installazione nel path di sistema. Su Windows, si apre il pannello di controllo, voce "Sistema e Sicurezza", voce "Sistema", "Impostazioni di sistema avanzate". Nel tab "Avanzate" si preme il pulsante "Variabili d'ambiente...". Nella parte bassa della finestra (Variabili di Sistema) si fa doppio click su "path", e nella finestra che si apre si aggiunge una riga che punta alla cartella di cui sopra.

Bisogna inoltre installare la libreria Python PYRFC, ad esempio con pip:

pip install pyrfc

A questo punto siamo pronti a cominciare. Usando la libreria pyrfc possiamo chiamare qualunque function module abilitato per la comunicazione RFC. Possiamo crearne uno noi, o possiamo usarne uno standard: nel nostro caso esiste già un modulo che permette di leggere il contenuto di una tabella SAP, e si chiama "RFC_READ_TABLE". Possiamo richiamarlo con questo codice:

from pyrfc import Connection

conn = Connection(
    ashost='xxx.xxx.xxx.xxx', 
    sysnr='00', 
    client='XXX', 
    user='xxxxx', 
    passwd='yyyyy'
)

table='MARA'
delimiter = '|'

response = conn.call(
    "RFC_READ_TABLE", 
    QUERY_TABLE=table, 
    DELIMITER=delimiter,
    FIELDS=[{'FIELDNAME':'MANDT'},{'FIELDNAME':'MATNR'}]
)

conn.close()

Nota: questo FM ha parecchie limitazioni, come ad esempio il fatto che ogni record restituito non può essere più lungo di 512 caratteri. In questo caso, visto che la MARA è una tabella con millemila colonne, abbiamo usato il parametro "FIELDS" per limitare le colonne lette.

A questo punto, nella variabile "response" troviamo un dizionario che contiene, tra le altre, le chiavi DATA e FIELDS.

La chiave FIELDS contiene l'elenco dei campi letti dalla tabella, con il tipo e la posizione all'interno della risposta. Ogni record della risposta, come vedremo dopo, è infatti costruito come stringa in cui i campi sono separati dal separatore specificato al momento della chiamata, e in FIELDS è presente per ciascun campo il carattere di inizio e la lunghezza.

print(response['FIELDS'])

[{'FIELDNAME': 'MANDT',
  'OFFSET': '000000',
  'LENGTH': '000003',
  'TYPE': 'C',
  'FIELDTEXT': 'Mandante'},
 {'FIELDNAME': 'MATNR',
  'OFFSET': '000004',
  'LENGTH': '000040',
  'TYPE': 'C',
  'FIELDTEXT': 'Codice materiale'}]

Nella chiave "DATA" sono invece presenti le righe lette:

print(response['DATA'])

[{'WA': '100|TG10'},
 {'WA': '100|TG11'},
 {'WA': '100|TG12'},
 {'WA': '100|TG13'},
 {'WA': '100|TG14'},
 {'WA': '100|FG129'},
 {'WA': '100|SM0001'},
 {'WA': '100|NS0002'},
 ....

A questo punto abbiamo in mano tutto quello che ci serve per gestire queste informazioni in Python. Ad esempio, potremmo usare le informazioni relative ai campi e alla loro lunghezza per trasformare le righe in dizionari:

data = []

for orig_record in [record['WA'] for record in response['DATA']]:

  parsed_record = {}
  
  for field in response['FIELDS']:
  
    parsed_record[field['FIELDNAME']] = orig_record[int(field['OFFSET']):int(field['OFFSET'])+int(field['LENGTH'])].strip()
    
    data.append(parsed_record)

Potremmo invece trasformare l'output direttamente in un dataframe Pandas, per facilitare successive analisi. Si può ottenere questo risultato con questo comodo snippet:

import pandas as pd

result = pd.DataFrame(
    [[x.strip() for x in response['DATA'][n]['WA'].split(delimiter)] for n in range(len(response['DATA']))],
    columns=[x['FIELDNAME'] for x in response['FIELDS']]
)

Questo il risultato:

Alla prossima!

Se il servizio è accessibile da browser, l'approuter si occupa di gestire tutte le fasi dell'autenticazione, compreso il rimando verso la pagina di login di SAP e l'invio del token al servizio. Ma se voglio richiamare il servizio senza passare dal browser, ad esempio usando uno script Python, devo occuparmi io di chiedere al server il token da utilizzare per effettuare le chiamate.

Lo standard OAuth 2.0 prevede diversi flussi di autenticazione. In questi esperimenti ne ho provati due, i più semplici: il Resource Owner Password Flow e il Client Credentials Flow.

Il Resource Owner Password Flow è utilizzato quando il client (ovvero chi vuole accedere al servizio) è sufficientemente fidato da poter avere accesso diretto alle credenziali dell'utente. Non è usati nei normali flussi autorizzativi app-app (ad esempio, se voglio autorizzare Facebook ad accedere alle mie foto su Google Drive, non voglio certo inserire in Facebook la mia password Google!), ma è accettabile se, per esempio, il client è uno script costruito su misura per un utilizzo specifico e in esecuzione in un ambiente privato.

In questo caso, per ottenere il token autorizzativo si effettua una richiesta di tipo "password" al server XSUAA. Bisogna fornire le credenziali dell'utente e le credenziali del client, così come registrate nel server XSUAA (client id e client server). Queste informazioni sono reperibili nel servizio XSUAA nella BTP (sezione "Instances and Subscriptions"), premendo il pulsante "Show Credentials".

A questo punto, nel nostro script Python possiamo fare questa richiesta al server di autenticazione:

print("Richiesta token con grant: PASSWORD")

token_req_payload = {
  'grant_type': 'password',
  'username': username,
  'password': password,
}

token_response = requests.post(
  auth_server_url + '/oauth/token',
  data = token_req_payload,  
  allow_redirects = False,
  auth = (client_id, client_secret)
)

tokens = json.loads(token_response.text)
access_token = tokens['access_token']

Se tutto è andato per il verso giusto, ora possiamo chiamare direttamente il nostro servizio (NON l'application router) usando il token:

test_api_url = "https://XXXXXXX.cfapps.us10-001.hana.ondemand.com/"
api_call_headers = {'Authorization': 'Bearer ' + access_token}
api_call_response = requests.get(test_api_url, headers=api_call_headers)

print(api_call_response.text)

La richiesta sarà gestita con le autorizzazioni dell'utente di cui abbiamo usato le credenziali.

Il Client Credentials Flow è diverso dal precedente poichè in questo caso non si utilizzano le credenziali di un utente ma solo le credenziali dell'applicazione. Questo flusso è infatti pensato per autenticare un servizio verso un altro servizio, senza dargli per esempio accesso diretto ai dati di un utente. La chiamata da effettuare è più semplice:

print("Richiesta token con grant: CLIENT_CREDENTIALS")

token_req_payload = {
  'grant_type': 'client_credentials'
}

token_response = requests.post(
  auth_server_url + '/oauth/token',
  data = token_req_payload, 
  allow_redirects = False,
  auth = (client_id, client_secret)
)

tokens = json.loads(token_response.text)
access_token = tokens['access_token']

Una volta ottenuto il token possiamo continuare come visto in precedenza.

Gestire permessi a livello di applicazione Python su BTP

Come visto in passato, la presenza del token non è necessaria per accedere all'applicazione, che comunque è accessibile sulla rete pubblica. Il tassello fondamentale per la sicurezza è che l'applicazione stessa, alla ricezione della richiesta, verifichi (utilizzando il server XSUAA) il token ricevuto per capire se è valido e di che tipo è, e se è legato o meno a un utente (o è un client credentials).

Una modalità semplice per effettuare questa verifica è prevedere nella nostra applicazione basata su Flask un metodo decorato con "@app.before_request". Questo metodo è eseguito prima di qualunque richiesta in entrata, ed è un buon posto per analizzare le credenziali e salvare le informazioni in una variabile globale accessibile agli altri metodi. Una cosa del genere:

import ...
from sap import xssec

# Global variables
SECURITY_CONTEXT = "security_context"
globals = {}

@app.before_request
def check_credentials():

  global globals

  auth_header = request.headers.get('Authorization')

  if not auth_header:
    return "Errore: nessun header autorizzativo!", 403

  try:
    auth_token = auth_header.split(" ")[1]
    globals[SECURITY_CONTEXT] = xssec.create_security_context(auth_token, uaa_service)
  except:
    return "Errore: token errato!", 403

Questo metodo ha questa caratteristica: se ritorna qualcosa, quel qualcosa viene restituito e termina immediatamente la chiamata in corso. Quindi, se troviamo dei problemi possiamo semplicemente restituire un 403 Unauthorized e tutto si ferma qui.

A questo punto, i nostri singoli endpoint possono analizzare l'oggetto globale e chiamarne metodi per verificare, per esempio, la presenza di uno scope o il nome utente (o l'assenza, nel caso di client credentials). Un esempio potrebbe essere una cosa del genere:

@app.route('/', methods=['GET'])
def info():

  global globals 

  isAuthorized = globals[SECURITY_CONTEXT].check_scope(f"{uaa_service['xsappname']}.split")
  grant_type = globals[SECURITY_CONTEXT].get_grant_type()
  logon_name = globals[SECURITY_CONTEXT].get_logon_name()

  text = (
    f"<h1>Barcode services up&running!</h1>"
    f"<ul>"
    f"<li>Split scope available: {isAuthorized}</li>"
    f"<li>Grant type: {grant_type}</li>"
    f"<li>Logon name: {logon_name}</li>"
    f"</ul>"
  )

  return(text)

Sarà poi l'applicazione a decidere cosa rendere disponibile all'esterno, ad esempio differenziando per grant type o per nome utente.

Alla prossima!