API SOAP-REST relative al servizio di importazione/esportazione questionari in GoPrivacy

0. Glossario

   Abbreviazione

  Descrizione

  API

Le API (acronimo di Application Programming Interface, ovvero Interfaccia di programmazione delle applicazioni) sono set di definizioni e protocolli con i quali vengono realizzati e integrati software applicativi.

  REST

Representational State Transfer (REST) è uno stile architetturale (di architettura software) per i sistemi distribuiti. Il termine REST rappresenta un sistema di trasmissione di dati su HTTP senza ulteriori livelli (quali ad esempio SOAP). I sistemi REST non prevedono il concetto di sessione (sono, come approfondito successivamente, stateless).

  SOAP

SOAP (inizialmente acronimo di Simple Object Access Protocol) è un protocollo per lo scambio di messaggi tra componenti software. La parola object manifesta che l'uso del protocollo dovrebbe effettuarsi secondo il paradigma della programmazione orientata agli oggetti.

  REQUEST

La richiesta da effettuare al servizio attraverso l’utilizzo di un Uniform Resource Identifier (URI) come un indirizzo web, tramite modalità GET o POST

  PAYLOAD

parametri, obbligatori e non, da associare ad una REQUEST.

  RESPONSE

La risposta del servizio web, contenente l’output richiesto.

  JSON

Acronimo di JavaScript Object Notation, è un formato adatto all'interscambio di dati fra applicazioni client/server.  È basato sul linguaggio JavaScript Standard ECMA-262 3ª edizione (dicembre 1999), ma ne è indipendente. Viene usato in AJAX come alternativa a XML/XSLT.

  GET

Il metodo di richiesta HTTP GET recupera le informazioni dal server. Come parte di una richiesta GET, alcuni dati possono essere passati all'interno della stringa di query dell'URL, specificando termini di ricerca, intervalli di date o altre informazioni che definiscono la query.

  POST

POST è un metodo di richiesta supportato dal protocollo HTTP utilizzato dal World Wide Web. In base alla progettazione, il metodo di richiesta POST richiede che un server Web accetti i dati racchiusi nel corpo del messaggio di richiesta. Viene spesso utilizzato quando si carica un file o quando si invia un modulo Web completo.

  MTOM

Message Transmission OptimizationMechanism

  PAYLOAD

La parte di dati trasmessi destinata all'utilizzatore, in contrasto con gli altri elementi del messaggio necessari a far funzionare il protocollo di comunicazione.

  CSV

Il comma-separated values (abbreviato in CSV) è un formato di file basato su file di testo utilizzato per l'importazione ed esportazione (ad esempio da fogli elettronici o database) di una tabella di dati.

 

1. Obiettivo del Documento

Il presente documento intende fornire una descrizione di dettaglio delle funzionalità esposte per garantire l’integrazione con software di terze per i clienti che utilizzano l’applicativo GoPrivacy.
Questo documento costituisce l’input per le attività di realizzazione e sviluppo di possibili integrazioni ed è rivolto a personale tecnico.

 

2. Introduzione

Il presente documento descrive l’implementazione di una interfaccia API REST e di una API SOAPper la lettura e la scrittura di questionari GoPrivacy.

 

3. Requisiti

I servizi descritti di seguito dovranno consentire, previa autenticazione, di inviare per l’importazione le compilazioni dei questionari in GoPrivacy o di richiedere un’esportazione testuale degli stessi.

 

4. Descrizione delle funzionalità

Sono state implementate delle API di tipo REST e di tipo SOAP che possono essere invocate dai software di terze parti per usufruire delle funzionalità espresse nei requisiti. I servizi consentiranno di caricare in maniera automatica i documenti nel formato stabilito, di valutarne il risultato della lavorazione nonché di richiederne un’esportazione testuale in un formato standard.

 

5. Assunzioni e limitazioni

Si precisa che un utilizzo non conforme del servizio (programmi sviluppati da terzi che eseguano chiamate incontrollate allo stesso) potrebbe causare gravi rallentamenti al sistema, impedendone in casi più critici, anche il normale utilizzo. In tal caso potrebbe essere inibito l’accesso ai servizi.

5.1 Clienti

A livello di Cliente sarà presente un flag che indicherà il permesso o meno di utilizzare i servizi esposti dalle API relativamente a tale Cliente.

Tale flag permetterà inoltre di abilitare / disabilitare all’utilizzo dei servizi i singoli utenti associati al Cliente.

5.2 Utenti

Per l’accesso alle API verranno utilizzati gli utenti già esistenti a sistema. Potranno accedere alle API solo gli utenti associati a Clienti abilitati al servizio e che sono stati a loro volta abilitati da utente admin o Utenti Gestori all’utilizzo degli stessi.

 

6. Dettaglio dei requisiti non realizzabili

Per motivi di sicurezza non è possibile usufruire di alcun servizio che possa essere invocato senza autenticazione.

 

7. Ambienti di test e produzione

