Accountservicesapiguide

Jump to: navigation, search

Contents

Understanding the BIRT onDemand Account Services API

This chapter contains the following topics:

  • About the BIRT onDemand Account Services API
  • About web services and WSDL
  • Understanding the elements of BIRT onDemand’s WSDL
  • Accessing the BIRT onDemand schema using a web browser

About the BIRT onDemand Account Services API

The BIRT onDemand Account Service Application Programming Interface (API) supports integrating and administering BIRT onDemand accounts using extensible markup language (XML) and the simple object access protocol (SOAP). Using the Account Service API, developers create applications that perform such tasks as creating accounts and users, uploading and downloading files, generating a document and scheduling document generation, sending an e-mail notification when a job completes, managing the users and security roles in an Encyclopedia volume. SOAP is the underlying layer that provides a messaging framework for web services. A web service supplies functionality and capability over the Internet, which assist in the creation of applications. Web services support integration of loosely coupled applications that are language-neutral and platform- independent, with application deployment using a standard transport protocol such as HTTP. Users, developers, and administrators can discover, describe, and invoke these applications in a distributed environment.

The BIRT onDemand Account Service API has the following features:

  • Platform and language independent access to Actuate web services Using SOAP messaging, BIRT onDemand’s web services integrate into applications developed in Java, Visual Basic, C++, C#, and other programming languages. The SOAP framework translates XML messages to the language of the calling application. Deployment of these applications can be across multiple platforms, including UNIX, Windows, or Linux, and integrate with web technologies such as J2EE and Microsoft Visual Studio .NET.
  • Comprehensive Encyclopedia volume administration: The Encyclopedia volume is the central repository for the design files, folders, and other items that Actuate iServer stores and manages. The Actuate Information Delivery API, can manage the items in an Encyclopedia volume from a single machine, and can send success or failure notices for immediate and scheduled jobs using simple mail transfer protocol (SMTP), Microsoft Exchange MAPI, or UNIX sendmail. The notifications can include attachments or embedded files.
  • Open infrastructure: The BIRT onDemand Account Services API supports BOD’s open server infrastructure. This infrastructure generates, distributes, and manages Actuate and third-party designs and integrates the designs into an Encyclopedia volume.
  • Localization support: By setting the Locale parameter in the header of a SOAP request, localization generates data in a language other than the Actuate iServer default language. The data display uses the currency format, date format, and other conventions for specific locales.

About web services and WSDL

BIRT onDemand’s web services support interactions with Actuate iServer, from running and viewing designs to managing Encyclopedia volume items. Actuate describes its services using Web Services Description Language (WSDL), an XML schema that provides the structure for requests to and responses from Actuate iServer.

A WSDL schema provides an abstract definition of the operations that a web service supports. The schema describes web services by providing such information as the name of the service, its transport protocol, data types, messages and operations, and input and output parameters. The schema binds these definitions to a concrete network protocol and message format. This schema resides on Actuate iServer.

BIRT onDemand’s WSDL schema serves as an interface to applications that integrate with BIRT onDemand accounts and your virtual Actuate iServer. The schema encompasses a subset of the web services accessible using the Actuate Information Delivery API. A developer can use the schema to generate a code library that contains the classes, including proxies, that the developer uses to write an application that communicates with a web service. A developer can use an integrated development environment (IDE) to develop an application that uses the Information Delivery API schema. Actuate supplies WSDL files for the Apache Axis and Microsoft .NET development environments.

The elements of BIRT onDemand’s schema are case-sensitive. Capitalization must occur as the schema indicates. For example, to use the AuthId element of the complex data type Header, write AuthId instead of AuthID or authid.

Understanding the elements of BIRT onDemand’s WSDL schema

A WSDL file defines every element used in a SOAP message. Additional details about how the BIRT onDemand Account Service API defines each element in the following sections.

Account Services API Reference

