SERVIZI WEB DEL CRM - Interazione con il CRM mediante flussi XML

PRESENTAZIONE

Il CRM offre la possibilità di avere diverse integrazioni in modalità BackEnd sfruttando le potenzialità di MS SQL Server (DTS, ETL, comandi schedulati, …) ovvero attraverso servizi custom SOAP, che consentono di creare dei flussi di import/export ed allineamento dati costante o periodico.

E’ inoltre possibile attraverso le funzionalità offerte dal macrolinguaggio interno Simple# renderizzare all’utente finale delle pagine web dinamiche ed in tempo reale di informazioni live presenti in altri sistemi gestionali (es. Legacy/Erp o altri DB).

E’ infine disponibile un metodo semplice ma molto potente e completamente configurabile per fornire accesso ai dati del sistema CRM ad applicazioni esterne, che possono così recuperare qualsiasi informazione attraverso chiamate http, ottenendo semplici stream in formato XML.

Attraverso i servizi Web messi a disposizione dalla pagina GETCRMINFO.aspx è possibile svolgere le seguenti funzionalità:

ottenere informazioni in formato XML con una semplice chiamate Web (passando parametri nella modalità preferita POST oppure GET)
ottenere informazioni nel formato XML nativo di SQL Server
inviare aggiornamenti di stato (es. cambiare lo stato di un'offerta) o di anagrafiche
ottenere flussi dati per alimentare Microsoft Excel, al fine di costruire rapidamente semplici e funzionali Cruscotti di Analisi mediante l'utilizzo delle funzionalità di Excel (es. PIVOT)
scaricare i file presenti nel sistema di archiviazione del CRM (Megabiblos)

L'utilizzo di questi servizi Web avviene nella massima sicurezza in quanto ogni richiesta dovrà essere corredata dalle credenziali di accesso al CRM (un utente del CRM). Tutte le richieste inoltre possono essere registrate nei log tecnici del sistema.

E' possibile altresì attivare ulteriori protezioni sistemistiche direttamente sul file GETCRMINFO.aspx, presente nella cartella di installazione del CRM. Così facendo oltre alle credenziali del CRM possono venire richieste le credenziali di Windows.

L'output che viene prodotto da GETCRMINFO dipende:

- dai parametri forniti in fase di chiamata

- dal tipo di QUERY SQL impostata nei comandi personalizzati. In particolare se la query restiuisce un normale "recordset" l'output è costituito da un flusso XML formato secondo le regole del CRM.

- Se la query restituisce già un file XML mediante l'utilizzo della clausola "FOR XML AUTO" di SQL

SELECT TOP 2000 RAGSOC, PROV, CITTÀ AS CITTA, TEL1, IDAGENTE, INDIRIZZO, EMAIL1 FROM CLIENTI FOR XML AUTO, ELEMENTS, ROOT('TEST')

CHIAMATA

La chiamata dovrà essere avviata al seguente URL:

http://serverCRM/GetCrmInfo.aspx

dove <serverCRM> corrisponde all’indirizzo di accesso del CRM.

Esempio: http://crm.miaazienda.it/getcrminfo.aspx

Istruzioni per l'uso della pagina GetCrmInfo.aspx

Si deve passare alla pagina GetCrmInfo.aspx un campo Params contenente un XML con il formato ESTESO:

<connection>nome connessione CRM</connection>

<user>utente CRM</user>

<password>password utente CRM</password>

<allowsamelogin>opzionale: se 'true' o '1' permette login multipli per lo stesso user</allowsamelogin>

<sqlcommandid>id o Codice GUID del comando sql da eseguire</sqlcommandid>

oppure

<megabiblosid>codice documento Megabiblos da scaricare</megabiblosid>

<format>opzionale: formato dei risultati (XML o CSV) - viene considerato solo per comandi SQL che restituiscono record di risultati. Il default è XML</format>

<parameter id="nome parametro 1">valore 1</parameter>

<parameter id="nome parametro 2">valore 2</parameter>

...

</parameters>

</execsql>

oppure un XML con il formato RIDOTTO:

<e>

<c>nome connessione CRM</c>

<u>utente CRM</u>

<p>password utente CRM</p>

<a>opzionale: se 'true' o '1' permette login multipli per lo stesso user</a>

<s>id o Codice GUID del comando sql da eseguire</s>

oppure

<m>codice documento Megabiblos da scaricare</m>

<f>opzionale: formato dei risultati (XML o CSV) - viene considerato solo per comandi SQL che restituiscono record di risultati. Il default è XML</f>

<r>

<t id="nome parametro 1">valore 1</t>

<t id="nome parametro 2">valore 2</t>

...

</r>

</e>

PARAMETRI [[parameters]] ed altri campi variabili

Alla chiamata devono essere inviati dei parametri in modalità POST oppure GET.

Sul CRM è possibile memorizzare traccia di tutte le chiamate attivando nei log tecnici quelli di tipo "Info".

I parametri vanno passati in ogni caso mediante un flusso XML molto semplice:

nel caso di modalità POST (consigliata per maggiore sicurezza) è necessario passare il flusso XML in un campo di input con nome Params con il seguente formato:

<connection>nome connessione bcom CRM</connection>

<user>utente bcom CRM</user>

<password>password utente bcom CRM</password>

<sqlcommandid>id commando sql da eseguire</sqlcommandid>

<format>opzionale: formato dei risultati (XML o CSV) - viene considerato solo per comandi SQL che restituiscono record di risultati. Il default è XML</format>

oppure

<megabiblosid>codice documento Megabiblos da scaricare</megabiblosid>

<parameter id=”nome parametro 1”>valore 1</parameter>

<parameter id=”nome parametro 2”>valore 2</parameter>

...

</parameters>

</execsql>

Nel caso di modalità GET è invece sufficiente fare l'encoding corretto dei caratteri (es. <, >, /, ecc...) è passare tutta l'intera stringa XML sull'URL.

La connessione al server CRM verrà effettuata con le credenziali dell’utente indicato; l’utente potrà essere già connesso al server CRM, ma in tal caso al termine l'utente risulterà "sconnesso".

Per questo si consiglia l’utilizzo di un account dedicato per l’esecuzione dei comandi GetCrmInfo.

[id commando sql da eseguire]

è l’identificativo del comando SQL che verrà eseguito ed il cui risultato costituisce il flusso XML oppure CSV della risposta. Solitamente si tratta di un comando di SELECT parametrico (i cui parametri vengono passati in fase di chiamata) ma può anche essere un comando di UPDATE o INSERT oppure una STORED PROCEDURE. In quest’ultimo caso verrà restituito solamente il numero di record aggiornati oppure il messaggio di Sql Server.

La gestione di questi comandi si trova nel menù Utilità / Comandi personalizzati e Schedulazioni del tool Client/Server.

Eventuali parametri nei comandi SQL potranno essere indicati con la sintassi [[nome parametro]] e nella chiamata alla pagina GetCrmInfo.aspx dovranno essere specificati i nomi e i valori di tutti i parametri presenti nel comando SQL che si vuole eseguire; se nel comando SQL non sono presenti parametri, il tag <parameters> può essere omesso.

VARIABILI DISPONIBILI

Oltre ai parametri che è possibile passare in fase di chiamata, prima di eseguire il comando il sistema effettua la sostituzione di tutti i nomi dei campi modulo presenti nel comando SQL impostato.

I campi modulo utilizzabili, sempre con la sintassi [[nomecampo]], sono gli stessi utilizzabili all'interno del Simple# 2.0 dell'Home page del CRM e che si possono ottenere andando nell'editor del Simple# e premendo l'icona informativa "Elenco Campi Modulo".

Ecco un esempio di QUERY parametri con i nomi dei campi modulo:

SELECT '[[NOMEUTENTE]]' AS NOMEUTENTE,RAGSOC,TEL1

FROM CLIENTI WHERE [[FILTROVISIBILITACLIENTI]]

RISPOSTA

In risposta alla chiamata si ottiene un file XML composto come segue:

L'output seguirà il seguente schema:

Come si nota i parametri <sqlcommandid> e <megabiblodid> sono mutuamente esclusivi.

Il formato CSV* consente di ottenere le informazioni nel formato in modo più rapido ed occupando meno banda Internet in quanto il formato è privo di tutti i classici Tag XML.

*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.

Vedremo in seguito il suo tipico utilizzo.

XML FORMATO CRM

Il formato generato dal CRM nel caso di una query di tipo SELECT normale è il seguente:

<field name=”nome campo 1”>valore</field>

<field name=”nome campo 2”>valore</field>

...

</record>

...

</results>

<error>

Messaggio di errore nell’esecuzione del comando SQL

</error>

</execsql>

Il tag <results> sarà vuoto in caso di comando SQL che non restituisce alcun record; in caso di comando SQL che modifica i dati, invece, sarà presente un solo tag <record> con un unico <field> con ID “Affected records” e valore pari al numero di record modificati.

Il tag <error> sarà presente in caso di errori nell’accesso al server CRM o nell’esecuzione del comando SQL e riporterà il messaggio di errore restituito dal server.

XML formato SQL

Il formato generato dal CRM nel caso di una query di tipo SELECT ... FOR XML AUTO, ad esempio:

SELECT TOP 2 RAGSOC, PROV, CITTÀ AS CITTA, TEL1, IDAGENTE, INDIRIZZO, EMAIL1 FROM CLIENTI FOR XML AUTO, ELEMENTS, ROOT('TEST')

Sarà simile al seguente, ovvero senza alcuna alterazione da parte del CRM rispetto all'output di SQL Server.

<TEST>

<RAGSOC>Rossi spa</RAGSOC>

<CITTA>ABANO TERME</CITTA>

<INDIRIZZO>VERDI 2</INDIRIZZO>

<EMAIL1>rossi@rossi.it</EMAIL1>

</CLIENTI>

<RAGSOC>Roberto Lorenzetti</RAGSOC>

<CITTA>BUSTO ARSIZIO</CITTA>

<INDIRIZZO>SILVESTRE</INDIRIZZO>

</CLIENTI>

</TEST>

Output in formato CSV

Il formato generato dal CRM nel caso di una query di tipo SELECT normale e parametro

Sarà simile al seguente, ovvero

ragsoc;prov;citta;tel1;idagente;indirizzo;email1

ACME SPA;MI;MILANO;03319351;36;CORSO SEMPIONE;prova@prova.com

Questo formato è utile per creare delle connessioni dati dinamiche direttamente dall'interno di Microsoft Excel verso il CRM, al fine di creare così dei cruscotti di consultazione pratici, rapidi e disponibili anche in modalità OffLine.

Il tag <error> sarà presente anche in questo in caso se durante l’accesso al server CRM o nell’esecuzione del comando SQL avvengono delle anomalie che devono essere segnalate al chiamante.

PROBLEMATICHE DI SICUREZZA

La connettività HTTP può essere impostata dal sistemista di fiducia in modalità HTTPS* al fine di garantire una maggiore sicurezza a questo tipo di richieste.

Inoltre è possibile anche abilitare l'autenticazione a livello di Windows per la specifica risorsa "GetCrmInfo.aspx". Così facendo l'accesso Web alle informazioni del CRM sarà criptato e protetto.

*L'HTTPS (Hypertext Transfer Protocol over Secure Socket Layer) è il risultato dell'applicazione di un protocollo di crittografia asimmetrica al protocollo di trasferimento di ipertesti HTTP. Viene utilizzato per garantire trasferimenti riservati di dati nel web, in modo da impedire intercettazioni dei contenuti che potrebbero essere effettuati tramite la tecnica del man in the middle.

ESEMPIO

Supponiamo si voglia ottenere con una semplice chiamata HTTP la lista delle trattative in corso, confermate, perse, ecc. può essere ottenuta con la query seguente, in cui il parametro [[stato ordine]] verrà sostituito di volta in volta con il valore corrispondente allo stato delle trattative che si desidera recuperare dal database:

SELECT

numeroordine AS [N. Ordine],

agenti.cognome AS Agente,

clienti.ragsoc AS [Rag. Soc.],

provenienza,

dataordine

FROM

ORDINI

INNER JOIN

PROVENIENZE

ON (provenienze.idprovenienza=ordini.idprovenienza)

INNER JOIN

AGENTI

ON (ordini.idagente=agenti.idagente)

INNER JOIN

CLIENTI

ON (ordini.idcliente=clienti.idcliente)

WHERE

ordini.stato=[[stato ordine]]

ORDER BY agenti.cognome

Supponendo di aver memorizzato la query nel database del CRM come comando personalizzato con IDComando 11 e di voler selezionare le trattative in corso (che hanno, ad esempio, stato ordine 35), la pagina GetCrmInfo.aspx dovrà essere richiamata passandole come parametro l’XML seguente (nell’ipotesi che la connessione al database sia stata salvata con il nome DBCRM e che l’utente UtenteCrmInfo con password p@ssw0rd abbia il diritto di accedere al CRM):

<connection>DBCRM</connection>

<user>utenteCrmInfo</user>

</parameters>

</execsql>

Il risultato della chiamata alla pagina GetCrmInfo.aspx sarà, ad esempio, l’XML seguente:

<field name="Agente">Ciccone</field>

<field name="Rag. Soc.">GALVAN GIACOMO</field>

<field name="provenienza">AFFISSIONE</field>

</record>

<field name="Rag. Soc.">STOLFI FRANCESCO</field>

<field name="provenienza">AFFISSIONE</field>

</record>

...

<field name="Agente">VIGO ELENA T</field>

<field name="Rag. Soc.">ASCHERI SILVIA</field>

<field name="provenienza">AFFISSIONE</field>

</record>

</results>

</execsql>

FLUSSO WEB PER FARE PIVOT IN EXCEL

Utilizzando la gestione dei comandi schedulati (si trova nel menù Utilità / Comandi personalizzati e Schedulazioni del tool Client/Server) è possibile anche creare dei particolari flussi dati che possono essere utilizzati come sorgente diretta di informazioni per un foglio XLS (dalla versione Office 2003).

Questo consente di visualizzare e manipolare direttamente dal WEB le informazioni del CRM mediante il client in assoluto più semplice, completo e conosciuto, ovvero Microsoft Excel.

Utilizzando questi flussi dati dal Web è possibile salvarsi un file Excel* sul desktop che punta direttamente all'URL della Pagina GetCrmInfo.Aspx del CRM.

Sarà sufficiente aprirlo per ottenere i dati aggiornati e quindi effettuare ordinamenti, operazioni di PIVOTING, grafici, raggruppamenti ed altre analisi in modo semplice ed economico.

*La licenza di Microsoft Excel è esclusa dalla licenza del CRM

Per creare un comando personalizzato di questo tipo è molto semplice.

Ecco un esempio (supponiamo abbia IDComando = 272)

SELECT ORDINI.IDORDINE, TIPI_ORDINI.DESCRIZIONE, ORDINI.ANNOORDINE, ORDINI.NUMEROORDINE, ORDINI.REVISIONE, ORDINI.DATAORDINE, ORDINI.CLIENTE, ORDINI.TEL1, ORDINI.TOT, ORDINI.OGGETTOTRATTATIVA, (SELECT (CODICEAGENTE + ' - ' + COGNOME) AS AGENTE FROM AGENTI WHERE IDAGENTE = ORDINI.IDAGENTE) AS AGENTE, (DBO.EXTRACTDATE(DATAAPPTO) + DBO.EXTRACTTIME(ORAAPPTO)) AS APPUNTAMENTO , STATI.DESCRIZIONESTATO AS STATO, ORDINI.PERIODOCHIUSURA,ORDINI.PERCENTUALECHIUSURA FROM ORDINI INNER JOIN STATI ON ORDINI.STATO = STATI.IDSTATO INNER JOIN TIPI_ORDINI ON TIPI_ORDINI.IDTIPOORDINE=ORDINI.IDTIPO WHERE [[FILTROVISIBILITAORDINI]] ORDER BY IDORDINE DESC

In questi comandi che dovranno essere utilizzati in modalità connessa a Microsoft Excel si consiglia di EVITARE i campi NOTE (campi di tipo TEXT), così da limitare l'utilizzo di banda nel passaggio dati ed ottimizzare la velocità di aggiornamento tra XLS e CRM.

Per utilizzare il flusso da Excel:

1) lanciare Microsoft Excel ed andare nella pagina ribbon "DATI"

