Web Services User Guidepublic.dhe.ibm.com/.../docs/en/10.2.0/ug_ccc_webservice.pdf · 2013. 10. 29. · To resume a process that is paused, use the following operation: Table 5. ResumeProcess

IBM Cognos Command CenterVersion 10.2.0

Web Services User Guide

��

NoteBefore using this information and the product it supports, read the information in “Notices” on page 13.

Product Information

This document applies to IBM Cognos Command Center Version 10.2.0 and may also apply to subsequent releases.

Licensed Materials - Property of IBM

© Copyright IBM Corporation 2008, 2013.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v

Chapter 1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Chapter 2. Configuring the Web Services interface . . . . . . . . . . . . . . . . . 3Security for the Web Services interface . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Chapter 3. Service reference . . . . . . . . . . . . . . . . . . . . . . . . . . . 5PauseProcess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5QueryProcess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5ResumeProcess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6StartProcess. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6StopProcess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Chapter 4. Web Services Description Language . . . . . . . . . . . . . . . . . . 9

Chapter 5. Testing the Web Services interface . . . . . . . . . . . . . . . . . . . 11

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

© Copyright IBM Corp. 2008, 2013 iii

iv IBM Cognos Command Center Version 10.2.0: Web Services User Guide

Introduction

This document provides information that is intended for users and administratorsof IBM® Cognos® Command Center® Web Services.

This guide does not cover product installation or other configuration informationas it relates to RDBMS systems (Relational database management systems). Formore information, see the IBM Cognos Command Center Installation Guide.

Finding information