This section outlines the public APIs for the BIRT onDemand web services. All calls to the public BOD web services must be secured via SSL to protect the content of the message. Any calls

Account Service API Methods

User Management

Account administrators have the capability, through the BIRT onDemand Account Services API to programmatically create and manage users on the service. Via this API you can…

  • Add users
  • Update users
  • Remove users
  • Lock and unlock access by a specified user
  • Get a list of all user in the specified account
addUser(credentials, user)

Creates and adds a user to the account. At this point the user is only associated with the account and not with any servers, volumes or databases. This call throws an exception if the supplied username is already in use for the account.

credentials - The Credentials object with the caller’s credentials.
user - The User object with all the information about the user to be added.
updateUser(credentials, user)

Updates the specified user information.

credentials - The Credentials object with the caller’s credentials.
user - The User object with all the information about the user. All elements will be updated based on the username of the object. It is recommended that you get the object by calling getUser rather than building the object from scratch. The guarantees that no additional information is lost in the update.
removeUser(credentials, username)

Removes the specified user user from the account.

credentials - The Credentials object with the caller’s credentials.
user - The username of the user to remove.
getUsers(credentials, filter, fetchSize)

Returns a list of User objects for an account.

credentials - The Credentials object with the caller’s credentials.
filter - A filter string to apply to the results.
fetchSize - The maximum number of records to return.

Role Management

addRole(credentials, roleName)

Adds a role to an account.

credentials - The Credentials object with the caller’s credentials.
roleName - The name of the role to add.
getRoles(credentials, filter, fetchSize)

Returns a list of the roles for an account.

credentials - The Credentials object with the caller’s credentials.
filter - A filter string to apply to the results.
fetchSize - The maximum number of records to return.
getUserRoles(credentials, username, filter, fetchSize)

Returns a list of roles assigned to the user.

credentials - The Credentials object with the caller’s credentials.
username - The username of the user to get the roles for.
filter - A filter string to apply to the results
fetchSize - The maximum number of records to return.
getRoleUsers(credentials, username, filter, fetchSize)

Returns a list of users assigned to the role.

credentials - The Credentials object with the caller’s credentials.
roleName - The name of the role to get the users for.
filter - A filter string to apply to the results.
fetchSize - The maximum number of records to return.
addUserRole(credentials, username, roleName)

Assigns a role to a user.

credentials - The Credentials object with the caller’s credentials.
username - The username of the user to assign the role to.
roleName - The role name to assign to the user.
removeUserRole(credentials, username, roleName)

Removes a role from a user.

credentials - The Credentials object with the caller’s credentials.
username - The username of the user to remove the role from.
roleName - The role name to remove from the user.


Feature System Roles FeatureMoble Permission to use the Mobile feature. FeatureBRS Permission to use the BRS feature. FeatureDataAnalyzer Permission to use the Data Analyzer feature. FeatureDashBoard Permission to use the Dash Board feature.

Administrator Administrator NOTE: This role includes all the permissions below.

Account System Roles AddAccount Permission to add an account. ViewAccount Permission view accounts. UpdateAccount Permission to update an account. NOTE: this role include the ability to set the IsTrial flag and the ExpirationDate. RemoveAccount Permission to remove an account. UpdateAccountIsTrial Permission to update an account's IsTrial flag. UpdateAccountExpirationDate Permission to update an account's expiration date. LockAccount Permission to lock an account.

Database Server System Roles AddDatabaseServer Permission to add a database server. ViewDatabaseServer Permission to view database servers. UpdateDatabaseServer Permission to update a database server. RemoveDatabaseServer Permission to remove a database server.

Group System Roles AddGroup Permission to add a group. ViewGroup Permission to view groups. UpdateGroup Permission to update a group. RemoveGroup Permission to remove a group. ManageUserGroup Permission to manage users in a group.


Role System Roles AddRole Permission to add a role. ViewRole Permission to view roles. UpdateRole Permission to update a role. RemoveRole Permission to remove a role. ManageUserRole Permission to manage users in a group.

