English Version
Salida Personalizada en GXplorer/GXquery Web
Alcance
Producto: GXplorer, GXquery
Introducción
En esta nueva versión se introduce la posibilidad de incluir una o varias salidas personalizadas, desarrolladas por el usuario, para las consultas creadas con las interfaces Web de GXplorer y GXquery. De esta manera los usuarios tienen la posibilidad de desarrollar e integrar dentro de los productos las funcionalidades que crean convenientes para procesar y presentar la información devuelta por las consultas de GXplorer y GXquery.
Descripción
Las consultas realizadas en las interfaces Web de GXplorer y GXquery tenían hasta el momento dos posibilidades para mostrar los datos al usuario:
- El componente Pívot Table de los Microsoft Office Web Components.
- Una o varias gráficas, de distinto tipo, de los datos de la consulta.
A partir de la nueva versión es posible, además de los componentes de Pivot Table y gráficas Cross-browser y los Reportes Web, agregar nuevas salidas personalizadas para los datos de la consultas. Estas salidas serán implementadas por los usuarios de las herramientas, agregando la funcionalidad que crean conveniente, utilizando dos Web Services, con formato predefinido, que serán consumidos por GXplorer y GXquery.
Arquitectura de la solución
Funcionamiento general
Básicamente lo que se hace es agregar nuevas pestañas a las existentes en la página de edición y visualización de consultas en GXplorer y GXquery Web. Estas pestañas se sumarán entonces a las existentes de Edición, Datos, Editar Reporte, Ver Reporte y a las de las gráficas que el usuario pudiera haber definido.
Cada una de estas nuevas pestañas se denominan visualizadores y para su implementación se utilizarán dos Web Services, los cuales serán creados por los usuarios siguiendo un formato predefinido que deberán respetar para que puedan ser correctamente consumidos por las interfaces Web de GXplorer y GXquery.
Cuando se especifica una consulta y se procede a ejecutarla se invocará a uno de estos servicios, que llamaremos Check, que verificará si tiene sentido mostrar la consulta utilizando el visualizador correspondiente. Resumiendo, determina si la consulta es "visualizable" según cada salida personalizada. En caso afirmativo, aparecerá disponible la pestaña correspondiente al visualizador para mostrar la consulta.
El segundo servicio utilizado para implementar esta funcionalidad, al que llamaremos Get, se encargará de devolver la salida personalizada de la consulta para el visualizador seleccionado. El mismo es invocado al hacer clic en la pestaña correspondiente al visualizador.
Configuración de los visualizadores
La información de los visualizadores a utilizar debe configurarse en un archivo de nombre viewers.xml que debe ir en el directorio Program de la instalación de las herramientas.
El formato de este archivo es el siguiente:
<Viewers>
<Viewer>
<Name>Viewer1</Name>
<Description>Personalized Viewer 1</Description>
<Connection Host= "localhost" BaseUrl="/WS2/" Port ="80"
Secure="0" TimeOut="0"></Connection>
</Viewer>
<Viewer>
<Name>Viewer2</Name>
...
...
</Viewer>
...
</Viewers>
Donde (las etiquetas marcadas con negritas son obligatorias):
<Viewer> indica cada uno de los nuevos visualizadores personalizados (nuevas pestañas en la página de la consulta)
<Name> es un identificador interno para el visualizador
<Description> es el texto que se mostrará en la pestaña correspondiente
<Connection> información de la ubicación de los servicios
- Host: servidor donde se encuentran los servicios. El valor
predeterminado es "localhost"
- Port: puerto del servidor donde se encuentran los servicios. El valor
predeterminado es 80.
- BaseURL: directorio virtual del servidor donde se encuentran los
servicios. El valor predeterminado es "/".
- Secure: Indica si se utilizará protocolo seguro HTTPS (valor 1) o
inseguro HTTP (valor 0, predeterminado)
- Timeout: indica el timeout, en segundos, que se utilizará en la
invocación de los servicios. El valor predeterminado es 0.
La URL para invocar los servicios se generará de la siguiente forma:
<http/https>://<host>:<port>/<baseurl>/...
Servicios a utilizar
Los servicios que es necesario implementar deberán seguir las siguientes especificaciones para que puedan ser correctamente consumidos por GXplorer y GXquery Web. En particular deberán pertenecer al namespace GXBI y se deberá respetar el nombre de los servicios, y el nombre y tipo de cada parámetro.
Servicio Check
Este servicio deberá llamarse GXBICheckQuery y seguir el siguiente formato:
GXBICheckQuery (in: Character xmlQuerySpec, out: Boolean check)
Donde:
- xmlQuerySpec es un texto en formato XML con la especificación de la consulta. Puede verse un ejemplo del formato de los valores de este parámetro en la sección Formato de parámetros XML.
- check indicará si la consulta correspondiente a la especificación dada esta apta para usarse con el visualizador. Devuelve 1 en caso afirmativo y 0 en caso negativo.
Servicio Get
Este servicio deberá llamarse GXBIGetResult y seguir el siguiente formato:
GXBIGetResult (in: Character xmlQueryResult, in: Character xmlAbstractFormat, out: Character urlResult)
Donde:
- xmlAbstractFormat es el formato abstracto de la consulta recientemente ejecutada. Es un texto en formato XML en el cual viene la información de tipos, nombre, descripciones, etc. de los campos que conforman la consulta. Puede verse un ejemplo del formato de los valores de este parámetro en la sección Formato de parámetros XML.
- xmlQueryResult es un texto, también con formato XML, en el cual se detallan los datos que se obtuvieron como resultado de la ejecución de la consulta. Puede verse un ejemplo del formato de los valores de este parámetro en la sección Formato de parámetros XML.
- urlResult es una URL que referencia a un sitio o archivo en donde se encuentra la salida de la consulta con el aspecto dado por el visualizador correspondiente.
Formato de parámetros XML
Para mostrar mejor como son los formatos de los textos XML que utilizan los servicios como parámetros vamos a tomar como ejemplo la siguiente consulta:
Compras en $ y Promedio de Compras en Unidades por País, analizado por Año y Mes.
Especificación de la consulta
El primer texto XML que se utilizará por los servicios será el que informará de la especificación de la consulta y tendrá el siguiente formato:
<?xml version="1.0" encoding="ISO-8859-1" ?>
<Metadata Id="10" Name="CarDealer (OLAP Simple)" CreatedOn="2006-05-10" ModifiedOn="2006-05-10" Version="0500"
Paradigm="Dimensions/Measures" Path="C:\Catalog\GXplorerCatalog\SampleOLAP\GXplData.gpm">
<WorkQuery Title="Purchases" Destination="Pivot Table" AllowPivoting="Yes" ShowSubTotals="Automatic">
<SubQuery Title="Purchases $" Measure=" Purchases $" Axis="Data" Position="1">
<QueryElement Name="Purchases $" Description=" Purchases in $">
</QueryElement>
<Aggregation Type="Sum">
</Aggregation>
</SubQuery>
<SubQuery Title="Purchases Un." Measure="Purchase Un." Axis="Data" Position="2">
<QueryElement Name=" Purchase Un." Description="Purchase in Units">
</QueryElement>
<Aggregation Type="Average">
<Dimension Name="Country">
<QueryElement Name="Country? Description="Country ">
</QueryElement>
</Dimension>
</Aggregation>
</SubQuery>
<Dimension Title="Year" Type="Axis" Axis="Rows" Position="1"
OrderBy="Description" Direction="Ascending">
<QueryElement Name="Year" Description="Year">
</QueryElement>
<Selection Type="All">
</Selection>
</Dimension>
<Dimension Title="Month" Type="Axis" Axis="Rows" Position="4"
OrderBy="Description" Direction="Ascending">
<QueryElement Name="Month" Description="Month">
</QueryElement>
<Selection Type="All">
</Selection>
</Dimension>
</WorkQuery>
</Metadata>
Los elementos (etiquetas) más importantes a tener en cuenta son :
-
<Metadata>: información general de la metadata.
-
<Workquery>: información de la salida de consulta, como título, tipo de tabla y otras propiedades
-
<SubQuery>: indicadores o datos de la consulta. Se indica que medidor (indicador o atributo) lo compone junto a la información de agregaciones, condiciones y filtros que se hayan especificado
-
<Dimension>: dimensiones o ejes de la consulta. Se indica que medidor (dimensión a atributo) lo compone junto al tipo de selección elegido y otras propiedades.
Formato abstracto de la consulta
Luego de procesada la especificación de la consulta, cuando se invoca al servicio que obtiene la salida correspondiente al visualizador debemos pasar otros dos textos XML correspondientes a la consulta. Uno de ellos indica el formato abstracto de la consulta y tendrá el siguiente formato:
<?xml version="1.0" encoding="ISO-8859-1"?>
<FormatSpec>
<Output Type="DinamicTable">
<Title>
<Caption>Purchases</Caption>
</Title>
</Output>
<QueryElements>
<QueryElement Id="D15" Name="Year" CanTotalize="false">
<Title>
<Caption>Year</Caption>
</Title>
<Cell>
<Picture>General</Picture>
</Cell>
<AxisInfo>
<Type>Row</Type>
<Position>1</Position>
</AxisInfo>
<OrderInfo Type="Alphabetic">
<AlphabeticOrder>
<Order>Descendent</Order>
</AlphabeticOrder>
</OrderInfo>
</QueryElement>
<QueryElement Id="D18" Name="Months" CanTotalize="false">
<Title>
<Caption>Months</Caption>
</Title>
<Cell>
<Picture>General</Picture>
</Cell>
<AxisInfo>
<Type>Row</Type>
<Position>4</Position>
</AxisInfo>
<OrderInfo Type="Alphabetic">
<AlphabeticOrder>
<Order>Descendent</Order>
</AlphabeticOrder>
</OrderInfo>
</QueryElement>
<QueryElement Id="S1" Name="Purchase in $" CanTotalize="false">
<Title>
<Caption>Purchase in ___FCKpd___2lt;/Caption>
</Title>
<Cell>
<Picture/>
</Cell>
<AxisInfo>
<Type>Data</Type>
<Position>1</Position>
</AxisInfo>
<OrderInfo Type="None">
</OrderInfo>
</QueryElement>
<QueryElement Id="S2" Name="Purchase in Units" CanTotalize="false">
<Title>
<Caption>Purchase in Units</Caption>
</Title>
<Cell>
<Picture/>
</Cell>
<AxisInfo>
<Type>Data</Type>
<Position>2</Position>
</AxisInfo>
<OrderInfo Type="None">
</OrderInfo>
</QueryElement>
</QueryElements>
</FormatSpec>
En este texto se indica información general de la consulta, como el título y que campos componen la salida de la misma. Para cada campo se indica un identificador, un título, formato (Picture) a utilizar, tipo de orden y tipo de campo (eje o dato), además de otras propiedades.
Datos de la consulta
El otro texto XML que se debe pasar al servicio Get contendrá los datos que resultaron de la ejecución de la consulta en el siguiente formato:
<xml xmlns:s='uuid:BDC6E3F0-6DA3-11d1-A2A3-00AA00C14882'
xmlns:dt='uuid:C2F41010-65B3-11d1-A29F-00AA00C14882'
xmlns:rs='urn:schemas-microsoft-com:rowset'
xmlns:z='#RowsetSchema'>
<s:Schema id='RowsetSchema'>
<s:ElementType name='row' content='eltOnly'>
<s:AttributeType name='D15' rs:number='1' rs:nullable='true'
rs:writeunknown='true'>
<s:datatype dt:type='string' dt:maxLength='255'/>
</s:AttributeType>
<s:AttributeType name='D16' rs:number='2' rs:nullable='true'
rs:writeunknown='true'>
<s:datatype dt:type='string' dt:maxLength='255'/>
</s:AttributeType>
<s:AttributeType name='S1' rs:number='5' rs:nullable='true'
rs:writeunknown='true'>
<s:datatype dt:type='number' rs:dbtype='currency' dt:maxLength='8'
rs:precision='19' rs:fixedlength='true'/>
</s:AttributeType>
<s:AttributeType name='S2' rs:number='6' rs:nullable='true'
rs:writeunknown='true'>
<s:datatype dt:type='number' rs:dbtype='currency' dt:maxLength='8'
rs:precision='19' rs:fixedlength='true'/>
</s:AttributeType>
<s:extends type='rs:rowbase'/>
</s:ElementType>
</s:Schema>
<rs:data>
<z:row D15='2000' D18='January' S1='84600' S2='9'/>
<z:row D15='2000' D18='June' S1='55700' S2='6'/>
<z:row D15='2000' D18='August' S1='83300' S2='9'/>
<z:row D15='2001' D18='January' S1='63430' S2='6'/>
<z:row D15='2001' D18='October' S1='37860' S2='3'/>
<z:row D15='2001' D18='November' S1='108800' S2='11'/>
<z:row D15='2001' D18='March' S1='53200' S2='3'/>
<z:row D15='2001' D18='May' S1='20560' S2='2'/>
<z:row D15='2001' D18='June' S1='26420' S2='2'/>
<z:row D15='2001' D18='July' S1='193870' S2='16'/>
<z:row D15='2001' D18='August' S1='68090' S2='5'/>
<z:row D15='2001' D18='September' S1='20740' S2='2'/>
<z:row D15='2002' D18='December' S1='46245' S2='3'/>
<z:row D15='2002' D18='February' S1='50500' S2='3'/>
<z:row D15='2002' D18='May' S1='145210' S2='10'/>
<z:row D15='2002' D18='June' S1='194380' S2='15'/>
<z:row D15='2002' D18='July' S1='10120' S2='1'/>
<z:row D15='2003' D18='October' S1='100350' S2='8'/>
<z:row D15='2003' D18='November' S1='64260' S2='4'/>
<z:row D15='2003' D18='February' S1='107800' S2='9'/>
<z:row D15='2003' D18='March' S1='217745' S2='13'/>
<z:row D15='2003' D18='May' S1='30220' S2='2'/>
<z:row D15='2003' D18='June' S1='121580' S2='10'/>
<z:row D15='2003' D18='July' S1='28500' S2='2'/>
<z:row D15='2004' D18='January' S1='62070' S2='5'/>
<z:row D15='2004' D18='October' S1='74360' S2='4'/>
<z:row D15='2004' D18='December' S1='96735' S2='6'/>
<z:row D15='2004' D18='April' S1='92020' S2='7'/>
<z:row D15='2004' D18='June' S1='54160' S2='3'/>
<z:row D15='2004' D18='July' S1='56590' S2='4'/>
<z:row D15='2004' D18='August' S1='142555' S2='11'/>
<z:row D15='2004' D18='September' S1='64860' S2='5'/>
<z:row D15='2005' D18='November' S1='243735' S2='15'/>
<z:row D15='2005' D18='March' S1='28290' S2='2'/>
<z:row D15='2005' D18='April' S1='27840' S2='2'/>
<z:row D15='2005' D18='May' S1='193980' S2='13'/>
</rs:data>
</xml>
La información más importante se encuentra debajo de la etiqueta <rs:data>, donde se detallan los datos que resultaron de la ejecución de la consulta. Se indica para cada campo de la consulta, utilizando el identificador especificado en el formato abstracto de la consulta, el valor correspondiente.
Consideraciones
- Los servicios deben desarrollarse utilizando .Net Framework 1.14 o superior. Si no se desarrollan con GeneXus se deberá agregar el prefijo generado por GeneXus para los procedimientos Main (hasta GeneXus 9.0) a los nombres de los servicios, A + nombre del servicio.
Troubleshooting
Si se detectan problemas en la utilización de los servicios se recomienda tomar en cuenta los siguientes puntos para detectar las posibles causas.
Verificar que el archivo viewers.xml se encuentra en el directorio Program de la instalación del producto y que la información sobre los visualizadores y su ubicación sea la correcta y esté ingresada en el formato correcto. Ver sección Configuración de los visualizadores.
- Nomenclatura en los Web Services
Verificar que se estén respetando los nombres de los servicios y los nombres y tipos de datos de los parámetros que son esperados por GXplorer/GXquery Web. Si los servicios no fueron implementados en GeneXus recordar agregar el prefijo "A" a los nombres de los servicios. Ver sección Servicios a utilizar.
- Obtención de la definición de los Web Services
Verificar que se obtenga correctamente el WSDL de los Web Services:
http://<server>/<VirtualDirectory>/agxbicheckquery.asmx?wsdl
http://<server>/<VirtualDirectory>/agxbigetresult.asmx?wsdl
por ejemplo en una instalación local ejecutar:
http://localhost/userServices/agxbicheckquery.asmx?wsdl
http://localhost/userServices/agxbigetresult.asmx?wsdl
- Debug de una llamada SOAP
Seguir las recomendaciones del siguiente link.
- Visor de Eventos de Windows
Verificar el visor de Eventos de Windows (sección aplicación) en busca de mensajes de error o Warning.