Sommario
Nel presente articolo sono descritti i passi necessari da seguire per poter accedere ad un documento di Perfetto utilizzando la tecnologia Magic Link. La descrizione dei passaggi è arricchita da stralci di codice scritti in linguaggio C#.
Autenticazione
Per poter effettuare una qualsiasi operazione su un documento di Perfetto è necessario essere autenticati al sistema di sicurezza del prodotto.
Il Web Service che si occupa dell'autenticazione al prodotto è il "LoginManager".
I metodi web del LoginManager che effettuano l'autenticazione al sistema sono "Login" e "LoginCompact".
Tali metodi a fronte di un nome utente, un nome azienda, una password e una producer key validi restituisco un codice di autenticazione.
Il codice di autenticazione sarà utilizzato per effettuare le successive chiamate ai metodi web, che gestiscono le operazioni relative ai documenti.
Di seguito è mostrato come è possibile autenticarsi mediante la chiamata al metodo LoginCompact:
string authToken = string.Empty;
string userName = "PerfAdmin"; string companyName = "TestCompany";
string pwd = "Your password";
string prodKey = "Your code here";
try { int result= aLoginManager.LoginCompact(
ref userName, ref companyName, pwd, prodKey, false, out authToken); if (result == 0)
MessageBox.Show("Connected!");
else MessageBox.Show(string.Format("Error occurred, code: {0}", result)); } catch (Exception logExc) { MessageBox.Show(string.Format("Exception occurred: {0}", logExc.Message)); }
Lettura documento
Il Web Service di Perfetto che si occupa di interagire con i documenti è TbServices.
I metodi web del TbServices che intervengono nel processo di estrazione di un documento sono "XmlGetParameters" e "GetData".
Il metodo XmlGetParameters è utilizzato per avere l'elenco dei parametri di filtro, consentiti per il documento, con i valori di default. Il metodo richiede il codice di autenticazione, una stringa xml contenente il namespace del documento e il profilo di esportazione, e la data dell'applicazione.
Di seguito il recupero dei parametri per il documento Dipendenti:
string parameters = "<?xml version=\"1.0\" encoding=\"utf-8\"?>" +
"<maxs:Dipendenti tbNamespace=\"Document.ImpiantiNet.Core.INCore.Dipendenti\ " +
"xTechProfile=\"DefaultLight\" " +
"xmlns:maxs=\"http://www.microarea.it/Schema/2004/Smart/" +
"ImpiantiNET/Core/Dipendenti/Standard/DefaultLight.xsd\">" +
"<maxs:Parameters></maxs:Parameters>" +
"</maxs:Dipendenti>";
DateTime applicationDate= System.DateTime.Now;
try { string docParameters = aTbServices.XmlGetParameters(
authToken, parameters, applicationDate, false); } catch (Exception exc) { MessageBox.Show(string.Format("Exception occurred: {0}", exc.Message)); }
Il metodo GetData, data la stringa dei parametri di filtro valorizzata, restituisce i dati del documento specificato in formato xml.
Nell'esempio sotto riportato si richiedono i documenti Dipendente che soddisfano la richiesta impostata nella stringa dei parametri, nome che inizia per la lettera A e cap uguale a 24100:
string docParams = "<?xml version=\"1.0\"?>" +
"<maxs:Dipendenti tbNamespace=\"Document.ImpiantiNet.Core.INCore.Dipendenti\ " +
"xTechProfile=\"DefaultLight\" " +
"xmlns:maxs=\"http://www.microarea.it/Schema/2004/Smart/" +
"ImpiantiNET/Core/Dipendenti/Standard/DefaultLight.xsd\">" +
"<maxs:Parameters>" +
"<maxs:DefaultDialog title=\"Ricerca campi\">" +
"<maxs:DefaultGroup title=\"Gruppo di ricerca\">" +
"<maxs:Name type=\"String\">A%</maxs:Name>" +
"<maxs:ZipCode type=\"String\">24100</maxs:ZipCode>" +
"</maxs:DefaultGroup>" +
"</maxs:DefaultDialog>" +
"</maxs:Parameters>" +
"</maxs:Dipendenti>";
DateTime applicationDate= System.DateTime.Now;
try
{
StringCollection docsData = aTbServices.GetData(
authToken, docParams, applicationDate, 0, 0, 0, false);
}
catch (Exception exc)
{
MessageBox.Show(string.Format("Exception occurred: {0}", exc.Message));
}
Inserimento, modifica e cancellazione documento
Le operazioni di inserimento, modifica e cancellazione di un documento di Perfetto possono essere effettuate richiamando il metodo "SetData" del TbServices.
Il parametro "postingAction" del metodo SetData specifica quale operazione deve essere eseguita.
Il metodo SetData, forniti il codice di autenticazione, la stringa xml contenente i dati del documento consistenti con il profilo di esportazione, la data dell'applicazione e la transazione da effettuare, restituisce una stringa xml con i dati del documento aggiornati.
Per sapere come costruire in modo corretto la stringa xml con i dati del documento è possibile invocare il metodo "GetDocumentSchema" del TbService. Tale metodo, dati il namespace e il profilo di esportazione del documento, ritorna lo schema del profilo di esportazione.
Inserimento documento
Se si desidera inserire un documento il parametro postingAction del metodo SetData deve essere impostato a 1.
Nell'esempio, di seguito riportato, è mostrato l'inserimento del documento Rapportino con il profilo di esportazione DefaultLight:
string xmlData = "<?xml version=\"1.0\"?>" +
"<maxs:Rapportino xmlns:maxs=\"http://www.microarea.it/Schema/2004/Smart/ImpiantiNet/" +
"Rapportini/Rapportino/Standard/DefaultLight.xsd\" " +
"tbNamespace=\"Document.ImpiantiNet.Rapportini.INRapportini.Rapportino\" " +
"xTechProfile=\"DefaultLight\">" +
"<maxs:Data>" +
"<maxs:RapportinoCommessa master=\"true\">" +
"<maxs:Job>17/00002</maxs:Job>" +
"</maxs:RapportinoCommessa>" +
"<maxs:Righe>" +
"<maxs:RigheRow>" +
"<maxs:Employee>ERNESTO</maxs:Employee>" +
"<maxs:OrdinaryHours>28800</maxs:OrdinaryHours>" +
"<maxs:OvertimeHours>3600</maxs:OvertimeHours>" +
"</maxs:RigheRow>" +
"</maxs:Righe>" +
"</maxs:Data>" +
"</maxs:Rapportino>";
DateTime applicationDate= System.DateTime.Now;
string result = string.Empty;
try
{
bool bOk = aTbServices.SetData(
authToken, xmlData, applicationDate, 1, false, out result);
if(bOk)
MessageBox.Show("Posted!");
else
MessageBox.Show("Not posted, some error occurred!");
}
catch (Exception exc)
{
MessageBox.Show(string.Format("Exception occurred: {0}", exc.Message));
}
Analizzando la stringa di dati passata al metodo, è possibile notare che la stringa è composta solo di alcuni dati essenziali, in testa solo la commessa e in riga il codice del dipendente e le ore lavorate divise per tipologia.
Mentre se si vede la stringa xml ritornata dal metodo essa contiene molti più campi, come ad esempio i campi id, numero, data del rapportino. Essi sono stati creati dalla logica del documento.
Modifica documento
Se si desidera modificare un documento il valore del parametro postingAction deve essere uguale a 2.
Nella casistica di modifica, la stringa xml da passare al metodo SetData deve contenere la chiave primaria della tabella principale e il TBGuid, nel caso in cui la chiave primaria è un campo id di tipo intero.
Di seguito un esempio di stringa xml da inviare al metodo SetData per modificare i dati di un Rapportino:
string xmlData = "<?xml version=\"1.0\"?>" +
"<maxs:Rapportino xmlns:maxs=\"http://www.microarea.it/Schema/2004/Smart/ImpiantiNet/" +
"Rapportini/Rapportino/Standard/DefaultLight.xsd\" " +
"tbNamespace=\"Document.ImpiantiNet.Rapportini.INRapportini.Rapportino\" " +
"xTechProfile=\"DefaultLight\">" +
"<maxs:Data>" +
"<maxs:RapportinoCommessa master=\"true\">" +
"<maxs:WorkingReportId>59</maxs:WorkingReportId>" +
"<maxs:Job>17/00002</maxs:Job>" +
"<maxs:TBGuid>00168999-E994-424C-929E-0148DA1E3069</maxs:TBGuid>" +
"</maxs:RapportinoCommessa>" +
"<maxs:Righe>" +
"<maxs:RigheRow>" +
"<maxs:WorkingReportId>59</maxs:WorkingReportId>" +
"<maxs:Line>1</maxs:Line>" +
"<maxs:Employee>ERNESTO</maxs:Employee>" +
"<maxs:OrdinaryHours>28800</maxs:OrdinaryHours>" +
"<maxs:OvertimeHours>3600</maxs:OvertimeHours>" +
"<maxs:TravelHours>3600</maxs:TravelHours>" +
"</maxs:RigheRow>" +
"</maxs:Righe>" +
"</maxs:Data>" +
"</maxs:Rapportino>";
Rispetto alla fase di inserimento sono stati aggiunti nel DBT principale WorkingReportId (chiave primaria) e TBGuid e nel DBT delle righe WorkingReportId, Line (chiave primaria) e un'ora di tipo trasferta.
Nel caso in cui non si sappia se il documento sia già stato inserito è possibile impostare il parametro postingAction a 0, e il prodotto effettua un inserimento nel caso in cui il documento non esista altrimenti esegue un aggiornamento del documento.
Cancellazione documento
Se si desidera cancellare un documento il parametro postingAction deve essere impostato a 3.
Di seguito un esempio di codice che effettua la cancellazione di un Rapportino:
string xmlData = "<?xml version=\"1.0\"?>" +
"<maxs:Rapportino xmlns:maxs=\"http://www.microarea.it/Schema/2004/Smart/ImpiantiNet/" +
"Rapportini/Rapportino/Standard/DefaultLight.xsd\" " +
"tbNamespace=\"Document.ImpiantiNet.Rapportini.INRapportini.Rapportino\" " +
"xTechProfile=\"DefaultLight\">" +
"<maxs:Data>" +
"<maxs:RapportinoCommessa master=\"true\">" +
"<maxs:WorkingReportId>59</maxs:WorkingReportId>" +
"</maxs:RapportinoCommessa>"
"</maxs:Data>" +
"</maxs:Rapportino>";
DateTime applicationDate= System.DateTime.Now;
string result = string.Empty;
try
{
bool bOk = aTbServices.SetData(
authToken, xmlData, applicationDate, 3, false, out result);
if(bOk)
MessageBox.Show("Deleted!");
else
MessageBox.Show("Not deleted, some error occurred!");
}
catch (Exception exc)
{
MessageBox.Show(string.Format("Exception occurred: {0}", exc.Message));
}
Commenti