Server System Roles AddServer Permission to add a server. ViewServer Permission to view servers. UpdateServer Permission to update a server. RemoveServer Permission to remove a server. ManageUserServer Permission to manager users on a server.

Volume System Roles AddVolume Permission to add a volume. ViewVolume Permission to view volumes. UpdateVolume Permission to update a volume. RemoveVolume Permission to remove a volume. ManageUserVolume Permission to manage users in a volume

URL System Roles AddUrl Permission to add a URL. ViewUrl Permission to view a URLs. RemoveUrl Permission to remove a URL.

User System Roles AddUser Permission to add a user. ViewUser Permission to view users. UpdateUser Permission to update a user. RemoveUser Permission to remove a user. LockUser Permission to lock a user.

Notification Group Management

addGroup(credentials, roleName)

Adds a role to an account.

credentials - The Credentials object with the caller’s credentials.
roleName - The name of the role to add.
getGroups(credentials, filter, fetchSize)

Returns a list of the roles for an account.

credentials - The Credentials object with the caller’s credentials.
filter - A filter string to apply to the results.
fetchSize - The maximum number of records to return.
getUserGroups(credentials, username, filter, fetchSize)

Returns a list of roles assigned to the user.

credentials - The Credentials object with the caller’s credentials.
username - The username of the user to get the roles for.
filter - A filter string to apply to the results.
fetchSize - The maximum number of records to return.
getGroupUsers(credentials, groupName, filter, fetchSize)

Returns a list of usernames assigned to the group.

credentials - The Credentials object with the caller’s credentials.
groupName - The name of the group to get the usernames for.
filter - A filter string to apply to the results.
fetchSize - The maximum number of records to return.
addUserGroup(credentials, username, roleName)

Assigns a role to a user.

credentials - The Credentials object with the caller’s credentials.
username - The username of the user to assign the role to.
roleName - The role name to assign to the user.
removeUserGroup(credentials, username, roleName)

Removes a role from a user.

credentials - The Credentials object with the caller’s credentials.
username - The username of the user to remove the role from.
roleName - The role name to remove from the user.

Account Management

addAccount(credentials, account, systemRoleNames)

Adds a new account (sub account). This call will add the account with a default Administrator user and a default server and volume. This call with return an exception of the account id is not unique.

credentials - The Credentials object with the caller’s credentials.
account - The Account object with the values for the new account. This is the “child account.” This ID must be unique within the BoD system.
systemRoleNames - The names of the system roles to give to the account. If null all the roles of the parent account will be applied to the new account.
doesAccountIDExist(credentials, accountID)

Checks whether or not an accountID is used. This call does not reserve the accountID.

credentials - The Credentials object with the caller’s credentials.
accountID - The account ID to check.
removeAccount(credentials, accountID)

Removes an account (sub account).

  • credentials – The Credentials object with the caller’s credentials.
  • accountID – The account ID of the new account. This is the “child account.” This ID must be unique

System Privileges Management

Each BIRT onDemand account has a set of privileges that can be assigned to it. The privileges are used to customize and control what an account holder can and cannot do.

getSystemPrivileges(credentials, filter, fetchSize)

Gets a list of the available system privileges.

credentials - The Credentials object with the caller’s credentials.
filter - The filter criteria for the role list.
fetchSize - The maximum number of records to return.
getUserSystemPrivileges(credentials, username, filter, fetchSize)

Gets a list of the system privileges for a user.

credentials - The Credentials object with the caller’s credentials.
username - The name of the users to get the list for.
filter - The filter criteria for the role list.
fetchSize - The maximum number of records to return.
getAccountSystemPrivileges(credentials, accountID, filter, fetchSize)

Gets a list of the system privileges for an account.

credentials - The Credentials object with the caller’s credentials.
accountID - The ID of the account to get the system privileges for.
filter - A filter to apply to the results.
fetchSize - The maximum number of records to return.
addUserSystemPrivilege(credentials, username, systemPrivilegeName)

