Libertya Web Service
Índice de contenido
Objetivos de este documento................................................................................................2
Prerequisitos..........................................................................................................................3
Instalación del servicio...........................................................................................................3
Acceso al Servicio..................................................................................................................3
Mecanismo de Interacción.....................................................................................................5
ParameterBean y Result Bean..........................................................................................5
Jerarquía de clases.......................................................................................................5
Log de Ejecución....................................................................................................................7
Parámetros y Argumentos de la invocación..................................................................7
API..........................................................................................................................................8
Objetivos de este documento
El presente documento explica la forma de acceder al Servicio Web Libertya y brinda el
detalle de los métodos y parámetros requeridos en cada caso.
Además presenta ejemplos de uso y funcionalidades adicionales como es la generación
del archivo de log de invocaciones y errores.
Prerequisitos
LYWS requiere al menos la versión 13.01 de Libertya CORE. De todas maneras, es
probable que sea parcialmente compatible con versiones anteriores de Libertya.
Instalación del servicio
Descomprimir el ZIP con nombre [Link] dentro del directorio:
/OXP_HOME/jboss/server/openXpertya/deploy/
Donde OXP_HOME refiere al directorio raiz de Libertya (generalmente llamado
ServidorOXP). Como resultado, dentro del directorio deploy se debería haber creado el
directorio [Link]:
/OXP_HOME/jboss/server/openXpertya/deploy/[Link]
Recordar que para estas acciones es necesario contar con los correspondientes permisos
de escritura sobre el directorio en cuestión.
Acceso al Servicio
Accediendo desde el navegador a:
[Link]
se pueden observar los servicios actualmente implementados:
LibertyaWS
• bPartnerCreate
• bPartnerRetrieveByID
• bPartnerRetrieveByValue
• bPartnerRetrieveByTaxID
• bPartnerUpdate
• bPartnerDelete
• invoiceCreateCustomer
• invoiceCreateCustomerFromOrderByID
• invoiceCreateCustomerFromOrderByColumn
• invoiceDeleteByID
• invoiceDeleteByColumn
• invoiceCompleteByID
• invoiceCompleteByColumn
• invoiceUpdateByID
• invoiceVoidByID
• invoiceVoidByColumn
• productCreate
• productRetrieveByID
• productRetrieveByValue
• productUpdateByID
• productUpdateByValue
• productDelete
• documentRetrieveOrderByID
• documentRetrieveOrderByColumn
• documentRetrieveInvoiceByID
• documentRetrieveInvoiceByColumn
• documentRetrieveInOutByID
• documentRetrieveInOutByColumn
• documentRetrieveAllocationByID
• documentRetrieveAllocationByColumn
• documentQueryOrders
• documentQueryInvoices
• documentQueryInOuts
• documentQueryAllocations
• orderCreateCustomer
• orderCreateVendor
• orderDeleteByID
• orderDeleteByColumn
• orderCompleteByID
• orderCompleteByColumn
• orderVoidByID
• orderVoidByColumn
• inOutCreateCustomer
• inOutCreateVendor
• inOutDeleteByID
• inOutDeleteByColumn
• inOutCompleteByID
• inOutCompleteByColumn
• inOutVoidByID
• inOutVoidByColumn
• bPartnerBalanceSumOrdersNotInvoiced
• bPartnerBalanceSumInvoices
• bPartnerBalanceSumPayments
• bPartnerBalanceSumChecks
• userCreate
• userRetrieveByID
• userUpdateByID
• userDeleteByID
• storageQuery
Desde un cliente Java, la URL de conexión al Web Service es la siguiente:
[Link]
El acceso a los servicios desde Java es sencillo debido a las clases de soporte para el
cliente que se entregan para este fin. Suponiendo que el Servidor de Aplicaciones de
Libertya se encuentra en [Link]:8080, el código para el acceso al WS de Libertya
es:
// Conexión al WS
LibertyaWSServiceLocator locator = new LibertyaWSServiceLocator();
[Link](“[Link]
// Recuperación del Servicio
[Link] lyws = [Link]();
// Invocación de ejempo a eliminación de factura
ResultBean result = [Link](...);
NOTA. Las clases LibertyaWSServiceLocator, LibertyaWS y las restantes clases
necesarias para el acceso y uso del WS de Libertya son proporcionadas junto con la
presente documentación. Mas adelante se presenta el ejemplo completo de aplicación
Cliente del WS de Libertya, incluyendo los archivos fuente de Java.
Mecanismo de Interacción
En la interacción con el WS por parte del cliente se invoca a uno de los servicios en
cuestión, pasándole los parámetros correspondientes, los cuales se encuentran
encapsulados en una jerarquía de clases de parámetros cuya superclase es
ParameterBean. Luego de procesar, el WS devolverá la respuesta con el mismo criterio,
en este caso la superclase de ResultBean.
ParameterBean y Result Bean
Cada invocación a un servicio requiere la carga previa de un conjunto de datos necesarios
para la ejecución de los servicios.
Los datos a cargar varían dependiendo la operación, aunque hay una serie de datos
obligatoria en todos los casos, que son: Nombre de usuario, Contraseña, Compañía,
Organización (la cual puede ser 0).
Las subclases de ParameterBean contienen información adicional específica. Por
ejemplo: BPartnerParameterBean contendrá información de la dirección de la Entidad
Comercial, e InvoiceParameterBean contendrá información sobre las líneas de una
factura.
De manera análoga, se obtendrá una clase ResultBean (o alguna de sus subclases) con
los resultados de la operación.
Jerarquía de clases
La jerarquía actual de parámetros y resultados es la siguiente:
Object
|
+ParameterBean
| |
| +BPartnerParameterBean
| |
| +DocumentParameterBean
| |
| +InvoiceParameterBean
|
+ResultBean
|
+BPartnerResultBean
|
+DocumentResultBean
|
+MultipleDocumentsResultBean
ParameterBean contiene los miembros generales a pasar como parámetro, tal como
compañía, usuario, password, y los datos a cargar para la tabla principal (ésta
dependiendo el WS en el que estemos: si es el WS de Entidades Comerciales será la
tabla C_BPartner, si es de facturas será la tabla C_Invoice, etc.):
/** Usuario LY */
protected String userName = "";
/** Contraseña LY */
protected String password = "";
/** Compañía a acceder */
protected int clientID = 0;
/** Organización */
protected int orgID = 0;
/** Coleccion para la tabla principal */
protected HashMap<String, String> mainTable = new HashMap<String, String>();
Los datos a cargar en la tabla en cuestión se reciben como pares: <nombre de columna,
dato>. De esta manera no es necesario modificar el WS en caso de que posteriormente
se modifique el número de columnas de una tabla, simplemente se envía un par adicional
desde el cliente.
Las subclases amplían esta estructura con información adicional según corresponda. Por
ejemplo para Entidades Comerciales, es necesario contar con información relacionada a
su dirección. Las facturas/pedidos/remitos tendrán las líneas, etc. Cada subclase
presenta métodos para hacer más intuitiva la carga de parámetros desde el cliente, con
invocaciones independientes para cada tabla:
/**
* Incorpora una nueva columna a los datos de parámetro la E.C.
* @param columnName nombre de la columna
* @param columnValue valor de la columna
*/
public void addColumnToBPartner(String columnName, String columnValue) {
...
}
/**
* Incorpora una nueva columna a los datos de parámetro de dirección de la E.C.
* @param columnName nombre de la columna
* @param columnValue valor de la columna
*/
public void addColumnToLocation(String columnName, String columnValue) {
...
}
La jerarquía de resultados es similar. La superclase ResultBean contiene los miembros:
/** El resultado fue un error */
protected boolean error = false;
/** Mensaje de error */
protected String errorMsg = "";
/** Valores de retorno principales o de tabla principal */
protected HashMap<String, String> mainResult = new HashMap<String, String>();
Luego las subclases amplían la información a devolver, por ejemplo BPartnerResultBean
contiene información inherente a este WS según los requerimientos, tal como dirección de
facturación, usuario de contacto, etc.
/** Valores de retorno de la última dirección de facturación */
protected HashMap<String, String> billAddress = new HashMap<String, String>();
/** Indica si existen más direcciones */
boolean modeAddresses = false;
/** Valores de retorno del contacto más nuevo */
protected HashMap<String, String> userContact = new HashMap<String, String>();
Desde el cliente se instancian entonces estas clases de parámetros, se asignan los
valores y luego se invoca al servicio, pasándo como parámetro este objeto (además de
otros datos según corresponda). Notar que dependiendo el servicio se recibe/devuelve
una especialización o una generalización en la jerarquía (no en todos los casos hacemos
uso de las hojas de la jerarquía). Esto hace más fácil la interpretación de qué parámetros
se deben enviar en cada caso y qué datos obtendremos como resultado.
Log de Ejecución
Toda ejecución de una acción o error queda persistida en el log con el siguiente formato:
Fecha y Hora, [INFO|WS_ERROR|MODEL_ERROR] (Usuario) – Datos específicos de
cada ejecución.
Dicho archivo de log se llama [Link] y se escribirá en la ubicación especificada en la
variable de entorno OXP_WS_LOG. Si dicha variable no se encuentra especificada,
utilizará por defecto la variable de entorno OXP_HOME de la aplicación (comunmente
/ServidorOXP en instalaciones Linux, y C:\ServidorOXP en Windows). Tener en cuenta
que es necesario contar con los permisos correspondientes en el directorio en cuestión
para que el WS de Libertya pueda escribir el archivo.
Ejemplo:
2012-08-05 [Link] [INFO] (AdminLibertya) - [Link] - Ejecutando
invoiceDelete
2012-08-05 [Link] [MODEL_ERROR] (AdminLibertya) - [Link] -
[Link]: No se pudo recuperar un registro para la tabla C_Invoice con los
criterios especificados. ([Link]([Link]),
[Link](Unknown Source)...
2012-08-05 [Link] [INFO] (AdminLibertya) - [Link] - Ejecutando
bPartnerCreate
2012-08-05 [Link] [MODEL_ERROR] (AdminLibertya) - [Link] -
[Link]: Error al persistir entidad comercial:Could not save changes: : Existe un
registro de Entidad Comercial que ya contiene el valor value188 para el campo Clave. El valor de este campo no
puede ser duplicado. ([Link](Unknown Source)...
2012-08-05 [Link] [INFO] (AdminLibertya) - [Link] - Ejecutando
bPartnerRetrieve
2012-08-05 [Link] [INFO] (AdminLibertya) - [Link] - Ejecutando
invoiceCreateCustomer
En el ejemplo primeramente se está invocando a invoiceDelete, posteriormente se indica
un error de modelo (no se encuentra la factura en cuestión), luego se intenta crear una
entidad comercial mediante bPartnerCreate, y posteriormente un error de modelo
indicando que ya existe una entidad comercial con la clave de búsqueda especificada.
Por último se invoca a la recuperación de una entidad comercial y la creación de una
factura.
Parámetros y Argumentos de la invocación
Adicionalmente al stack de error informativo, se incorpora en el log el conjunto de
parámetros enviados en el ParameterBean correspondiente, así como los argumentos
adicionales que completan la firma del método invocado; indicados mediante Parameters
y Method Arguments correspondientemente. Un ejemplo se muestra a continuación:
ERROR. [Link]: Error de acceso para usuario AdminLibertya
([Link]([Link]),
[Link]([Link]),
[Link](AllocationDocum
[Link]),
[Link](AllocationDocum
[Link]),
[Link]([Link]),
[Link]([Link]))
- Parameters -
[Link] - UserName = AdminLibertya;
ClientID = 1010016; OrgID = 1010053
mainTable: Description = Un RC desde WS;
Invoices:
Amount = 350; C_Invoice_ID = 1021694;
Payments:
Amount = 70; C_POSPaymentMedium_ID = 1010038; C_Invoice_ID = 1021695;
TransferNo = 1234; Amount = 30; C_POSPaymentMedium_ID = 1010034; TransferDate = 2012-
09-03 [Link]; C_BankAccount_ID = 1010071;
Amount = 20; CreditCardNumber = 102929281810; C_POSPaymentMedium_ID = 1010036; A_Bank
= Comafi; CouponNumber = 12341234; M_EntidadFinancieraPlan_ID = 1010033;
Amount = 40; C_POSPaymentMedium_ID = 1010037; DateTrx = 2012-09-03 [Link]; DueDate
= 2012-09-04 [Link]; CheckNo = 12345; C_BankAccount_ID = 1010070;
Amount = 40; C_POSPaymentMedium_ID = 1010033; C_Cash_ID = 1010062;
Amount = 70; C_CashLine_ID = 1010100; C_POSPaymentMedium_ID = 1010035;
C_Payment_ID = 1011960; Amount = 30; C_POSPaymentMedium_ID = 1010035;
Amount = 50; C_POSPaymentMedium_ID = 1010039; Retenc_Date = 2012-09-04 [Link];
Retenc_DocumentNo = 5311181; C_RetencionSchema_ID = 1010054;
- Method arguments: bPartnerID = -1; bPartnerValue = MC; taxID = null; isEarlyPayment =
false;
API
Se adjunta al presente documento el JavaDoc correspondiente a la implementación de los
WebServices.
