Lettura di un catalogo di dati da un sistema esterno

<< Fare clic per visualizzazione il sommario >>

Percorso:  Jamio openwork > Le risorse >

Lettura di un catalogo di dati da un sistema esterno

Le interfacce applicative Jamio sono esposte per mezzo del protocollo SOAP. A tale scopo Jamio mette a disposizione una serie di endpoint che espongono le funzionalità erogate dalla piattaforma. Ogni applicazione è esposta su protocollo SSL (https). Per interfacciare Jamio è dunque sufficiente utilizzare le utility fornite per i vari linguaggi e dai vari IDE di sviluppo per produrre i proxy, che consentono di utilizzare i servizi dal codice come librerie locali. Gli oggetti esposti sono strutturalmente uguali nelle varie applicazioni, ma diversamente definiti per ogni endpoint. Per evitare duplicazioni di codice utile ad invocare i servizi, inseriamo alcune indicazioni per la produzione del proxy riportate nel relativo paragrafo.

Nell'esempio che segue le applicazioni coinvolte sono due, descritte in seguito:

Session Management, questa sezione è necessaria per la login alla piattaforma e la gestione della sessione.

 Endpoint: https://paas.jamio.com/gateway/gateway/ISessionManagement/mex?wsdl

Data Management, questa applicazione consente la gestione delle risorse di tipo dati.

 Endpoint: https://paas.jamio.com/gateway/gateway/IDataManagement/mex?wsdl

 

Lettura di un catalogo di dati Jamio openwork da un sistema esterno

In questo paragrafo descriviamo i metodi coinvolti e i relativi parametri. Prima di procedere occorrono alcune specificazioni:

E’ necessario possedere le credenziali di accesso alla piattaforma Jamio openwork (nome utente, password e Area). Normalmente queste informazioni sono già in possesso di che vuole accedere alla piattaforma. In caso contrario richiederle all’Amministratore dell’Area;

Il catalogo che si vuole interrogare deve essere noto alla piattaforma per nome e contenuto. Questo implica che il modello di catalogo debba essere pubblicato sull'area in questione;

Occorre possedere l’identificativo - oltre che il nome - dell’Area. Queste informazioni devono essere richieste al gestore dell’Area;

Occorre possedere l'URL - oltre che il nome - del modello di catalogo. Queste informazioni devono essere richieste al gestore dell’Area;

Il risultato della invocazione a qualsiasi metodo dei Servizi di Jamio è di tipo ServiceResult. Esso contiene l’esito della chiamata, il risultato vero e proprio del metodo – laddove previsto - e una lista di eventuali messaggi (informazioni, warning o errori).

 

Lettura di un catalogo specifico di risorse di tipo dati

Le azioni da effettuare per leggere un catalogo sono le seguenti:

1.Autenticazione del chiamante tramite invocazione al metodo Login del servizio SessionManagement. Questa può essere effettuata una tantum, fintanto che la relativa sessione aperta resti in piedi e quindi non scada il token generato o non sia chiusa la sessione. Il metodo Login del servizio SessionManagement richiede in input i parametri:

Parametri del metodo Login

Nome

Descrizione

Tipo

Opzionale

identityRepositoryName

Identificativo dell’Area.

String

 

userName

Nome utente di autenticazione.

String

 

password

Password dell'utente che effettua l'autenticazione.

String

 

multiPosition

Indicare come valore false.

Bool

 

source

Rappresenta un identificativo del sistema che effettua la richiesta

String

 

 

2.Lettura dei dati di sessione tramite invocazione al metodo GetSession del servizio SessionManagement.  Questa invocazione permette di ricavare l'identificativo dell'Area corrente. Il metodo GetSession del servizio SessionManagement richiede in input i parametri:

Parametri del metodo GetSession

Nome

Descrizione

Tipo

Opzionale

info

Oggetto contenente il token di sessione.

RequestInfo

 

 

