Automazione documentale per Word con la libreria docxTemplate

Anzitutto mi scuso per il ritardo nella pubblicazione di un nuovo articolo. Ho interrotto una serie di routine che mi garantivano continuità ed effortless.

Ma la sorte è stata propizia perché pubblico questo articolo nel mese giusto ovvero Automation April: Aprile il mese delle automazioni! 😄

Ciò detto credo e spero che questo articolo possa essere di utilità a molti di voi, quantomeno per introdurvi all’automazione documentale con Microsoft Word in modo relativamente semplice.

Credo infatti di aver trovato un modo per automatizzare la creazione di documenti: piuttosto facile, gratuito e che, addirittura, non vi richiede di utilizzare Word.

Quello che leggerete qui sotto è un articolo introduttivo che espone l’idea di base ma che non vi propone un metodo perfezionato in tutte le sue parti.

Questo perché, come saprà chi mi legge da tempo, io non uso i file DOCX per scrivere i miei atti e documenti ma Markdown e LaTeX.

Se ci fosse molto interesse (nel caso lasciate un commento qui sotto o mandatemi una email) potrei approfondire in futuri articoli casomai cercando di risolvere un caso concreto.

Ultima premessa è che questo metodo funziona sia su macOS che su iOS / iPadOS e, potenzialmente, anche su altri sistemi operativi (ma non ho fatto test / cercato soluzioni simili a quelle implementate da me).

Ringraziamenti e menzione d’onore

Questa “scoperta” non sarebbe stata possibile senza l’aiuto e le dritte dell’amico e collega Roberto Alma.

È infatti stato lui a spiegarmi le basi del sistema (le mie capacità di programmatore sono basilari) e mi ha permesso di sperimentare con suoi esempi.

Se siete interessarti ad un software per gestire il PCT e non solo vi suggerisco di provare il software di Cassazione.net che, oltre essere macOS compatibile, è amabilmente sviluppato da Roberto.

Bando alle ciance ed entriamo nel vivo dell’articolo!

1. La libreria docxTemplate

Anzitutto non spaventatevi se iniziamo a parlare di librerie Python (per chi non lo sapesse Python è un linguaggio di programmazione).

La cosa bella di una libreria (di qualsiasi linguaggio di programmazione) è che un’anima pia ha sviluppato una soluzione per semplificarci la vita e, nel nostro caso, la libreria docxTemplate ci permette di creare in pochissimo tempo dei file .DOCX automatizzati.

Come detto non è mia intenzione entrare troppo nel dettaglio perché, eventualmente, si potranno fare dei futuri approfondimenti. Il concetto che qui vi voglio passare è che utilizzando questa libreria ed un strumento di automazione come può essere Comandi Rapidi, a parte una “installazione” iniziale non dovrete sporcarvi le mani con il codice.

1.1 Come funziona docxTemplate

Qui trovate la documentazione ufficiale della libreria (in inglese ovviamente) ma di seguito cercherò di darvi le informazioni di base per poter poi lavorare autonomamente e creare il vostro template.

1.2 Creare un modello Word

Aprite un documento Word vuoto (ma potete farlo anche con un modello non automatizzato che avete già) e, dove volete inserire un segnaposto, ovvero una parola che verrà poi sostituita dall’automazione ad esempio il nome del vostro cliente, digitate {{ nomeCliente }}.

Questa è la dichiarazione della variabile di docxTemplate. Ciò significa che quando lanceremo lo script (di cui vi parlerò poco più avanti) al segnaposto che abbiamo appena inserito verrà sostituito il contenuto che decideremo noi.

Ora che avete capito il concetto di base (è semplice concedetemelo) potremo creare il modello che più ci piace … per questo semplice articolo faremo un esempio banale: l’intestazione di una lettera, con nome cognome ed indirizzo.

Segnalo, ma non lo tratteremo in questo articolo, che oltre ad inserire dei semplici segnaposto, è possibile strutturare anche documenti più complessi in cui se una circostanza è vera o falsa viene inserita una specifica porzione del testo; immaginate una clausola che può essere inserita in un contratto a determinate condizioni.
Questo sistema è chiamato condizionale e utilizza la funzione SE o _if_ in inglese. Se siete curiosi trovate spiegato nella documentazione della libreria come fare, io qui non esaminerò l’argomento ma ve lo segnalo per completezza ed anche per farvi capire le possibilità di questo sistema.

