Prácticas Comprobadas de IBM Cognos: Programación práctica con el kit de desarrollo de software de IBM Cognos

Naturaleza del documento: práctica comprobada; producto(s): kit de desarrollo de software de IBM Cognos; área de interés: desarrollo

Un documento introductorio al SDK de IBM Cognos que explica los requisitos básicos de una aplicación de SDK a través de una muestra autónoma.

Claudiu Popescu, Software Engineer, IBM Cognos SDK Support Group, IBM

Claudiu Popescu es miembro del equipo de SDK y diagnóstico de IBM Cognos. Es especialista en el kit de desarrollo de software de Cognos, Cognos Mashup Services y JavaScript.



09-06-2011

Introducción

Propósito

Este documento se destina a diseñadores de software muy familiarizados con el producto IBM Cognos BI y que desean usar el componente kit de desarrollo de software (SDK) de IBM Cognos BI. El kit de desarrollo de software de IBM Cognos contiene muchas muestras, pero las mismas pueden ser intimidantes para personas que están comenzando a usar el SDK, porque son complejas y no autónomas, pues usan clases definidas en otros directorios. Este documento ofrece un enfoque más simple, pues contiene sólo un archivo de origen con una aplicación independiente de SDK.

Aplicabilidad

Este documento fue escrito usando como referencia IBM Cognos BI versión 10.1. Sin embargo, los conceptos presentados también se aplican a las versiones 8.3 y posteriores de IBM Cognos 8 BI. La muestra de código que se suministra con este documento debe ser adaptada para funcionar con IBM Cognos 8 BI.


¿Qué es el kit de desarrollo de software de IBM Cognos?

Usos del kit de desarrollo de software de IBM Cognos

El kit de desarrollo de software de IBM Cognos es un componente adicional de instalación que permite la ejecución programática de

  • La mayoría de las tareas que se pueden ejecutar con la interfaz de usuario (UI) de IBM Cognos BI
  • La automatización de tareas repetitivas que no son de la UI, como la planificación de una gran cantidad de informes, el cambio de permisos para varios informes, etc.
  • La Integración de IBM Cognos BI a otras aplicaciones.

Los ejemplos de tareas específicas del kit de desarrollo de software de IBM Cognos incluyen:

  • Mostrar a todos los usuarios de IBM Cognos BI y su acceso a los informes
  • Asignar un nuevo propietario a todos los informes cuyo propietario original fue suprimido
  • Después de la republicación de un paquete, actualizar los informes y consultas pertenecientes al mismo.
  • Mostrar una lista de informes de IBM Cognos BI en una página Web personalizada

Sin embargo, no se puede usar el kit de desarrollo de software de IBM Cognos para tareas típicamente asociadas a la configuración y a interfaces de usuario empaquetadas. Por ejemplo: el SDK no puede modificar los componentes de la interfaz de usuario de IBM Cognos BI, tales como:

  • Páginas de portal
  • Páginas de inicio de sesión
  • Cualquier widget de interfaz de usuario
  • Estudios en IBM Cognos Connection
  • Marcas

La API del kit de desarrollo de software de IBM Cognos

El principal componente del kit de desarrollo de software de IBM Cognos es la Interfaz de Programación de Aplicaciones (API), conocida como API BI Bus. La API del kit de desarrollo de software de IBM Cognos soporta lenguajes de programación específicos a través del uso de kits de herramientas. Los lenguajes de programación soportados son:

  • Java
  • Lenguajes .NET Framework

Se puede usar la API del kit de desarrollo de software de IBM Cognos en programas autónomos o páginas Web, como ASPs o JSPs.

Además de los kits de herramientas, hay otros componentes del kit de desarrollo de software de IBM Cognos que no se presentarán en este documento. Los otros componentes son:

  • Interfaz de URL que se usa para automatizar acciones al pasar comandos y parámetros en HTTP para integrar a otras aplicaciones
  • SDK Framework Manager (FM) que se usa para modelar metadatos y publicar paquetes
  • Cognos Mashup Services (CMS) que expone una interfaz de REST y WSDL/SOAP para salidas de IBM Cognos, para que esta salida pueda ser consumida fácilmente por otras aplicaciones.