Nel seguito del documento verrà utilizzata la dicitura <HostGoPrivacy> per identificare l’host verso cui eseguire la chiamata. Tale dicitura va sostituita con i seguenti host.
Ambiente di produzione


<HostGoPrivacy> = tool.goprivacy.it


Ambiente di test
<HostGoPrivacy> = test.goprivacy.it

 

8. Specirfiche tecniche di dettaglio delle API REST

8.1 Endpoint

Le API REST saranno raggiungibili tramite chiamate HTTPS ad una sottoapplicazione dedicata raggiungibile con la seguente url:


https://<HostGoPrivacy>/api/index.php?module=api


Il parametro method indica l’azione da eseguire e verrà descritta di seguito.

8.2  Auth

Tale metodo permette l’autenticazione dell’utente a sistema per il conseguente accesso ai servizi esposti.
La richiesta attraverso l’invio in GET o POST di alcuni parametri minimi essenziali, provvederà, se vengono soddisfatti i criteri di autenticazione, alla restituzione di un token da utilizzare nelle chiamate di metodi successivi.

 

8.2.1.Ottenere il token di autenticazione (chiamata auth)

8.2.1.1 AuthRequest

Request: https://<HostGoPrivacy>/api/index.php?module=api&method=auth

PAYLOAD

Elemento

Obbligatorietà

Cardinalità

Tipo

Descrizione

username

1 .. 1

string

Username dell’utenza

password

1 .. 1

string

Password dell’utenza

id_cliente

1 .. 1

integer

Id del cliente su cui si vuole operare

versione

1 .. 1

string

Versione dell’API utilizzata.

Valori possibili:

1.0

 

 

8.2.1.2 Esempio di richiesta GET per la chiamata auth

https://<HostGoPrivacy>/api/index.php?module=api&method=auth&username=utenteprova&password=miapassword&id_cliente=8060&versione=1.0

 

8.2.1.3 Esempio di richiesta POST pere la chiamata auth

POST api/index.php?module=api&amp; method=auth HTTP/1.1
Host: <HostGoPrivacy>
cache-control: no-cache
Client-Token: 60ffc464-19eb-475c-ad65-aea063af15f7
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW 


Content-Disposition: form-data; name="username"
utenteprova
------WebKitFormBoundary7MA4YWxkTrZu0gW--,
Content-Disposition: form-data; name="password"


miapassword
------WebKitFormBoundary7MA4YWxkTrZu0gW--,
Content-Disposition: form-data; name="id_cliente"


8060
------WebKitFormBoundary7MA4YWxkTrZu0gW--,
Content-Disposition: form-data; name="versione"


1.0
------WebKitFormBoundary7MA4YWxkTrZu0gW—

 

8.2.1.4 AuthResponse

Il metodo auth ritorna il seguente messaggio JSON

PAYLOAD

Elemento

Obbligatorietà

Cardinalità

Tipo

Descrizione

auth

1 .. 1

boolean

Indica se l’autenticazione è stata concessa o meno.

Se concessa vale: TRUE

Se negata vale: FALSE

token

No       

0 .. 1

string

Se auth vale true, viene restituito un token univoco di 36 caratteri alfanumerici nella forma [A-Z0-9]{8}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{12} (Es. 2D3E671D-3176-4202-827F-6CEB1B56EE27).

Il token è valido per 20 minuti dal suo ultimo utilizzo.

 

 

 

 

8.2.1.5 Esempio di messaggio JSON con la risposta di autenticazione non riuscita

HTTP/1.1 200 OK
{"auth":"false"}

 

8.2.1.6 Esempio di messaggio JSON con la risposta di autenticazione riuscita

HTTP/1.1 200 OK
{"auth":"true","token":"C2B1D9AE-0CFB-4DD0-B5F8-D0C24975ABE1"}

 

8.3 Invio di un file per l'importazione di un questionario

La seguente chiamata serve ad inviare un file csv per l’importazione di una compilazione di un questionario. Il metodo riceve i parametri in POST come di seguito esposti e restituisce un messaggio JSON con l’esito dell’operazione.

 

8.3.1 Inviare un file per l'importazione (chiamata importQuestionari)

8.3.1.1 importQuestionariRequest

Request: https://<HostGoPrivacy>/api/index.php?module=api&method=importQuestionari

PAYLOAD

Elemento

Obbligatorietà

Cardinalità

Tipo

Descrizione

token

1 .. 1

String

token restituito dal metodo auth.

file

 

1 .. 1

File multipart/form-data

 

parametro di tipo file (la chiamata deve essere fatta in modalità multipart/form-data) che contiene un file csv auto descrittivo con i dati da importare come descritto nell’appendice A.1

 

8.3.1.2 Esempio di messaggio POST per la chiamata importQuestionari

POST /api/index.php?module=api& method=importQuestionari HTTP/1.1

Host: <HostGoPrivacy>

cache-control: no-cache

Client-Token: bc036882-9570-4ad3-b0fa-124c2d6743d0

Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

 