Bene, adesso fate i compiti e create il file .DOCX o, se siete pigri, scaricate quello che ho prodotto io con un modello di lettera di Pages (piccola nota: bisognerebbe sempre evitare di scaricare da internet file di questo genere, io non ho intenzioni malevole ma suggerisco sempre di evitare operazioni simili).

*Esempio di modello .docx creato in Pages*

1.3 Installare la libreria sul vostro Mac

Questa attività va fatta solo una volta ed è la parte che un principiante potrebbe trovare più ostica ma, se seguite la mia guida, non avrete problemi.

Su macOS aprite una finestra di Terminale e digitate:

pip3 --version

Questo comando dovrebbe restituirvi il risultato che vedete qui sotto: ovvero il numero della versione di PiP, ovvero la certezza che abbiate Python e PiP installati sul vostro Mac.

Se così non fosse dobbiamo installare Python e PiP. Pyhton è un linguaggio di programmazione mentre PiP) è in gestore di pacchetti che permette di installare librerie e software scritti in Python in modo automatizzato e semplice. Di fatto ci serve proprio per installare la libreria di docxTemplate.

Tempo addietro ho scritto un breve articolo su come installare PiP ma, con l’esperienza ho scoperto che il modo più facile e veloce è quello di utilizzare il mio amato HomeBrew.
Se non lo conoscete ho già scritto un articolo su come installarlo sul vostro Mac e sul perché dovreste farlo.

Una volta installato HomeBrew vi basterà digitare a Terminale il seguente comando:

brew install python

Alla fine dell’installazione controllate usando nuovamente il comando pip3 --version e dovreste essere operativi.

Ora non dovete fare altro che installare la libreria docxtemplate.

Il comando, sempre da digitare a terminale è semplicissimo:

pip install docxtpl

Salvo imprevisti avete finito e non dovrete più toccare il terminale da ora in avanti. Ovviamente se cambiate Mac o avete più Mac dovrete procedere a ripetere questo passaggio per ogni computer.

1.3 Installare la libreria sul vostro iPhone / iPad

Se volete usare questo sistema in mobilità su iPhone o su iPad non demoralizzatevi, pur non avendo a disposizione il Terminale potrete utilizzare l’app gratuita ed open-source a-Shell. Se bazzicate su Avvocati e Mac sapete come sia un amante di questa app ed abbia scritto svariati articoli al riguardo ma, per questo articolo, ci servirà solo come collante della nostra automazione.

Installate sul vostro dispositivo a-Shell, se non lo avete già fatto.

Aprite l’app e procedete a digitare il comando che abbiamo visto al punto precedente ovvero:

pip install docxtpl

Non dovremo installare Python perché questo è già compreso all’interno di a-Shell.

Dovrebbe comparirvi a schermo una cosa simile a quella che vedete nell’immagine sottostante.

*Installazione in a-Shell della libreria docxTemplate*

2. Creiamo un Comando rapido per automatizzare il nostro documento Word

Vi avevo anticipato all’inizio dell’articolo che avremmo usato Comandi Rapidi per renderci la vita più semplice ed automatizzare la creazione del nostro documento automatizzato.

2.1 Come funziona la libreria

Per utilizzare la libreria basta implementare questo “semplice” script:

from docxtpl import DocxTemplate

doc = DocxTemplate("my_word_template.docx")
context = { 'company_name' : "World company" }
doc.render(context)
doc.save("generated_doc.docx")

Non voglio tediarvi con cose troppo particolari ma, per poterlo personalizzare, dovete capire come funziona.

La prima riga importa la libreria (non ve ne dovete curare).

La seconda riga, invece, individua dov’è il modello che vogliamo utilizzare; dobbiamo inserire il percorso del modello che vogliamo utilizzare ed abbiamo creato nei passi precedenti.

La terza riga, per quel che ci interessa è quella più importante, perché individua i segnaposti che abbiamo creato nel modello iniziale e di permette di sostituire i segnaposti con i termini che vogliamo noi.
Nell’esempio sopra riportato viene sostituito al segnaposto company_name (che potremmo tradurre in italiano come nome della società) il testo World company.
Nel caso volessimo (come è normale che sia) avere più segnaposto nel nostro modello, potremo inserire le ulteriori coppie (segnaposto / parola da sostituire) con il medesimo schema e dividendo le coppie con una virgola. Come si vede anche qui sotto in un altro esempio:

