CONNECTOR AMB S@RCAT 2.1


Versió Optimitzada

Disponible una nova versió optimitzada del connector. Trobareu més informació al següent apartat.



Introducció

Propósit

El connector S@rcat ens permet connectar amb el Sistema de registre corporatiu S@rcat
per realitzar l'enregistrament, consulta d'assentaments o descàrrega de taules mestres .

Les funcions bàsiques que ha d'assolir aquest connector amb S@RCAT :

  • Execucio de funcionalitats on-line encapsulant crides a serveis webservices existents a S@RCAT.
  • Utilització del connector de S@RCAT per l'enviament de documents a registrar mitjançant FTP o SFTP.

Context i Escenaris d'Ús

El connector sarcat es troba dins els connectors de serveis funcional.

Versions i Dependències

Les dependències descrites a la següent url son requerides per tal de fer funcionar el servei:
Dependències Connector amb S@rcat

A qui va dirigit

Aquest document va dirigit als següents perfils:

  1. Programador. Per conéixer l'ús del connector.
  2. Arquitecte. Per conéixer quins són els components i la configuració del connector.

Documents i Fonts de Referència

[1] Anàlisi Funcional - Connector Serveis Funcionals - 16-Nov.doc Document d'anàlisi dels connectors de serveis funcionals.
[2] DT_CC-s@rcat_v06.doc Sistema de registre corporatiu

Glossari

Descripció Detallada

Arquitectura i Components

Interfícies i Components Genérics

Es pot trobar tota la documentació JavaDoc y el codi font referent aquests components a les següents urls:

JavaDoc: http://canigo.ctti.gencat.net/confluence/canigodocs/site/canigo2_0/canigo-connectors-root/canigo-connectors-sarcat/apidocs/index.html
Codi Font:  http://canigo.ctti.gencat.net/confluence/canigodocs/site/canigo2_0/canigo-connectors-root/canigo-connectors-sarcat/xref/index.html

Instal- lació i Configuració

Instal- lació

La instal- lació del connector requereix de la utilització de la llibreria 'canigo-connectors-sarcat' i les dependències indicades a l'apartat 'Introducció-Versions i Dependències'.

La instal- lació es realitzarà seguint el procediment habitual per components/serveis Canigó.

És necesari tenir accés a la intranet de la Generalitat per poder fer proves i/o utilitzar-lo.

Configuració


Per a la utilització del connector de SarCat cal un fitxer de configuració on es configuri el servei de WebServices (webServicesContext.xml):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd">

<beans>

<bean abstract="true" id="ImportedInterfaceDefinition"
	  class="net.gencat.ctti.canigo.services.webservices.impl.ImportedInterfaceImpl"/>

<bean id="loggingConfigurator" class="net.gencat.ctti.canigo.services.logging.log4j.xml.HostDOMConfigurator"
	  init-method="init">
    <property name="configFileName"><value>classpath:log4j.xml</value></property>
</bean>

<bean name="WebServicesService" class="net.gencat.ctti.canigo.services.webservices.impl.WebServicesServiceImpl">
        <property name="importedInterfaces">
            <list>
                <bean parent="ImportedInterfaceDefinition">
                    <property name="name" value="sarcatWebService" />
                    <property name="serviceLocator"    value="org.openuri.www.ConnectorWSLocator"/>
                    <property name="serviceLocatorImpl" ref="sarcatBeanConfiguration"/> 
                    <property name="localInterface" value="org.openuri.www.ConnectorWSSoap"/>
                </bean>
            </list>
        </property>
        <property name="logService">
            <bean id="loggingService" class="net.gencat.ctti.canigo.services.logging.log4j.Log4JServiceImpl"
		      init-method="init">
                <property name="configurator"><ref local="loggingConfigurator"/></property>
            </bean>
        </property>
</bean>
<bean name="sarcatBeanConfiguration" class="org.openuri.www.ConnectorWSLocator"> 
<property name="connectorWSSoapAddress" value="${WS_Sarcat_URL_Locator}"/> 
</bean> 
</beans>