3.Lettura di un catalogo di risorse dati tramite invocazione al metodo GetCatalog del servizio DataManagement di cui riportiamo i parametri:

Parametri del metodo GetCatalog

Nome

Descrizione

Tipo

Opzionale

repositoryId

Identificativo dell’Area.

String

 

modelUrl

URL del modello di catalogo.

String

 

parameters

Parametri di apertura del catalogo (paginazione, numero di righe, etc.)

SearchParameters

 

info

Oggetto contenente il token di sessione.

RequestInfo

 

 

Lettura dell'elenco di tutti i cataloghi di risorse di tipo dati

Per alcuni scenari applicativi può essere utile leggere l'elenco di tutti i cataloghi il quale riporta i riferimenti di tutti i cataloghi di dati a disposizione dell'utente pubblicati nell'Area, sia di tipo predefinito che di tipo personalizzato. Ad esempio se si conosce solo il nome di un modello di catalogo e si vuole ottenere il suo URL, dal risultato ottenuto dalla lettura dell'elenco di tutti i cataloghi è possibile ricercare il catalogo specifico attraverso la proprietà name. Le azioni da effettuare per leggere l'elenco di tutti i cataloghi di risorse di tipo dati sono le seguenti:

1.Autenticazione del chiamante tramite invocazione al metodo Login del servizio SessionManagement. Questa può essere effettuata una tantum, fintanto che la relativa sessione aperta resti in piedi e quindi non scada il token generato o non sia chiusa la sessione. I parametri di input previsti dal metodo Login sono sopra riportati.

2.Lettura dei dati di sessione tramite invocazione al metodo GetSession del servizio SessionManagement.  Questa invocazione permette di ricavare l'identificativo dell'Area corrente. I parametri di input previsti dal metodo GetSession sono sopra riportati.

3.Lettura dell'elenco di tutti i cataloghi di risorse dati tramite invocazione al metodo GetMainCatalog del servizio DataManagement di cui riportiamo i parametri:

Parametri del metodo GetMainCatalog

Nome

Descrizione

Tipo

Opzionale

repositoryId

Identificativo dell’Area.

String

 

info

Oggetto contenente il token di sessione.

RequestInfo

 

 

 

Jamioware di esempio

Nei paragrafi successivi sono riportati esempi di lettura di un catalogo di risorse dati specifico e del catalogo di tutti gli eventi in C#.

L' applicazione di esempio GetCatalog.zip a corredo di questa pagina effettua le seguenti operazioni:

autenticazione del chiamante, mediante la funzione SessionManagement.Login. Da questa funzione si ottiene il token di sessione, che sarà usato per tutte le chiamate successive;

lettura dati di sessione con la funzione SessionManagement.GetSession (utilizzato per ricavare l'identificativo dell'area corrente);

lettura dell'elenco di tutti i cataloghi di DataManagement, con la funzione DataManagement.GetMainCatalog: questo contiene i riferimenti di tutti i cataloghi a disposizione dell'utente, sia di tipo predefinito che di tipo personalizzato;