Content-Disposition: form-data; name="token"

 

71858F9F-B24A-4E49-9B3B-0BB7761E21C2

------WebKitFormBoundary7MA4YWxkTrZu0gW--,

Content-Disposition: form-data; name="token"

 

71858F9F-B24A-4E49-9B3B-0BB7761E21C2

------WebKitFormBoundary7MA4YWxkTrZu0gW--

Content-Disposition: form-data; name="file"; filename="/C:/path_to_file/questionario_20190927_130310.csv

 

 

------WebKitFormBoundary7MA4YWxkTrZu0gW--

 

8.3.1.3 importQuestionariResponse

il metodo importQuestionari ritorna il seguente messaggio JSON

PAYLOAD

Elemento

Obbligatorietà

Cardinalità

Tipo

Descrizione

errors

1 .. 1

boolean

Indica l’esito dell’operazione.

Vale FALSE per indicare che il procedimento è andato a buon fine e non sono stati riscontrati errori.

Vale TRUE se sono stati riscontrati degli errori durante la procedura.

errorsList

No

0 .. 1

array

Array di stringhe contenente gli errori riscontrati durante il processo di importazione. L’elemento è presente solo se errors = TRUE

 

 

8.3.1.4 Esempio di messaggio JSON per la risposta di importQuestionari con esito positivo

HTTP/1.1 200 OK

{"errors":"false"}

 

8.3.1.5 Esempio di messaggio JSON per la risposta di importQuestionari con errori

HTTP/1.1 200 OK

{"errors":"true","errorsList":["Token inesistente"]}

 

8.4 Richiesta di un'esportazione di un questionario

La seguente chiamata serve per richiedere la generazione di un file CSV di un questionario di un cliente . Il metodo riceve i parametri in POST come di seguito esposti e restituisce un messaggio JSON con l’esito dell’operazione.

 

8.4.1 Richiesta esportazione (chiamata exportQuestionari)

8.4.1.1 exportQuestionariRequest

Request: https://<HostGoPrivacy>/api/index.php?module=api&method=exportQuestionari

PAYLOAD

Elemento

Obbligatorietà

Cardinalità

Tipo

Descrizione

token

1 .. 1

String

token restituito dal metodo auth

params

1 .. 1

String

Elemento in formato JSON che contiene i dati identificativi del questionario da esportare

 

8.4.1.2 Array params

L’elemento params è così formato:

Elemento

Obbligatorietà

Cardinalità

Tipo

Descrizione

id_questionario

1 .. 1

integer

Id del questionario da esportare

domande

 

No

0 .. 1

string

Elemento in formato JSON contenente un array di domande da esportare. Se non indicato o lasciato vuoto verranno esportati solo i campi fissi e nessuna domanda specifica

 

8.4.1.3 Array domande

L’elemento domande è così formato:

Elemento

Obbligatorietà

Cardinalità

Tipo

Descrizione

id_domanda

1 .. 1

integer

Id della domanda da esportare

formato

 

1 .. 1

string

Formato della domanda

  • “D” è il formato standard
  • “T” è il formato testuale per le domande che lo prevedono

 

8.4.1.4 Esempi di messaggio POST per la chiamata exportQuestionari

POST /api/index.php?module=api& method=exportQuestionari HTTP/1.1

Host:<HostGoPrivacy>

cache-control: no-cache

Client-Token: 88e899cc-2f94-4190-859a-64034ca2505b

Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

 

Content-Disposition: form-data; name="token"

 

D2929C39-5007-4D8C-AE1C-4BF36C8EC403

------WebKitFormBoundary7MA4YWxkTrZu0gW--,

Content-Disposition: form-data; name="params"

 

{"id_questionario":136,"domande":[{"id_domanda":4357,"formato":"D"},{"id_domanda":2733,"formato":"D"}]}

------WebKitFormBoundary7MA4YWxkTrZu0gW—

 

8.4.1.5 exportQuestionariResponse

il metodo exportQuestionari ritorna il seguente messaggio JSON

PAYLOAD

Elemento

Obbligatorietà

Cardinalità

Tipo

Descrizione

errors

1 .. 1

string

Indica l’esito dell’operazione.

Vale FALSE per indicare che il procedimento è andato a buon fine e non sono stati riscontrati errori.

Vale TRUE se sono stati riscontrati degli errori durante la procedura.

file

 

No

0 .. 1

String

Stringa codificata in Base64 contenente il file esportato. Il formato del file è quello indicato nell’Appendice A.1.

Il tag è presente solo se errors = FALSE

errorsList

No

0…1

Array

Array di stringhe contenente gli errori riscontrati durante il processo di importazione. L’elemento è presente solo se errors = TRUE

 

 

8.4.1.6 Esempio di messaggio JSON per la risposta di exportQuestionari con file allegato

HTTP/1.1 200 OK

