Working with Essbase Web Services

In This Section:

Key Features

Deploying Web Services

Datasource

Administration

Query

Writing Client Programs

Sample Client Programs

Key Features

Web services are self-contained, modular applications that can be described, published, located, and invoked over a network. Web services use XML to code and decode data, and SOAP (Simple Object Access Protocol) to transport it. Web services are defined using WSDL (Web Service Description Language).

Essbase Web Services support access to and administration of Essbase applications and cubes. Essbase Web Services include the following modules:

  • Datasource

  • Administration

  • Data and Metadata Query

Deploying Web Services

Oracle recommends deploying Web Services in secure mode with Oracle Web Services Manager (OWSM).

Note:

You must also configure the Provider Services deployment in Oracle WebLogic Server to support OWSM. For information on OWSM, see the Oracle Fusion Middleware Security and Administrator’s Guide for Web Services.

  To configure Web Services to support OWSM:

  1. Stop Provider Services.

  2. Find and open essbase.properties in Middleware_HOME\user_projects\domains\epmsystem1\aps\bin.

  3. Set essbase.webservices.disable.owsm to False.

  4. Save and close essbase.properties.

  5. Restart Provider Services.

To use Web Services in non-OWSM mode, set the essbase.webservices.disable.owsm property in essbase.properties to True Client applications should send the non-OWSM or native Essbase user credentials using a SOAP message header in ClientMessageHandler similar to the following:

SOAPElement el = header.addHeaderElement(envelope.createName("Parameters", "", "http://context.webservices.epm.oracle/"));
                SOAPElement el0 = el.addChildElement(envelope.createName("UserName", "", "http://context.webservices.epm.oracle/"));
                el0.setValue(s_userName);
                SOAPElement el1 = el.addChildElement(envelope.createName("Password", "", "http://context.webservices.epm.oracle/"));
                el1.setValue(s_password);
                SOAPElement el2 = el.addChildElement(envelope.createName("IsToken", "", "http://context.webservices.epm.oracle/"));
                el2.setValue(Boolean.toString(b_isPwdToken));
                SOAPElement el3 = el.addChildElement(envelope.createName("UserNameAs", "", "http://context.webservices.epm.oracle/"));
                el3.setValue(userNameAs);

You will also need to modify your Oracle WebLogic Server deployment to use Web Services in non-OWSM mode.

Datasource

You use the Datasource service to identify and connect with Essbase servers, applications, cubes, and dimensions. You can perform the following operations:

  • GetTypes()

    Input: none
    Output: BaseObject[] (array)
  • Get()

    Input: URI
    Output: BaseObject
  • Create()

    Input: BaseObject
    Output: BaseObject
  • Rename()

    Input: URI, String(newName)
    Output: None
  • Update()

    Input: URI, Base Object (application or cube)
    Output: BaseObject
  • Delete()

    Input: URI
    Output: None
  • List()

    Input: UriType, URI
    Output: BaseObject[]

Administration

You use Administration Web Services to start, monitor, or stop Essbase servers, applications, and cubes and to perform operations, such as executing MaxL scripts. You can perform the following operations:

  • Start()

    Input: URI (Essbase application or cube)
    Output: Void
  • Stop()

    Input: URI (Essbase application or cube)
    Output: Void
  • Ping()

    Input: URI (Essbase application or cube)
    Output: Packet round trip time in milliseconds
  • Perform()

    Input: MaxL statement
    Output: Two-dimensional string array of MaxL result set

Query

You use Query Web Services to perform data and metadata queries, update data, and retrieve metadata from Essbase servers, applications, and cubes. You can perform the following operations:

Data Queries

  • Retrieve()

    Input:
    	URI: (Essbase cube)
    	Options: Grid operation parameters
    	Grid: Input grid
    Output: Output grid
  • UpdateData()

    Input:
    	Cube: URI (Essbase cube)
    	Options: Grid operation parameters
    	Grid: Input grid
    Output: Output Grid
  • zoomIn()

    Input:
    	URI: (Essbase cube)
    	ZoomOptions: Zoom in operation parameters
    	Range: Grid range to zoom in on
    	Grid: Input grid
    Output: Output grid
  • zoomOut()

    Input:
    	URI: (Essbase cube)
    	ZoomOptions: Zoom out operation parameters
    	Range: Grid range to zoom out of
    	Grid: Input grid
    Output: Output grid
  • pivot()

    Input:
    	URI: (Essbase cube)
    	Options: Grid operations parameters
    	FromPivotLocation: Location member is pivoted from
    	ToPivotLocation: Location member is pivoted to
    
    Output: Grid

    Pivot pivots the grid on a selected member to a new location. The resulting grid is returned.

  • keepOnly()

    Input:
    	URI: Essbase cube location
    	Options: Grid operation parameters
    	Range: Grid range to keep
    	Grid: Input grid
    Output: Output grid
  • removeOnly()

    Input:
    	URI: Essbase cube location
    	Options: Grid operation parameters
    	Range: Grid range to remove
    	Grid: Input grid
    Output: Output grid
  • execute()

    Input:
    	Cube: URI (Essbase cube)
    	Text: MDX query statement
    	Options: MDX query options
    Output: Either an MDX MDData result set or a grid based on resultFormat specified as part of input Options

