Therefore™ Help

Zoom Window Out
Larger Text | Smaller Text
Hide Page Header
Show Expanding Text
Printable Version
Save Permalink URL

Esercitazioni > Solution Designer > Workflow > Personalizzazione di workflow in Therefore™ Online

Risoluzione dei problemi

Come funziona il lavoro 'Chiama funzione'?

Una comprensione di base del funzionamento di questa funzione è fondamentale per le procedure di risoluzione dei problemi. Il diagramma illustra l'interazione tra i diversi componenti.

SD_T_Workflow_Cust_TFO_016

Quando il lavoro “Chiama funzione” viene eseguito in 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.

Come vengono segnalati gli errori?

Tutti i messaggi di errore generati devono essere registrati nello storico del workflow.

Come illustrato nel diagramma dell'architettura, Therefore™ invia soltanto una richiesta HTTPS, mentre la parte più importante (il codice del cliente) viene eseguita all'interno della funzione chiamata.

Se la funzione ha esito negativo, tutti gli errori devono essere segnalati a Therefore™, così possono essere registrati nello storico del workflow. Se la funzione restituisce un errore, la voce nello storico del workflow inizierà con il testo “La funzione chiamata ha segnalato un errore”. Se la funzione si interrompe in modo anomalo a causa di un'eccezione non gestita o perché non restituisce l'informazione, non può essere registrato nulla in Therefore™. Se la funzione restituisce solo un oggetto JSON con una stringa “TheError” vuota e il valore booleano “TheRoutingDone” impostato su false, l'operazione viene considerata riuscita perché la chiamata HTTPS è stata eseguita e non è stato segnalato alcun errore.

Ecco alcuni degli errori che si possono verificare quando si chiama una funzione:

La voce dello storico workflow inizia con il testo...	Descrizione del problema
Si è verificato un errore nel workflow. Si è verificato un errore durante l'invio della richiesta.	Non è stato possibile inviare la richiesta a causa di un problema di rete. Controllare che l'URL sia corretto e che la porta richiesta sia aperta (porta 80 se non diversamente configurata).
La funzione è stata chiamata correttamente, ma è stato richiesto un nuovo tentativo tra %d minuti.	La funzione ha restituito il valore “TheRetryAfterMin” nella richiesta. Il modulo workflow attende %d minuti, quindi chiama di nuovo la funzione. Non si tratta di un errore e viene semplicemente registrato nello storico del workflow come informazione aggiuntiva.
The HTTP request to '%s' has timed out.	L'invio della richiesta è riuscito ma la funzione non ha restituito nulla entro l'intervallo prestabilito di 4 minuti.
The called function did not return a mandatory value.	La funzione deve obbligatoriamente restituire un oggetto JSON in base alla definizione della specifica.
La funzione chiamata ha segnalato un errore.	La richiesta è riuscita ma si è verificato un problema all'interno della funzione. Le informazioni seguite da questa stringa dovrebbero essere sufficienti per determinare il tipo di problema.
La funzione chiamata ha segnalato un errore. No connection could be made because the target machine actively refused it.	La richiesta è riuscita ma la funzione non si è connessa al servizio web XML tramite l'API web. Potrebbe trattarsi di un problema di rete oppure l'impostazione server “URL API web” non è configurata correttamente.
La funzione chiamata ha segnalato un errore. Web API base URL not set.	L'impostazione “URL API web ” non è configurata nelle impostazioni server avanzate.
La funzione chiamata ha segnalato un errore. Accesso negato.	È stata effettuata una chiamata API web con privilegi insufficienti. Sono richieste autorizzazioni aggiuntive.
La funzione chiamata ha segnalato un errore. Non si è autorizzati a…	È stata effettuata una chiamata API web con privilegi insufficienti. Sono richieste autorizzazioni aggiuntive.
Richiesta HTTP non riuscita; codice di stato 401.	Il codice di stato 401 significa “Non autorizzato”. È stata specificata una chiave funzione non corretta per la chiamata della funzione Azure.
Richiesta HTTP non riuscita; codice di stato 404.	Il codice di stato 404 significa “Non trovato”. L'URL configurato non è corretto.
Richiesta HTTP non riuscita; codice di stato 403.	Il codice di stato 401 significa “Vietato”. La funzione Azure chiamata non è in esecuzione.
Richiesta HTTP non riuscita; codice di stato 500.	Il codice di stato 500 significa “Errore interno del server”. Si può verificare in caso di eccezione non gestita. Vedere Monitoraggio nel portale Azure per informazioni su come ottenere le informazioni sull'eccezione.

Come funziona il monitoraggio nel portale Azure?

Per monitorare le funzioni Azure è necessario configurare il servizio “Application Insights” di Microsoft. Quando si fa clic su “Monitora” dopo aver selezionato una funzione nel portale Azure, viene visualizzato un elenco delle chiamate di funzione recenti.

SD_T_Workflow_Cust_TFO_017

