HtmlViewService Service

Use the HtmlViewService service to embed Oracle Analytics HTML results in third-party dynamic web pages, such as Active Server Pages (ASP) or JavaServer Pages (JSP), and portal frameworks.

The embed process merges Oracle Analytics web services content with the content of third-party web pages.

Method Name	Description
addReportToPage() Method	Adds results to an HTML page.
endPage() Method	Destroys a server page object and all data associated with it.
getCommonBodyHTML() Method	Retrieves HTML to include in the <BODY> section.
getHeadersHTML() Method	Retrieves HTML to include in the <HEAD> section.
getHtmlforPageWithOneReport() Method	Retrieves HTML for a page that contains only one analysis.
getHTMLForReport() Method	Retrieves HTML to display a particular set of results.
setBridge() Method	Specifies a bridge URL to receive communications. Can be useful when the Oracle Analytics web services server and the Presentation Services that the user is accessing reside on different machines or when you want to modify the results in your application development environment.
startPage() Method	Creates a new page object and returns its ID.

The methods in HtmlViewService extract fragments of HTML code that can be inserted in third-party web pages.

HTML Code Fragment	Desired Page Location
Header	Should be inserted in the <HEAD> section of an HTML page. The code contains links to common JavaScript files and style sheets.
Report Objects	Can be inserted anywhere in the <BODY> section.
Common Body	Should be inserted in the <BODY> tag after all analysis links. The code contains hidden HTML elements that are used to implement drilldown links.

For each returned analysis object, the HTML code fragment contains a callback link that is followed automatically when the web page is loaded by the browser. The code fragment does not contain the full user interface definition of the analysis. While the analysis is being constructed by Oracle Analytics Presentation Services, the interface displays the Oracle Analytics web services "Searching..." image embedded on the third-party web page.

For smooth analysis transitioning, Oracle Analytics Presentation Services tracks the Oracle Analytics analyses that have been added to third-party web pages by maintaining information in an internal logical page object during the construction of the third-party web page. The HtmlViewService service methods explicitly refer to the internal logical page by its ID.

About HtmlViewService Bridging and Callback URLs

To embed an analysis with active drilldown linksdrilldown links, the HtmlViewService service allows the web browser to issue callback requests from embedded analyses to the Oracle Analytics Presentation Services server.

Although it is possible to route requests directly to the Oracle Analytics Presentation Services server, in many cases it is preferable to route requests through the Oracle Analytics instance that originally serviced the third-party page. Also, in situations where Oracle Analytics Presentation Services and the third-party web server don't belong to the same Domain Name Service (DNS) domain, users may get JavaScript errors related to browser security constraints for cross-domain scripting.

To avoid these issues, use the setBridge() method to modify callback URLs to point to the third-party web server. Be aware that a web component executed by the third-party web server to re-route requests to Oracle Analytics Presentation Services isn't provided. This function would need to be fulfilled by the third-party application. For more information about the setBridge() method, see setBridge() Method.

addReportToPage() Method

Use the addReportToPage() method to add results to an HTML page.

Signature

void addReportToPage(String pageID, String reportID, ReportRef report, String reportViewName, ReportParams reportParams, ReportHTMLOptions options, String sessionID);

Arguments	Description
String pageID	Specifies a character string page ID returned by the startPage() method. See startPage() Method.
String reportID	Specifies a character string that identifies the analysis containing the results to add to the page. It should be used to reference this analysis in subsequent method invocations; for example, corresponding user interface elements generated by the Oracle Analytics Presentation Services server would reference the same ID.
ReportRef report	Specifies the analysis definition, supplied in the ReportRef structure.
String reportViewName	Specifies the view to display. If this parameter is null, the analysis' default view is used. The view name should match the one used to identify the view in the analysis XML definition.
ReportParams reportParams	Optional. Specifies the filters or variables to apply to the analysis before execution, supplied in the ReportParams common structure.
ReportHTMLOptions options	Optional. Specifies the display options to apply to the analysis after execution, supplied in the ReportHTMLOptions structure. See QueryResults Structure.
String sessionID	Specifies the session ID, which is usually returned by the logon method. If the SOAP client engine can handle HTTP cookies, you can omit the session ID or set it to null.

endPage() Method

Use the endPage() method to destroy the Oracle Analytics Presentation Services server page object and all data associated with it.

Signature

void endpage(String pageID, String sessionID);

Arguments	Description
String pageID	Specifies the ID of the page object, which is returned by the startPage() method. See startPage() Method.
String sessionID	Specifies the session ID, which is usually returned by the logon method. If the SOAP client engine can handle HTTP cookies, you can omit the session ID or set it to null.

getCommonBodyHTML() Method

Use the getCommonBodyHTML() method to retrieve HTML to include in the <BODY> section.

Signature

String getCommonBodyHTML(String pageID, String sessionID);

Arguments	Description
String pageID	Specifies the ID of the page object, which is returned by the startPage() method. See startPage() Method.
String sessionID	Specifies the session ID, which is usually returned by the logon method. If the SOAP client engine can handle HTTP cookies, you can omit the session ID or set it to null.

Returns

Returns a string containing the HTML to include in the<BODY> section.

getHeadersHTML() Method

Use the getHeadersHTML() method to retrieve HTML to include in the <HEAD> section.

Signature

String getHeadersHTML(String pageID, String sessionID);