La documentación del kit de desarrollo de software de IBM Cognos

La documentación del kit de desarrollo de software de IBM Cognos está dividida en los siguientes componentes (el número de páginas es del conjunto de documentos de IBM Cognos 10):

  • IBM Cognos Software Development Kit Getting Started (44 páginas)
  • IBM Cognos Software Development Kit Installation and configuration guide (15 páginas)
  • IBM Cognos Software Development Kit Developer Guide (3565 páginas)
  • IBM Cognos Custom Authentication Provider Developer Guide (41 páginas)
  • IBM Cognos Framework Manager Developer Guide (172 páginas)
  • IBM Cognos Mashup Service Developer Guide (275 páginas)

Ya que la documentación del kit de desarrollo de software de IBM Cognos es muy extensa, se recomienda que el nuevo usuario lea acerca de los fundamentos del SDK en el artículo de developerWorks “IBM Cognos Proven Practices: Approach to the IBM Cognos SDK”, que se encuentra en el siguiente URL:

http://www.ibm.com/developerworks/data/library/cognos/development/how_to/page129.html

Cómo instalar el kit de desarrollo de software de IBM Cognos

Se debe instalar el kit de desarrollo de software de IBM Cognos en una computadora donde cualquier componente del servidor de IBM Cognos BI ya esté instalado. El procedimiento de instalación del SDK es semejante al procedimiento de instalación del IBM Cognos BI Server.

El resto de este documento presupone que el kit de desarrollo de software de IBM Cognos fue instalado y que un IBM Cognos BI Server está disponible. Se recomienda, si es posible, que se use una única instalación de servidor al comenzar a usar el SDK. Una instalación del IBM Cognos BI basada en una estación de trabajo Linux o Windows que usa el IBM Cognos Content Store y la implementación de la muestra de IBM Cognos PowerCubes constituyen un excelente entorno de aprendizaje independiente.

Cómo el kit de desarrollo de software de IBM Cognos funciona

La API del kit de desarrollo de software de IBM Cognos contiene clases que corresponden a servicios de IBM Cognos BI, tales como el Content Manager Service, el Report Service o el Monitor Service. Los servicios que están disponibles en un servidor de IBM Cognos BI son especificados en IBM Cognos Configuration y se pueden ver bajo la pestaña Configuration en IBM Cognos Administration.

Ilustración 1: Servicios de IBM Cognos 10 listados en IBM Cognos Configuration
Illustration 1: IBM Cognos 10 Services listed in the IBM Cognos Configuration
Ilustración 2: Servicios de IBM Cognos 10 listados en IBM Cognos Administration
Illustration 2: IBM Cognos 10 Services listed in IBM Cognos Administration

Un programa del kit de desarrollo de software de IBM Cognos puede ejecutar en una computadora que no tiene el servidor de IBM Cognos BI instalado. Sin embargo, las bibliotecas del kit de desarrollo de software de IBM Cognos deben obligatoriamente ser instaladas en esa computadora. Las bibliotecas del SDK están ubicadas en:

  • <cognos-directory>\sdk\java\lib para Java; axisCognosClient.jar es la principal biblioteca del SDK de Java y el resto de los archivos JAR se destina a soportar axisCognosClient.jar y las muestras que se instalan con el SDK
  • <cognos-directory>\sdk\csharp\lib para los lenguajes de .NET

Generalmente una aplicación del kit de desarrollo de software de IBM Cognos suministra un conjunto de credenciales para el servidor de IBM Cognos BI y la aplicación estará restringida y limitada a esas credenciales. Eso significa que la aplicación debe ser autentificada para realizar operaciones, de la misma manera que el usuario necesita iniciar una sesión en IBM Cognos Connection. Eso garantiza el acceso seguro al contenido de IBM Cognos.


