Therefore™ Help

Il lavoro 'Chiama funzione' permette di personalizzare Therefore™ Online. Può essere usato come qualunque altro lavoro di workflow automatico. Al momento dell'esecuzione del lavoro viene inviata una richiesta HTTP(S) POST all'URL specificato. Questo 'URL richiesta' è l'unico campo obbligatorio nella configurazione.

Il diagramma illustra l'interazione tra i diversi componenti.

Quando il lavoro “Chiama funzione” viene eseguito in Therefore™ Workflow Engine, viene inviata una richiesta POST HTTPS alla funzione. Se la chiamata ha esito positivo, la funzione chiamata viene eseguita e molto probabilmente invia una chiamata a Therefore™ Server mediante Web API per recuperare documenti, dati indice o ulteriori informazioni richieste per questo scopo.

La funzione chiamata può essere una funzione Azure, un servizio web o qualsiasi eseguibile in grado di rispondere a una richiesta POST HTTPS. È tuttavia necessario che la funzione chiamata restituisca un oggetto JSON che contenga la stringa "TheError" e anche il valore booleano “TheRoutingDone” oppure il numero intero “TheRetryAfterMin”. Se la funzione è stata sviluppata da Therefore™, può risiedere in hosting nell'abbonamento Azure di Therefore™ Online.

Per motivi di sicurezza, le funzioni sviluppate dai clienti devono essere eseguite sul loro abbonamento Azure o sulla loro infrastruttura. Come illustrato nel diagramma, tutte le connessioni tra Therefore™ e la funzione chiamata sono soltanto richieste POST HTTPS e chiamate (Web) API. Nessun codice del cliente viene eseguito direttamente dal servizio server, né all'interno dell'ambiente Therefore™ Online. Per le chiamate Web API vengono eseguite tutte le verifiche delle autorizzazioni abituali. Il token di accesso fornito con la richiesta HTTPS è limitato all'istanza di workflow corrente. In virtù di questa architettura, la personalizzazione del workflow può essere utilizzata in Therefore™ Online in modo sicuro.

La funzione chiamata può essere una funzione Azure, un servizio web o qualsiasi applicazione che sia pubblicamente disponibile e possa essere attivata da una richiesta HTTPS. L'unica caratteristica obbligatoria sono i seguenti "parametri di risposta" che la funzione deve inviare come risposta JSON:

•TheError: valore stringa obbligatorio. Se la stringa non è vuota, verrà visualizzata nello storico del workflow. L'istanza sarà contrassegnata come errata, a meno che non venga richiesto un nuovo tentativo in un momento seguente.

•TheRetryAfterMin: valore intero opzionale. Può essere utilizzato per richiedere l'esecuzione di un nuovo tentativo da parte di Therefore™.

Se è impostato su un valore maggiore di zero, il lavoro 'Chiama funzione' funzionerà come un lavoro 'Attendi' e invierà una nuova richiesta una volta trascorso (circa) il numero di minuti specificato. Se "TheError" è impostato, viene trattato come avviso e non contrassegna l'istanza di workflow come errata.

•TheRoutingDone: valore booleano obbligatorio, a meno che non sia stato specificato un valore per "TheRetryAfterMin".

Può essere impostato su 'true' per indicare che l'indirizzamento dell'istanza di workflow è già stato eseguito dalla funzione mediante la funzione Web API 'FinishCurrentWorkflowTask'. Se è impostato su 'false', Therefore™ indirizza l'istanza di workflow al lavoro successivo. Se "TheRetryAfterMin" è specificato, l'indirizzamento non viene eseguito per il momento, quindi in questo caso è facoltativo. Con ogni chiamata di funzione, Therefore™ invia i parametri seguenti alla funzione come oggetto JSON insieme alla richiesta HTTPS:

•TheWebAPIUrl: contiene l'impostazione server "URL API web", che può essere configurata nella scheda 'XML Web Service' o nelle impostazioni avanzate. Questa impostazione sarà già configurata nel modo corretto se si usa Therefore™ Online, ma può essere lasciata vuota se non è configurata.