2) Premere il tasto "Carica dati esterni - Da Testo"

3) come indirizzo inserire l'URL del CRM seguito da GetCrmInfo.aspx e dalla sintassi XML già su introdotta:

Esempio:

http://urlcrm/crm/getcrminfo.aspx?params=<execsql><connection>TEST</connection>

<user>ADMIN</user><password>12345Aa!</password><sqlcommandid>272</sqlcommandid>

Premendo Aggiorna si ottengono in ogni momento le informazioni aggiornate direttamente dal CRM attraverso una semplice connessione Web (su protocollo Http:80).

In alternativa è possibile utilizzare il file xlsM (richiede l'abilitazione delle MACRO per poter lavorare correttamente) che viene fornito come esempio insieme al CRM, che si presenta come segue:

MEGABIBLOS: DOWNLOAD DOCUMENTI TRAMITE SERVIZI WEB

Il servizio Web GETCRMINFO.aspx consente di scaricare dal CRM i documenti presenti all'interno dell'archivio Megabiblos. E' così possibile ottenere un file archiviato nel CRM con una semplice chiamata HTTP, utilizzando delle credenziali di accesso che abbiano il permesso di visualizzare il documento richiesto.

Per farlo è sufficiente conoscere preventivamente il Codice del documento, ricavabile in modo semplice dalla finestra "Proprietà del documento" all'interno della gestione Megabiblos oppure dal campo Documenti.CodiceDoc.

Solitamente viene fatta prima una chiamata a GETCRMINFO per sapere la lista dei documenti da scaricare (con relativo "Codice") e successivamente una chiamata per ognuno di essi.

La chiamata Web segue lo standard già illustrato ma con il parametro <megabiblosid> valorizzato.

Vediamo un esempio:

http://serverCRM/urlCRM/getcrminfo.aspx?params=<execsql>

<connection>CONNESSIONE</connection><user>ADMIN</user>