VERSIONE: 1.0

INTRODUZIONE

ITEMSync è un programma ETL sviluppato in .NET in grado di connettersi ad una base dati MS SQL e gestire una sincronizzazione tra viste/tabelle ed i corrispondenti moduli presenti nel CRM. L'iterazione con il CRM avverrà esclusivamente via API con chiamata HTTPS.

Il programma può essere eseguito manualmente oppure come operazione pianificata (di solito ogni 5-10 minuti, ma è possibile definire una frequenza specifica per ogni regola).

Tramite ITEMSync sarà possibile creare nuove regole per mappare una vista/tabella presente a database con il corrispondente modulo nel CRM. Una volta definiti i campi chiave di collegamento sarà possibile specificare la corrispondenza tra i campi della vista/tabella ed il relativo campo nel CRM. Sono gestiti anche i moduli inventario, quindi è possibile importare da database a crm Preventivi, Ordini, Fatture.

ITEMSync permette inoltre di alimentare tabelle presenti nella base dati MS SQL estraendo record dal CRM. Ad esempio è possibile riportare in una tabella di frontiera nel database i nuovi clienti registrati nel CRM a fronte del primo Ordine acquisito oppure riportare testata e righe dei nuovi ordini.

PREREQUISITI

Il programma ITEMSync può essere installato su qualsiasi PC o server Windows. Di seguito riportiamo le caratteristiche minime:

• Spazio disco 1GB
• Ram minima 2GB
• CPU minima 1core
• framework .NET 4.8 o superiore

Il programma ITEMSync dovrà potersi connettere all’istanza MS SQL da cui dovrà leggere i dati (viste o tabelle). Prima di procedere all’installazione è opportuno farsi creare un database (es. ETL_CRM) dedicato all’interno dell’istanza SQL SERVER da cui dovranno essere letti e scritti i dati. E’ buona norma farsi creare un utente dedicato che abbia pieno accesso al database ETL_CRM in quanto dovrà poter creare, modificare, cancellare tabelle/viste. All’interno di questo database dovranno essere messe a disposizione tabelle e viste su cui leggere e/o scrivere. E’ buona norma che l'utente non abbia diritti di scrittura fuori da tale database così da evitare di creare accidentalmente modifiche indesiderate.

** La gestione del database dedicato a ITEMSync (es. ETL_CRM) sia in gestione al cliente sia in termini di manutenzione che di backup. **

