NEW 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 su 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.

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