3.15 Chiama Web Service Esterno
Permette di richiamare un Web Service esterno ti tipo REST precedentemente configurato su Impostazioni -> Business Process Manager -> Webservice REST. (Figura 1 e 2)
Figura 1
Figura 2
- Nome → Permette di definire un nome al WS che stiamo configurando, utile per:
1) rendere più semplice ed intuitiva la sua selezione lato processo
2) rendere più facile il suo riconoscimento nella lista dei WS per un eventuale modifica lato interfaccia
- Descrizione → Permette di definire una descrizione al WS che stiamo configurato, utile per inserire specifiche di dettaglio in merito al suo funzionamento
- Attivo → Se impostato, permette il susuo utilizzo lato processi
- Tipo → Permette di definire la tipologia di WS da richiamare, al momento è possibile selezionare solamente la voce "REST"
- Metodo → Permette di definire il metodo HTTP da utilizzare per la richiesta, è possibile selezionare uno tra i seguenti valori: "GET","HEAD","POST","PUT","DELETE","OPTIONS","PATCH"
- Indirizzo → Permette di definire l'endpoint del WS che stiamo configurando, come ad esempio https://mywebsite.example.com/api/
- Autenticazione → Permette di definire il metodo di autenticazione utilizzato per richiamare il WS, nello specifico:
1) Basic: permette di definire un Nome utente e relativa Password statica con il quale il WS eseguirà l'autenticazione
2) Bearer (OAuth2): permette di eseguire un autenticazione a 2 fattori
- Client ID: rappresenta l'ID per accedere all'applicazione
- Autenticazione Client Secret: rappresenta la chiave segreta da utilizzare per autenticarsi correttamente
- Autenticazione Chiave Privata (PEM o JWK): permette di caricare una file di tipo PEM o JWK che rappresenta la chiave privata da utilizzare per autenticarsi correttamente
- Scope: permette di definire lo scope, ovvero quali operazioni sono ammesse dal sistema (sola lettura, sola scrittura, oppure in lettura/scrittura)
- Token URL: permette di definire l'URL da utilizzare come Token
- Headers → Permette di definire i parametri headers richiesti dal WS che stiamo configurando
Solitamente, la necessità di tali parametri dipende dalla struttura del WS e pertanto viene definita all'interno della sua documentazione dedicata.
- Parametri → Permette di definire i parametri in input richiesti dal WS che stiamo configurando
Solitamente, la necessità di tali parametri dipende dalla struttura del WS e pertanto viene definita all'interno della sua documentazione dedicata.
- Corpo grezzo → Permette di passare un unica stringa in formato JSON contenente tutti i parametri in input richiesti dal WS che stiamo configurando
Solitamente, la necessità di mappare tale sezione dipende dalla struttura del WS e pertanto viene definita all'interno della sua documentazione dedicata.
- Campi restituiti → Permette di salvare N parametri restituiti in output dal WS
Solitamente, la necessità di tali campi dipende dalla struttura del WS e pertanto viene definita all'interno della sua documentazione dedicata.
- Pulsante Prova Web Service → Permette di eseguire un test di chiamata restituendo un popup con il Codice di ritorno, il Messaggio della risposta, lo Stato e l'Output previsto dal WS.
Quindi, una volta configurato il WS lato Impostazioni -> Business Process Manager -> Webservice REST, sarà possibile richiamare tale WS all'interno dei processi (Figura 3, 4 e 5).
Figura 3
Figura 4
Al fine di spiegare al meglio la configurazione di tale azione all'interno di un processo, qui di seguito viene riportato un esempio di configurazione di una chiamata WS.
L'obiettivo del processo è quello di generare, all'attivazione di un collaboratore su Vtenext, un utente su un sistema esterno associato ad esso.
Il WS richiede il input un JSON con la seguente struttura:
{
"firstname" : "Mario",
"lastname" : "Rossi",
"type" : "Dipendente Interno",
"email" : "mariorossi@test.com",
"status" : "Active"
}
In caso di esito positivo, verrà restituito Codice della risposta = 201 e come output un JSON contenente diversi variabili, tra cui l'id dell'utenza creata, qui di seguito un esempio del JSON:
{
"firstname":"Mario",
"lastname":"Rossi",
"type":"Dipendente Interno",
"email":"mariorossi@test.com",
"status":"Active",
"id":"532",
"createdAt":"2025-07-03T13:05:11.752Z"
}
Per prima cosa, all'interno di Impostazioni -> Business Process Manager -> Webservice REST eseguiamo al configurazione iniziale del WS (Figura 5)
Figura 5
Successivamente, creiamo un processo avente il diagramma di flusso mostrato in figura 5:
Nella ServiceTask "Chiamata WS" configuriamo l'azione di chiamata WS esterno. (Figura 6)
Figura 6
Il sistema ha riportato in automatico tutti gli elementi configurati in Impostazioni -> Business Process Manager -> Webservice REST.
In aggiunta, è possibile definire ulteriori Headers, Parametri e Campi restituiti potendo passare quindi valori dinamici presi dai record coinvolti all'interno del processo.
ATTENZIONE! → in alcuni casi, i parametri Headers ereditati dalla configurazione eseguita in Impostazioni -> Business Process Manager -> Webservice REST verranno impostati di default come vuoti (Figura 7)
Figura 7
Di conseguenza, per fare in modo che la chiamata WS funzioni correttamente, si dovrà selezionare una tra voce "Default" disponibile nella picklist "Seleziona opzioni" presente in alto a destra di ogni campo. (Figura 8)
Figura 8
All'interno del Corpo grezzo, modifichiamo il JSON di partenza inserendo dinamicamente il contenuto dei campi del modulo Collaboratore associato al processo.
Nella ScriptTask "Storicizza risposta WS" attiviamo un process helper e nella sua form dinamica andiamo a creare 4 campi testuali (Figura 9).
Infatti, la chiamata WS di default restituisce le variabili "Codice della risposta", "Messaggio della risposta" e "Esito Positivo?" (1 se la chiamata ha avuto esito positivo, 0 se ha avuto esito negativo).
Infine, andiamo a creare il campo "id" all'interno del quale andremo a storicizzare l'output previsto dal WS che ci interessa, ossia l'id esterno dell'utenza creata.
N.B: nel caso di risposte complesse (oggetto con più attributi) è possibile eseguire un'estrazione fino ad massimo un livello di escalation (indicando nome campo restituito e attributo, es. object.attribute).
ATTENZIONE! → Non è supportata la lettura di attributi nel caso di liste di oggetti come response.
Figura 9
Per mapparne il contenuto, all'interno della picklist "Seleziona opzioni", il sistema mette a disposizione una sezione dedica per le chiamate WS con relativo metaid (Figura 10)
Figura 10
Nella Task "Controllo Chiama WS" andiamo ad eseguire un controllo sul contenuto del campo "Codice della risposta" ed "Esito Positivo?" e instradiamo il processo in due rami differenti (Figura 11)
Figura 11
Le ScriptTask finali "OK" e "KO" mostrate nel diagramma di flusso del processo potranno essere configurate a piacimento, ad esempio per storicizzare l'output del WS (quindi l'id dell'utenza creata nel sistema esterno) all'interno di un campo dedicato nell'anagrafica del collaboratore, oppure mandare una mail/notifica al reparto IT in caso di chiamata non andata a buon fine.