Il programma ITEMSync si collegherà al CRM tramite protocollo https (quindi usando la porta 443). Per farlo dovranno essere abilitate le connessioni in uscita verso il server crm (es. https://crmcliente.opencrmitali.com) e verso gli applicativi di monitoraggio (https://panel.opencrmitalia.com e https://monitoring.opencrmitalia.com).

INSTALLAZIONE

Per installare il programma è necessario avere a disposizione una macchina windows che supporti framework .NET 4.6.1 o superiore.

Prima di procedere all’installazione è opportuno farsi creare un DATABASE dedicato all’interno dell’istanza SQL SERVER da cui dovranno essere letti i dati (o scritti). E’ buona norma farsi creare un utente dedicato che abbia pieno accesso al database in quanto dovrà poter creare, modificare, cancellare tabelle/viste. All’interno di questo database dovranno essere messe a disposizione tabelle e viste su cui leggere e/o scrivere. E’ buona norma che l'utente non abbia diritti di scrittura fuori da tale database così da evitare di creare accidentalmente modifiche indesiderate.

L’installazione consiste nel copiare i seguenti file nella cartella del programma (di norma C:\Program Files (x86)\ITEMSync):

• ITEMSync.exe
• ITEMSyncLib.dll
• ITEMUtility.dll
• VTigerNetApi.dll
• Jayrock.Json.dll
• FontAwesome.Sharp.dll

Alla prima esecuzione di ITEMSync.exe comparirà una maschera in cui dovranno essere inseriti i parametri di connessione all’istanza MS SQL.

Al salvataggio sarà creato il file ITEMSync.exe.Settings contenente questi dati (con la password cifrata).

Completata questa fase di setup il programma si riavvierà e comparirà il messaggio che indica che i parametri di connessione all’istanza crm non sono inseriti in modo corretto:

Sarà sufficiente compilare i parametri e proseguire.

Valorizzare i PARAMETRI con i riferimenti al CRM:

• CMRURL: url del CRM
• CRMUSER: utente del CRM (creare utente specifico con diritti di admin)
• CRMACCESSKEY: non è la password ma l’accesskey (ultimo parametro nei dettagli utenti)

A questo punto se i parametri di connessione sono corretti dovreste trovarvi in questa schermata.

Per completare il setup è necessario creare un’operazione pianificata di windows.

Attenzione ai parametri, deve essere selezionata l’opzione: “Esegui indipendentemente dalla connessione degli utenti”.

Si consiglia di crearne una con esecuzione ripetuta ogni 5 minuti.

Usare il parametro di esecuzione “AUTO” per non far aprire la form.

Nota bene: ITEMSync non è necessario sia installato sul server dove risiede MS SQL è sufficiente che lo possa raggiungere.

INFORMAZIONI PRELIMINARI

In fase di progettazione di uno scambio dati tra due sistemi deve essere analizzato l’intero flusso, in particolar modo quando il flusso è bidirezionale è necessario avere la dovuta visione d’insieme.

Prima di attivare ITEMSync è fondamentale verificare che:

• i moduli oggetto di sincronizzazione non abbiamo WF che scattino alla creazione/salvataggio onerosi (es. Loop sugli utenti, invio email,…). In caso di problemi di sincronizzazione la prima causa è infatti dovuta a WF che mandano in timeout i webservices. Se ci troviamo nelle condizioni di dover comunque implementare tali WF allora è meglio inserire un blocco di esecuzione ritardata (impostazione WF in modalità ritardata) così che la chiamata webservice si conclude subito ed al primo run dello scheduler il WF viene completato.
• I moduli non presentino regole di gestione duplicati che possano far fallire la creazione/modifica (flusso SQL2CRM).
• La Suite Opencrmitalia sia alla versione 7.14 o superiore
• Esiste un database (Es. XXX_ETLCRM) con all’interno le tabelle o le viste contenente i dati da riportare nel CRM o le tabelle dove riportare i dati dal CRM. E’ importante che l’utente di connessione alla base dati MS SQL abbiamo piene autorizzazioni sul database (creazione/cancellazione oggetti, chiavi,…)

ITEMSync è un motore in grado di eseguire una serie di REGOLE. Per regola si intende l’insieme delle configurazioni per portare da SORGENTE a DESTINAZIONE dei dati.

TIPI DI REGOLE

ITEMSync gestisce le seguenti tipologie di regole:

• SQL2CRM: accetta come SORGENTE una vista o una tabella e come destinazione un MODULO del crm. Saranno resi disponibili tutti i moduli presenti a CRM compresi quelli custom creati tramite il gestore moduli. Queste regole gestiscono CREAZIONE, MODIFICA e CANCELLAZIONE.
• CRM2SQL: accetta come SORGENTE una query (non è una query SQL ma una query accettata dalle API della Suite Opencrmitalia) e come DESTINAZIONE una tabella del database MS SQL. Queste regole gestiscono CREAZIONE e MODIFICA
• CRM2NTS: accetta come SORGENTE una query (non è una query SQL ma una query accettata dalle API della Suite Opencrmitalia) e come DESTINAZIONE un set di identità specifiche del software gestionale NTS Business Cube: Clienti, Sedi, Fornitori, Prodotti, Ordini, Documenti (DDT, Fatture,..).

ITEMSync può essere eseguito sia manualmente sia su base schedulata, ogni regola ha uno stato, una frequenza di elaborazione ed è soggetta a monitoraggio.

GESTIONE ASSEGNATO A

È possibile pilotare l’assegnatario dei record scritti da ITEMSync nel crm nei seguenti modi:

1. Impostando un valore fisso a livello di mapping. Nota bene “19x1” vuol dire “19” users con id “1” (admin).
2. Aggiungere al punto precedente una post elaborazione a livello CRM con un WF che in base a criteri personalizzati cambia l’assegnato a. In questo scenario viene usato spesso il modulo AGENTI. Quindi nel mapping viene riportato anche il crmid dell’agente (modulo uitype10) ed il WF riporta l’assegnatario dell’agente sul record
3. Creare a livello di ERP un campo sugli agenti in cui manualmente riportare il crmid (nel formato “19x”). Nel mapping l’assegnatario sarà impostato con questo campo personalizzato dell’anagrafica agente. Per gestire il caso di agente mancante o codice mancante è previsto all’interno di ITEMSync la possibilità di impostare un assegnatario di default per ogni regola (modulo).
4. È possibile inoltre non mappare questo campo. Anche se è obbligatorio in caso di mancata mappatura il connettore in caso di creazione imposterà di default il valore (‘19x1’ assegnando tutto all’utente admin). In fase di modifica però non modificherà l’assegnatario presente.

UTILIZZO

Il programma si presenta con la seguente interfaccia:

Tale interfaccia sarà utilizzata per le fasi di impostazione iniziale e di esecuzione manuale, la normale fase di utilizzo prevede invece che l’esecuzione avvenga su base panificata (task manager di windows) e che non si aprano finestre di programma.

AVVIA LA SINCRONIZZAZIONE: invoca la sincronizzazione (una volta configurato) allo stesso modo in cui viene eseguita dall’operazione pianificata. Ad ogni esecuzione il sistema eseguirà le regole attive eseguita da più di X minuti, dove X è la FREQUENZA (parametro sempre definito all’interno della singola regola).

IMPOSTAZIONI Permette di accedere all’area impostazioni (vedi seguente paragrafo)

DATI DI CONNESSIONE AL DATABASE

**CHIUDE IL PROGRAMMA **

IMPOSTAZIONI

Per accedere alle maschere che permettono la definizione delle regole è richiesta una password per evitare che un utente del cliente possa modificarle.

La password di default è “Password”, è modificarla a piacimento all’interno della sezione PARAMETRI.

Una volta inserita la password il sistema in automatico aprirà l’elenco delle regole.

L’utente avrà a disposizione queste due azioni:

Salva/Conferma

Annulla/Esco dall’area settings

Se la password è corretta l’utente potrà accedere all’elenco delle REGOLE di sincronizzazione.

Centralmente sono visibili le regole di sincronizzazione, a destra si apre un menù contenenti le azioni:

SALVA le modifiche apportate alle regole.

AGGIUNGI REGOLA: permette di aggiungere una nuova regola

UTILITY: in fase di prima configurazione carica le regole di default, permette inoltre di migrare le regole da myddleware. Permette anche di gestire i controlli sui campi mappati (es. Se il campo esiste nel CRM e se è attivo)

PARAMETRI: permette di accedere all’area parametri

Filtra solo le regole attive per migliorare la leggibilità

Permette di visualizzare informazioni aggiuntive delle regole

DEBUG: abilita messaggi aggiuntivi in fase di sincronizzazione

CHIUDE AREA IMPOSTAZIONI

• ID Identificativo numerico univoco delle regole. Campo di sola lettura non modificabile
• Relations Apre l’area di configurazione delle relazioni (es. Cliente – Metodo di pagamento)
• Mapping Apre l’area di configurazione della mappatura attributi. Singolo campo della sorgente con singolo campo della destinazione
• Retrive Apre la procedura che accede alla destinazione, recupera i record (campo chiave) e li considera come “sincronizzati”.
• TIPO ORDINE Tipologia di regola SQL2CRM, CRM2SQL, CRM2NTS. Campo non modificabile. Sequenza di esecuzione delle regole sia nell’operazione pianificata sia nell’esecuzione manuale
• ATTIVA STATO Loro le regole attive sono oggetto di sincronizazione. Stato di elaborazione della regola: In caso di stati S o E ITEMSync proverà a risottomettere la regola dopo un tempo di 20 ore dall’ultima esecuzione.
  • N non in esecuzione,
  • S in esecuzione,
  • E in errore.
• REGOLA Nome della regola. Il valore di questo campo ha il solo obiettivo di dare un nome parlante.
• SORGENTE In base al tipo di regola assumerà diversi valori: SQL2CRM: il nome ad una vista/tabella presente a database CRM2SQL o CRM2NTS: la query di estrazione dati dal CRM. SELECT * | column_list | FROM object LEFT JOIN object [WHERE conditionals] [ORDER BY column_list] [LIMIT [m, ] n]

* **column_list** Comma separated list of field names. 
* **object** Type or Module Name. 
* **conditionals** <condition_operations> or <in_clauses> or <like_clauses> separated by ‘and’ or ‘or’ operators these are processed from left to right. The are no grouping that is bracket operators. 
* **condition_operations** <, >, <=, >=, =, != 
* **in_clauses** in () 
* **like_clauses** like ‘sqlregex’ 
* **value_list** a comma separated list of values. 
* **m, n** integer values to specify the offset and limit respectively. 

    LIMITI: 

    * sono supportate solo le LEFT JOIN, in numero massimo di 10 
    * La SELECT dovrà sempre riportare * così da estrarre sempre tutti i campi 
    * tutte le query hanno un limite di estrazione di massimo 100 record        

    ESEMPI:

    * SELECT * FROM Products WHERE inviare_a_gestionale='Da inviare'
    * Select * from Invoice LEFT JOIN Accounts on Invoice.account_id=Accounts.id    LEFT JOIN ModalitaPagamento on  ModalitaPagamento.id=Invoice.condizioni_pagamento LEFT JOIN Users on Users.id=Accounts.assigned_user_id where stato_invio_gestionale='Da inviare'  and serie='FTS' 
    * Select * from LineItem LEFT JOIN Invoice on LineItem.parent_id=Invoice.id LEFT JOIN Products on LineItem.productid=Products.id LEFT JOIN Services on LineItem.productid=Services.id LEFT JOIN SuiteTaxRates on SuiteTaxRates.id=LineItem.suitetaxrate_id

DESTINAZIONE In base al tipo di regola assumerà diversi valori: * SQL2CRM: il nome del modulo del CRM * CRM2SQL: la vista/tabella destinazione nel database * CRM2NTS: il modulo di atterraggio in Business Cube: Clienti, Sedi, Prodotti, Ordini, Documenti

**INVENTARIO ** Identifica se la regola deve gestire moduli con righe inventario (Preventivi, Ordini, Fatture). Sarà selezionato sia sulla regola relativa alla testata che a quella relativa alle righe. E’ previsto infatti che siano sempre presenti due regole correlate tra loro (vedi relazioni) ma dove è possibile gestire in modo indipendente la mappatura.

**CANCELLAZIONE ** Identifica se la regola deve gestire anche la cancellazione. La funzione è disponibile solo per le regole di tipo SQL2CRM. Quindi a fronte della mancanza di un record nella tabella/vista di sorgente andrà a cancellare il corrispondente record nel modulo CRM.

**LIMITE ** Numero di record che saranno sincronizzati ad ogni esecuzione. Si consiglia di impostare il valore a poche unità nella fase di setup.

FREQ (min) Indica la frequenza con cui deve essere eseguita la regola espressa in minuti.

LAST RUN Viene riportata la data e ora dell’ultima esecuzione. Questo campo è modificabile al fine di poter forzare alcune esecuzioni

CAMPO CHIAVE SORG. Nome del campo che viene usato come identificativo univoco del record nella sorgente. N.B. E’ sempre necessario che ci sia un campo univoco. ITEMSync utilizza questa i campi chiave (sorg. e dest.) per collegare in modo corretto sorgente e destinazione. In fase di attivazione di una nuova regola viene eseguito il controllo di univocità.

CAMPO CHIAVE DEST. Nome del campo della destinazione dove viene riportato il valore del campo chiave.

PIÙ COLONNE Abilitando le colonne aggiuntive

SORGENTE DIFF Solo nel caso di regola SQL2CRM ITEMSync genera in automatico una nuova vista (con lo stesso nome di quella originale con suffisso _ITEMSYNC). Questa vista è necessaria per calcolare la differenza (DIFF.) tra i record presenti in questo momento nella tabella/vista di frontiera e l’esecuzione precedente. In questo modo il sistema è in grado di estrarre i record modificati anche in assenza di un campo di DATA ORA ULTIMA MODIFICA. Questo campo va lasciato vuoto e viene popolato in automatico da ITEMSync.

**CAMPO DATA AGG. ** Nome del campo di tipo data e ora che può essere usato per rilevare i record modificate nella sorgente. Questo campo è OPZIONALE, ITEMSync in assenza calcolerà le differenze basandosi sulla generazione di una hash.

**CAMPO HASH DEST ** Nome del campo di tipo stringa presente nella destinazione in cui sarà riportato il valore dell’hash del record. Questo campo è OPZIONALE, ITEMSync in presenza di questo campo lo popolerà con l’hash e lo userà nella procedura di quadratura.

ASSEGN. DEFAULT Permette di specificare un assegnatario di default da usare nelle regole SQL2CRM.

QUADR.(min) Valido solo per le regole SQL2CRM, indica ogni quanti minuti deve essere eseguita la procedura di quadratura. È la procedura che recupera dalla destinazione tutte le chiave, le confronta con quelle presenti nella vista sorgente forzando eventuali riallineamenti (cancellazioni o creazioni, non lavora in modifica). Se non si desidera eseguire la quadratura è sufficiente inserire il valore 0.

LAST QUADR Indica data e ora dell’ultima quadratura

DURATA ELAB Riporta la durata dell’ultima sincronizzazione. Può essere un’informazione utile al consulente per verificare il corretto funzionamento.

AGGIUNGI REGOLA

Il pulsante permette di aggiungere nuove regole.

Una volta dato il nome alla regola, se il nome risulta univoco, verrà proposta la scelta della tipologia:

TIPO È possibile scegliere tra: SQL2CRM, CRM2SQL, CRM2NTS

Selezionato il tipo sarà possibile definire il sorgente e la destinazione

SORGENTE È possibile digitare manualmente oppure è possibile trascinare il contenuto dalla lista a sinistra

DESTINAZIONE È possibile digitare manualmente oppure è possibile trascinare il contenuto dalla lista a destra

MODULO INVENTARIO Abilitato significa che si sta configurando un modulo testata che richiede anche la parte relativa alle righe inventario

ABILITA CANCELLAZIONE Se abilitato sarà gestita anche la cancellazione: quando un record nella sorgente non è più disponibile sarà eliminato nella destinazione

FREQUENZA SYNC Numero minimo di minuti che deve intercorrere tra due sincronizzazioni della regola. Se non specificato viene inserito di default 5 min.

FREQUENZA CTRL Numero minimo di minuti che intercorre tra una verifica di controllo. ITEMSync quando esegue il controllo recupera dalla destinazione tutti i record con campo chiave non vuoto e li controlla con la tabella sorgente. Se un record presente nella destinazione non è più persente nel sorgente sarà cancellato dalla destinazione.

Dopo aver premuto il pulsante SALVA sarà possibile continuare la configurazione.

Sarà possibile compilare manualmente o mediante drag&drop i seguenti campi:

SORGENTE Campo chiave È la chiave univoca della sorgente

SORGENTE Ult Agg Se nella vista/tabella sorgente è presente un campo data ora contenente l’ultima modifica è possibile specificarlo.

DESTINAZIONE Campo Chiave È il campo in cui sarà salvato la chiave univoca.

DESTINAZIONE Campo Hash Campo opzionale per salvare l’hash dell’ultima sincronizzazione

Completata questa fase, se tutti i dati sono corretti il sistema rimanderà alla maschera delle regole dalla quale sarà possibile procedere all’inserimento delle RELATIONS e MAPPING.

Per nuove installazioni bisogna rispondere sempre NO. Solo nel caso in cui ci sia già un processo di sincronizzazione in corso e non si vuole risincronizzare tutto il pregresso allora rispondere SI.

CASO PARTICOLARE PREZZI DI LISTINO

Meritano una gestione a parte i prezzi di listino in quanto all’interno del CRM non sono gestiti come modulo entità e pertanto non hanno un crmid. Tecnicamente sono “solo” una riga nella tabella vtiger_pricebookproductrel.

Sarà necessario che la vista/tabella di partenza nella sincronizzazione SQL2CRM riporti come campo chiave la concatenazione della chiave del listino con la concatenazione della chiave del prodotto.

La mappatura di questo modulo ha delle peculiarità in quanto oltrea al prezzo ed agli ID di listino e prodotto non è mappabile altro.

In automatico sarà aggiunto il campo target_key_field collegato al campo chiave della source di inizio.

CASO PARTICOLARE GESTIONE FILE

Meritano una gestione a parte l’importazione di DOCUMENTI (qualsiasi estensione di file). E' previsto che sia fornita una tabella/vista SQL di partenza che contenga una riga per ogni file che si vuole importare nel CRM. Uno dei campi conterrà il nome file con path completo.

È previsto che tramite il consueto sistema di mapping sia possibile definire quali fields del modulo Documents del CRM debbano essere alimentati. E’ previsto che sia mappato il campo speciale “FULLFILENAME” con il nome completo del file (compreso il path).

Per ogni riga presente nella Tabella/Vista di frontiera ITEMSync si occuperà di creare il relativo Document comprensivo di upload file.

È previsto che sia possibile definire mappare le relazioni tra il file ed i record a cui questo debba essere collegato.

Per relazionare il documento a dei record è necessario mappare le chiavi sul record e far creare la relazione tramite workflow.

SETUP E CONTROLLO

In presenza di nuove installazioni il pulsante permette di importare delle regole di default.

Nel caso di migrazione da Myddleware tramite questo pulsante si attiva la procedura guidata di importazione regole.

La fase di CONTROLLO invece aiuta il consulente a verificare che le regole ed i campi siano coerenti. Ad esempio verifica la presenza delle tabelle/viste su sorgente e destinazione fino ad arrivare alla verifica dell’esistenza dei singoli campi mappati.

PARAMETRI

All’interno dell’area settings è possibile accedere alla sezione parametri mediante il pulsante .

All’interno è possibile specificare i parametri di accesso al CRM e la modificare la password per accedere all’area settings.

RELATIONS

ITEMSync converte in automatico il valore contenuto nel CAMPO CHIAVE FIGLIO nell’ID del padre. Ad esempio nella sincronizzazione SQL2CRM al posto del COD_IVA sarà preso il crmid corrispondente al codice iva.

Tramite queste relazioni è possibile specificare se si vuole vincolare la sincronizzazione di un modulo ad un altro. Esempio i clienti potranno essere sincronizzati solo se il suo codice iva è già presente nel CRM. In altre parole, se il connettore sa che a quel codice iva corrisponde un crmid allora renderà sincronizzabile il cliente altrimenti no.

A partire dal pulsante Relations è possibile accedere all’elenco di relazioni di uno specifico modulo.

ATTIVO Identifica se la relazione è ATTIVA

MODULO PADRE Indica data e ora dell’ultima quadratura

CAMPO CHIAVE PADRE, MODULO FIGLIO, CAMPO CHIAVE FIGLIO Riporta la durata dell’ultima sincronizzazione. Può essere un’informazione utile al consulente per verificare il corretto funzionamento.

TIPO Tipo di relazione: * OPZIONALE: accetta che il campo sia vuoto, ma se è compilato il valore deve corrispondere ad uno dei valori del modulo PADRE. Esempio: il codice iva dell’anagrafica articolo. * OBBLIGATORIO: non accetta che il campo sia vuoto, il valore deve corrispondere ad uno dei valori del modulo PADRE. Esempio: il codice cliente nella testata di un ordine. * INVENTARIO: indica la relazione tra la testata di un documento e le sue righe.

MODIFICA Permette di accedere all’area di MODIFICA in cui sarà possibile modificare i campi padre e figlio ed il tipo di legame

Da qui tramite il pulsante è possibile eliminare la relazione.

Permette di definire una nuova relazione

I campi MODULO PADRE e MODULO FIGLIO possono essere compilati manualmente o tramite drag&drop. Dopo aver premuto il pulsante sarà possibile valorizzare il TIPO di relazione ed i campi chiave sempre tramite drag&drop.

MAPPING

Per ogni modulo è possibile consultare e modificare i mapping.

A sinistra la prima lista contiene l'elenco dei campi disponibili nella sorgente (sola lettura).

La lista MAPPING contiene i riferimenti del campo SORGENTE e del campo DESTINAZIONE (alcuni campi sono modificabili altri ereditati).

Al primo caricamento vengono create in automatico tante righe quanti sono i campi presenti nella destinazione. In questa tabella è possibile eliminare le righe che non interessano e compilare il CAMPO DEST. NOME per i rimanenti.

Elenco impostazioni:

CREAZIONE Se selezionato il campo viene considerato nel mapping in fase di creazione di un nuovo record destinazione

AGGIORNAMENTO Se selezionato il campo viene considerato nel mapping in fase di modifica di un record destinazione esistente

CTRL DUPLICATI Indica se il campo deve essere usato per evitare i duplicati. ITEMSync quando non trova corrispondenza tra CAMPO CHIAVE SORG e CAMPO CHIAVE DEST verificherà se nella destinazione esiste un altro record avente gli stessi valori dei campi che hanno il CTRL DUPLICATI abilitato (le condizioni saranno in AND).

CAMPO SORG è il nome del campo della sorgente. Per associare un campo della SORGENTE con uno della DESTINAZIONE è sufficiente trascinare il campo dalla lista a sinistra sulla riga desiderata. E’ possibile in ogni caso variare questo campo manualmente. E’ possibile usare valori fissi (compresi tra apice semplice) e anche formule.

• SQL2CRM: possono essere usate tutte le funzioni SQL, non è richiesta una sintassi particolare. Esempi: Coalesce(campo1,’AA’), CASE WHEN campo1=’A’ THEN campo2 ELSE campo1 END...
• CRM2SQL/CRM2NTS:Tutte le formule prevedono che per identificare una formula tutto venga inserito tra parentesi quadre, i campi sorgente vanno inserito tra parentesi graffe. Esempi 'A' COALESCE: Esempio [COALESCE({condizioni_pagamento.codice_pagamento},'28')] SUBSTRING: Esempio: [{invoice_no}.substring(9,4)]

AGGIORNA A indica note relative al campo nella destinazione. Si possono inserire stringhe (non usare gli apici per delimitarle) oppure una delle seguenti variabili: * LOG: viene riportato il messaggio d’errore (consigliato utilizzo di un campo TEXT come destinazione) * CODICE: è il codice ritornato dal gestionale (es. Codice cliente, numero ordine,…) * STATE: lo stato sarà sempre impostato a: * Sincronizzato * Scartato Da notare che se questo campo è valorizzato non è necessario sia flaggato come CREAZIONE o AGGIORNAMENTO, sarà preso in considerazione in ogni caso. Di fatto il campo CAMPO DEST. NOME ininfluente.

CAMPO DEST. ETICHETTA è l’etichetta del campo della destinazione. Non modificabile. CAMPO DEST. NOME è il nome del campo della destinazione. Non modificabile. OBBLIGATORIO indica se il campo nella destinazione è obbligatorio. Non modificabile. TIPO CAMPO indica il tipo del campo nella destinazione. Non modificabile. NOTE indica note relative al campo nella destinazione. Non modificabile.

RETRIEVE

Funzionalità attiva solo per il tipo SQL2CRM e permette di scaricare massivamente dal CRM tutti i record che hanno il CAMPO CHIAVE DEST valorizzato. Se è presente anche il campo hash viene scaricato anche quello. In questo modo sarà popolata con tempi molto veloci la tabella di frontiera ITEMSYNC_ROW e si eviterà di sincronizzare inutilmente record che hanno lo stesso chiave ed hash.

APPROFONDIMENTI

LOGICHE DI FUNZIONAMENTO

Per ogni esecuzione del programma, per ogni modulo oggetto di sincronizzazione con data ultima esecuzione più vecchia di SYNCRO_FREQUENCE minuti il programma esegue i seguenti passaggi:

• ITEMSync_sync - Inserisce in ITEMSync_ROWS per quel modulo (id_module, key_value, hash_value, last_update)
• ITEMSync_sync - Aggiorno le righe in ITEMSync_ROWS aggiornando la data di ultima modifica dove l’HASH è diversa tra quella memorizzata su ITEMSync_ROWS e quella ricacolata con i dati attuali della vista source.
• ITEMSync_sync - Aggiorno data last_syncro sulla tabella ITEMSYNC_SETTINGS_ENTITIES per tracciare il run
• In cascata viene richiamata la sincronizzazione verso il crm (ITEMSync_syncAPI) per il modulo specifico così da prendere i record con ULT_AGG maggiore dell’ultimo syncro (last_syncro_api) oppure quelli con crmid vuoto. Per ogni record
  • Se nella tabella di frontiera ITEMSync_ROWS esite il crmid allora vado in aggiornamento
  • Se non esiste il crmid ricerco che esiste un record nel crm con target_key_field con quel valore. Se lo trovo aggiorno
  • Altrimenti creo un nuovo elemento nel crm
  • Il crmid ritornato viene salvato in ITEMSync_ROWS

CONFIGURAZIONE SPECIFICA NTS

ITEMSync contiene al suo interno una configurazione predefinita per collegare NTS al CRM.

Tramite il pulsante “SETUP/CTRL” sarà richiesto all’utente se vuole caricare questo default, in caso affermativo il programma:

• Crea le viste “ETL_ERP2CRM...”
• Carica nelle tabelle ITEMSYNC_SETTINGS_ENTITIES, ITEMSYNC_SETTINGS_MAPPING e ITEMSYNC_SETTINGS_RELATIONS la mappatura di default
• Lancia il controllo della presenza nel CRM dei moduli e dei campi oggetto della mappatura

Per completare l’installazione copiare nella directory di NTS I file BNHHITEM.dll. Creare le seguenti impostazioni di registro:

• MastroCliente es “901”
• Debug “0”

Le funzioni di importazione da NTS a CRM comprendono le entità:

• Codici IVA
• Agenti
• Listini
• Famiglia
• Contropartite Vendite
• Contropartite Acquisto
• Ruoli Aziendali
• Zone Geografiche
• Lingua
• Stati Esteri
• Categorie Cli - For
• Tipi pagamento
• Tipi documento
• Marche
• Gruppi_Merceologici
• UnitaMisura
• Anagrafica Clienti
• Destinazioni diverse
• Contatti
• Prodotti
• Prezzi di Listino e Sconti
• SCONTI
• Preventivi
• Impegni cliente
• DDT
• Fatture
• Scadenze

Le funzioni di importazione da CRM a NTS prevedono la possibilità di importare:

• Clienti (non è prevista la gestione della parte lead)
• Sedi
• Contatti
• Impegni
• DDT o Fatture

DATABASE DIVERSI DA MS SQL

ITEMSync può essere utilizzato anche quando la base dati di partenza è diversa da MS SQL.

In presenza ad esempio di database AS400, Oracle, Mysql, Sybase, Postgress, fireboard,... È possibile utilizzare infatti un database MS SQL come frontiera per renderli compatibili con ITEMSync.

In questo caso sarà sufficiente installare la versione gratuita di MS SQL Express (https://www.microsoft.com/it-it/download/details.aspx?id=101064) ed all’interno configurare il database non MS SQL come LINKED SERVER (https://learn.microsoft.com/it-it/sql/relational-databases/linked-servers/create-linked-servers-sql-server-database-engine?view=sql-server-ver16)

Sarà sufficiente avere il connettore alla base dati desiderata. Di fatto ogni connessione ODBC può essere utilizzata per creare un linked server.

ROADMAP

• Implementare processo di ereditarietà sull’assegnato (es. AGENTE --> CLIENTE). Introdurre tipo relazione A (assegned_user_id). Dovrà essere fatto un controllo di congruità ASSEGNATI- UTENTI come prima cosa.
• Procedura di cambio campo CHIAVE. Molto utile nel caso di aggiornamento di CRM esistente, in particolare quando il cliente passa da e/ a NTS
• ESEMPIO update r set r.key_value=COD_CLIENTE from ITEMSYNC_ROWS r inner join ETL_ERP2CRM_Clienti_ITEMSYNC on key_value=codesa and id_module=3
• Creare un sistema di controllo tra mappature di SQL2CRM e CRM2SQL.
• Possibilità di cancellare una regola (aggirabile al momento tramite cancellazione a database)
• Introdurre sistema di simulazione regole (aggirabile impostando il limite di esecuzione a 1)
• Introdurre gestione FUNZIONI CONCAT E IF

[00.00.06] - WIP

• Implementare processo guidato creazione relazioni
• Permettere di importare file (es. PDF, Word,…) posizionati nel file system locale al CRM con relativi collegamenti alle entità (es. Import PDF su Fattura)
• Completare interfaccia utente introducendo dropdown control nelle datagridview
• Dettagliare nel manuale il funzionamento della QUADRATURA (solo SQL2CRM).
• Introdotta gestione ERRORE: “DATABASE_QUERY_ERROR: Database error while performing requested operation”. Solo a fronte del verificarsi di questo errore il connettore non aggiornerà la tabella ITEMSYNC_ROW. In questo modo la sincronizzazione del record riprenderà alla prossima esecuzione.

[00.00.05]

• SQL2CRM: Portare a livello di ITEMSYNC_SETTINGS_ENTITIES Assegnato a di default ed implementare logica: se assegnatario vuoto prendo quello di default
• SQL2CRM rivedere parte modifica. Differenziato comportamento tra CREATE e UPDATE. Nel caso in cui in aggiornamento non venisse passato il campo assegnato_a sarà recuperato dal valore corrente
• CRM2SQL E’ già previsto i campo target_field_lenght per definire la lunghezza massima del campo. Il connettore dovrà troncare i valori eccedenti. Forzata scrittura su MS SQL con troncamento in caso di superamento della lunghezza fisica dei campi
• SQL2CRM Introdotta possibilità di utilizzare qualsiasi costrutto SQL
• Evoluta maschera gestione REGOLE per bloccare i campi non usati in base al tipo (SQL2CRM, CRM2SQL, CRM2NTS).
• Evoluta maschera gestione REGOLE per poter filtrare solo le regole attive
• Evoluta maschera MAPPING per poter filtrare solo le righe attive
• SQL2CRM: evolute logiche di HASH per far logica solo sui campi mappati (inserimento/modifica) e non su tuti quelli presenti nella sorgente.
• Aggiungere un TOP XX record in fase di selezione (parametrico a livello di ENTITY)
• Introdurre controlli preliminari su univocità dei campi chiave

[00.00.04]

• Risolto problema di record con DELETED=0 nella tabella ITEMSYNC_ROWS. Questo faceva sì che se quel record era richiesto come “padre” il figlio non veniva estratto dalle viste _ITEMSYNC. Oltre ad installare il nuovo file è opportuno lanciare la rigenerazione delle viste.
• Evoluta gestione esiti. Introdotte le parole chiavi nel campo SOURCE_UPDATE_VALUE:
  • LOG: viene riportato il messaggio d’errore (consigliato utilizzo di un campo TEXT come destinazione)
  • CODICE: è il codice ritornato dal gestionale (es. Codice cliente, numero ordine,…)
  • STATE: lo stato sarà sempre impostato a:
    • SINCRONIZZATO
    • SCARTATO

[00.00.03]

• Realizzare flusso inverso da CRM a Database anche in aggiornamento. Sdoppiata configurazione nel mapping per poter definire quali campi devono essere riportati in creazione e quali in modifica.
• SQL2CRM Gestione cancellazione con flag a livello di ENTITIES. Per ogni record presente nella ITEMSYNC_ROWS che non è presente nella vista di partenza lancia la cancellazione nel CRM direttamente per crmid.
• SQL2CRM Quadratura: controllo impostabile per singola regola (campo integrity_check_frequence per definire il numero di minuti che intercorre tra due quadrature). La quadratura recupera dal CRM tutti i crmid dei record che hanno il campo chiave popolato. Li salva sulla tabella ITEMSYNC_ROWS_TMP e poi aggiorna o cancella l’hash dei record sulla ITEMSYNC_ROWS per i record che non tornano
• CRM2SQL: all’interno del mapping è stato introdotto il campo source_update_value che permette di definire il valore che dovrà assumere il campo specifico nel CRM a fronte della corretta sincronizzazione CRM2SQL. Esempio: importo un cliente che ha stato connettore DA IMPORTARE e lo faccio diventare SINCRONIZZATO. Funziona sia su moduli entità normali che moduli inventario. Per questi secondi è necessario utilizzare l’ultima versione VTigerNetApi.dll (08/05/2023).
• Aumentate performance: introdotta ricostruzione indici della tabella ITEMSYNC_ROWS ad ogni chiusura programma
• Evoluta iterazione con MONITORING: ora le regole disattivate vengono contrassegnate come tali anche in MONITORING per evitare inutili notifiche di ritardo.
• 16/05/2023 Risolto problema di CRM2SQL nel caso in cui nessun campo viene impostato nell’UPDATE.

[00.00.02]

• Realizzare flusso inverso da CRM a Database CRM2SQL

[00.00.01]

• Procedura di registrazione automatica su monitoring.opencrmitalia.com per gestire l’attivazione e quindi la chiave
• Procedura di log e gestione errori su monitoring.opencrmitalia.com

NON FARE

• Campi picklist con multiselezione: ma come capisco che in partenza sono più valori? Tanto vale far creare il campo con la giusta formattazione nella vista?