Adds a system privilege to a user.

credentials - The Credentials object with the caller’s credentials.
username - The name of the user to add the system privilege to.
systemPrivilegeName - The name of the system privilege to add to the user.
addAccountSystemPrivilege(credentials, accountID, systemPrivilegeName)

Adds a system privilege to an account.

credentials - The Credentials object with the caller’s credentials.
accountID - The ID of the account to add the system privilege to.
systemPrivilegeName - The name of the system privilege to add to the user.
removeUserSystemPrivilege(credentials, username, systemPrivilegeName)

Removes a system privilege from a user.

credentials - The Credentials object with the caller’s credentials.
username - The name of the user to remove the system privilege from.
systemPrivilegeName - The name of the system privilege to remove from the user.
removeAccountSystemPrivilege(credentials, accountID, systemPrivilegeName)

Removes a system privilege from an account.

credentials - The Credentials object with the caller’s credentials.
accountID - The ID of the account to remove the system privilege from.
systemPrivilegeName - The name of the system privilege to remove from the user.


Special System Privileges AccountServiceAPI Permission to use the account services API. This role should only be assigned to an account. SingleSignon Permission to use Single signon. This role should only be assigned to an account.

Feature System Privileges FeatureMoble Permission to use the Mobile feature. FeatureBRS Permission to use the BRS feature. FeatureDataAnalyzer Permission to use the Data Analyzer feature. FeatureDashBoard Permission to use the Dash Board feature.

Administrator Administrator NOTE: This role includes all the permissions below.

Account System Privileges AddAccount Permission to add an account. ViewAccount Permission view accounts. UpdateAccount Permission to update an account. NOTE: this role include the ability to set the IsTrial flag and the ExpirationDate. RemoveAccount Permission to remove an account. UpdateAccountIsTrial Permission to update an account's IsTrial flag. UpdateAccountExpirationDate Permission to update an account's expiration date. LockAccount Permission to lock an account.

Database Server System Privileges AddDatabaseServer Permission to add a database server. ViewDatabaseServer Permission to view database servers. UpdateDatabaseServer Permission to update a database server. RemoveDatabaseServer Permission to remove a database server.


Group System Privileges AddGroup Permission to add a group. ViewGroup Permission to view groups. UpdateGroup Permission to update a group. RemoveGroup Permission to remove a group. ManageUserGroup Permission to manage users in a group.

Role System Privileges AddRole Permission to add a role. ViewRole Permission to view roles. UpdateRole Permission to update a role. RemoveRole Permission to remove a role. ManageUserRole Permission to manage users in a group.

Server System Privileges AddServer Permission to add a server. ViewServer Permission to view servers. UpdateServer Permission to update a server. RemoveServer Permission to remove a server. ManageUserServer Permission to manager users on a server.

