Prácticas probadas de IBM Cognos: Un acercamiento a IBM Cognos 8 SDK

Modalidad del documento: Consejo práctico o técnica; Producto(s): IBM Cognos 8; Área de interés: Desarrollo

IBM Cognos 8 Software Development Kit (SDK) puede usarse para crear cualquier cosa desde simples aplicaciones de utilidades hasta aplicaciones altamente complejas a gran escala. De hecho, la mayor parte de la funcionalidad provista a través de IBM Cognos 8 Connection puede volver a crear usando IBM Cognos 8 SDK.

Introducción

generalidades

The IBM Cognos 8 Software Development Kit (SDK) puede usarse para crear cualquier cosa desde simples aplicaciones de utilidades hasta aplicaciones altamente complejas a gran escala. De hecho, la mayor parte de la funcionalidad provista a través de IBM Cognos 8 Connection se puede volver a crear usando IBM Cognos 8 SDK.

A partir de la versión 8.4.1, la documentación de IBM Cognos 8 SDK contiene más de 2900 páginas en formato PDF. Además de la documentación, existen muestras de códigos que se instalan con SDK y una cantidad considerable de notas técnicas y artículos de SupportLink relacionados con IBM Cognos 8 SDK. Para las personas que recién comienzan a usar IBM Cognos 8 SDK, toda esta información puede resultar avasallante y dificultar la tarea de encontrar un lugar por donde empezar.

Tel propósito de este documento es poner énfasis en los elementos de conocimiento que resultan fundamentales para casi todas las aplicaciones de IBM Cognos 8 SDK. Una vez que used se familiarice con estos elementos de conocimiento, le resultará mucho más fácil navegar y e identificar la información en la documentación de IBM Cognos 8 SDK para poder entender el sentido de los numerosos fragmentos de código que se encuentran disponibles.

Este documento hará muchas referencias a la documentación de IBM Cognos 8 SDK pero no repetirá lo que se incluye en la documentación del producto a menos que la información resulte necesaria con fines ilustrativos.

Los temas que se destacarán en este documento son:

  • Estructura del Almacén de Contenidos y rutas de búsqueda
  • Conjuntos de enumeración
  • Clases y propiedades
  • Servicios de IBM Cognos 8
  • Inicio y fin de sesión
  • Consultas al Almacén de Contenidos
  • Ejecución de un informe simple
  • Introducción a la conversación asincrónica

Los temas que no serán cubiertos por este documento pero que serán mencionados aquí con el fin de alertar al lector sobre qué se puede hacer con IBM Cognos 8 SDK son:

  • Agregado, eliminación y modificación de objetos en el Almacén de Contenidos
  • Ejecución de informes complejos que requieren prompting
  • Planificación de informes y ejecución de trabajos
  • Servicios de IBM Cognos 8 que no sean Content Manager Service (Servicio de administración de contenidos) ni Report Service (Servicio de informes)

En el conjunto de información sobre IBM Cognos 8 SDK, existen diferentes manuales para el desarrollo de modelos de metadatos del Framework Manager y para el desarrollo de Custom Authentication Providers (Proveedores de autenticación personalizada). Estos son temas que requieren un conocimiento avanzado y se encuentran fuera del alcance de este documento.

Para crear aplicaciones con IBM Cognos 8 SDK, no es necesario ser un experto en generación de informes o modelado de datos. Sin embargo, es útil conocer los conceptos básicos tanto de la generación de informes como del modelado. Estos conceptos básicos se pueden obtener en las muestras y la documentación del producto que se ofrece con IBM Cognos 8 o en cualquier otro curso de capacitación formal ofrecido por IBM Cognos Education. Para obtener más información sobre las ofertas de capacitación en IBM Cognos Education, visite http://www.ibm.com/software/data/education/cognos.html.

Requisitos previos de la documentación

El lector de este documento deberá cumplir con los siguientes requisitos:

  • Cierta experiencia en programación de Java, C# o VB.NET
  • Una instalación completa y configurada de IBM Cognos 8 BI en una única máquina
  • SDK instalado en la misma máquina que IBM Cognos 8 BI
  • Algunos paquetes y datos de muestra de IBM Cognos 8 BI instalados e implementados
  • Comprensión de la funcionalidad disponible en IBM Cognos Connection.

Alcance del documento

Los conceptos que se presentan en este documento corresponden a todas las versiones de IBM Cognos 8 SDK.


Obtenga las herramientas necesarias para el trabajo

Antes de comenzar, se recomienda seriamente la obtención de un Entorno de desarrollo integrado (IDE) para el lenguaje de programación preferido. Entre todas las ventajas que ofrece un IDE, las características más útiles son la ayuda sensible al contexto, las facilidades de construcción y depuración, la verificación de sintaxis en tiempo real y los códigos ¡con color.

Si se intenta escribir aplicaciones de IBM Cognos 8 SDK en Java, el entorno más utilizado es Eclipse IDE, que puede descargarse sin costo alguno de la siguiente página http://www.eclipse.org.

Si se van a escribir aplicaciones de IBM Cognos 8 SDK en C# o VB.NET, Visual Studio de Microsoft será el entorno usado como IDE. También existen IDEs de código abierto gratuitos que se pueden usar.

Si se tiene la intención de usar Visual Basic 6 (VB6) como lenguaje de desarrollo, se recomienda en su lugar usar VB.NET. Además de que VB6 no cuenta con el soporte extendido de Microsoft desde abril de 2008, el soporte de IBM Cognos 8 SDK para VB6 se ha visto desfavorecido con el lanzamiento de la versión 8.4 de IBM Cognos 8 BI.

Una vez elegido el lenguaje de programación de su preferencia, es importante leer la información relevante incluida en la sección denominada Kits de herramientas de IBM Cognos 8 de la Guía de Primeros Pasos de IBM Cognos 8 SDK.


Acerca de IBM Cognos 8 Web Services