To find IBM Cognos Command Center product documentation on the web, accessthe IBM Cognos Information Center (http://pic.dhe.ibm.com/infocenter/ccc/v10r2m0/index.jsp). Release Notes are published directly to Information Centers,and include links to the latest technotes and APARs.

You can also access PDF versions of the product documentation from the productdisks or from the IBM Cognos Command Center documentation web page(http://www.ibm.com/support/docview.wss?uid=swg27039519).

Accessibility features

IBM Cognos Command Center does not currently support accessibility featuresthat help users with a physical disability, such as restricted mobility or limitedvision, to use this product.

Forward-looking statements

This documentation describes the current functionality of the product. Referencesto items that are not currently available may be included. No implication of anyfuture availability should be inferred. Any such references are not a commitment,promise, or legal obligation to deliver any material, code, or functionality. Thedevelopment, release, and timing of features or functionality remain at the solediscretion of IBM.

© Copyright IBM Corp. 2008, 2013 v

http://pic.dhe.ibm.com/infocenter/ccc/v10r2m0/index.jsp

http://www-01.ibm.com/support/docview.wss?uid=swg27039519

vi IBM Cognos Command Center Version 10.2.0: Web Services User Guide

Chapter 1. Overview

The IBM Cognos Command Center Web Services interface provides astandards-compliant SOAP-based web service that runs on top of HTTP. You canuse the Cognos Command Center Web Services interface to start, stop, andmonitor the execution of Cognos Command Center processes. You can performthese operations from any client that consumes SOAP-based services.

© Copyright IBM Corp. 2008, 2013 1

2 IBM Cognos Command Center Version 10.2.0: Web Services User Guide

Chapter 2. Configuring the Web Services interface

Before you can use the IBM Cognos Command Center Web Services interface, thereare configuration tasks that you must complete.

About this task

The Cognos Command Center Web Services component is available in the standardedition.

To configure and enable the Web Services interface, you set the followingproperties:

Enable APISet to true to enable the Web Services interface.

HostnameThe base address for the Web Services. Set the address to the external IPaddress of the host where the Cognos Command Center server is running.

Port The port that hosts the Web Services interface.

UsernameThe name of an existing Cognos Command Center user. All requests thatare received on the Web Services interface are processed under this useridentity. To manage what is exposed on the Web Services interface, you canrestrict the access for this Cognos Command Center user.

Procedure1. Log on to Cognos Command Center.2. Click Tools > System Configuration and enter or select values for the

properties.3. Restart the Cognos Command Center server.

Security for the Web Services interfaceThe IBM Cognos Command Center Web Services interface is an open service. Youcan secure it by using a firewall and limiting the access rights of users.

A firewall can restrict the location from which incoming connections can be made.Setting access rights for users that are assigned to the interface, controls what canbe managed through the Web Services interface. For information on setting accessrights for users, see the IBM Cognos Command Center Administration Guide.



Chapter 3. Service reference

In IBM Cognos Command Center, you can use the Web Services interface toperform operations with APIs.

Use the Web Services interface to perform the following operations:v Pause a running processv Query the state of a processv Resume a paused processv Query the state of a processv Start a processv Stop a running process

PauseProcessIn the IBM Cognos Command Center Web Services interface, use the PauseProcessoperation to pause a running process.

To pause a running process, use the following operation:

Table 1. PauseProcess request

Property Type Description

processId int The job id of the process to pause.

Table 2. PauseProcess response


HasException boolean A flag that signals if the operation failed. For a successfuloperation, the value is false.

ExceptionInfo string Holds an error message if HasException is true.

QueryProcessIn the IBM Cognos Command Center Web Services interface, use the QueryProcessoperation to query the state of a process.

To query the state of a process, use the following operation:

Table 3. QueryProcess request


processId int The job id of the process to query.

Table 4. QueryProcess response


State string The state of the process. Only set if HasException is false.The state is one of: running, canceling, canceled, pausing,paused, failed, completed, or waiting to retry.


Table 4. QueryProcess response (continued)




ResumeProcessIn the IBM Cognos Command Center Web Services interface, use theResumeProcess operation to resume a process that is paused.

To resume a process that is paused, use the following operation:

Table 5. ResumeProcess request


processId int The job id of the process to resume.

Table 6. ResumeProcess response




StartProcessIn the IBM Cognos Command Center Web Services interface, use the StartProcessoperation to start a process.

To start a process, use the following operation:

Table 7. StartProcess request


ecosystem string Name of the ecosystem that contains the process to start.

environment string Name of the environment to run the process in.

process string Name of the process to start.

args array of{name,value}

List of ecosystem and process variable {name,value} pairs.Use this to provide values for variables that are checked asprompt.

Table 8. StartProcess response


ProcessId int The job id of the process that has started. Only set ifHasException is false.




StopProcessIn the IBM Cognos Command Center Web Services interface, use the StopProcessoperation to stop a process.

To stop a process, use the following operation:

Table 9. StopProcess request


processId int The job id of the process to stop.

Table 10. StopProcess response




Chapter 3. Service reference 7


Chapter 4. Web Services Description Language

The Web Services Description Language (WSDL) for the IBM Cognos CommandCenter Web Services is distributed with the Cognos Command Center serverinstallation.

The WSDL is in the INSTALLDIR\Server\config\schemas.staranalytics.com.sfcc.wsdl file.

Additionally, the Cognos Command Center Web Services interface enables clientsto query the service definition at run time. The WSDL is available by queryinghttp://serverhost:9003/Sfcc?wsdl.



Chapter 5. Testing the Web Services interface

You can test and demonstrate the IBM Cognos Command Center Web Servicesinterface by using a web services browser. The following procedure uses the opensource soapUI tool.

Before you begin

This test example shows how to start a process through the Web Services interface.The test requires a process that can be started in the Cognos Command Centerrepository and assumes the following objects exist in the Command Centerrepository:v An ecosystem named WS Test that contains an environment named WS Test.v A process named WS Test that has a process variable named MSG.

Procedure1. Start soapUI and create a new project.

Tip: The WSDL file is in INSTALLDIR\Server\config\schemas.staranalytics.com.sfcc.wsdl.

2. Double-click on the Projects > StartProcess > Request node in the navigator.3. In the Request window, edit the endpoint of the url to point to Cognos

Command Center. For example, http://127.0.0.1:9003/Sfcc.4. In the Request window, Edit the SOAP header to include the to address. For

example,<soap:Header>

<To soap : mustUnderstand="1" xmlns="http://www.w3.org/2005/08/addressing">http://127.0.0.1:9003/Sfcc</To>

<soap:Header>

5. Edit the SOAP body to include names that match the target Cognos CommandCenter system and optionally, add ecosystem and process variable values. Forexample,<soap:Body>

<sfcc: StartProcess><sfcc:ecosystem>WS Test</sfcc:ecosystem><sfcc:environment>WS Test</sfcc:environment><sfcc:process>WS Test</sfcc:process><sfcc:args><sfcc:NameValuePair><sfcc:Name>MSG</sfcc:Name><sfcc:Value>Hello from soapUI</sfcc:Value></sfcc:NameValuePair></sfcc:args></sfcc: StartProcess>

</soap:Body>

6. Issue the request from the soapUI tool and inspect the result.



Notices

This information was developed for products and services offered worldwide.

IBM may not offer the products, services, or features discussed in this document inother countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user's responsibility to evaluate and verify theoperation of any non-IBM product, program, or service. This document maydescribe products, services, or features that are not included in the Program orlicense entitlement that you have purchased.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not grant youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:

Intellectual Property LicensingLegal and Intellectual Property LawIBM Japan Ltd.19-21, Nihonbashi-Hakozakicho, Chuo-kuTokyo 103-8510, Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law: INTERNATIONALBUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS"WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OFNON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULARPURPOSE. Some states do not allow disclaimer of express or implied warranties incertain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

Any references in this information to non-IBM Web sites are provided forconvenience only and do not in any manner serve as an endorsement of those Websites. The materials at those Web sites are not part of the materials for this IBMproduct and use of those Web sites is at your own risk.


IBM may use or distribute any of the information you supply in any way itbelieves appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact:

IBM Software GroupAttention: Licensing3755 Riverside DrOttawa, ON K1V 1B7Canada

Such information may be available, subject to appropriate terms and conditions,including in some cases, payment of a fee.

The licensed program described in this document and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement or any equivalent agreementbetween us.

Any performance data contained herein was determined in a controlledenvironment. Therefore, the results obtained in other operating environments mayvary significantly. Some measurements may have been made on development-levelsystems and there is no guarantee that these measurements will be the same ongenerally available systems. Furthermore, some measurements may have beenestimated through extrapolation. Actual results may vary. Users of this documentshould verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements or other publicly available sources.IBM has not tested those products and cannot confirm the accuracy ofperformance, compatibility or any other claims related to non-IBM products.Questions on the capabilities of non-IBM products should be addressed to thesuppliers of those products.

All statements regarding IBM's future direction or intent are subject to change orwithdrawal without notice, and represent goals and objectives only.

This information contains examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples include thenames of individuals, companies, brands, and products. All of these names arefictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.

If you are viewing this information softcopy, the photographs and colorillustrations may not appear.


Trademarks

IBM, the IBM logo and ibm.com are trademarks or registered trademarks ofInternational Business Machines Corp., registered in many jurisdictions worldwide.Other product and service names might be trademarks of IBM or other companies.A current list of IBM trademarks is available on the Web at “ Copyright andtrademark information ” at www.ibm.com/legal/copytrade.shtml.

Notices 15

http://www.ibm.com/legal/copytrade.shtml

http://www.ibm.com/legal/copytrade.shtml

Documents

Web Services User Guidepublic.dhe.ibm.com/.../docs/en/10.2.0/ug_ccc_webservice.pdf · 2013. 10. 29. · To resume a process that is paused, use the following operation: Table 5. ResumeProcess