Volume System Privileges AddVolume Permission to add a volume. ViewVolume Permission to view volumes. UpdateVolume Permission to update a volume. RemoveVolume /** Permission to remove a volume. ManageUserVolume /** Permission to manage users in a volume

URL System Privileges AddUrl /** Permission to add a URL. ViewUrl Permission to view a URLs. RemoveUrl /** Permission to remove a URL.


User System Privileges AddUser Permission to add a user. ViewUser Permission to view users. UpdateUser Permission to update a user. RemoveUser Permission to remove a user. LockUser Permission to lock a user.

Server Management

addServer(credentials, serverName)

Creates a server under the current account.

credentials - The Credentials object with the caller’s credentials.
serverName - The name of the server to create.
removeServer(credentials, serverName)

Deletes a server from the current account.

credentials - The Credentials object with the caller’s credentials.
serverName - The name of the server to create.

Volume Management

addVolumeUser (credentials, volumeUser)

Adds a user to a volume.

credentials - The Credentials object with the caller’s credentials.
volumeUser - The VolumeUser object to add.
removeVolumeUser (credentials, serverName, volumeName, username)

Removes a user from a volume.

credentials - The Credentials object with the caller’s credentials.
serverName - The name of the server containing the volume to remove the user from.
volumeName - The name of the volume to remove the user from.
username - The username of the user to remove from the volume.
updateVolumeUser (credentials, volumeUser)

Updates a volume user.

credentials - The Credentials object with the caller’s credentials.
volumeUser - The VolumeUser object to update.
getUserVolumes(credentials, username, serverName, filter, fetchSize)

Gets a list of the volumes for a user.

credentials - The Credentials object with the caller’s credentials.
username - The username of the user to get the volumes for.
serverName - The name of the server to get the volumes for.
filter - A filter to apply to the results.
fetchSize - The maximum number of records to return.
getVolumeUsers(credentials, serverName, volumeName, filter, fetchSize)

Returns a list of users for a volume.

credentials - The Credentials object with the caller’s credentials.
serverName - The name of the server containing the volume to get the users for.
volumeName - The name of the volume to get the users for.
filter - A filter string to apply to the results.
fetchSize - The maximum number of records to return.


addVolume(credentials, serverName, volumeName)

Returns a list of usernames for a volume.

credentials - The Credentials object with the caller’s credentials.
serverName - The name of the server that will own this volume.
volumeName - The name of the volume to create.

Database Server Management

BIRT onDemand supports creating and associating multiple database server instances with accounts.

addDatabaseServer (credentials, databaseServerInfo)

Adds a database server instance to an account.

credentials - The Credentials object with the caller’s credentials.
databaseServerInfo - The DatabaseServerInfo object with the values for the new database server instance.
getDatabaseServer(credentials, name)

Gets the DatabaseServerInfo object containing the info about a database server instance.

credentials - The Credentials object with the caller’s credentials.
name - The name of the database server instance to get the info for.
removeDatabaseServer(credentials, name, finalSnapshotName)

Removes a database server.

credentials - The Credentials object with the caller’s credentials.
name - The name of the database server instance to get the info for.
finalSnapshotName - A name for a final snapshot (null for none).
updateDatabaseServer(credentials, databaseServerInfo)

Updates a database server.

credentials - The Credentials object with the caller’s credentials.
databaseServerInfo - The database server to update.
getAvailableDatabaseServerEngineTypes(credentials)

Gets a list of the available database server engine types.

credentials - The Credentials object with the caller’s credentials.
getAvailableDatabaseServerInstanceClasses(credentials, engineType)

Gets a list of the available database server instance classes for an engine type.

credentials - The Credentials object with the caller’s credentials.
engineType - The engine type to get the list for.
getDatabaseServerCidrs(credentials, name)

Gets the list of CIDRs for the database server.

credentials - The Credentials object with the caller’s credentials.
name - The name of the database server.
addDatabaseServerCidr(credentials, name, cidr)

Adds a CIDR record to a database server.

credentials - The Credentials object with the caller’s credentials.
name - The name of the database server.
cidr - The CIDR to add.
removeDatabaseServerCidr(credentials, name, cidr)

Removes a CIDR record from a database server.

credentials - The Credentials object with the caller’s credentials.
name - The name of the database server.
cidr - The CIDR to remove.
getDatabaseServers(credentials)

Gets a list of the database servers for an account.

credentials - The Credentials object with the caller’s credentials.

Embedding BIRT onDemand Content

The Actuate JavaScript API enables the creation of custom web pages that use Actuate BIRT report elements. The Actuate JavaScript API handles connections, security, and content. The Actuate JavaScript API classes enable the embedding of whole BIRT reports or BIRT report elements into a web page as well as the provision of encapsulated report data for new web services or to an existing Corporate web site.

To read more about integrating BIRT onDemand into your web application read “Using Actuate JavaScript API” available at BIRT Exchange.

Single Sign On

BIRT On Demand supports Single Sign-On (SSO).