Metadata Queries

  • queryMemberHeader

    In: URI (Essbase cube), QueryMemberOptions
    Out: Essbase member array
  • queryMember

    In: URI (Essbase cube), QueryMemberOptions
    Out: Essbase member array
  • queryMemberReport

    In: URI (Essbase cube), QueryReportOptions
    Out: Essbase member array

QueryMemberOptions is an object containing two other objects, QueryOption and QueryType:

QueryOption fields in QueryMemberOptions 
 QUERY_OPTION_MEMBERSONLY           
     QUERY_OPTION_ALIASESONLY           
     QUERY_OPTION_MEMBERSANDALIASES     
     QUERY_OPTION_COUNTONLY            
     QUERY_OPTION_NOTOTALCOUNTS        
     QUERY_OPTION_INCLUDEHYBRIDANALYSIS 
     QUERY_OPTION_EXCLUDEHYBRIDANALYSIS 
     QUERY_OPTION_FORCECASESENSITIVE    
     QUERY_OPTION_FORCEIGNORECASE      
     QUERY_OPTION_UNIQUENAME           
     QUERY_OPTION_USESUBSTITUTIONVAR   

QueryType  fields in QueryMemberOptions 
     QUERY_TYPE_CHILDREN       
     QUERY_TYPE_DESCENDANTS    
     QUERY_TYPE_BOTTOMLEVEL    
     QUERY_TYPE_SIBLINGS      
     QUERY_TYPE_SAMELEVEL      
     QUERY_TYPE_SAMEGENERATION 
     QUERY_TYPE_PARENT         
     QUERY_TYPE_DIMENSION      
     QUERY_TYPE_NAMEDGENERATION
     QUERY_TYPE_NAMEDLEVEL     
     QUERY_TYPE_SEARCH         
     QUERY_TYPE_WILDSEARCH     
     QUERY_TYPE_USERATTRIBUTE  
     QUERY_TYPE_ANCESTORS      
     QUERY_TYPE_DTSMEMBERS      
     QUERY_TYPE_DIMUSERATTRIBUTES   
     QUERY_TYPE_INDEPDIMS           
     QUERY_TYPE_INDEPDIMS_DISCRETE  
     QUERY_TYPE_INDEPDIMS_CONTINUOUS

QueryReportOptions is an object containing two other objects, fieldSelection and mbrSelection.

Writing Client Programs

  To create a client program using Web Services:

  1. Deploy the Web Services aps.ear file.

  2. Determine, using WSDL, which services are available.

  3. In a development environment (Java or C++), generate client program stubs.

  4. Using the classes included in these stubs, develop your program.

Sample Client Programs

The file build.xml in APS_HOME\ws-samples contains information on how to create, compile, and execute programs. There is also a sample ws-build.properties file, which you modify to match your development environment.

The sample program listing below starts an Essbase application, pings the application to determine the round-trip transit time, and stops the application.

public static void doAdmin() throws Exception {
          
 AdminService adminService = new AdminService(new URL("http://localhost:7101/oracle-essbase-webservices/AdminService?wsdl"), new  QName ("http://essbase.webservices.oracle", "AdminService"));
           
IAdminService admin = adminService.getAdminServicePortType(s_securityFeatures);         
IAdminService admin = adminService.getAdminServicePortType();
 // Add OWSM/Non-OWSM header information                            
 // initialize -- build up server, app, db URI  first
 //create URI 

              try {
	 // start
               	admin.start(uri);
               	System.out.println("[" + server + ":" + app + ":" + db + "] started");
           
         
	 // ping          
           	long pingRes = admin.ping(uri);
           	System.out.println("pingRes : " + pingRes);


           	// Stop (server:app)
	  admin.stop(uri);

	   } catch (Exception ex) {
               ex.printStackTrace();
                 }

        }