lettura di un catalogo specifico di DataManagement (il primo disponibile dall'elenco precedente), con la funzione DataManagement.GetCatalog;

chiusura della sessione, funzione SessionManagement.CloseSession.

 

Preparazione del Proxy

Nell’esempio, è utilizzata la generazione del proxy dal WSDL delle interfacce dei Web Services attraverso l’utilizzo dell’applicazione svcutil.exe presente nel pacchetto Microsoft SDK for Windows. Questa utility cambia in base alla versione dell’SDK, cambiando la location dell’utility stessa e il risultato che essa genera. Se il comando di seguito riportato non funzionasse occorrerebbe trovare la versione installata sulla propria macchina.

 

"C:\Program Files (x86)\Microsoft SDKs\Windows\v8.1A\bin\NETFX 4.5.1 Tools\svcutil.exe" /out:ProxyJamio.cs /serializer:Auto 

https://paas.jamio.com/gateway/gateway/ISessionManagement/mex?wsdl 

https://paas.jamio.com/gateway/gateway/IDataManagement/mex?wsdl

 

Durante l’esecuzione del comando la console mostrerà una serie di errori, ma non inficeranno il risultato finale, che sarà la generazione del file ProxyJamio.cs.

 

Jamioware Visual Studio

Il Jamioware di seguito descritto è disponibile nell’archivio qui scaricabile GetCatalog.zip.

Per la preparazione del Jamioware effettua i seguenti passi:

1.Inserisci nel progetto Visual Studio il file ProxyJamio.cs prodotto al passo precedente;

2.Verifica che nel progetto siano presenti i riferimenti a System.Runtime.Serialization, System.ServiceModel e System.XML, altrimenti aggiungili;

3.Sovrascrivi il file app.config con il contenuto qui di seguito riportato:

<configuration>

 <system.serviceModel>

   <bindings>

     <basicHttpBinding>

<binding name="basicHttpsBinding_Gateway" maxReceivedMessageSize="2147483647">

 <readerQuotas maxDepth="65536" maxStringContentLength="65536"

maxArrayLength="65536" maxBytesPerRead="65536" maxNameTableCharCount="65536"/>

 <security mode="Transport" />

</binding>

     </basicHttpBinding>

   </bindings>

   <client>

     <endpoint address="https://paas.jamio.com/gateway/gateway/ISessionManagement"

binding="basicHttpBinding" bindingConfiguration="basicHttpsBinding_Gateway"

contract="ISessionManagement"

name="basicHttpsBinding_Gateway_ISessionManagement"/>

     <endpoint address="https://paas.jamio.com/gateway/gateway/IDataManagement"

binding="basicHttpBinding" bindingConfiguration="basicHttpsBinding_Gateway"

contract="IDataManagement"

name="basicHttpsBinding_Gateway_IDataManagement"/>

   </client>

 </system.serviceModel>

</configuration>

 

4.Inserisci prima del codice di invio lo using www.openworkbpm.com.schema, o comunque quello del namespace inserito dall’utility;

5.Copia il codice e valorizza i parametri e le credenziali.

 

Codice di esempio

// Indirizzo di base dei servizi Jamio

static string realBaseAddress = "https://paas.jamio.com/gateway/gateway/";

 

// parametri e credenziali da impostare

static string identityRepositoryName = null;

static string userName = null;

static string password = null;

static string source = null;

 

static SessionManagementClient sessionManagement = null;

static DataManagementClient dataManagement = null;

static string token = null;

static string tenantId = null;

static string dataModelUrl = null;

 

static void Main(string[] args)

{

  // rappresenta un identificativo del sistema che effettua la richiesta

   source = Environment.MachineName;

 

  // creazione del client per la gestione delle sessioni

   sessionManagement = new SessionManagementClient("basicHttpsBinding_Gateway_ISessionManagement", realBaseAddress + "ISessionManagement");

 

  Console.Write("Tenant: ");

   identityRepositoryName = Console.ReadLine();

  if (String.IsNullOrWhiteSpace(identityRepositoryName)) return;

  Console.Write("Username: ");

   userName = Console.ReadLine();

  if (String.IsNullOrWhiteSpace(userName)) return;

  Console.Write("Password: ");

   password = Console.ReadLine();

  Console.WriteLine();

 

  try

   {

      if (DoLogin())

       {

           GetSession();

 

          // creazione del client per la gestione dei dati

           dataManagement = new DataManagementClient("basicHttpsBinding_Gateway_IDataManagement", realBaseAddress + "IDataManagement");

           GetDataMainCatalog();

           GetDataCatalog();

           dataManagement.Close();

 

          // logout e chiusura sessione

          Console.WriteLine("Logout...");

           www.openworkbpm.com.schema.RequestInfo info = new www.openworkbpm.com.schema.RequestInfo();

           info.Token = token;

           sessionManagement.CloseSession(info);

       }

   }

  catch (Exception e)

   {

      Console.WriteLine(e.Message);

      Console.WriteLine();

   }

 

   sessionManagement.Close();

  Console.WriteLine("Terminato... Premi INVIO per uscire");

  Console.ReadLine();

 

}

 

private static bool DoLogin()

{

  // invocazione del servizio di login

   www.openworkbpm.com.schema.ServiceResultOfLoginInfo loginResult = sessionManagement.Login(identityRepositoryName, userName, password, false, source);

  if (!loginResult.Error)

   {

      Console.WriteLine("Login: OK");

       token = loginResult.Value.Token; // memorizza il token di sessione

   }

  else

   {

      Console.WriteLine("Login: KO. " + loginResult.ResultInfoList[0].Message);

   }

  Console.WriteLine();

  return !loginResult.Error;

}

 

private static void GetSession()

{

  // lettura dati sessione corrente

   www.openworkbpm.com.schema.RequestInfo info = new www.openworkbpm.com.schema.RequestInfo();

   info.Token = token;

   www.openworkbpm.com.schema.ServiceResultOfSession sResult = sessionManagement.GetSession(info);

  if (!sResult.Error)

   {

      Console.WriteLine("GetSession: OK");

       tenantId = sResult.Value.TenantId; // memorizza l'identificativo del tenant

   }

  else

   {

      Console.WriteLine("GetSession: KO. " + sResult.ResultInfoList[0].Message);

   }

  Console.WriteLine();

}

 

private static void GetDataMainCatalog()

{

  // lettura catalogo dei cataloghi di DataManagement

  RequestInfo info = new RequestInfo();

   info.Token = token;

  ServiceResultOfCatalog mcatResult = dataManagement.GetMainCatalog(tenantId, info);

  if (!mcatResult.Error)

   {

      Console.WriteLine("GetMainCatalog: OK");

      Catalog mainCatalog = mcatResult.Value;

 

      // prende il primo catalogo con un URL

      string catalogName = null;

      foreach (var item in mainCatalog.ItemList)

       {

          if (item.Fields.Length>1) // l'URL si trova nel secondo campo

           {

               dataModelUrl = item.Fields[1].Val.ToString();

               catalogName = item.Name;

              break;

           }

       }

      Console.WriteLine(String.Format("Catalog Name: {0} - model URL: {1}", catalogName, dataModelUrl));

   }

  else

   {

      Console.WriteLine("GetMainCatalog: KO. " + mcatResult.ResultInfoList[0].Message);

   }

  Console.WriteLine();

}

 

private static void GetDataCatalog()

{

  // lettura catalogo dati

  RequestInfo info = new RequestInfo();

   info.Token = token;

 

  // inizializzazione parametri per la GetCatalog

  SearchParameters parameters = new SearchParameters();

   parameters.OrderingCriteria = new Ordering[0]; // questo per evitare errori

  // paginazione

   parameters.PageSize = 50;

   parameters.PageSizeSpecified = true;

   parameters.PageNumber = 1;

   parameters.PageNumberSpecified = true;

 

  ServiceResultOfCatalog catResult = dataManagement.GetCatalog(tenantId, dataModelUrl, parameters, info);

  if (!catResult.Error)

   {

      Console.WriteLine("GetCatalog: OK");

      Catalog catalog = catResult.Value;

      Console.WriteLine(String.Format("Catalog items: {0}/{1}", catalog.ItemList.Length, catalog.TotalCount));

      foreach (var item in catalog.ItemList) // stampa il Name per ogni riga

       {

          Console.WriteLine("\t" + item.Name);

       }

   }

  else

   {

      Console.WriteLine("GetCatalog: KO. " + catResult.ResultInfoList[0].Message);

   }

  Console.WriteLine();

}