•TheTenant: nome del locatario (tenant) corrente. Sarà vuoto se il sistema non utilizza la modalità di multi-locazione.

•TheAccessToken: un token JWT che può essere utilizzato per connettersi a Therefore™ mediante l'API web.

Il token è configurato in modo da concedere a "$TheWFSystem" l'accesso utente al documento o al fascicolo associato con l'istanza di workflow corrente, nonché all'istanza di workflow corrente e al token. Con le autorizzazioni concesse è possibile modificare il documento associato, il fascicolo o i documenti associati al fascicolo. Inoltre, le autorizzazioni consentono di indirizzare l'istanza di workflow a un altro lavoro. Non è invece possibile creare nuovi documenti o fascicoli, né eseguire query. Non si può nemmeno eliminare il fascicolo o documento principale associato all'istanza di workflow, né l'istanza di workflow stessa.

•TheInstanceNo: numero istanza dell'istanza di workflow corrente.

•TheTokenNo: numero di token dell'istanza di workflow corrente.

•TheCaseNo: numero di fascicolo del fascicolo associato all'istanza di workflow corrente. Questo parametro è disponibile solo per i workflow basati su fascicoli.

•TheDocNo: numero di documento del documento principale associato all'istanza di workflow corrente. Questo parametro è disponibile solo per i workflow basati su documenti.

•TheSettings: oggetto JSON (passato come stringa) di tutte le 'Impostazioni funzione personalizzate' configurate.

Può essere vuoto oppure utilizzato per passare ulteriori parametri alla funzione chiamata. Nome e valore di ogni impostazione possono essere scelti liberamente, ma i nomi devono essere univoci in base alla specifica JSON. Tutti i valori vengono trattati come valori stringa e devono essere convertiti in un altro tipo all'interno della funzione, se richiesto.

Se è configurata una chiave funzione per le funzioni Azure, la richiesta HTTPS includerà tale chiave in "x-functions-key" nell'intestazione della richiesta.

Eventuali altre informazioni richieste devono essere recuperate mediante l'API web di Therefore™, utilizzando il token JWT fornito oppure specificando un nome utente e una password, se sono richiesti diritti più elevati. Quando si usano le funzioni Azure, le credenziali possono essere fornite nelle impostazioni dell'applicazione come "WebAPIUser" e "WebAPIPassword". Se queste impostazioni sono assenti, la funzione utilizzerà il token JWT per impostazione predefinita.

Quando si scrive una funzione, ricordarsi di inviare una risposta in meno di 4 minuti, altrimenti la chiamata alla funzione scadrà. Considerare anche l'uso del parametro "TheError" per restituire eventuali eccezioni generate, in modo da facilitare l'individuazione del problema.

Non vi è praticamente nessuna restrizione rispetto alle possibilità di personalizzazione.

Quando si usano funzioni Azure, sono previste alcune limitazioni specifiche di Azure, ad esempio quando si caricano dipendenze, a causa dell'ambiente PaaS (Platform as a Service) o del tempo di esecuzione (230 secondi di timeout HTTPS) e altre implicazioni legate all'esecuzione del codice in Azure.

La limitazione del timeout può essere evitata scrivendo una funzione asincrona che invia una richiesta di nuovo tentativo a Therefore™. In questo modo, l'esecuzione può proseguire in un lavoro di background separato ed è possibile restituire il risultato/la risposta a Therefore™ quando viene attivata la successiva richiesta di nuovo tentativo.

A causa delle restrizioni relative alle dipendenze in Azure, non è possibile utilizzare l'API Therefore™ e occorre invece usare l'API web. Questo limite può essere evitato eseguendo invece la funzione HTTPS attivata su un sistema con Therefore™ installato. L'unico requisito per questo tipo di soluzione è che il sistema in questione sia raggiungibile dall'esterno.