Class actuate
Description
The entry point to the Actuate JavaScript API library. The actuate class uses load( ) to generate data, viewer, cross tab, parameter, explorer, and other components. The actuate class uses initialize( ) and authenticate( ) to connect to an Actuate web application service.
Use actuate.load( ) before calling actuate.initialize( ). The actuate.initialize( ) function loads all of the components added with load( ).
The initialize( ) function connects to an initial Actuate web application service. To connect to additional services simultaneously, use authenticate( ). Call initialize( ) before calling authenticate( ).
Constructor
The static actuate class loads when the a <script> element loads the Actuate JavaScript API.
Function summary
Table 44‑2 lists actuate functions.
Table 44‑2 actuate functions 
Function
Description
Connects to an Actuate web application service and authenticates
Returns the default service URL
Returns the default request options
Returns the Actuate web application version
Returns a viewer instance containing the given bookmark element
Connects to an initial Actuate web application service, loads an initial component, and invokes a callback function
Reports whether a given Actuate web application is connected
Returns whether a library is initialized
load( )
Loads the library for an additional component
logout( )
Logs a user out of an Actuate web application service
authenticate
Syntax
void authenticate(string iPortalURL, actuate.RequestOptions requestOptions, string userid, string password, function callback, string credentials, function errorCallback)
Connects to the Actuate web application service that is addressed by iPortalURL and authenticates the connection.
Parameters
iPortalURL
The iPortalURL parameter is a required string parameter that specifies the target Actuate web application URL.
requestOptions
The requestOptions parameter is an optional actuate.RequestOptions object. The requestOptions parameter defines the URL parameters to send with the authentication request, such as the iHub URL, volume, or repository type. Functions in the RequestOptions class enable the addition of custom parameters to the URL. When requestOptions is null, authenticate( ) uses the default parameter values for the target Actuate web application URL. These default parameter values are defined in the Actuate web application’s web.xml file.
userid
The userid parameter is an optional string parameter that contains the login user id when the login user id is not provided in the session.
password
The password parameter is an optional string parameter that contains the login password when the login password is not provided in the session.
credentials
The credentials parameter is an optional string parameter. This parameter holds information that supports checking user credentials with an externalized system such as LDAP. The credentials parameter supports additional credential information for any additional security systems in place on the application server where the web service is deployed.
callback
The callback parameter is an optional function to call after initialization. The actuate.authenticate( ) function passes the following variables to the callback function:
*iportalURL: The iportal URL passed in from the iPortalURL parameter
*userid: The authenticated user ID
*iserverURL: The BIRT iHub URL
*volume: The volume name
errorCallback
The errorCallback parameter is an optional function that specifies a function to call when an error occurs. The possible errors are actuate.ConnectionException, actuate.AuthenticationException, and actuate.Exception. The callback function must take an exception as an argument.
Example
To connect to an additional Actuate web service called digits, use code similar to the following:
actuate.authenticate("http://digits:8700/iportal", null, myname, mypassword, null, null, null);
getDefaultIportalUrl
Syntax
String getDefaultIportalUrl( )
Returns the default service URL.
Returns
String. The default service URL.
Example
This example calls actuate.getDefaultIportalUrl( ) to return the default service URL:
alert ("The default service URL is " + actuate.getDefaultIportalUrl( ));
getDefaultRequestOptions
Syntax
actuate.RequestOptions getDefaultRequestOptions( )
Returns the default request options.
Returns
actuate.RequestOptions object that contains the default request options.
Example
This example calls actuate.getDefaultRequestOptions( ) to return the default iHub URL:
alert ("The default iHub URL is " + actuate.getDefaultRequestOptions( ).getServerUrl( ));
getVersion
Syntax
string getVersion( )
Returns the Actuate web application version.
Returns
String. The string contains the Actuate web application version in the format "#version# (Build #buildnumber#)".
Example
The following sample code displays the version in an alert box:
alert("Version: " + actuate.getVersion( ));
getViewer
Syntax
actuate.Viewer getViewer(string bookmark)
actuate.Viewer getViewer(htmlelement viewer)
Returns a viewer instance containing the given bookmark element. Load the viewer module before calling actuate.getViewer( ).
Parameters
bookmark
This string parameter contains the name of the bookmark to retrieve or the name of an HTML <div> element.
viewer
This parameter is the DOM htmlelement object for the HTML <div> element that contains a viewer.
Returns
An actuate.Viewer object that contains a viewer. When actuate.getViewer( ) does not find a viewer, the function returns null.
Example
To retrieve the viewer assigned to the first_viewer <div> element on the page, use code similar to the following:
currentViewer = actuate.getViewer("first_viewer");
initialize
Syntax
void initialize(string iPortalURL, actuate.RequestOptions requestOptions, reserved, reserved, function callback, function errorCallback)
Connects to an initial Actuate web application service, loads all of the components added with load( ), and invokes a callback function.
Authentication is optional in initialize( ).
When using more than one service in one mashup page, use actuate.authenticate( ) to connect to additional services.
Parameters
iPortalURL
String. The target Actuate web application URL.
requestOptions
actuate.RequestOptions object. Optional. requestOptions defines URL parameters to send in the authentication request, such as the iHub URL, volume, or repository type. It can also add custom parameters to the URL. If requestOptions is null, initialize( ) uses the default parameter values for the target Actuate web application URL. These default parameter values are defined in Actuate web application’s web.xml file. Loading performance is improved if you create a requestOptions object to pass to initialize().
reserved
Set to null.
reserved
Set to null.
callback
Function. The callback function called after the initialization is done. The following variables are passed to the callback function:
*iportalUrl: The iportal URL passed in from the iPortalURL parameter
*userId: The authenticated user ID
*iserverUrl: The BIRT iHub URL
*volume: The volume name
errorCallback
Function. The function to call when an error occurs. The possible errors are actuate.ConnectionException, actuate.AuthenticationException, and actuate.Exception. errorCallback must take an exception as an argument.
Example
To initialize the client connection to a web service on myhost and then run the init( ) function, use the following code:
actuate.initialize("http://myhost:8700/iportal", null, null, null, init, null);
isConnected
Syntax
boolean isConnected(string iportalUrl, actuate.RequestOptions requestOptions)
Returns whether a given Actuate web application URL is connected.
Parameters
iPortalURL
String. The target Actuate web application URL.
requestOptions
actuate.RequestOptions object. Optional. requestOptions defines URL parameters to send with the authentication request, such as the iHub URL, volume, or repository type. It can also add custom parameters to the URL. If requestOptions is null, initialize( ) uses the default parameter values for the target Actuate web application URL. These default parameter values are defined in Actuate web application’s web.xml file.
Returns
Boolean. True if there is a connection to the given Actuate web application, False if there is no connection or if it is pending.
Example
The following sample code connects to the digits service using authenticate if not currently connected:
if (!actuate.isConnected("http://digits:8700/iportal", null)){
actuate.authenticate("http://digits:8700/iportal", null, myname, mypassword, null, null, null);
}
isInitialized
Syntax
boolean isInitialized( )
Returns whether the library is already initialized.
Returns
Boolean. True if the library is already initialized.
Example
The following sample code initializes a connection with the Actuate web service if one is not already initialized:
if (!actuate.isInitialized( )){
actuate.initialize("http://myhost:8700/iportal", null, null, null, init, null);
}
load
Syntax
void load(string componentName)
Specifies a component to be loaded by actuate.initialize( ). The available components are:
*dashboard: The dashboard component including the actuate.Dashboard package
*dialog: The dialog component including the actuate.Dialog class
*parameter: The parameter page component including the actuate.Parameter package
*reportexplorer: The report explorer component including the actuate.ReportExplorer package
*viewer: The viewer component including the actuate.Viewer and actuate.DataService packages
*xtabAnalyzer: The interactive crosstab component, including the actuate.XTabAnalyzer package
Parameter
componentName
String. componentName is a case-sensitive parameter. Valid component names are listed above.
Example
To enable a page to use viewer, dialog, and parameters, call actuate.load( ) three times, as shown in the following code:
actuate.load("viewer");
actuate.load("dialog");
actuate.load("parameter");
logout
Syntax
void logout(string iPortalURL, actuate.RequestOptions requestOptions, function callback, function errorCallback)
Logs out from the given Actuate web application URL and removes authentication information from the session. If the application was previously not logged in to this Actuate web application, it generates no errors but still calls the callback function.
Parameters
iPortalURL
String. The target Actuate web application URL.
requestOptions
actuate.RequestOptions object. Optional. requestOptions defines URL parameters to send with the authentication request, such as the iHub URL, volume, or repository type. It can also add custom parameters to the URL. If requestOptions is null, initialize( ) uses the default parameter values for the target Actuate web application URL. These default parameter values are defined in Actuate web application’s web.xml file.
callback
Function. Optional. The callback function called after the logout is done.
errorCallback
Function. The function called when an error occurs. The possible errors are actuate.ConnectionException, actuate.AuthenticationException, and actuate.Exception. errorCallback must take an exception as an argument.
Example
The following sample code disconnects to the digits service if currently connected:
if (actuate.isConnected("http://digits:8700/iportal", null)){
actuate.logout("http://digits:8700/iportal", null, null, null);
}