Overview of the Oracle CRM On Demand Report Services API

This chapter provides an overview of the Oracle CRM On Demand Report Services application programming interface (API) available with Oracle CRM On Demand. It contains the following topics:

About the Oracle CRM On Demand Report Services API

The Oracle CRM On Demand Report Services API is a framework that provides a mechanism for administrators and users to list the reports in the company shared folders or to execute any specific report and download the output in specified formats to their local machines. The following methods are available for users:

ReportExecute method. For more information, see Using the ReportExecute Method.
ReportList method. For more information, see Using the ReportList Method.

Note: The Oracle CRM On Demand Report Services API is not compatible with V2 Analytics, it is compatible only with V3 Analytics.

The Oracle CRM On Demand Report Services API supports only company shared reports. It does not support prebuilt reports or personal reports. All reports executed by the Oracle CRM On Demand Report Services API are subject to the same limitations (time limits, row limits, data visibility, and so on) that apply to reports that run within Oracle CRM On Demand.

Note: The terms Report and Analysis are equivalent and are used interchangeably in this documentation.

About Downloading Reports with the ReportExecute Method

The ReportExecute method provides a means to execute and download reports without using the Oracle CRM On Demand user interface. You can then share those reports with others.

You can download reports in the following formats:

Comma separated values (CSV)
Excel spreadsheet (XLSX)
MIME HTML (MHTML)
Portable document format (PDF)
Text (Txt)

Users can use the Oracle CRM On Demand Report Services API to obtain specific reports on a regular basis. Administrators can use software tools to automate report generation and send the reports on a scheduled basis. Also, administrators can provide faster response times for popular analytic reports by generating them every morning, thus calculating some of the values used in future runs of the report.

To use the ReportExecute method you must create reports in Oracle CRM On Demand and save those reports in a shared folder. Also, you must acquire a download tool, such as cURL or Wget or use a scripting language such as JavaScript or Perl. The download tool’s purpose is to call the Oracle CRM On Demand Report Services API to generate a report and then to retrieve the report to your computer. cURL and Wget are examples of such download tools but you can use any tool of your choice that can post a request to the API and get a response back.

About Listing Reports with the ReportList Method

The ReportList method provides a means to list the reports in the company shared folders without using the Oracle CRM On Demand user interface. You can use the ReportList method to generate a summary list of reports in the company shared folder. The ReportList method accesses each folder and creates a zipped UTF-8 encoded CSV file with the summary list of reports.

To use the ReportList method you must create reports in Oracle CRM On Demand and save those reports in a shared folder. Also, you must acquire a download tool, such as cURL or Wget or use a scripting language such as JavaScript or Perl. The download tool’s purpose is to call the ReportList method to generate a summary report list and then to retrieve it to your computer. cURL and Wget are examples of such download tools but you can use any tool of your choice that can post a request to the API and get a response back.

About Data Visibility Rules

When you use the Oracle CRM On Demand Report Services API, the user account you use to sign on to Oracle CRM On Demand through the API determines what visibility rules are applied. The Oracle CRM On Demand Report Services API retrieves the same data that users get when the report is run from within Oracle CRM On Demand. All Manager, Team, Book and Role-Based Record Type visibilities are maintained.

If you sign on with an account that has full visibility, then the API delivers a report that shows all applicable rows of data. It might not be appropriate to share this report with users who do not normally have access to such data.

The user account must have access permissions to the shared folder that contains the reports and must have the following privileges:

Access Analytics Reports
Access V3 Analytics
Access Migrated Company Wide Shared Folder

Companies that want to automate executing and retrieving reports by using their infrastructure must consider their data security and privacy policies.

About the Download Tool

If you do not already have a download tool, then download one from the Internet. Most are available for free. You can use any tool of your choice that can post a request to the API and get a response back.

For example, the Wget tool is a command line download tool that you can use. All commands are issued from a command line. You can also use a scripting language to do the same function.

Sequence of Operation

The following steps describe the basic sequence of how to use the Oracle CRM On Demand Report Services API. This applies to all methods included with the API:

Create reports in Oracle CRM On Demand and save them in a shared folder.
Using the download tool or scripting language, sign on to Oracle CRM On Demand with a command that creates a session cookie file.
This step captures the Web session ID into a file for use in the next step. For more information, see Creating a Session Cookie File.
Using the download tool or scripting language, call the selected method:
- Using the ReportExecute Method
- Using the ReportList Method
Sign off from Oracle CRM On Demand to close the session.
For more information, see Signing Off from Oracle CRM On Demand.

Creating a Session Cookie File

Before you can call a method, you must sign on to the Oracle CRM On Demand and establish a Web session. The following example shows the format of the command for the Wget tool:

wget  --content-on-error  --keep-session-cookies --save-cookies "cookiefile1.txt" --post-data
"j_username=repuser1&j_password=pass1&langCode=ENU" https://secure-servername/OnDemand/authenticate

Substitute your specific information for the following parameters as shown in the following table.

Table Wget Command Parameters for Creating the Session Cookie File

Parameter	Value in Example	Description
`--save-cookies`	`"cookiefile1.txt"`	The name of the file into which Wget stores the Web session ID. The quotation marks around the file name are mandatory in Wget.
`j_username`	`repuser1`	The user name for the account you are using to sign on to Oracle CRM On Demand. The account you use controls the data visibility used to create the report. The user name must be URL Encoded, which means that special characters, such as spaces must be rendered in their hexadecimal equivalents. For example, the space character is ASCII 32, which in hexadecimal is %20.
`j_password`	`pass1`	The password associated with the user name. This password must also be URL Encoded. The password is transmitted unencrypted. To prevent compromising your personal data, do not use your own account. Instead, create a special account solely for the use of accessing reports.
`langcode`	`ENU`	The three letter code for your language.
`servername`	`servername`	The name or address of the server hosting Oracle CRM On Demand.

Signing Off from Oracle CRM On Demand

When you have retrieved all the reports you want, close the session with Oracle CRM On Demand by signing off. The following is an example of signing off using Wget:

wget  --load-cookie "cookiefile1.txt" https://secure-servername/OnDemand/logoff.jsp

Displaying the Oracle CRM On Demand Report Services API Allotments

To ensure that all users have equitable use of report services, the Oracle CRM On Demand Report Services API is subject to a set of service allotment limitations. You can display the allotments in the Service Allotment List.

To display service allotments

Navigate to Admin, Company Administration, and then Service Allotment Administration.

To display the current usage of your allotment

Navigate to Admin, Company Administration, and then Service Allotment Administration.

To display the usage history of your allotment

Navigate to Admin, Company Administration, and then to Service Allotment Usage History.

The following table describes the report services allotments.

Table Report Services Allotments

Service Allotment Resources	Service Allotments	Description
Report Services Bandwidth Allotment	100 MB/day	Determines the total size in megabytes (MB) of the Report Service results that can be used by a company within a 24-hour period.
Report Services Concurrent Request Allotment	5	Determines the maximum number of concurrent Report Service requests that a company can process. Abandoned requests typically take an hour to clear, depending on the value of the SESSION_TIMEOUT control.
Report Services Operations Allotment	20/day	Determines the number of Report Service operations that a company can perform within a 24-hour period.