Le chiamate di funzione vengono indicate come ‘riuscita’ se non si è verificata nessuna eccezione non gestita, indipendentemente dal codice di risultato o dalle eccezioni rilevate. Therefore™ ha un comportamento analogo; se viene rilevata un'eccezione, deve essere riportata con il codice di stato 200 e con le informazioni sull'eccezione nella stringa di ritorno “TheError”.

Se si è verificata un'eccezione non gestita, la funzione non può restituire nulla a Therefore™ e il servizio web invia soltanto il codice di stato 500. In questo caso, in Therefore™ non possono essere visualizzate altre informazioni oltre al codice di stato 500 ed è necessario controllare il servizio di monitoraggio di Azure per conoscere i dettagli.

L'“ID operazione” può essere utilizzato per interrogare la tabella delle eccezioni e ottenere i dettagli e le analisi dello stack. Copiare l'ID operazione e fare clic su “Esegui in Application Insights” per aprire il servizio in una nuova scheda.

SD_T_Workflow_Cust_TFO_018

Incollare l'ID operazione nella finestra di query e strutturare una query nel modo seguente:

exceptions | where operation_Id == "OperationID"

| limit 50

Quando si fa clic su “Esegui” dovrebbero apparire le informazioni sull'eccezione relative all'ID operazione specificato.

Dovrebbe essere presente almeno una riga contenente le informazioni sull'eccezione.

SD_T_Workflow_Cust_TFO_019

Esportare tutte le righe e inviarle allo sviluppatore responsabile di questa funzione Azure.

Inoltre, controllare la tabella delle analisi per ottenere ulteriori informazioni sul workflow. Se è stato usato un codice di esempio, ogni chiamata di funzione dovrebbe essere registrata con numero di istanza, token e fascicolo o documento.

SD_T_Workflow_Cust_TFO_020

Copiare la query precedente e sostituire “exceptions” con “traces”:

traces | where operation_Id == "OperationID"

| limit 50

Includere queste informazioni anche quando si informa lo sviluppatore.

Se la funzione prevede operazioni di conversione, è necessario fornire anche il documento.

Domande frequenti sullo sviluppo

Come e dove si sviluppa una funzione Azure?

Lo sviluppo di una funzione Azure può essere eseguito interamente in Visual Studio senza la necessità di un abbonamento Azure. Dopo aver creato una nuova funzione Azure utilizzando la procedura di creazione guidata progetto, è possibile avviarla subito premendo F5. Il debugger con punti di interruzione funziona come qualsiasi altra applicazione.

È necessario un abbonamento Azure?

Non per attività di testing e sviluppo. Le funzioni Azure possono essere scritte ed eseguite direttamente da Visual Studio. Se il sistema di sviluppo è accessibile pubblicamente tramite http, potrebbe anche essere utilizzato con Therefore™ Online. Tuttavia, quando diventa necessario eseguire la funzione Azure in un ambiente di produzione, occorre disporre di un abbonamento Azure. In alternativa è anche possibile creare una funzione per un servizio web non ospitato in Microsoft Azure. In questo caso non è necessario un abbonamento.

Perché la funzione non ha restituito un parametro obbligatorio?

Tutte le funzioni chiamate mediante il lavoro “Chiama funzione” devono restituire un oggetto JSON che contiene la stringa “TheError” e il valore booleano “TheRoutingDone” o il valore intero “TheRetryAfterMin”.

In assenza di errori, la stringa “TheError” deve essere vuota ma comunque presente nell'oggetto JSON. Tuttavia, specialmente in caso di errore, è importante rilevare l'eccezione e inviarla a Therefore™ utilizzando la stringa “TheError” per consentirne la corretta registrazione.

Come si fa per testare una funzione (Azure) senza Therefore™?

Specialmente quando si inizia a sviluppare le prime funzioni (Azure), può essere più rapido chiamare direttamente la funzione per testarla. A questo scopo è possibile usare cURL con il comando seguente:

curl –d “” –i –X POST http://localhost:Port/api/Route

Se la funzione è già stata distribuita in Azure, utilizzare invece il comando seguente:

curl –d “” –i –X POST “https://AppName.azurwebsites.net/api/Route?code=FunctionKey”

Il valore “Route” può essere definito nel codice. In caso contrario, viene invece utilizzato il nome della funzione.

La chiamata all'API web restituisce “Accesso negato” o “Non si è autorizzati a…”

Per motivi di sicurezza, il token JWT fornito ha autorizzazioni molto limitate ed è quindi probabile incorrere in problemi di autorizzazione. Se sono necessarie maggiori autorizzazioni, occorre creare un utente interno provvisto delle autorizzazioni richieste. Le credenziali possono quindi essere passate alla funzione aggiungendo “WebAPIUser” e “WebAPIPassword” come impostazioni applicazione nel portale Azure oppure per lo sviluppo locale nel file “local.settings.json”.

È possibile usare l'API Therefore™ per la funzione?

Dipende dalla piattaforma in uso. Quando si usano le funzioni Azure, è necessario utilizzare l'API web di Therefore™ perché l'API normale ha troppe dipendenze.