La estructura de un programa del kit de desarrollo de software de IBM Cognos

Un programa típico del kit de desarrollo de software de IBM Cognos tiene cuatro secciones principales.

  1. Conectar al (a los) servicio(s) de IBM Cognos BI
  2. Iniciar una sesión en IBM Cognos BI
  3. Ejecutar tareas
  4. Cerrar la sesión en IBM Cognos BI

Este documento contiene una muestra de aplicación de SDK escrita en Java y métodos que corresponden a esas secciones principales.

Paso 1: Conectar al servidor de IBM Cognos BI

Nombre del método: connectToCognos

El programa del kit de desarrollo de software de IBM Cognos Software Development primero debe conectarse a un IBM Cognos BI Dispatcher a través del URL del servidor de IBM Cognos BI. Ese URL es definido en IBM Cognos Configuration y es el valor del campo “Dispatcher URI for external applications”. El URL tiene la forma http://host.domain:port/p2pd/servlet/dispatch.

Ilustración 3: IBM Cognos Configuration mostrando el campo “Dispatcher URI for external applications”
Illustration 3: IBM Cognos Configuration showing the 'Dispatcher URI for external applications' field

Una vez conectado a un IBM Cognos BI Dispatcher, la aplicación del kit de desarrollo de software de IBM Cognos solicita un servicio de IBM Cognos BI. A menos que la aplicación vaya a usar las credenciales de Anonymous, debe solicitar el servicio de Content Manager porque éste es el servicio que maneja el proceso de inicio/ cierre de sesión.

Paso 2: Iniciar la sesión en el servidor de IBM Cognos BI

Nombre del método: logonToCognos

El inicio de sesión se realiza a través del servicio Content Manager. IBM Cognos BI soporta el acceso tanto de usuarios autentificados como de usuarios anónimos. En este paso, si el acceso anónimo está inhabilitado, la aplicación de SDK debe iniciar una sesión a través de un ID de espacio de nombres, un nombre de usuario y la contraseña asociada. El ID de espacio de nombres es el valor del campo Namespace ID en IBM Cognos Configuration.

Ilustración 4: El campo "Namespace ID" en IBM Cognos Configuration
Illustration 4: The &quot;Namespace ID&quot; field in IBM Cognos Configuration

El ID de espacio de nombres, nombre de usuario y contraseña se suministran en una cadena de caracteres XML conocida como credencial. La credencial toma la forma de:

 <credential>
	 <namespace>namespaceID</namespace>
	 <username>user<username>
	 <password>pwd</password>	
 </credential>

En la muestra de código Java, observe las tres líneas después de la llamada al método logon() . Esas líneas son necesarias para recuperar y almacenar información relacionada con la sesión autentificada en la variable cmService. En IBM Cognos 8, eso se manejaba automáticamente pero, en IBM Cognos 10, se debe hacer eso programáticamente, pues algunas de las informaciones relacionadas con la sesión son dinámicas y necesitan renovación antes de llamar un servicio de IBM Cognos 10. Para obtener más información acerca de eso, consulte el tema Managing Service Headers en el capítulo Coding Practices and Troubleshooting en la guía IBM Cognos 10 SDK Developers.

Paso 3: Ejecutar tareas específicas de la aplicación

Nombre de método: executeTasks

Ese paso realiza las tareas específicas de la aplicación. El ejemplo de código muestra cómo exhibir la lista de paquetes en los “Public Folders”. El Content Manager Service realiza una consulta con la ruta de acceso de búsqueda "/content//package" y extrae las propiedades “searchPath” y “defaultName”. La sintaxis de la ruta de acceso de búsqueda está descrita en la Sección 4 a continuación. La consulta retorna una matriz de objetos BaseClass, que luego se imprime. Si las muestras de IBM Cognos BI fueron instaladas, la salida será semejante a:

GO Data Warehouse (analysis) - /content/folder[@name='Samples']/folder[@name='Models']
     /package[@name='GO Data Warehouse (analysis)']
GO Data Warehouse (query) - /content/folder[@name='Samples']/folder[@name='Models']
     /package[@name='GO Data Warehouse (query)']
GO Sales (analysis) - /content/folder[@name='Samples']/folder[@name='Models']
     /package[@name='GO Sales (analysis)']
GO Sales (query) - /content/folder[@name='Samples']/folder[@name='Models']
     /package[@name='GO Sales (query)']
Sales and Marketing (conformed) - /content/folder[@name='Samples']/folder[@name='Models']
     /package[@name='Sales and Marketing (conformed)']

Paso 4: Cierre la sesión del servidor de IBM Cognos BI

Nombre del método: logoffFromCognos

El logoff se realiza a través del servicio Content Manager. Si una aplicación de SDK termina sin cerrar la sesión, los recursos que estaban asignados a la sesión de IBM Cognos 10 que se estableció cuando la aplicación de SDK inició la sesión seguirán asignados hasta que se agote el tiempo de la sesión.

El ejemplo de código Java

El siguiente código está contenido en el archivo ZIP adjunto que acompaña este documento. Descomprímalo en el directorio <c10_install>/sdk/java y se creará una carpeta llamada SDKExample. Desde la carpeta SDKExample, puede usar los scripts build.bat/build.sh para desarrollar la aplicación y los scripts run.bat/run.sh para ejecutarla.

Antes de desarrollar y ejecutar este ejemplo, se debe editar el archivo de origen de Java, el script de construcción y el script de ejecución.

  • En el archivo SDKExample.java se deben modificar las variables nameSpaceID, userName y password para contener valores que funcionarán en nuestro entorno
  • En los scripts de desarrollo y ejecución, se debe definir la variable JAVA_HOME como la vía de acceso al JDK utilizado, siendo que la versión mínima de JDK es 1.5 (también conocida como JDK 5.0). En los scripts build.sh y run.sh, puede ser necesario definir la variable de entorno CRN_HOME.
import java.net.URL;
import javax.xml.namespace.QName;
import org.apache.axis.client.Stub;
import org.apache.axis.message.SOAPHeaderElement;
import com.cognos.developer.schemas.bibus._3.BaseClass;
import com.cognos.developer.schemas.bibus._3.BiBusHeader;
import com.cognos.developer.schemas.bibus._3.ContentManagerService_PortType;
import com.cognos.developer.schemas.bibus._3.ContentManagerService_ServiceLocator;
import com.cognos.developer.schemas.bibus._3.PropEnum;
import com.cognos.developer.schemas.bibus._3.QueryOptions;
import com.cognos.developer.schemas.bibus._3.SearchPathMultipleObject;
import com.cognos.developer.schemas.bibus._3.Sort;
import com.cognos.developer.schemas.bibus._3.XmlEncodedXML;