IBM Cognos 8 está construido con una arquitectura basada en servicios web y el IBM Cognos 8 SDK se implementa sobre estos servicios web. En la práctica, no hay necesidad de preocuparse por los aspectos prácticos de IBM Cognos 8 Web Services. Con seguridad podemos decir que funcionan de la manera que se publicita. Si tiene interés en saber cómo se ven en realidad estos servicios web, existen numerosas herramientas disponibles que permiten la visualización de los mensajes de SOAP.


Implantación de una instalación independiente de IBM Cognos 8

Cuando se comienza a trabajar con IBM Cognos 8 SDK, se recomienda construir un espacio seguro o sistema de desarrollo independiente para las primeras etapas del desarrollo. De esta manera, se protegerán las demás instalaciones de IBM Cognos 8 de potenciales errores que puedan surgir debido a la curva de aprendizaje inicial.

En la instalación independiente de IBM Cognos 8, se recomienda permitir un acceso irrestricto a todos los objetos de Content Store (Almacenamiento de contenidos). Así se elimina la necesidad de tomar en cuenta los permisos de acceso mientras se aprenden los temas centrales. Esto no quiere decir que los permisos de acceso no sean importantes, pero su uso e implicancias podrán aplicarse de manera progresiva.

La configuración de un acceso irrestricto al Content Store se realiza especificando objetos Cuenta o Grupo individuales como miembros del rol incorporado de System Administrators en el espacio de nombres de Cognos. Como se tratará más adelante, una aplicación de IBM Cognos 8 SDK obtiene acceso conectándose como usuario de la misma manera que un usuario interactivo. Si dicho usuario es miembro del rol incorporado de System Administrators, la aplicación de IBM Cognos 8 SDK tendrá total acceso a todos los objetos de Content Store.

Una instalación predeterminada en un único servidor permitirá acceso anónimo y dará al grupo Everyone (Todos) en el espacio de nombres de Cognos los permisos del rol incorporado System Administrators. La aplicación de IBM Cognos 8 SDK no necesitará iniciar sesión y será tratada como un usuario anónimo.

Si no es posible o no se desea el acceso anónimo, usted deberá agregar un usuario desde un espacio de nombres de seguridad, el cual fuera configurado durante el proceso de instalación, a los miembros del rol de System Administrators. La aplicación de IBM Cognos 8 SDK deberá usar esta cuenta de usuario para autenticar e iniciar sesión en IBM Cognos 8.


Implantaciones y datos de muestra

Se recomienda furetemente la instalación de algunas implantaciones y algunos datos de muestra de IBM Cognos 8 BI antes de usar IBM Cognos 8 SDK. De esta manera se creará un entorno de informes independiente y se obtendrán los siguientes beneficios para el desarrollo de aplicaciones de IBM Cognos 8 SDK.

  • Se puebla el Content Store con informes de muestra de diversos estilos y grados de complejidad
  • Se hace referencia al mismo en la documentación de IBM Cognos 8 SDK
  • Es utilizado por la mayoría de las muestras de códigos de SDK
  • Es un entorno de informes reconocido con el cual muchas personas están familiarizadas.
  • Permite la fácil replicación del entorno de informes incluido en IBM Cognos Support en caso de necesitar asistencia

Se recomienda también la ejecución de algunos de los informes de muestra a través de IBM Cognos Connection para lograr cierta comprensión sobre las posibilidades que existen cuando se ejecutan y gestionan informes. Toda la funcionalidad específica relacionada con la ejecución y la gestión de informes mediante IBM Cognos Connection se encuentra disponible a través de IBM Cognos 8 SDK.


Disposición del Content Store y rutas de búsqueda

Los objetos con los cuales funciona IBM Cognos 8 SDK están incluidos en el Content Store en una estructura jerárquica similar a la de carpetas y archivos anidados. Para acceder a estos objetos, es necesario estar familiarizado con la disposición del Content Store. Usted podrá encontrar la disposición del Content Store en la Guía del Desarrollador de IBM Cognos 8 SDK.

  • Para las versiones 8.1, 8.2 y 8.3 de IBM Cognos 8 BI, consulte la sección Estructura del Content Store en este capítulo Cómo gestionar contenidos.
  • Para la versión 8.4 de IBM Cognos 8 BI, ver Apéndice C: Configuraciones iniciales del Content Store.

La disposición del Content Store define la ruta de búsqueda. La ruta de búsqueda es un componente clave para el desarrollo de aplicaciones de IBM Cognos 8 SDK debido a que se usa para identificar cuál es, o cuáles son, los objetos de Content Store que hay que recuperar. El Apéndice titulado Sintaxis de la ruta de búsqueda de la Guía del Desarrollador de IBM Cognos 8 SDK ofrece información detallada sobre las rutas de búsqueda, incluyendo cómo obtener una ruta de búsqueda para un objeto individual IBM Cognos Connection. En esta sección, aparece una tabla corta que incluye algunas muestras de rutas de búsqueda. En esta tabla, preste especial atención al significado de "~", "/" (barra simple), "//" (barra doble) y"//*" (barra doble y asterisco).

  • El signo "~" (tilde simple) es un atajo a la ruta de búsqueda que representa el objeto Account (Cuenta) del usuario que está usando la aplicación IBM Cognos 8 SDK para la autenticación. Más adelante en este documento se discute más información sobre la conexión a una aplicación de IBM Cognos 8 SDK
  • El signo "/" (barra simple) en la ruta de búsqueda significa "devolver elementos secundarios directos” del tipo especificado desde la ubicación actual.
  • El signo "//" (barra doble) en la búsqueda significar "devolver todos los elementos del tipo especificado" desde la ubicación actual
  • El signo "//*" (barra doble y asterisco) en la ruta de búsqueda significa "devolver todos los elementos de cualquier tipo" desde la ubicación actual