Arguments	Description
String pageID	Specifies the ID of the page object, which is returned by the startPage() method. See startPage() Method.
String sessionID	Specifies the session ID, which is usually returned by the logon method. If the SOAP client engine can handle HTTP cookies, you can omit the session ID or set it to null.

Returns

Returns a string containing the HTML to include in the <HEAD> section.

getHtmlforPageWithOneReport() Method

Use the getHtmlforPageWithOneReport() method to retrieve the HTML for a page that contains only one analysis. A page that contains only one analysis doesn't have <BODY> and <HEAD> sections.

Signature

String getHtmlForPageWithOneReport(String reportID, ReportRef report, String reportViewName, ReportParams reportParams, ReportHTMLOptions reportOptions, StartPageParams pageParams, String sessionID);

Arguments	Description
String pageReportID	Specifies the analysis ID returned by the getHtmlForPageWithOneReport() method. See addReportToPage() Method.
ReportRef report	Specifies the analysis definition, supplied in the ReportRef structure.
String reportViewName	Specifies the view to display. If this parameter is null, the analysis' default view is used. The view name should match the one used to identify the view in the analysis XML definition.
ReportParams reportParams	Optional. Specifies the filters or variables to apply to the analysis before execution, supplied in the ReportParams common structure.
ReportHTMLOptions reportOptions	Optional. Specifies the display options to apply to the analysis after execution, supplied in the ReportHTMLOptions structure. See QueryResults Structure.
StartPageParams pageParams	Specifies the options to use when starting the page, supplied in the StartPageParams structure. See StartPageParams Structure.
String sessionID	Specifies the session ID, which is usually returned by the logon method. If the SOAP client engine can handle HTTP cookies, you can omit the session ID or set it to null.

getHTMLForReport() Method

Use the getHTMLForReport() method to retrieve an HTML excerpt to display the results for a particular analysis. Before invoking this method, use the addReportToPage method to add the results to an HTML page.

Signature

String getHTMLForReport(String pageID, String pageReportID, String sessionID);

Arguments	Description
String pageID	Specifies the ID of the page object, which is returned by the startPage() method. See startPage() Method).
String pageReportID	Specifies the analysis ID returned by the addReportToPage() method. See addReportToPage() Method.
String sessionID	Specifies the session ID, which is usually returned by the logon method. If the SOAP client engine can handle HTTP cookies, you can omit the session ID or set it to null.

Arguments

Description

String pageID

Specifies the ID of the page object, which is returned by the startPage() method. See startPage() Method).

String pageReportID

Specifies the analysis ID returned by the addReportToPage() method.

See addReportToPage() Method.

String sessionID

Specifies the session ID, which is usually returned by the logon method. If the SOAP client engine can handle HTTP cookies, you can omit the session ID or set it to null.

Returns

Returns a string containing the HTML excerpt that displays the specified analysis.

setBridge() Method

Use the setBridge() method to specify a bridge URL to receive communications. Specifying a bridge URL can be useful when the Oracle Analytics web services server and the user's web server reside on different machines, or when you want to modify the results in your application development environment.

After the setBridge() method is called, all requests from the client browser to the Oracle Analytics Presentation Services server are sent to the bridge URL, which then forwards requests to theOracle Analytics Presentation Services server.

Signature

setBridge(String bridge, String sessionID);

Arguments	Description
String bridge	Specifies the bridge URL. For example, http://myserver/myapplication/sawbridge
String sessionID	Specifies the session ID, which is usually returned by the logon method. If the SOAP client engine can handle HTTP cookies, you can omit the session ID or set it to null.

Arguments

Description

String bridge

Specifies the bridge URL. For example,

http://myserver/myapplication/sawbridge

String sessionID

Specifies the session ID, which is usually returned by the logon method. If the SOAP client engine can handle HTTP cookies, you can omit the session ID or set it to null.

Usage

You must make sure that the client browser provides a handler to the bridge URL in the form of a Java servlet, an Active Server Pages (ASP) page, a Common Gateway Interface (CGI), an Internet Server application programming interface (ISAPI), or an equivalent application.

You must also perform the following tasks:

Decode the path of the requested Oracle Analytics web services resource in the RedirectURL argument of the request character string. See How Callback URLs Are Replaced.
Forward all other request arguments, together with all headers and the request body, to the bridge URL.
Copy the response from the Oracle Analytics Presentation Services server to the response stream.

How Callback URLs Are Replaced

The new callback URL is based on the bridge URL, with the addition of a RedirectURL argument. The value of the RedirectURL argument should be the original value of the URL, encoded using standard URL encoding rules.

Internally, Oracle Analytics web services usually uses relative URLs for callback links. For example, if the original callback link is saw.dll?Go and the bridge URL is

http://myserver/myapplication/sawbridge

then the new callback URL is

http://myserver/myapplication/sawbridge?RedirectURL=saw.dll%3fGo

startPage() Method

Use the startPage() method to create a page object and returns its ID.

Signature

String startPage(StartPageParams options, String sessionID);

Arguments	Description
StartPageParams options	Specifies the options to use when starting the page, supplied in the StartPageParams structure. See StartPageParams Structure.
String sessionID	Specifies the session ID, which is usually returned by the logon method. If the SOAP client engine can handle HTTP cookies, you can omit the session ID or set it to null.

Returns

Returns a string containing the Oracle Analytics Presentation Services page ID.