{"errors":"false","file":"UEsDBBQAAgAIAFF7Q09d\/x1fegIAAOMJAAAgAAAAcXVlc3Rpb25hcmlvXzIwMTkxMDAzXzE1MjYzNC5jc3ZtlcluVDEQRfd8BeIHugaXXZZXCAFLEhLE8ikivWgpEIYgJXw97ub5dV0HqTfnvhpueerb\/d3+Yd8Ot8uP3\/tfD4f7bzc\/D\/dH\/nL\/9fvh7uZPl\/YtqZUmRfVFY80tcdJKjaqXnN2rN7Id5Z0Q+xaResTlZyIqvLtuxHOAiad2+aYHMIsIC7fxKRNpO1Nma6\/ffyQy4xLlvMo5aZTLPzmVLgTZ12glinI9yZYtBgutwa6xY\/e4Gik1yrLKrCDraqSKRTmtsleonePIUrZOHGXfZIlyXUvmmoKsY4piII8pSo6+dEyRoaXqaNn3Ocgp2tWxQ5ohd+yQc1wYHcP10xPlMZxT3E9dh7MKu5\/W4RJBy8TRVxKgMUrxaCetG6LHgxbkMVOVGG2bnXgGSorrUXpupAxUIhkDCVC4BSX1rb36dLF8uHi7XF1dL++4Liy2HO\/UQvyfG9ZTQmOXMVAWkyDHnp0gxQpQjZQJiIGgZlagBGRAoXt1OlcRcTudz8fHx6enp6Z9Wj5OW0eAHi\/tFt5fCm+vevzLPm8VftX1HUtcnx7jHDN8PQfef419RwoNesC6gMWpNu4OZAo4rjc9c2YSB+mPW4nEBASRrEAZaNuMqArkC+QL5CtE6vbNjpgU0RAroBEifs0FsAhiAnS04VCK+7ZEZEYURAwWQoy5hdKEipgQDTEjFkRHrICwdB3RhgkiujJ0ZejK0JWhK0NXhq4yusrginF8RpN8LsXlJJwv\/xDSLPgkFJoFnoW5aJmLFpsEl1mYa5wP3xDmWerso05Fw01fBd18CKeSXHPy\/XxzuVIhCQ\/DELxJ\/6OVuqManpTx9dkLMKWfnpa\/UEsBAj8DFAACAAgAUXtDT13\/HV96AgAA4wkAACAAAAAAAAAAAAAAALaBAAAAAHF1ZXN0aW9uYXJpb18yMDE5MTAwM18xNTI2MzQuY3N2UEsFBgAAAAABAAEATgAAALgCAAAAAA=="}

 

8.4.1.7 Esempio di messaggio JSON per la risposta di exportQuestionari con errori

HTTP/1.1 200 OK