Una ruta de búsqueda es similar a un enunciado de XPath. Si usted no está familiarizado con XPath, puede ser útil repasar los conceptos básicos: podrá encontrar un tutorial introductorio en http://www.w3schools.com/xpath. No es necesario ser experto en XPath para usar IBM Cognos 8 SDK, pero cabe señalar que el uso de XPath para analizar y procesar cualquier documento en XML podrá simplificar en gran medida el desarrollo al reducir la cantidad de códigos requeridos dentro de una aplicación.

En la Guía del Desarrollador de IBM Cognos 8 SDK, el capítulo denominado Clases incluye una sección titulada Content Manager Containment Relationships (Relaciones de contención en Content Manager). Esta sección es muy útil para determinar dónde reside un objeto en la jerarquía de Content Store y cuál será la ruta de búsqueda a ese objeto.

Además de su rol en el desarrollo de aplicaciones de Cognos 8 SDK, las rutas de búsqueda se usan también para otros fines que no son de SDK, como por ejemplo:

  • Ejecución de un informe vía URL, independiente de Cognos Connection
  • Referencias a las cuentas de usuarios y a los listados de directorios cuando se explotan los informes

En la jerarquía del Content Store de Cognos 8, existen 7 carpetas del máximo nivel. Éstas son:

  • adminFolder (Carpeta de administración)
  • capability (capacidad)
  • configuration (configuración)
  • content (contenidos)
  • directory (directorio)
  • portal (portal)
  • transientStateFolder (Carpeta de estado transitorio)

Las más usadas de las carpetas de alto nivel en una aplicación de Cognos 8 SDK serán content y directory. En especial, las siguientes subcarpetas:

  • /content/package incluirá todos los informes y las vistas de informes creadas para un paquete en particular.
  • /directory/namespace incluirá información de seguridad externa, como por ejemplo usuarios, grupos y roles para un espacio de nombres en particular. Es importante observar que, a excepción del espacio de nombres incorporado de Cognos, la información que aquí se incluye no son los datos reales almacenados en el proveedor de seguridad externo., sino que es una representación de los datos asociados que son específicos de Content Store.

Los objetos de Content Store en /directory/namespace (incluyendo el espacio de nombres) poseen una ruta de búsqueda que difiere del resto de la jerarquía de Content Store. Estos objetos tendrán una ruta de búsqueda que comienza con la palabra "CAMID", que significa Cognos Access Manager ID. Una CAMID es una ruta de búsqueda completa de igual manera que "~". Una CAMID es una representación interna y la aplicación de IBM Cognos 8 SDK no deberá depender de los componentes individuales que componen una CAMID. No hay garantía de que el formato o los contenidos de la CAMID permanezcan inalterables en las distintas versiones de los productos.


Conjuntos de enumeración

En el contexto de IBM Cognos 8 SDK, un conjunto de enumeración puede ser considerado como una lista de constantes de sólo lectura. Al igual que las entidades independientes, los conjuntos de enumeración no tienen demasiado valor. Su único propósito es actuar como identificador sin necesidad de conocer los contenidos reales. Los valores de un conjunto de enumeración se usan por lo general para ofrecer datos de entrada a un método, si bien existen situaciones en las que son útiles para determinar el tipo de salida.

Una entidad de un conjunto de enumeración se especifica con la forma:

  • enumSetName.enumMemberName

Por ejemplo:

  • Para especificar el miembro defaultName del conjunto de enumeración propEnum, use propEnum.defaultName.
  • Para especificar el miembro account del conjunto de enumeración classEnum, use classEnum.account.

Existen muchos conjuntos de enumeración en IBM Cognos 8 SDK (80+ en la versión 8.2 y 110+ en la versión 8.4) pero sólo se deberá estar familiarizado con 7 de ellos en este momento. Los mismos son:

  • Uso general
    • classEnum
  • Consulta a Content Store
    • propEnum
  • Ejecución de informes
    • runOptionEnum
    • outputEncapsulationEnum
    • outputFormatEnum
    • asynchReplyStatusEnum
    • asynchDetailReportStatusEnum

La lista completa de conjuntos de enumeración se encuentra en la Guía del Desarrollador de IBM Cognos 8 SDK en el capítulo titulado Enumeration Sets (Conjuntos de enumeración). En la siguiente sección, se observará que classEnum y propEnum también son útiles como referencia en la identificación del propósito de las muchas clases que componen Cognos 8 SDK.


Todas esas clases

Existen varios ceintos de clases que componen IBM Cognos 8 SDK. Cada una de ellas aparece y se describe en la Guía del Desarrollador de IBM Cognos 8 SDK en el capítulo titulado Clases.

la lista de clases de e IBM Cognos 8 puede clasificarse en dos grupos distintos:

  • Clases que representan objetos de Content Store
  • Clases que implementan propiedades de los objetos del Content Store

Clases que representan objetos de Content Store

Las clases que representan objetos de Content Store son aquellas que conciernen más a una aplicación de IBM Cognos 8 SDK. Son las mismas clases que se observan en la disposición de Content Store. También están definidas en el conjunto de enumeración classEnum.

Además de las clases que aparecen en classEnum, existen muchas otras clases cuyo sólo propósito es definir propiedades comunes para oras clases. Estas clases son conocidas como clases abstractas. Existen numerosas clases abstractas en IBM Cognos 8 SDK pero en este momento, las más relevantes son:

  • baseClass – define propiedades que corresponden a todas las clases de classEnum y las clases que se enumeran a continuación.
  • uiClass – define propiedades que se pueden manipular con IBM Cognos Connection. Esta clase es heredada por muchas de las clases enumeradas en classEnum.
  • baseReport – heredada de uiClass. Incluye propiedades comunes a la ejecución y la gestión de informes.
  • authoredReport. – heredada de baseReport. Incluye propiedades que son específicas de un informe determinado. La especificación del informe es una propiedad de esta clase.