context = { 
    'nomeCognome' : "Macchia Nera",
    'indirizzoVia':"Via dell'armonia 5",
    'indirizzoCap':"00156",
    'indirizzoCittà':"Roma",
    'indirizzoPR':"RO"
 }

Le ultime due righe, infine, specificano di prendere il modello, sostituire ai segnaposti il testo da noi scelto e, fatto ciò, salvare il tutto in un nuovo documento che, sempre nell’esempio proposto, è "generated_doc.docx" (ma il nome potrebbe essere quello che preferite).

Se mi avete seguito fin qui, vi potrebbe essere sorta la legittima domanda: ma che mi serve avere una lista di sostituzione (segnaposto / parole) statica?

A niente! Ma qui entra in gioco Comandi Rapidi ed in particolare le sue funzioni di manipolazione del testo. Grazie infatti a questa applicazione potremo inserire delle parole arbitrarie nel nostro modello, parole che l’utente può digitare in risposta ad una domanda proposta dall’interfaccia di Comandi Rapidi o addirittura, ed è qui che viene il bello, recuperando i dati da altre fonti ad esempio un foglio di calcolo come Excel (ma oggi non affronteremo questa ulteriore sfida e ci accontenteremo di imparare le basi).

3. Su macOS

*Semplice comando rapido per macOS per creare il documento finale dal nostro modello*

Qui di seguito è raffigurato un semplice comando rapido che, utilizzando i concetti che abbiamo appena imparato genera dal nostro modello un file con i dati che abbiamo pre-impostato, usando lo script python ed alcune semplici azioni di Comandi Rapidi.

Vediamo un attimo cosa fa il comando rapido in questione.

La prima azione (punto 1 dell’immagine), denominata semplicemente “File” recupera il nostro modello. Questo ci permette di catturare tutta una serie di informazioni sul file del nostro modello. In particolare useremo i dati catturati da questa azione per: 1) passarli allo script python per la creazione del file finale, 2) estrapolare il percorso del modello e salvare il file finale nella medesima cartella (ma potremmo salvarlo anche altrove).

Successivamente (punto 2), con un azione Testo, il comando rapido estrapola il nome e l’estensione del modello. Non sono infatti riuscito a estrapolare direttamente questo dato come variabile magica dalla precedente azione.

Al punto 3, grazie ad una azione Sostituisci estrae il percorso della cartella in cui si trova il nostro modello (/percorso/modello/modello.docx - modello.docx =/percorso/modello/) da poi utilizzare, come vedremo a breve, nel nostro script python.

Infine (punto 4), giusto per dare una dimostrazione di cosa è possibile fare, ho inserito una azione Richiedi input che permette nel caso specifico di recuperare del testo e pone una domanda attraverso una finestra a comparsa: "chi è il tuo cliente?" come si vede nell’immagine sottostante.

*Esempio di finestra con richiesta di input da parte dell’utente*

Ottenuti tutti in nostri “dati” possiamo cucinare la nostra piccola automazione (punto 5).

In una azione di Testo ho copia incollato il nostro semplice script python. Al posto di indicare il percorso del file del modello ho inserito una variabile magica che ho denominato significativamente “Percorso file”. Stesso discorso per il segnaposto nomeCognome, ho inserito il testo fornito dal punto 4 ovvero l’input fornito dall’utente.

*Esempio di variabile magica che estrapola il percorso del file*

Da ultimo, nella parte finale dello script, dove viene indicato dove salvare il documento finale e che nome attribuirgli ho inserito il percorso della cartella generato al punto 3 e dato il nome arbitrario “outputCR.docx” al file finale.

Vedete come è semplice creare una interfaccia per il nostro script e personalizzarlo a piacimento con comandi rapidi!

Ora non c'è altro da fare che passare il testo dello script all’azione Esegui script shell (presente solo su Comandi Rapidi per macOS), come si vede al punto 6 dell’immagine, e specificare che la shell dovrà essere python 3, l’input è quello passato dalla precedente azione (ovvero input) e di passare tale input a stdin che sta per standard input.