{"errors":"true","errorsList":["Nessunacompilazionetrovata per ilquestionarioindicatorelativa al cliente

selezionato"]}

 

9. Specifiche tecniche di dettaglio delle API SOAP

9.1 endpoint

Le API SOAP saranno raggiungibili tramite chiamate HTTPS ad una sottoapplicazione dedicata raggiungibile con la seguente url:

https://<HostGoPrivacy>/api/index.php?module=soap 

Il WSDL è reperibile alla seguente url:

https://<HostGoPrivacy>/api/index.php?module=soap&WSDL

Sono previsti una serie di metodi descritti nel seguenti paragrafi: auth, importQuestionari, exportQuestionari

 

9.2 auth

Tale metodo permette l’autenticazione dell’utente a sistema per il conseguente accesso ai servizi esposti.

La richiesta attraverso l’invio di una richiesta SOAP provvederà, se vengono soddisfatti i criteri di autenticazione, alla restituzione di un token da utilizzare nelle chiamate di metodi successivi.

 

9.2.1 AuthRequest

Il metodo prevede la ricezione di un tipo complesso denominato AuthRequest contenente i seguenti elementi

Elemento

Obbligatorietà

Cardinalità

Tipo

Descrizione

username

1 .. 1

string

Username dell’utenza

password

1 .. 1

string

Password dell’utenza

id_cliente

1 .. 1

integer

Id del cliente su cui si vuole operare

versione

1 .. 1

string

Versione dell’API utilizzata.

Valori possibili:

1.0

 

 

9.2.2 Esempio di richiesta per la chiamata auth

POST /api/index.php HTTP/1.1

Host:<HostGoPrivacy>

Connection: Keep-Alive

User-Agent: PHP-SOAP/7.0.33-11+ubuntu18.04.1+deb.sury.org+1

Content-Type: text/xml; charset=utf-8

SOAPAction: "http://<HostGoPrivacy>/api/auth"

Content-Length: 720

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://<HostGoPrivacy>/api/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"><SOAP-ENV:Body><ns1:auth><paInput xsi:type="SOAP-ENC:Struct"><username xsi:type="xsd:string">utenteprova</username><password xsi:type="xsd:string">miapassword</password><id_cliente xsi:type="xsd:string">8060</id_cliente><versione xsi:type="xsd:string">1.0</versione></paInput></ns1:auth></SOAP-ENV:Body></SOAP-ENV:Envelope>

 

9.2.3 AuthResponse

Il metodo auth prevede il ritorno di un tipo complesso denominato AuthResponse contenente i seguenti elementi

PAYLOAD

Elemento

Obbligatorietà

Cardinalità

Tipo

Descrizione

Auth

1 .. 1

boolean

Indica se l’autenticazione è stata concessa o meno.

Se concessa vale: TRUE

Se negata vale: FALSE

token

No       

0 .. 1

string

Se auth vale true, viene restituito un token univoco di 36 caratteri alfanumerici nella forma [A-Z0-9]{8}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{12} (Es. 2D3E671D-3176-4202-827F-6CEB1B56EE27).

Il token è valido per 20 minuti dal suo ultimo utilizzo.

 

 

 

9.2.4 Esempio di risposta per la chiamata auth

HTTP/1.1 200 OK
Date: Mon, 21 Oct 2019 07:28:52 GMT
Server: Apache/2.4.29 (Ubuntu)
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Cache-Control: no-store, no-cache, must-revalidate
Pragma: no-cache
Set-Cookie: _api_=fvi8anbqf53t4bsqmd4qspvh56; path=/
Content-Length: 642
Vary: Accept-Encoding
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-Type: text/xml; charset=utf-8
 
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://<HostGoPrivacy>/api/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"><SOAP-ENV:Body><ns1:authResponse><return xsi:type="SOAP-ENC:Struct"><auth xsi:type="xsd:boolean">true</auth><token xsi:type="xsd:string">54C5CC8E-E607-4A5F-859F-CAD40FE436B6</token></return></ns1:authResponse></SOAP-ENV:Body></SOAP-ENV:Envelope>

 

9.3 importQuestionari

La seguente chiamata serve ad inviare un file csv per l’importazione di compilazioni di un questionario.

 

9.3.1 ImportQuestionariRequest

Il metodo prevede la ricezione di un tipo complesso denominato importQuestionariRequest contenente i seguenti elementi

PAYLOAD

Elemento

Obbligatorietà

Cardinalità

Tipo

Descrizione

token

1 .. 1

String

token restituito dal metodo auth.

file

 

1 .. 1

String

 

parametro di tipo stringa codificata in Base64 che contiene un file csv auto descrittivo con i dati da importare come descritto nell’appendice A.1

 

9.3.2 Esempio di risposta per la chiamata importQuestionari

POST /api/index.php HTTP/1.1
Host: <HostGoPrivacy>
Connection: Keep-Alive
User-Agent: PHP-SOAP/7.0.33-11+ubuntu18.04.1+deb.sury.org+1
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://<HostGoPrivacy>/api/importQuestionari"
Content-Length: 789
Cookie: _api_=2bipiqa1v2vq5mcaqbcrk5lc63;
 
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://<HostGoPrivacy>/api/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"><SOAP-ENV:Body><ns1:importQuestionari><paInput xsi:type="SOAP-ENC:Struct"><token xsi:type="xsd:string">F7F51691-AB74-4B4C-8398-34A5B3DDE5D9</token><file xsi:type="xsd:string">ZGVsZXRlO2lkX3F1ZXN0aW9uYXJpbztpZF9jb21waWxhemlvbmU7MjczMzs0MzU3DQo7MTM2OzQxNDM5MDswNS8wNi8yMDE4O0EzMw0KOzEzNjs0MTQ0OTA7MDEvMDYvMjAxODtBNDQ=</file></paInput></ns1:importQuestionari></SOAP-ENV:Body></SOAP-ENV:Envelope>

 

9.3.3 ImportQuestionariResponse

Il metodo importQuestionari prevede il ritorno di un tipo complesso denominato ImportQuesrionariResponse contenente i seguenti elementi

PAYLOAD

Elemento

Obbligatorietà

Cardinalità

Tipo

Descrizione

errors

1 .. 1

boolean

Indica l’esito dell’operazione.

Vale FALSE per indicare che il procedimento è andato a buon fine e non sono stati riscontrati errori.

Vale TRUE se sono stati riscontrati degli errori durante la procedura.

errorsList

No

0 .. 1

array

Array di stringhe contenente gli errori riscontrati durante il processo di importazione. L’elemento è presente solo se errors = TRUE

 

 

9.3.4 Esempio di risposta per la chiamata importQuestionari

HTTP/1.1 200 OK
Date: Mon, 21 Oct 2019 07:40:38 GMT
Server: Apache/2.4.29 (Ubuntu)
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Cache-Control: no-store, no-cache, must-revalidate
Pragma: no-cache
Content-Length: 627
Vary: Accept-Encoding
Keep-Alive: timeout=5, max=99
Connection: Keep-Alive
Content-Type: text/xml; charset=utf-8
 
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://<HostGoPrivacy>/api/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"><SOAP-ENV:Body><ns1:importQuestionariResponse><return xsi:type="SOAP-ENC:Struct"><errors xsi:type="xsd:boolean">false</errors><errorsList xsi:nil="true"/></return></ns1:importQuestionariResponse></SOAP-ENV:Body></SOAP-ENV:Envelope>

 

9.4 exportQuestionari

La seguente chiamata serve per richiedere la generazione di un file CSV di un questionario di un cliente .

 

9.4.1 ExportQuestionariRequest

Il metodo prevede la ricezione di un tipo complesso denominato ExportQuestionariRequest contenente i seguenti elementi

PAYLOAD

Elemento

Obbligatorietà

Cardinalità

Tipo

Descrizione

Token

1 .. 1

String

token restituito dal metodo auth

id_questionario

1 .. 1

Integer

Id del questionario da esportare

domande

Si

1..N

Array di ExportQuestionariDomande

Elenco delle domande da eseportare

Il tipo complesso ExportQuestionariDomande contiene i seguenti elementi

Elemento

Obbligatorietà

Cardinalità

Tipo

Descrizione

id_domanda

1 .. 1

integer

Id della domanda da esportare

formato

 

1 .. 1

string

Formato della domanda

  • “D” è il formato standard
  • “T” è il formato testuale per le domande che lo prevedono

 

9.4.2 Esempio di richiesta  exportQuestionari

POST /api/index.php HTTP/1.1
Host: <HostGoPrivacy>
Connection: Keep-Alive
User-Agent: PHP-SOAP/7.0.33-11+ubuntu18.04.1+deb.sury.org+1
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://<HostGoPrivacy>/api/exportQuestionari"
Content-Length: 1016
Cookie: _api_=20e79qc8ierfkfgq3jj0dve525;
 
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://<HostGoPrivacy>/api/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"><SOAP-ENV:Body><ns1:exportQuestionari><paInput xsi:type="SOAP-ENC:Struct"><token xsi:type="xsd:string">8C4672A7-D937-44D5-852D-746ECAC7DE8E</token><id_questionario xsi:type="xsd:int">136</id_questionario><domande SOAP-ENC:arrayType="SOAP-ENC:Struct[2]" xsi:type="SOAP-ENC:Array"><item xsi:type="SOAP-ENC:Struct"><id_domanda xsi:type="xsd:int">2733</id_domanda><formato xsi:type="xsd:string">D</formato></item><item xsi:type="SOAP-ENC:Struct"><id_domanda xsi:type="xsd:int">4357</id_domanda><formato xsi:type="xsd:string">D</formato></item></domande></paInput></ns1:exportQuestionari></SOAP-ENV:Body></SOAP-ENV:Envelope>

 

9.4.3 ExportQuestionariResponse

Il metodo exportQuestionari prevede il ritorno di un tipo complesso denominato ExportQuesrionariResponse contenente i seguenti elementi:

PAYLOAD

Elemento

Obbligatorietà

Cardinalità

Tipo

Descrizione

errors

1 .. 1

string

Indica l’esito dell’operazione.

Vale FALSE per indicare che il procedimento è andato a buon fine e non sono stati riscontrati errori.

Vale TRUE se sono stati riscontrati degli errori durante la procedura.

File

 

No

0 .. 1

String

Stringa codificata in Base64 contenente il file esportato. Il formato del file è quello indicato nell’Appendice A.1.

Il tag è presente solo se errors = FALSE

errorsList

No

0…1

Array

Array di stringhe contenente gli errori riscontrati durante il processo di importazione. L’elemento è presente solo se errors = TRUE

 

 

9.4.4 Esempio di risposta exportQuestionari

HTTP/1.1 200 OK
Date: Mon, 21 Oct 2019 08:01:52 GMT
Server: Apache/2.4.29 (Ubuntu)
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Cache-Control: no-store, no-cache, must-revalidate
Pragma: no-cache
Content-Length: 4023
Vary: Accept-Encoding
Keep-Alive: timeout=5, max=98
Connection: Keep-Alive
Content-Type: text/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://<HostGoPrivacy>/api/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"><SOAP-ENV:Body><ns1:exportQuestionariResponse><return xsi:type="SOAP-ENC:Struct"><errors xsi:type="xsd:boolean">false</errors><file xsi:type="xsd:string">ZGVsZXRlO2lkX3F1ZXN0aW9uYXJpbztpZF9jb21waWxhemlvbmU7MjczMzs0MzU3CjsxMzY7NDE0MzkwOzA1LzA2LzIwMTg7QTMzCjsxMzY7NDE0NDkwOzAxLzA2LzIwMTg7QTQ0CjsxMzY7NDE1Mjg0OztRQzAwMDExMjIyMTIxCjsxMzY7NDE2MDAzOzsKOzEzNjs0MTY2MTU7O0FHUjAwNTUxNwo7MTM2OzQxNjYxNjs7QUdSMDA1NjQzCjsxMzY7NDE2NjE3OztBR1IwMDQ3MzYKOzEzNjs0MTY2MTg7O0FHUjAwNTMwMAo7MTM2OzQxNjYxOTs7QUdSMDU2NTYKOzEzNjs0MTY2MjA7O0FHUjAwNTgzNwo7MTM2OzQxNjYyMTs7QUdSMDA1NTc5CjsxMzY7NDE2NjIyOztBR1IwMDUxMzkKOzEzNjs0MTY2MjM7O0FHUjAwNDkyNQo7MTM2OzQxNjYyNDs7QUdSMDA0ODk3CjsxMzY7NDE2NjI2OzsKOzEzNjs0MTY2Mjc7O0FHUjAwNTU3MQo7MTM2OzQxNjYyODs7QUdSMDA1NTcyCjsxMzY7NDE2NjI5OztBR1IwMDQ2OTQKOzEzNjs0MTY2MzA7O0FHUjAwNTc1NAo7MTM2OzQxNjYzMTs7QUdSMDA1NzY1CjsxMzY7NDE2NjMyOztBR1IwMDU2NzEKOzEzNjs0MTY2MzM7O0FHUjAwNTU5OAo7MTM2OzQxNjYzNDs7CjsxMzY7NDE2NjM1OztBR1IwMDUzNjEKOzEzNjs0MTY2MzY7O0FHUjAwNTgxOQo7MTM2OzQxNjYzNzs7QUdSMDA1NjY4CjsxMzY7NDE2NjM4OztBR1IwMDU4MDMKOzEzNjs0MTY2Mzk7O0FHUjAwNTkxNwo7MTM2OzQxNjY0MDs7QUdSMDA0MDYxCjsxMzY7NDE2NjQxOzsKOzEzNjs0MTY2NDI7Owo7MTM2OzQxNjY0Mzs7QUdSMDA1Nzg5CjsxMzY7NDE2NjQ0OztBR1IwMDM2MTUKOzEzNjs0MTY2NDU7O0FHUjAwNTkyOQo7MTM2OzQxNjY1OTs7QUdSMDA1OTc5CjsxMzY7NDE2NzQ0OzsKOzEzNjs0MTY3NDU7Owo7MTM2OzQxNjc0Njs7CjsxMzY7NDE2NzQ3OzsKOzEzNjs0MTY3NTE7Owo7MTM2OzQxNjc1Mjs7CjsxMzY7NDE2NzUzOzsKOzEzNjs0MTc0OTQ7MDEvMDYvMjAxODtTVVBfT1BFX1NTVF9GMTlfMTI1XzIwMThfMDEKOzEzNjs0MTc0OTY7Owo7MTM2OzQxODI0NTs7QUdSMDA2MjUyCjsxMzY7NDE4MjUyOzsKOzEzNjs0MTgyNTY7Owo7MTM2OzQxODI1Nzs7CjsxMzY7NDE4MjU5OzsKOzEzNjs0MTgyNjA7Owo7MTM2OzQxODI2MTs7CjsxMzY7NDE4MjYyOzsKOzEzNjs0MTgyNjM7Owo7MTM2OzQxODI2NDs7CjsxMzY7NDE4MjY1OzsKOzEzNjs0MTgyNjY7Owo7MTM2OzQxOTgwMjs7CjsxMzY7NDIyODUyOzMxLzAxLzIwMTk7QUdSeHh4eXl5CjsxMzY7NDIzNjIwOzsKOzEzNjs0MjUxNzg7MTMvMTIvMjAxODsiQUdSIDAwNjkyMSIKOzEzNjs0MjUxODE7Owo7MTM2OzQyNTE4NDsxOC8wMy8yMDE5O0FHUjAwODAwOAo7MTM2OzQyNTE4NTsxMS8wMi8yMDE5O0FHUjAwNzgwOQo7MTM2OzQyNTE5NjswMS8wMS8yMDE5Owo7MTM2OzQyNTIwMjs7CjsxMzY7NDI2MDA3OzsKOzEzNjs0MjYwMTA7Owo7MTM2OzQyNjAxMjs7CjsxMzY7NDI2MDEzOzsKOzEzNjs0MjYwMTY7Owo7MTM2OzQyNjAxOTs7CjsxMzY7OzsKOzEzNjs0MjYwMjI7Owo7MTM2OzQyNjAyMzs7CjsxMzY7NDI2MDI2OzsKOzEzNjs0MjYwMzI7Owo7MTM2OzQyNjAzNjs7CjsxMzY7NTQyNjA0Mzs7CjsxMzY7NTQyNjA0NTs7CjsxMzY7NTQyNjA0OTs7CjsxMzY7NTQyNjA1MDs7CjsxMzY7NTQyNjA1OTs7CjsxMzY7NTQyNjA2Nzs7CjsxMzY7NTQyNjA3Mjs7CjsxMzY7NTQyNjA3NDs7CjsxMzY7NTQyNjA4Njs7CjsxMzY7NTQyNjA4OTs7CjsxMzY7NTQyNjEwODs7CjsxMzY7NTQyNjExMTs7CjsxMzY7NTQyNjExMjs7CjsxMzY7NTQyNjExODs7CjsxMzY7NTQyNjEyMDs7CjsxMzY7NTQyNjEyMTs7CjsxMzY7NTQyNzA0MTs7CjsxMzY7NTQyNzA0Mzs7CjsxMzY7NTQyNzA0NDs7CjsxMzY7NTQyNzA0NTs7CjsxMzY7NTQyNzA0Njs7CjsxMzY7NTQyNzA0Nzs7CjsxMzY7NTQyNzA0ODs7CjsxMzY7NTQyNzA0OTs7CjsxMzY7NTQyNzA1MDs7CjsxMzY7NTQyNzA1MTs7CjsxMzY7NTQyNzA1Mjs7CjsxMzY7NTQyNzA1Mzs7CjsxMzY7NTQyNzA1NDs7CjsxMzY7NTQyNzA1NTs7CjsxMzY7NTQyNzA1Njs7CjsxMzY7NTQyNzA1Nzs7CjsxMzY7NTQyNzA1ODs7CjsxMzY7NTQyNzA1OTs7CjsxMzY7NTQyNzA2MDs7CjsxMzY7NTQyNzA2MTs7CjsxMzY7NTQyNzE0NTs7CjsxMzY7NTQyNzE1Mjs7CjsxMzY7NTQyNzE1OTs7CjsxMzY7MTc1NDI3MTYzOzsKOzEzNjsxNzU0MjcxNjQ7Owo7MTM2OzE3NTQyNzE2ODs7CjsxMzY7MTc1NDI3MTcwOzsKOzEzNjsxNzU0MjcxNzE7Owo7MTM2OzE3NTQyNzE3Mzs7CjsxMzY7MTc1NDI3MTc0OzsKOzEzNjsxNzU0MjcxNzU7Owo7MTM2OzE3NTQyNzE4Mjs7CjsxMzY7MTc1NDI3MTgzOzsKOzEzNjsxNzU0MjcxODY7Owo7MTM2OzE3NTQyNzE4OTs7CjsxMzY7MTc1NDI3MTkxOzsKOzEzNjsxNzU0MjcxOTI7Owo7MTM2OzE3NTQyNzIwMjs7CjsxMzY7MTc1NDI3MjM1OzsKOzEzNjsyMTQ3NDgzNjQ4ZTs7CjsxMzY7OzsKOzEzNjsxOTA3MDIwMDc7Owo7MTM2OzE5MDcwMjAwODsyOS8wOS8yMDE5OzIzNAo7MTM2OzE5MDcwMjAwOTs7CjsxMzY7OzsKOzEzNjs7Owo7MTM2OzE5MDcwMjAxMDs7Cg==</file><errorsList xsi:nil="true"/></return></ns1:exportQuestionariResponse></SOAP-ENV:Body></SOAP-ENV:Envelope>

 

10. Appendice

10.1 A.1 File CSV per l'importazione/esportazione dei questionari


Il formato del file prevede una prima riga di intestazione con i seguenti valori, separati dal carattere di punto e virgola (;),  nell’ordine dato:

  • delete
  • id_questionario
  • id_compilazione
  • per ogni risposta da importare una colonna con l’id della domanda

Ognuna delle righe successive contiene una compilazione che si intende inserire, modificare o cancellare. Ogni riga contiene i dati in quest’ordine separati sempre dal carattere di punto e virgola (;):

  • 1/0 se 1 la compilazione va cancellata altrimenti inserita o modificata
  • Id del questionario
  • Id della compilazione (se l’id esiste sarà un aggiornamento altrimenti un inserimento)
  • Per ogni risposta da importare il valore della risposta (riferito alla domanda indicata nella intestazione)

Sono gestiti i seguenti tipi di campi risposta:

    CHI - Risposta chiusa

    ORG - Combo selezione Organigramma (Richiesto Id Organigramma)

    BOO - Boolean (1=Si; 0=No)

    INT - Intero

    TES - Testo

    TAL - TextArea con lista risposte di aiuto

    TAR - TextArea

    LIS - Testo con lista risposte di aiuto

    CHT - Testo selezionabile da tendina

    DAT - Data (nel formato DD/MM/YYYY)

    MUL - Risposta chiusa multipla

    QUE - Incrocio tra questionari (Richiesto ID Compilazione)

    ASS - TextArea con selezione Assets da popup

 

10.2 A.2 Esempio di file CSV per l'importazione/esportazione dei questionari

delete;id_questionario;id_compilazione;4444;5555;6666.T;1111;2222;3333.T

 

;999;123456;00;"VIDEOSORV.001 - VideosorveglianzaAREA1";"99 - Direzione Generale";61;"sicurezza del luogo di lavoro e tutela del patrimonio dell'azienda"

 

9;555;654321;77;"VIDEOSORV.002 - VideosorveglianzaAREA2";"55 - Direzione Generale";88;"sicurezza del luogo di lavoro e tutela del patrimonio dell'azienda"