Los términos objeto y clase a menudo se usan de manera indistinta. En este documento, el término class (clase) se usará como una definición y el término object (objeto) se usará para representar una instancia física de esta definición. Por ejemplo, el término report object (objeto de informe) se referirá a un objeto real de Content Store de la clase report (informe). Se puede acceder a un objeto con una ruta de búsqueda.

Clases que implementan propiedades de los objetos de Content Store

El resto de las calses del capítulo titulado Clases de la Guía del Desarrollador de IBM Cognos 8 SDK son clases que implementan propiedades de los objetos de Content Store. De hecho, todas las propiedades de IBM Cognos 8 SDK se implementan como clases. Con IBM Cognos 8 SDK, no existe tal cosa como tipos de datos "simples" o "nativos" como por ejemplo int,de cadena, o booleano. En cambio, estos tipos de datos se implementan a través del uso de clases. Por ejemplo:

  • la clase booleanProp representa un tipo nativo booleano de datos
  • la clase intProp representa un tipo nativo int de datos
  • la clase stringProp representa un tipo nativode cadena de datos.

Las clases que representan propiedades pueden encontrarse en el conjunto de enumeración propEnum. En la versión 8.2 existen más de 300 clases que representan propiedades, y en la versión 8.4 hay más de 400.


Servicios de IBM Cognos 8

Los servicios de IBM Cognos 8 son una interfaz de la aplicación de SDK al servidor de IBM Cognos 8. Según la versión, existen entre 15 y 20 servicios que se pueden usar en una aplicación de IBM Cognos 8 SDK.

Cada uno de los servicios de IBM Cognos 8 está definido por un propósito funcional específico. Por ejemplo, ContentManagerService se usa para acceder a y manipular el Content Store, ReportService contiene funcionalidad que asegura que los informes se ejecuten y JobService es responsable de la ejecución de los informes.

Internamente, un servicio de IBM Cognos 8 puede llamar a otro servicio de IBM Cognos 8 para que realice parte de la tarea. Por ejemplo, si un trabajo incluye un informe a ejecutar, JobService llamará a ReportService para que ejecute el informe.

Cada servicio de IBM Cognos 8 posee métodos asociados y cada uno de estos métodos forma parte de un conjunto de métodos. Es posible que varios servicios contengan el mismo método. Por ejemplo, ReportService y JobService contienen el método run().ReportService ejecuta los informes y JobService ejecuta trabajos.

El resto de este documento pondrá énfasis en los siguientes dos servicios:

  • ContentManagerService
  • ReportService

Estos dos servicios son los más usados en una instalación típica de IBM Cognos 8 y son usados por una aplicación de SDK para iniciar y finalizar sesión, realizar consultas al Content Store y ejecutar informes. Cuando se está familiarizado con ellos, el uso de otros servicios como por ejemplo JobService será bastante más directo.

Para ver información detallada sobre cada uno de los servicios de IBM Cognos 8, los métodos disponibles para cada servicio y las muestras de código para crear y conectarse a un servicio de IBM Cognos 8, consulte el capítulo titulado Servicios de la Guía del Desarrollador de Cognos 8 SDK.

NOTA: En las versiones 8.1 y 8.2 de IBM Cognos 8 SDK, existe un servicio denominado CognosReportNetService. Este servicio se brinda con fines de compatibilidad para las aplicaciones de SDK que fueron escritas en IBM Cognos ReportNet. El CognosReportNetService fue incluido en la lista de los servicios desfavorecidos por el lanzamiento de la versión 8.1 y fue eliminado del producto con la versión 8.3.


Inicio y finalización de sesión

Cuando una aplicación de IBM Cognos 8 SDK crea un objeto que representa un servicio de IBM Cognos 8, el servicio se conectará automáticamente al servicio de IBM Cognos 8 en la URL especificada durante la creación del objeto. El proceso para crear y conectarse a un servicio de IBM Cognos 8 es el mismo independientemente del servicio que se use

A menos que se permita acceso anónimo, cuando una aplicación de IBM Cognos 8 SDK se conecta al servidor de IBM Cognos 8 la aplicación no tiene derechos o permisos de acceso implícitos. La aplicación de IBM Cognos 8 SDK debe iniciar sesión de la misma manera que lo haría un usuario interactivo. Si se permite el acceso anónimo, la aplicación de IBM Cognos 8 SDK recibirá los mismos derechos y permisos que el usuario anónimo del espacio de nombres de Cognos. Por ejemplo, si no se permite acceso anónimo y no se conecta una aplicación de IBM Cognos 8 SDK, se producirá una excepción cuando la aplicación trate de realizar una acción como por ejemplo realizar una consulta al almacenamiento de contenidos o ejecutar un informe.

Todos los inicios y las finalizaciones de sesión se realizan por medio del ContentManagerService con los métodos logon() y logoff(). Ninguno de los demás servicios de IBM Cognos 8 puede realizar una aoperación de inicio o finalización de sesión.

Inicio de sesión

El método logon() de ContentManagerService toma dos parámetros: credentials (credenciales) y roles.

El parámetro credentials es una cadena de XML codificados cuyo formato se describe en la clase credentials en el capítulo titulado Clases de la Guía del desarrollador de IBM Cognos 8 SDK. El XML para un parámetro credentials básico tiene la siguiente apariencia:

<credential> <namespace> namespace ID
                    as specified in Cognos Configuration </namespace>
                    <username> username contained in
                namespace </username> <password> password for
                    username </password> </credential>

El parámetro roles se usa para especificar las rutas de búsqueda de los objetos role del espacio de nombres de Cognos. Los permisos de estos objetos role se aplicarán al usuario especificado en las credenciales. Si no se requieren roles adicionales, este parámetro deberá ser un array vacío en lugar de nulo.

Uso compartido del pasaporte CAM entre servicios