Ora se eseguiamo l’azione verrà generato un nuovo file DOCX con il nome del cliente a piacimento.

4. Salvare il nostro modello all’interno del comando rapido

In macOS è relativamente semplice accedere ai file, su iOS ed iPadOS questa funzione è più complessa (anche se presente a determinate condizioni).

Mentre stavo preparando l’automazione su iPad ho quindi deciso di testare un trucco che ho imparato da Federico Viticci ovvero la possibilità di incorporare un file all’interno di un comando rapido.

L’operazione a livello concettuale è relativamente semplice: basta codificare in base64 il nostro modello. Se volete approfondire vi lascio il link alla pagina di Wikipedia.

Per quel che ci interessa, basti sapere che è possibile convertire un qualsiasi tipo di file binario in un enorme file di testo. Il testo sarà incomprensibile all’uomo ma il computer potrà riconvertirlo in un file binario all’abbisogna. Gli allegati delle email vengono salvati proprio utilizzando questo sistema all’interno di una email che, di fatto, è un semplice file di testo. Il trucco sta nel creare un semplice comando rapido che converta il nostro modello .docx in base64 e poi copiare questo testo dentro una azione testo di Comandi Rapidi. In questo modo potremo avere a disposizione il modello e, tra l’altro, nessuno ci vieta di avere differenti modelli salvati in un comando rapido.

Quello che segue è un comando rapido che, sia su iOS che su macOS, salva negli appunti del sistema il file che gli viene passato come stringa (lunghissima) di testo.

*Esempio di comando rapido per la conversione in base64*

Su iOS / iPadOS è possibile passare il file attraverso la share sheet o funzione condividi, mentre su macOS è possibile farlo abilitando nei dettagli il comando rapido come azione rapida (come si vede nell’immagine soprastante) e poi selezionando nel Finder il file e usando l’azione rapida (cliccando il tasto destro e cercando nello specifico menù – come si vede nell’immagine sottostante).

*Esempio di azione rapida per convertire in base64 all’interno del Finder*

5. Su iOS / iPadOS

*Esempio di comando rapido che utilizza a-Shell su iOS / iPadOS per creare dal modello un file DOCX*

Possiamo quindi creare il nostro comando rapido per iOS / iPadOS.

Abbiamo già visto come installare quel che ci serve al punto 1.3 a cui vi rimando.

Quello che segue è un primo comando rapido che prende il modello salvato in base64, lo riconverte in un file e, utilizzando a-Shell, genera un file DOCX finale.

Le azioni di cui al punto 1 convertono da testo a file il nostro modello, rinominano il documento come “modello.docx” e salvano in a-Shell il documento.

Le azioni di cui al punto 2 fanno una cosa simile per lo script python (rispetto a quello che abbiamo visto per macOS in quello per iOS non ho implementato l’input dell’utente ma non sarebbe stato un problema) ed anche qui il file viene rinominato “script.py” e salvato in a-Shell.

Infine, con le azione del punto 3, viene lanciato in a-Shell lo script che prende il modello e crea il file finale. Questo file Word può quindi essere visualizzato (come avviene con le azioni del punto 4) o potrebbe essere salvato in una cartella.

Rispetto a macOS, dove esiste un interprete python, in iOS occorre sfruttare a-Shell e, così facendo, ci si complica un po' la vita dovendo salvare i vari file all’interno dell’applicazione e poi lanciare lo script all’interno dell’applicazione stessa “saltando” da Comandi Rapidi ad a-Shell.

Ciò detto è innegabile che avere uno strumento di automazione come quello mostrato su iOS / iPadOS permette di fare cose che, altrimenti, sarebbero impossibili.

In conclusione

Spero di non aver messo troppa carne al fuoco con questo articolo ma credo che esemplifichi bene come sia possibile, senza usare Word, creare automazioni documentali con un file .DOCX.

Dall’altro lato spero vi abbia fatto apprezzare le possibilità di Comandi rapidi che è diventato una colla per creare questa automazione senza dover scrivere una riga di codice.

Come vi ho anticipato, quella che vi ho proposto è una prova di concetto e possono essere fatte (e forse dovrebbero) varie ulteriori implementazioni. La più significativa è quella di estrapolare i dati di completamento del modello da un database di qualche sorta, come ad esempio un file CVS o Excel.