public class SDKExample {
private static String dispatcherURL = "http://localhost:9300/p2pd/servlet/dispatch";
private static String nameSpaceID = "NSID";
private static String userName = "user";
private static String password = "pwd";
private ContentManagerService_PortType cmService=null;

public static void main(String args[]) {
	SDKExample mainClass = new SDKExample(); // instantiate the class

	// Step 1: Connect to the Cognos services
	mainClass.connectToCognos (dispatcherURL); 

	// Step 2: Logon to Cognos 
	mainClass.logonToCognos(nameSpaceID, userName, password); 

	// Step 3: Execute tasks 
	mainClass.executeTasks(); 

	// Step 4: Logoff from Cognos 
	mainClass.logoffFromCognos(); 
}

// Step 1: Connect to the Cognos services
private void connectToCognos(String dispatcherURL) {
	ContentManagerService_ServiceLocator cmServiceLocator =
        new ContentManagerService_ServiceLocator();

	try {
		URL url = new URL(dispatcherURL);
		cmService = cmServiceLocator.getcontentManagerService(url);
	} catch (Exception e) {
		e.printStackTrace();
	}
}

// Step 2: Logon to Cognos 
private void logonToCognos(String nsID, String user, String pswd) {
	StringBuffer credentialXML = new StringBuffer();
	credentialXML.append("<credential>");
	credentialXML.append("<namespace>").append(nsID).append("</namespace>");
	credentialXML.append("<username>").append(user).append("</username>");
	credentialXML.append("<password>").append(pswd).append("</password>");
	credentialXML.append("</credential>");

	String encodedCredentials = credentialXML.toString();
	XmlEncodedXML xmlCredentials = new XmlEncodedXML();
	xmlCredentials.set_value(encodedCredentials);

	try {
		cmService.logon(xmlCredentials, null);
		SOAPHeaderElement temp = ((Stub)cmService).getResponseHeader(
			"http://developer.cognos.com/schemas/bibus/3/", "biBusHeader");
		BiBusHeader CMbibus = (BiBusHeader)temp.getValueAsType(
			new QName ("http://developer.cognos.com/schemas/bibus/3/",
				"biBusHeader"));
		((Stub)cmService).setHeader(
            "http://developer.cognos.com/schemas/bibus/3/", 
			"biBusHeader", CMbibus);
	} catch (Exception ex) {
		ex.printStackTrace();
	}
}

// Step 3: Execute tasks 
private void executeTasks() {
	PropEnum props[] = new PropEnum[] { PropEnum.searchPath, PropEnum.defaultName };
	BaseClass bc[] = null;
	String searchPath = "/content//package";

	try {
		SearchPathMultipleObject spMulti =
            new SearchPathMultipleObject(searchPath);
		bc = cmService.query(spMulti, props, new Sort[] {}, new QueryOptions());
	} catch (Exception e) {
		e.printStackTrace();
		return;
	}

	System.out.println("PACKAGES:\n");
	if (bc != null) {
		for (int i = 0; i < bc.length; i++) {
			System.out.println(bc[i].getDefaultName().getValue() + " - "
					+ bc[i].getSearchPath().getValue());
		}
	}
}

// Step 4: Logoff from Cognos 
private void logoffFromCognos() {
	try {
		cmService.logoff();
	} catch (Exception ex) {
		ex.printStackTrace();
	}
}

Rutas de acceso de búsqueda

Se usa una ruta de acceso de búsqueda para especificar la ubicación de los objetos en la jerarquía de IBM Cognos BI Content Store. Una ruta de acceso de búsqueda puede especificar una vía de acceso a un único objeto de Content Store o puede usar expresiones y caracteres comodín para recuperar más de un objeto de Content Store

La sintaxis de la ruta de acceso de búsqueda es semejante a una vía de acceso en un sistema operativo como DOS o UNIX. Más específicamente, se asemeja a XPath, que es un lenguaje de consulta para seleccionar nodos desde un documento XML.

La sintaxis de una ruta de acceso de búsqueda está descrita detalladamente en IBM Cognos Software Development Kit Developer Guide.

Ruta de acceso de búsqueda para un objeto

Ejemplo: una vía de acceso tomada desde la UI de IBM Cognos Connection, que ubica el informe específico "Budget vs. Actual" en la carpeta "Report Studio Report Samples":

/content/folder[@name='Samples']/folder[@name='Models']
      /package[@name='GO Data Warehouse (analysis)']
      /folder[@name='Report Studio Report Samples']
      /report[@name='Budget vs. Actual']

Para obtener la ruta de acceso de búsqueda de un informe, haga clic en el ícono “Set properties” referente al informe en IBM Cognos Connection. En el diálogo “Set properties”, haga clic en el enlace “View the search path, ID and URL“. Aparecerá un diálogo que contiene Search Path como el primer campo.

Ilustración 5: El ícono "Set Properties" en IBM Cognos Connection
Illustration 5: The 'Set Properties' icon in IBM Cognos Connection
Ilustración 6: La ruta de acceso de búsqueda de un objeto de IBM Cognos BI Content Store como se ve al usar IBM Cognos Connection para ver las propiedades del objeto
Illustration 6: The search path of an IBM Cognos BI Content Store object as seen using IBM Cognos Connection to view the object's properties

Ruta de acceso de búsqueda para varios objetos

El caracter comodín (*) indica todos los objetos bajo la raíz especificada. Por ejemplo: para buscar todos los objetos de la carpeta "Report Studio Report Samples" use la ruta de acceso de búsqueda:

/content/folder[@name='Samples']/folder[@name='Models']
    /package[@name='GO Data Warehouse (analysis)']
    /folder[@name='Report Studio Report Samples']/*

Cuando una vía de acceso comienza por dos barras inclinadas (//), se seleccionan todos los objetos del almacenamiento de contenido que cumplen con los criterios especificados. Por ejemplo:

  • //folder – retornará todos los objetos Folder en el Content Store
  • //report – retornará todos los objetos Report en el Content Store

Cuando una vía de acceso contiene “//”, se seleccionan todos los descendentes del objeto actual que cumplen con los criterios especificados. Por ejemplo: para seleccionar y retornar todos los informes de la carpeta "Report Studio Report Samples", use la ruta de acceso de búsqueda:

/content/folder[@name='Samples']/folder[@name='Models']
    /package[@name='GO Data Warehouse (analysis)']
    /folder[@name='Report Studio Report Samples']//report

Cómo ejecutar las muestras del kit de desarrollo de software de IBM Cognos

El kit de desarrollo de software de IBM Cognos tiene dos kits de herramientas diferentes: Java y .NET. Los kits de herramientas están ubicados en el directorio <cognos-directory>/sdk, bajo los siguientes nombres de carpeta:

  • java para el kit de herramientas Java
  • csharp para el kit de herramientas .NET

Cada uno de los directorios de los kits de herramientas contiene muchos subdirectorios con muestras. La funcionalidad de cada muestra está descrita en el archivo .html bajo el mismo directorio. Los comentarios en los archivos de origen describen el propósito principal de cada muestra, que incluye un resumen de los métodos de SDK que se usan. Los pasos para usar las muestras en los kits de herramientas están descritos en la guía IBM Cognos Software Development Kit Getting Started.

Para ejecutar una muestra de Java, se debe primeramente desarrollarla y luego ejecutarla.

  • Los archivos de script para Windows son build.bat y run.bat
  • Los archivos de script para UNIX son build.sh y run.sh
  • Se debe instalar un JDK en la computadora
  • En cada archivo de script, se deben actualizar los valores de las dos variables, JAVA_HOME y CRN_HOME, con los valores reales referentes a la computadora
  • También es posible desarrollar todas las muestras de una sola vez al usar los scripts build-samples.bat o build-samples.sh ubicados en <cognos-directory>\sdk\java

Para ejecutar las muestras de SDK con .NET, es necesario haber instalado la versión 2.0 ó 3.0 de .NET Framework. Para modificar o desarrollar nuevamente las muestras de C# .NET, es necesario haber instalado un entorno de desarrollo C#, como Visual Studio 2005 o el kit de desarrollo de software (SDK) .NET Framework v2.0. En cada muestra, el script build.bat script incluido en la muestra de código muestra una forma de desarrollar la aplicación con el compilador de Visual Studio .NET.


Descargar

DescripciónNombretamaño
Article contained in ZIP fileHandsOnSDK.zip579KB

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=964939
ArticleTitle=Prácticas Comprobadas de IBM Cognos: Programación práctica con el kit de desarrollo de software de IBM Cognos
publish-date=06092011