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 3 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