Si el inicio de sesión fue exitoso, ContentManagerService se convierte en un servicio autenticado y se volverá a enviar una cadena conocida como CAM Passport a la aplicación de IBM Cognos 8 SDK en BIBusHeader. Cuando una aplicación de IBM Cognos 8 SDK crea un objeto para representar un servicio de IBM Cognos 8, ese objeto incluirá una propiedad denominada BIBusHeader. BIBusHeader representa el encabezado de SOAP que se usa para comunicarse con el servidor de IBM Cognos 8. Dentro de BIBusHeader, hay una propiedad denominada CAM que a su vez contiene una propiedad denominada CAMPassport. El CAM Passport devuelto por el método logon() se almacena en la propiedad CAMPassport.

¿Por qué es importante el CAM Passport? En una aplicación de IBM Cognos 8 SDK, el CAM Passport evita la propagación automática a otros servicios que podrían ser utilizados dentro de una aplicación. Debido a que ContentManagerService es el único servicio que puede iniciar o finalizar sesión, debe existir una capacidad para asignar el CAM Passport a los otros servicios que pueda necesitar la aplicación de SDK (como, por ejemplo, ReportService). Esta asignación se realiza simplemente mediante la copia del BIBusHeader de ContentManagerService al BIBusHeader del otro servicio, convirtiendo de este modo al servicio en un servicio autenticado.

Las muestras que se instalan con el IBM Cognos 8 SDK incluyen códigos que muestran cómo conectarse a un servicio de IBM Cognos 8, cómo iniciar sesión usando ContentManagerService y cómo copiar un BIBusHeader de ContentManagerService a otro servicio.

Muestras de Java

Los archivos de muestras de Java que muestran cómo iniciar sesión y cómo compartir un CAM Passport son:

<install_location>/sdk/java/Common/CRNConnect.java
                <install_location>/sdk/java/Security/Logon.java

Para conectarse a un servicio de IBM Cognos 8, vea en CRNConnect.java uno de los métodos connectToCognosServer. Este es un método de utilidad que conectará muchos de los servicios de IBM Cognos 8 a la misma URL.

Una vez que el servicio de IBM Cognos 8 ha sido conectado, el método quickLogon()del archivo Logon.java muestra cómo construir las credenciales en XML y cómo llamar al método logon() de ContentManagerService.

Para copiar el BIBusHeader, consulte el método getReportService() en CRNConnect.java. Una revision más detallada de CRNConnect.java revelará numerosos métodos con la forma get____Service()donde "____" puede archivarse con un nombre de servicio de IBM Cognos 8. El proceso de copiado del BIBusHeader de ContentManagerService en otro servicio de IBM Cognos 8 es el mismo, independientemente del servicio.

Muestras de C#

Los archivos de muestras de C# que muestran cómo iniciar sesión y cómo compartir un CAM Passport son

<install_location>/sdk/csharp/SamplesCommon/SamplesConnect.cs
                <install_location>/sdk/csharp/SamplesCommon/SamplesLogon.cs

Como se puede observar en SamplesConnect.cs, todo lo que se requiere para conectarse a un servicio de IBM Cognos 8 es fijar la propiedad Url del objeto de servicio de IBM Cognos 8.

Una vez que se ha conectado el servicio de Cognos 8, el método specificUserLogon()muestra cómo construir las credenciales en XML y cómo llamar al método logon() de ContentManagerService.

Para copiar el BIBusHeader de ContentManagerService en otro servicio, simplemente use el operador "=" como se muestra en los métodos get que están implementados al final de SamplesConnect.cs.

Finalización de sesión

Una aplicación de IBM Cognos 8 SDK finaliza sesión usando el método logoff() de ContentManagerService. No existen parámetros para el método logoff().

Cuando se llama al método logoff(), el CAM Passport será invalidado por el servidor de IBM Cognos 8. Esto significa que cualquier otro servicio autenticado de IBM Cognos 8 que hubiera sido establecido por la aplicación de SDK queda automáticamente desconectado. Cualquier uso posterior del CAM Passport desde un BIBusHeader guardado devolverá una falla.

Si una aplicación de IBM Cognos 8 SDK no se desconecta de manera explícita, la sesión permanecerá activa hasta que venza el tiempo límite. Todas las aplicaciones de SDK que se han conectado se deberán desconectar una vez finalizado el proceso.


Consultas al Content Store

En algún momento, una típica aplicación de IBM Cognos 8 SDK deberá buscar uno o más objetos de Content Store. Esto se realiza usando ContentManagerService. Como se mencionó antes, los objetos de Content Store que se pueden recuperar son aquellos que figuran en el conjunto de enumeración classEnum y que se encuentran especificados con una ruta de búsqueda.

Método ContentManagerService.query ()

El método query(searchPath, properties, sortBy, options) de ContentManagerService se usa para recuperar objetos de Content Store. Debido a que se puede devolver más de un objeto de Content Store, el método query() devuelve un array de objetos de Content Store.

Los parámetros del método query() son los siguientes:

  • searchPath es una cadena que incluye la ruta de búsqueda del objeto de Content Store.
  • properties es un array de valores tomados del conjunto de enumeración propEnum que identifican las propiedades que se deben devolver con el objeto de Content Store.
  • sortBy es un array de objetos sort que determina cómo se clasifica el array que se devuelve. Este documento no se ocupará de este parámetro pero incluso si no se usa, se deberá proporcionar un objeto sort vacío.
  • options es un objeto de queryOptions que ofrece varias opciones para el procesamiento de los datos. Este documento no se ocupará de este parámetro pero incluso si no se usa, se deberá proporcionar un objeto queryOptions vacío.

En muchos fragmentos de código de muestra, usted observará que se llama al método query() de la siguiente manera:

query(searchPath, properties, new Sort[] {}, new
                QueryOptions())

Observe que los parámetros sortBy y options no son nulos. Son instancias vacías de un objeto. Si se proporcionan valores nulos, se producirá un error (excepción).