A partir de la versió 2.3.3 del connector, l'adreça dels WebServices de Sarcat es configura en l'arxiu ValidateWSLocator.properties :

WS_Sarcat_URL_Locator=http://preproduccio.sarcat.intranet.gencat.cat/ConnectorWebservice/AppJava/ConnectorWS


Atenció

L'arxiu de propietats ValidateWSLocator.properties s'ha de trobar desplegat a l'arrel del directori classes, és a dir, a l'arrel de la carpeta resources de la nostra aplicació.
Si no es troba en aquesta ubicació no es tindrà en compte la configuració.
Actualització
A partir de la versió 2.3.5 el fitxer pot estar en una carpeta dintre del directori de recursos, recomanem: <PROJECT_ROOT>/src/main/resources/connectors/ValidateWSLocator.properties.
Per carregar aquest fitxer cal modificar l'XML del servei de configuració canigo-services-configuration.xml i afegir aquesta entrada:

<value>classpath:connectors/ValidateWSLocator.properties</value>


Per tal d'evitar configuracions errònies, a partir de la versió 2.3.4 el valor per defecte d'aquesta configuració és una adreça clarament erronea ( _http://adreca.sarcat.no.configurada_ ), de forma que es faci evident que no s'ha configurat correctament.


Com es pot veure a la definició del bean WebServicesService s'importa el web service de SarCat. Es podrà accedir al web service a partir del servei i realitzar les accions que es desitgin a SarCat.


Respecte a la configuració del projecte, el fitxer de configuració Maven2 (pom.xml) haurà d'incloure les dependències de SarCat:

<dependency>
    <groupId>canigo.connectors</groupId>
    <artifactId>canigo-connectors-sarcat</artifactId>
    <version>2.2</version>
</dependency>



Utilització del Servei

La utilització del Connector es basa principalment en la configuració. L'ús directe des dels clients es permet mitjançant les interfícies definides.

Hi ha dues possibilitats d'us on-line i mitjançant transmissions de fitxers per FTP. Els noms d'aquest fitxers han de complir un determinat format per formar el nom (veure document _DT_CC-s@rcat_v06.doc_ apartat 7.3.4 Des de la conexió FTP pàg. 72) :

  1. La nomenclatura del fitxer FTP que haurà de rebre el s@rcat ha de ser la següent:
    [urUsuari-rangInici-rangFi-tipusAssentament-accio-tipusfitxer-yyyymmddhhmmss]
    on urUsuari ha de ser_: _codi d'unitat registre que ha estat assignat des de l'administrador del sistema. __
    on rangInici ha de ser: en cas d'acció "R", el primer número obtingut a la petició de reserva de numeració.
    en cas d'acció "A", el nombre d'assentaments que conté el fitxer
    on rangFi ha de ser: en cas d'acció "R", darrer número obtingut a la petició de reserva de numeració.
    en cas d'acció "A", el nombre d'assentaments que conté el fitxer
    on tipusAssentament pot ser : E (assentaments d'entrada)
    S (assentaments de sortida)
    P (assentaments de presortida)
    on acció pot ser : R (assentaments reservats)
    D (diligència d'assentaments)
    A (nous assentaments)
    on tipusfitxer pot ser: XML (contingut XML)
    PLA (fitxer ASCII)
    on yyyymmddhhmmss ha de ser: la data de creació del fitxer
    Exemple de fitxers de peticions:
    00001-100-200-S-R-PLA-20040302141236. En aquest cas, la inserció es realitza sobre la unitat de registre 00001. El fitxer està en format pla (especificat en el punt 7.5) i es processa per la data d'avui. Al ser un fitxer de tipus R, els números de registre assignats a cada assentament es validaran contra una taula interna de "reserves" del s@rcat.
    00001-100-200-S-D-PLA-20040302141236. En aquest cas, la diligència es realitza sobre la unitat de registre 00001. El fitxer està en format pla (especificat en el punt 7.5) i es processa per la data d'avui. Al ser un fitxer de tipus D, els números de registre assignats a cada assentament es validen contra la taula d'assentaments del s@rcat.

Per utilitzar el servei instanciarem un objecte ConnectorWSSoap mitjançant el servei canigo web services, cridant després a qualsevol dels seus mètodes. Exemple d'utilització:

public void test()
{
logDebug("TestSarcat.test inicio");
BeanFactory beanFactory = new ClassPathXmlApplicationContext("webServicesContext.xml");
WebServicesService service = (WebServicesService) beanFactory.getBean(WebServicesService.
WEB_SERVICES_BEAN_FACTORY_KEY);

ConnectorWSSoap sarcat = (ConnectorWSSoap) service.getWebService("sarcatWebService");

LoginInfo login = new LoginInfo();
login.setUser(user);
login.setPassword(password);

LoginRetorn ret = null;
String token = null;

try {
ret = sarcat.login(login);
assertNotNull(ret);

token = ret.getToken();
assertNotNull(token);

AltaAssentamentEntradaSortida assentament = new AltaAssentamentEntradaSortida();
assentament.setToken(token);
assentament.setUrUsuari("00001");
assentament.setEmail("name@atosorigin.com");

AssentamentEntradaInfo entrada = new AssentamentEntradaInfo();
entrada.setAnyPK(2006);
entrada.setCodiURPK("00001");
entrada.setAssumpte("Test2");
entrada.setDataPresentacio("21/01/2006");
entrada.setDataDocument("20/01/2006");
//entrada.setDataAlta("20/01/2006 18:35:01");
entrada.setDescripcio("descripcio2");
entrada.setNom("Victor");
entrada.setCognom1("Fdez");
entrada.setCognom2("Castanyo");
// Barcelona : 080193
entrada.setIdPoblacioProc("080193");
// Via presentació 8 : Telemática
entrada.setIdViaPresentacio(8);
// Tipus Tramesa 1 : Persona Física
entrada.setIdTipusTramesa(1);
// Dest Interna 2340 : Direcció General de Cooperació Cultural
entrada.setIdCentreDestInterna(2340);
// Support Físic 3 : Electronic
entrada.setIdSuportFisic(3);
// Tipus Document 13 : Sol.licitud
entrada.setIdDocument(13);
entrada.setNumExpedient("23400");
//entrada.setNumPK(2);
entrada.setLda(0);
entrada.setUrgent(0);
// Parametres buits!! a -1
entrada.setAnySort(-1L);
entrada.setIdAnnex(-1L);
entrada.setIdCategoria(-1L);
entrada.setIdCentreDestExterna(-1L);
entrada.setIdCentreProcedencia(-1L);
entrada.setIdMotiuDiligencia(-1L);
entrada.setIdPlantilla(-1L);
entrada.setIdSubdivEspecifica(-1L);
entrada.setIdSubdivUniforme(-1L);
entrada.setIdVolum(-1L);
entrada.setNumEmergencia(-1L);
entrada.setNumPK(-1L);
entrada.setNumSort(-1L); AssentamentEntradaInfo[] array = new AssentamentEntradaInfo[1];
array[0] = entrada;
assentament.setAssentamentEntrada(array);

AssentamentsRetorn retAss = sarcat.insertarAssentamentEntrada(assentament);

logDebug("AssentamentsRetorn : " + retAss.getAssentamentRetorn()[0]);
logDebug("AssentamentsRetorn error: " + retAss.getAssentamentRetorn()[0].getDataAlta());
logDebug("AssentamentsRetornerror: " + retAss.getAssentamentRetorn()[0].getErrorAssentament().
getDescripcio());
logDebug("AssentamentsRetorn error: " + retAss.getAssentamentRetorn()[0].getErrorAssentament().
getDescripcioExtesa());

} catch (RemoteException e) {
logError("Error en TestSarcat.test2 " + e.getMessage());
e.printStackTrace();
}

finally
{
try {
sarcat.logout(token);
} catch (RemoteException e) {
// TODO Auto-generated catch block
e.printStackTrace();
}
}

logDebug("TestSarcat.test2 fin");
}

Exemple d'utilització amb batch (FTP)

public void testFTP1()
{
logDebug("TestSarcat.testFTP1 inicio");

FtpClientIF ftpClient=null;

try {
PlanificatTaulaMestraCerca tmc = createTaulaMestraCerca();

//org.apache.commons.net.ftp.FTPClient ftpClient=new org.apache.commons.net.ftp.FTPClient();
//ftpClient.connect(realIP);
//boolean isConnected=ftpClient.login(userFTP,passwordFTP);

ftpClient=getFtpService();
boolean isConnected=ftpClient.login(userFTP, passwordFTP, realIP);
//boolean isConnected=ftpClient.connectAndLogin(testIP, "pepe", "pepe");
logDebug("User: "+ userFTP + " Is Connected? = "+ isConnected);
assertTrue(isConnected);

if (isConnected)
{
FTPMarshalImp ftpM= new FTPMarshalImp(ftpClient);
assertTrue(ftpM.ftpUpload(tmc, "00001-100-200-S-D-XML-20060209141236"));

PlanificatTaulaMestraCerca tmcDownloaded=(PlanificatTaulaMestraCerca)ftpM.ftpDownload
("net.gencat.sarcat.planificat.taulamestracerca", "PlanificatTaulaMestraCerca.xml");

if (tmcDownloaded!=null)
logDebug("tmcDownloaded.getToken="+tmcDownloaded.getToken());
else
logDebug("tmcDownloaded=null");

assertNotNull(tmcDownloaded);
}

}
catch (Exception e) {
logError("Error en TestSarcat.testFTP1 " + e.getMessage());
e.printStackTrace();
}

finally
{
ftpClient.disconnect();
}

logDebug("TestSarcat.testFTP1 fin");
}



A partir de la versió 2.3.5 es poden fer transferències per SFTP (Secure FTP). Per fer-ho servir s'ha de construïr l'objecte del tipus net.gencat.sarcat.ftp.Impl.FTPMarshalImp amb el Servei de SFTP com a paràmetre.
SftpService sftpService = getSftpService();
FTPMarshalImp ftpM = new FTPMarshalImp(sftpService);

Per veure les possibles configuracions i més informació del servei de SFTP consulteu la següent adreça: Servei de SFTP 2.3.x


Pel correcte funcionament de les crides al connector de SarCat es OBLIGATORI que els camps numèrics dels quals no es desitja informar el seu valor es faci amb el valor -1 (Ex. entrada.setIdCentreProcedencia(-1L), entrada.setLda(-1), ...).

Integració amb Altres Serveis

Integració amb el Servei de Internacionalització

En els fitxers de configuració es defineixen claus que permeten especificar quins missatges retornar en cas errors. Per a poder traduir aquestes claus és necessari especificar que el connector usarà el Servei d'Internacionalització (veure Configuració).

Versió Optimitzada

S'ha portat a terme una optimització del connector de SARCAT per tal de reduïr el seu número de classes i com a conseqüència el seu tamany.
Per tal de fer-ho s'han modificat una sèrie de classes, concretament s'han traslladat totes les classes del paquet runtime de la pròpia funcionalitat a un paquet comú accessible per aquestes.

Aquest canvi no hauria d'afectar a cap projecte ja que les classes modificades són utilitzades internament pel propi connector.
Per realitzar el canvi només s'ha de descarregar la nova versió i sobreescriure l'anterior al repositori local de maven.

Podeu trobar la nova versió per descarregar-la al següent enllaç


image004.gif (image/gif)
image005.gif (image/gif)
image002.gif (image/gif)
image003.gif (image/gif)
image001.gif (image/gif)
image006.gif (image/gif)
canigo-connectors-sarcat-2.X.jar (application/java-archive)