Esto es, en esencia, todo lo que hay que saber acerca de la recuperación de objetos desde Content Store. La mayor parte del código de la aplicación de IBM Cognos 8 SDK involucrará el procesamiento de las propiedades del /de los objeto/s recuperado/s de Content Store.

Cómo se devuelven los objetos de Content Store

El tipo de devolución del método query(searchPath, properties, sortBy, options) es un array de objetos baseClass. Sin embargo, esto no significa que el array realmente contenga los objetos baseClass. En realida el array contiene los objetos de Content Store en la clase que usted espera. El motivo para que el array que se devuelve sea de objetos baseClass es que el lenguaje de programación (Java, C#, VB.NET) requiere que todos los miembros del array sean de la misma clase y la única clase que corresponde a todos los objetos del Content Store esbaseClass. Para acceder al objeto de Content Store que se almacena en el array como la clase que se espera que se devuelva, el objeto debe estar elegido para su clase real. En la mayoría de las instancias, la clase real del objeto de Content Store devuelto será conocida para que se pueda elegir directamente.

En los casos en que no se conoce la clase devuelta, puede ser necesario determinar la clase de objeto para poder elegirla adecuadamente. Por ejemplo, es posible que la searchPath que especifica la devolución de todos los objetos de Content Store en un objeto folder determinado devuelva una combinación de objetosreport, reportView, folder y URL. Para determinar la clase de objeto devuelto, existen dos técnicas que se pueden emplear.

La primera técnica consiste en usar un operador de lenguaje específico que realizará una comparación al nivel del objeto. En Java, use el operador instanceof, para C# use el operador is y para VB.NET use la combinación de TypeOf y Is.

La segunda técnica consiste en comparar el valor de la propiedad objectClass de un objeto baseClass con un miembro de ClassEnum. Por ejemplo,

if (baseClassObj.getObjectClass().getValue()== ClassEnum.Report)
                    {<code to process a Report object>} if
                (baseClassObj.getObjectClass().getValue()== ClassEnum.ReportView) {<code
                    to process a ReportView object>} if
                (baseClassObj.getObjectClass().getValue()== ClassEnum.Account) {<code to
                    process an Account object>}

Ejecución de un informe simple

Esta sección se centrará en los informes que se crean y se guardan con Report Studio. Sin embargo, es importante dares cuenta de que los mismos conceptos corresponden igualmente a los informes creados y guardados con Query Studio. Existen unas pocas diferencias menores entre ambos, que se mencionan a continuación:

  • Report Studio guarda objetos report (informe) en el Content Store.
  • Query Studio guarda objetos query (consulta) en el Content Store.
  • Los objetos report y query tienen el mismo conjunto de propiedades.

Cuando se habla de IBM Cognos 8 y de los informes, a menudo se usa el término especificación de informe(con frecuencia abreviado report spec). Una especificación de informe es simplemente un documento XML que puede ser interpretado por IBM Cognos 8 para generar un informe. El documento XML no tiene significado fuera de IBM Cognos 8. Una especificación de informe contiene gran cantidad de información y puede ser muy compleja. Los detalles de las especificaciones de informes se encuentran fuera del alcance de este documento pero se puede obtener más información en la Guía del desarrollador de IBM Cognos 8 SDK en el capítulo titulado Uso de Especificaciones de Informes y Referencia a las Especificaciones de informes.

Los términos informe y especificación de informe a veces se usan de manera indistinta fuera del contexto de una aplicación de IBM Cognos 8 SDK. Sin embargo, en términos de IBM Cognos 8 SDK esta utilización no es correcta. Un informe es un objeto de Content Store y forma parte del conjunto de enumeración classEnum. Una especificación de informe es una propiedad y forma parte del conjunto de enumeración propEnum. Como es de esperarse, la especificación de informe es una propiedad de la clase del informe.

La sección titulada Ejecución de informes de la Guía del desarrollador de IBM Cognos 8 SDK incluye información relacionada con la ejecución de informes.

Método ReportService.run ()

Para ejecutar un informe usando IBM Cognos 8 SDK, se usa el método run(objectPath, parameterValues, options) de ReportService. Este método ejecutará una especificación de informe XML que ha sido guardada previamente en el Content Store como parte de un objeto informe o reportView. El parámetro objectPath es una ruta de búsqueda de un objeto report o reportView. Este es el método que se invoca cuando un usuario hace clic en un objeto report o reportView en IBM Cognos Connection.

El método runSpecification(specification, parameterValues, options) ejecutará una especificación de informe en XML que pasa a través del parámetro de la especificación. Este método se adecua mejor a aquellas situaciones en las que las especificaciones de informes se crean en tiempo real y no se almacenan en el Content Store. Este es el método invocado por Report Studio y Query Studio para ejecutar un informe.

Los parámetros parameterValues y options son iguales para los métodos run() y runSpecification(). Estos parámetros deben ser objetos reales independientemente de si se están usando o no. Un valor nulo (o nada) generará un error (excepción).

parameterValues es un array de objetos ParameterValue. Cada elemento del array se mapea a un prompt contenido dentro del informe. Las complejidades del procesamiento de prompts/parámetros pueden ser muchas y se encuentran fuera del alcance de este documento.

options es un array de objetos option. Debe observarse que el objeto option en sí mismo es un objeto abstracto y que sólo se usa para definir las propiedades que heredarán otros objetos. La lista de opciones reales que corresponden a la ejecución de un informe se encuentra en el conjunto de enumeración runOptionEnum.

Algunas de las opciones de ejecución más comunes son:

  • outputFormat – especifica el /los tipo/s de resultados a generar. Los tipos de resultados válidos se especifican en el conjunto de enumeración outputFormatEnum.
  • outputEncapsulation – especifica dónde se almacena el resultado. Las encapsulaciones de resultados válidas están especificadas en el conjunto de enumeración outputEncapsulationEnum.
  • prompt – especifica si se deben crear o no páginas de prompts para satisfacer parámetros de informes no resueltos. El procesamiento de páginas de prompts y el envío de valores de prompts desde una aplicación de SDK se encuentran fuera del alcance de este documento.
  • primaryWaitThreshold – tiempo inicial de espera, en segundos, a que finalice el informe antes de que se inicie una conversación asincrónica. La conversación asincrónica será tratada en la sección siguiente.
  • secondaryWaitThreshold – cuando una conversación asincrónica se encuentra en progreso, la cantidad de tiempo de espera, en segundos, entre las verificaciones de estado.
  • saveOutput – especifica si el resultado del informe se debe guardar en el Content Store

Como es de esperar, el método run() esperará a que el informe se termine de ejecutar, aunque cabe señalar que no esperará eternamente. La opción de ejecución primaryWaitThreshold especifica el tiempo máximo de espera en el método run(). El valor predeterminado es 7 segundos. Si el resultado del informe no está listo transcurrido este lapso, el métodorun()se completará y la aplicación de IBM Cognos 8 SDK continuará con el procesamiento. Pueden ser necesarios bloques de códigos adicionales después del método run() para poder manejar los informes de ejecución extensa. Esto se discutirá en la siguiente sección, en el punto Conversación asincrónica.

Sólo para brindar un panorama completo, existe también el método runAt(startTime, objectPath, parameterValues, options) del EventManagementService. Este método se comporta igual que el método run(objectPath, parameterValues, options) con la excepción de que se especifica un horario para la ejecución del informe en el parámetro startTime y el resultado se almacena en el Content Store. El métodorunAt()no se trata en este documento.

Conversación asincrónica

Los informes pueden ser muy dinámicos por naturaleza y a menudo existen muchos factores externos que determinan el desempeño y la presentación del informe. Estos factores incluyen cuestiones tales como la cantidad de datos que se recuperan, la cantidad de formateo que se debe realizar en el informe, y el mantenimiento de los sockets de comunicación en estado activo. Cada uno de estos factores también sufre la influencia de la cantidad de usuarios que acceden al entorno y la carga que se coloca en el hardware utilizado en ese entorno. Con tantas variables, es imposible saber cuánto tiempo demorará la ejecución de un informe dado. Además, existen también características de los productos como por ejemplo la generación de informes y el prompting interactivos que agregarán complejidad a la generación de un informe. Para que una aplicación de IBM Cognos 8 SDK ejecute un informe en un entorno tan complejo, se utiliza la conversación asincrónica.

Cuando se comienza a trabajar con IBM Cognos 8 SDK, la conversación asincrónica puede ser más confusa que cualquier otro tema; no obstante, seguramente será necesaria una comprensión acabada de la conversación asincrónica para las aplicaciones de calidad en producción. Además, es importante comprender que la conversación asincrónica no se aplica sólo a la ejecución de informes. Se aplica a todos los demás servicios de IBM Cognos 8 que implementan el método run().

Como ejemplo de una aplicación que usa ampliamente la conversación asincrónica, podemos mencionar el Cognos Viewer. Algunos de los aspectos más visibles de la conversación asincrónica son el reloj de arena rotativo que se usa mientras se espera un resultado, la presentación de páginas de prompts, el envío de valores de prompts y el avance y retroceso de páginas en un informe HTML.

Los detalles de la conversación asincrónica aparecen dentro de la Guía del desarrollador de IBM Cognos 8 SDK en la sección titulada Cómo comprender la conversación asincrónica en el capítulo denominado Cómo ejecutar tareas. Esta sección incluye una típica conversación asincrónica para ejecutar un informe.

Incluso los informes simples sin prompts pueden llegar a demorar mucho en su ejecución. Esto sucede a menudo cuando el informe presenta grandes cantidades de datos. Como se mencionara en la sección anterior,primaryWaitThreshold se usa para determinar la cantidad de tiempo que el método run()esperará el resultado. Si este tiempo se cumple y el resultado aún no está listo, la aplicación de IBM Cognos 8 SDK deberá esperar y permanecer sincronizada al servidor de Cognos 8 hasta que el resultado esté listo. Esto se logra usando el método wait() del ReportService. La aplicación de IBM Cognos 8 SDK permanecerá en el método wait() hasta que el resultado del informe esté listo o haya transcurrido el tiempo especificado por la opción de ejecución secondaryWaitThreshold. El valor predeterminado para secondaryWaitThreshold es de 30 segundos. Por lo general, una aplicación de IBM Cognos 8 SDK simplemente realizará un bucle alrededor del método wait()hasta que esté listo el resultado del informe.

La Guía del desarrollador de IBM Cognos 8 SDK sostiene que es posible fijar cualquiera de los umbrales de espera en 0. Esto significa que no habrá conversación asincrónica y que la aplicación de IBM Cognos 8 SDK esperará hasta que se devuelvan los datos del informe o hasta que se produzca un error. Una espera indeterminada se considera por lo general como una mala técnica para las aplicaciones de calidad en producción. Este es un enfoque pasivo y hace que sea difícil, si no imposible, reaccionar ante los errores. Además, la aplicación por lo general requerirá códigos adicionales para gestionar otros recursos que dependen del tiempo como por ejemplo los sockets de comunicación. Será preferible conocer y usar la conversación asincrónica para gestionar el procesamiento del informe de manera activa. Fijar el umbral de espera en cero o un valor alto es aceptable cuando se desea aprender, pero no se recomienda para las aplicaciones de IBM Cognos 8 SDK que operan en un entorno de producción. Todos los umbrales de espera se especifican en segundos.

Cómo se devuelven los contenidos de un informe

Tanto el método run() como el método wait() devuelven un objeto asynchReply. Un objeto asynchReply cumple diversos propósitos según el estado de la conversación asincrónica.

Si el informe no está completo, el objeto asynchReply se usa fundamentalmente como un rastreador de estado en la conversación asincrónica, y se actualiza con el método wait().

Si el informe está completo, la propiedad detailsdel objeto asynchReply incluirá un objeto asynchDetailReportOutput. Dependiendo de algunas de las opciones de ejecución, el objeto asynchDetailReportOutput incluirá el resultado real del informe o una ruta de búsqueda al lugar en donde se ha guardado el resultado dentro del Content Store.

Las opciones de ejecución saveOutput, outputFormat y outputEncapsulation son los principales impulsores de dónde se almacena el resultado de un informe y de cómo deberá la aplicación de Cognos 8 SDK acceder a este resultado.

Si la opción de ejecución saveOutput es verdadera, entonces:

  • Se ignora la opción de ejecución outputEncapuslation.
  • Se pueden especificar uno o más formatos de resultados.
  • El resultado del informe se almacenará en el Content Store como parte de un objeto reportVersion.
  • El objeto reportVersion será nombrado con una marca de tiempo y será un objeto secundario del objeto report que se ejecutó.
  • Este objeto reportVersion incluirá uno o más objetos secundarios output. Se creará un objeto output para cada formato de resultados especificado en la opción de ejecución outputFormat.
  • La lista de objetos output se obtiene con el método getOutputObjects()de asynchDetailReportOutput.

Observe que el método runSpecification() no puede haber guardado el resultado debido a que no hay un objeto report correspondiente en el Content Store que pueda contener el objeto reportVersioncreado para contener el resultado guardado.

Si la opción de ejecución saveOutput es falsa, entonces:

  • Si se especifican múltiples formatos de resultados, se generará un error (excepción) y no se ejecutará el informe.
  • El resultado del informe podrá ser almacenado según el valor de la opción de ejecuciónoutputEncapsulation.
    • OutputEncapsulationEnum.none
      • Se devolverá el resultado en el objeto asynchDetailReportOutput y se podrá acceder al mismo con el método getOutputPages().
    • OutputEncapsulationEnum.URL
      • El método getOutputPages() del objeto asynchDetailReportOutput contendrá una URL que apunta al resultado del informe.
      • Además, el métodogetOutputObjects()del objetoasynchDetailReportOutputincluirá una ruta de búsqueda completa a un objeto temporal de Content Store que aloja el resultado del informe.
    • OutputEncapsulationEnum.URLQueryString
      • El método getOutputPages()del objeto asynchDetailReportOutput incluirá solamente la cadena de consultas de una URL. La cadena de consultas de una URL es todo lo que sigue al signo "?" que se ve a menudo después del componente ruta de la URL.
      • Más aún, el método getOutputObjects() del objeto asynchDetailReportOutput incluirá una ruta de búsqueda completa a un objeto temporal de Content Store que aloja el resultado del informe .
    • OutputEncapsulationEnum.HTML
      • Es posible acceder al resultado en HTML con el método getOutputPages() del objeto asynchDetailReportOutput. Si el formato del resultado fuera HTML, entonces se devolverá el resultado real del informe. Si el formato del resultado no fuera HTML, entonces se devolverá una página HTML que haga referencia al resultado del informe.

Como se puede observar en esta lista, si se especifica cualquiera de los valores outputEncapsulation a excepción de "ninguno", el resultado del informe quedará almacenado en un objeto temporal de Content Store. Si el informe que se ejecuta es de gran tamaño, no tener almacenado el resultado del informe podría provocar que la aplicación de IBM Cognos 8 SDK se quedara sin memoria mientras intenta recuperar el resultado del informe de golpe. Si se coloca el resultado del informe en el Content Store, es posible consultar al objeto de Content Store y recuperar el resultado en trozos más pequeños.


Para más información

Existen numerosas Technotes que contienen códigos de muestra que muestran cómo realizar una amplia variedad de tareas usando IBM Cognos 8 SDK.

para acceder a estas Technotes, visite el Portal de soporte de IBM Cognos en:

http://www-947.ibm.com/support/entry/portal/Overview/Software/Information_Management/Cognos_Business_Intelligence_and_Financial_Performance_Management

y escriba "SDK sample" en el campo Search support (Soporte de búsqueda) del lado izquierdo de la página.


Conclusión

La información de este documento deberá brindar conocimientos básicos sobre IBM Cognos 8 SDK. Con esta base, no deberá ser problemático navegar por todo el conjunto de documentación sobre IBM Cognos 8 SDK ni hacer uso de otros servicios de IBM Cognos 8 para construir aplicaciones robustas.

Comentarios

developerWorks: Ingrese

Los campos obligatorios están marcados con un asterisco (*).


¿Necesita un IBM ID?
¿Olvidó su IBM ID?


¿Olvidó su Password?
Cambie su Password

Al hacer clic en Enviar, usted está de acuerdo con los términos y condiciones de developerWorks.

 


La primera vez que inicie sesión en developerWorks, se creará un perfil para usted. La información en su propio perfil (nombre, país/región y nombre de la empresa) se muestra al público y acompañará a cualquier contenido que publique, a menos que opte por la opción de ocultar el nombre de su empresa. Puede actualizar su cuenta de IBM en cualquier momento.

Toda la información enviada es segura.

Elija su nombre para mostrar



La primera vez que inicia sesión en developerWorks se crea un perfil para usted, teniendo que elegir un nombre para mostrar en el mismo. Este nombre acompañará el contenido que usted publique en developerWorks.

Por favor elija un nombre de 3 - 31 caracteres. Su nombre de usuario debe ser único en la comunidad developerWorks y debe ser distinto a su dirección de email por motivos de privacidad.

Los campos obligatorios están marcados con un asterisco (*).

(Por favor elija un nombre de 3 - 31 caracteres.)

Al hacer clic en Enviar, usted está de acuerdo con los términos y condiciones de developerWorks.

 


Toda la información enviada es segura.


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=90
Zone=Information mgmt
ArticleID=505796
ArticleTitle=Prácticas probadas de IBM Cognos: Un acercamiento a IBM Cognos 8 SDK
publish-date=07292011