Reporting API

Introduction to the Aprimo Reporting API

The Aprimo Reporting API retrieves real-time data from MPM reports with Web Service Access enabled. It is designed for seamless integration with reporting tools like Crystal Reports, Power BI, and other third-party platforms.

API Basics

HTTP Method: GET
Purpose: Pull data from Aprimo reports in real time.

API URL

Requests are made to a report-specific URL. Below is the URL format: https://<customer_name>.aprimo.com/WebApi/api/Reports/<report_id>.<type>/

URL Components:

<customer_name>: Replace with your Aprimo instance name.
<report_id>: Replace with the report's ID (e.g., 515 for the "Tasks by Project" report).
<type>: Specify the response format:
- XSD, XML, or JSON (default is JSON).

Notes:

The . character between <report_id> and <type> is required.
If <type> is omitted, the response defaults to JSON.
Ensure the / character follows the <type> value.

Description: MPM Report Parameters

When an MPM report includes user prompts, the required values must be provided in the API request. Missing parameters will result in an error response specifying the missing parameter name.

Parameter Guidelines

Parameter Names:
- Use the Attribute value from the Parameters tab in the report details.
- If the name contains spaces, include them but apply proper URL encoding.
Parameter Values:
- Match the value as used in the Aprimo report.
- Examples:
  - Date Fields: Use valid date formats, e.g., 12/15/2017.
  - Picklist Fields: Use valid choices, e.g., "In Process" for a Task Status field.

Parameter Types

1. Single Value Parameters

Format: <Parameter Name>=<Parameter Value>
Example:
?Task Status=Open&MyProjectEA=100&Begin_Date=01/01/2016

2. List Value Parameters

Format: Multiple <Parameter Name>=<Value> instances. Example: ?Begin Date=01/01/2016&Begin Date=02/02/2016&Task Status=Open&Task Status=Closed For parameters with multiple objects, include the object name before the parameter name. Example: ?Activity.Begin Date=01/01/2016&Task.Begin Date=03/03/2016

3. Range Value Parameters

Foramt: <Range Name>=<Start Value>;<End Value> Example: ?Begin Date=01/01/2016;01/01/2017&End Date=06/01/2016;12/31/2017

Example URL

Here’s a complete URL combining parameters for ranges, single values, and list values:

https://yournamehere.aprimo.com/WebApi/api/Reports/503.xml/?Begin Date=01/01/2016;01/01/2017&End Date=06/01/2016;12/31/2017&Status=Open&Type=1&Type=2

tip

Additional parameters not required by the report are ignored (e.g., when requesting XSD data).
For readability, examples above are shown without URL encoding. Ensure proper encoding is applied to spaces and special characters.

Generating an Authentication Token

Accessing a report via the Reporting API requires explicit permission granted within Aprimo. This process generates an authentication token, which is required for the API call. Users must have the “Analysis, Web Service Access Administration” domain right to access the Web Service Access tab and generate the token.

Steps to Enable Web Service Access

Navigate to the Web Service Access tab of the report.
Set the “Allow External Web Service Access?” picklist to:
- Yes – Basic Authentication or
- Yes – OAuth 2 Authentication
  (Default value is No).

Basic Authentication

When “Yes – Basic Authentication” is selected, a token is generated in the “Web Service Authentication Token” field after saving the page.
Note: The token is generated only once per report. If the setting is toggled back to No and then Yes, the same token will be reused.

Request Header Format:

Include the following in the request header:

Username: <report_id>
Password: <web_service_authentication_token>

OAuth 2 Authentication

For OAuth 2.0, follow the steps outlined in the Authorization Guide to generate a token using an OAuth 2.0 flow.

Request Header Format:

Include the generated token as:

Authorization: Bearer [token]

Request Responses: Reporting API Formats

The Reporting API supports the following format types:

XSD: Returns the schema definition for the specified report.
XML: Returns report data in XML format.
JSON: Returns report data in JSON format (default if no format is specified).
PDF: Returns the report as a PDF, formatted as if run inside Aprimo.

The format type is specified in the URL after the report ID. If omitted, the API defaults to JSON.

Example Responses

XSD Request

Example URL:

https://yournamehere.aprimo.com/WebApi/Api/Reports/515.xsd/

Example Response:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" attributeFormDefault="unqualified" elementFormDefault="qualified">
   <xs:element name="ReportDetails">
      <xs:complexType>
         <xs:sequence>
            <xs:element name="title" type="xs:string" />
            <xs:element name="subTitle" type="xs:string" />
            <xs:element minOccurs="0" maxOccurs="unbounded" name="Row">
               <xs:complexType>
                  <xs:sequence>
                     <xs:element name="Title" type="xs:string" />
                     <xs:element name="Task_ID" type="xs:string" />
                     <xs:element name="Title_1" type="xs:string" />
                     <xs:element name="Start_Type" type="xs:string" />
                     <xs:element name="Task_Status" type="xs:string" />
                     <xs:element name="Begin_Date" type="xs:string" />
                     <xs:element name="End_Date" type="xs:string" />
                     <xs:element name="Baseline_Begin_Date" type="xs:string" />
                     <xs:element name="Baseline_End_Date" type="xs:string" />
                     <xs:element name="Actual_Begin" type="xs:string" />
                     <xs:element name="Actual_End" type="xs:string" />
                     <xs:element name="Estimated_Work" type="xs:string" />
                     <xs:element name="Actual_Work" type="xs:string" />
                     <xs:element name="Out_Work" type="xs:string" />
                  </xs:sequence>
               </xs:complexType>
            </xs:element>
         </xs:sequence>
      </xs:complexType>
   </xs:element>
</xs:schema>

Notes

XSD: Use to understand the schema structure of a report.
XML/JSON: Ideal for consuming structured data.
PDF: Use for pre-formatted reports, similar to how they appear in the Aprimo UI.

XML Request

Example URL:

https://yournamehere.aprimo.com/WebApi/Api/Reports/515.xml/?Begin Date=1/1/2007;2/20/2017&Task Status=In Process

Example Response:

<?xml version="1.0" encoding="UTF-8"?>
<ReportDetails>
   <title>Tasks by Project</title>
   <subTitle />
   <Row>
      <Title>1a,1b Start Type Scenario</Title>
      <Task_ID>4535</Task_ID>
      <Title_1>Create Ad components</Title_1>
      <Start_Type>As Late As Possible</Start_Type>
      <Task_Status>In Process</Task_Status>
      <Begin_Date>2016-04-15 00:00:00</Begin_Date>
      <End_Date>2016-04-19 00:00:00</End_Date>
      <Baseline_Begin_Date>2016-04-05 00:00:00</Baseline_Begin_Date>
      <Baseline_End_Date>2016-04-09 00:00:00</Baseline_End_Date>
      <Actual_Begin>2016-04-15 00:00:00</Actual_Begin>
      <Actual_End />
      <Estimated_Work>2400</Estimated_Work>
      <Actual_Work>0</Actual_Work>
      <Out_Work>2400.000000000000000000</Out_Work>
   </Row>
   <Row>
      <Title>Asset Review</Title>
      <Task_ID>4432</Task_ID>
      <Title_1>Link Asset</Title_1>
      <Start_Type>As Soon As Possible</Start_Type>
      <Task_Status>In Process</Task_Status>
      <Begin_Date>2016-04-15 00:00:00</Begin_Date>
      <End_Date>2016-04-15 00:00:00</End_Date>
      <Baseline_Begin_Date>2016-04-15 00:00:00</Baseline_Begin_Date>
      <Baseline_End_Date>2016-04-15 00:00:00</Baseline_End_Date>
      <Actual_Begin>2016-04-15 00:00:00</Actual_Begin>
      <Actual_End />
      <Estimated_Work>480</Estimated_Work>
      <Actual_Work>0</Actual_Work>
      <Out_Work>480.000000000000000000</Out_Work>
   </Row>
</ReportDetails>

Notes

Purpose: Fetch report data in XML format for specified criteria (e.g., date ranges and task status).
Example Query Parameters:
- Begin Date=1/1/2007;2/20/2017
- Task Status=In Process
Rows: Represent individual report entries, containing fields such as Title, Task_ID, Start_Type, Task_Status, and more.

JSON Request Example

Example URL:

https://yournamehere.aprimo.com/WebApi/Api/Reports/515?Begin Date=1/1/2007;2/20/2017&Task Status=In Process

Example Response:

{
   "ReportDetails": {
      "title": "Tasks by Project",
      "subTitle": "",
      "Rows": [
         {
            "Title": "1a,1b Start Type Scenario",
            "Task_ID": "4535",
            "Title_1": "Create Ad components",
            "Start_Type": "As Late As Possible",
            "Task_Status": "In Process",
            "Begin_Date": "2016-04-15 00:00:00",
            "End_Date": "2016-04-19 00:00:00",
            "Baseline_Begin_Date": "2016-04-05 00:00:00",
            "Baseline_End_Date": "2016-04-09 00:00:00",
            "Actual_Begin": "2016-04-15 00:00:00",
            "Actual_End": "",
            "Estimated_Work": "2400",
            "Actual_Work": "0",
            "Out_Work": "2400.000000000000000000"
         },
         {
            "Title": "Asset Review",
            "Task_ID": "4432",
            "Title_1": "Link Asset",
            "Start_Type": "As Soon As Possible",
            "Task_Status": "In Process",
            "Begin_Date": "2016-04-15 00:00:00",
            "End_Date": "2016-04-15 00:00:00",
            "Baseline_Begin_Date": "2016-04-15 00:00:00",
            "Baseline_End_Date": "2016-04-15 00:00:00",
            "Actual_Begin": "2016-04-15 00:00:00",
            "Actual_End": "",
            "Estimated_Work": "480",
            "Actual_Work": "0",
            "Out_Work": "480.000000000000000000"
         }
      ]
   }
}

Notes

Purpose: Fetch report data in JSON format for specified criteria (e.g., date ranges and task status).
Example Query Parameters:
- Begin Date=1/1/2007;2/20/2017
- Task Status=In Process
Rows: Each row represents a report entry with fields like Title, Task_ID, Start_Type, Task_Status, and more.

Request Status Codes

The Reporting API provides HTTP status codes to indicate the outcome of a request. Below are the possible status codes and their meanings:

Success Codes

200: Request was successful, and the response body contains the report data in the requested format.
206: Partial content was returned because the report exceeded the maximum record limit set by the "Report Result Record Limit" system parameter.
- The Content-Range header indicates which records were returned (e.g., 0-9999/12001).

Error Codes

400: Bad request due to an issue with the request sent by the client.
401: Unauthorized request due to invalid authentication data.
- Example Response:
```
<Error>Web Service Access is not allowed for this report.</Error>
```
403: Forbidden request to a URL that is not accessible with the provided credentials.
404: Report not found for the provided Report ID.
- Example Response:
```
<Error>No report was found with ID = 5150.</Error>
```
500: Internal server error while processing the request.

Best Practices

Optimize Report Performance:
- Ensure reports take no more than 5 minutes to return results.
- If a report exceeds this duration, consult Aprimo for optimization strategies to avoid timeouts.
Avoid Concurrent Calls:
- Avoid making concurrent API calls to the same MPM object, as this may result in timeouts or errors like:
```
ExecuteNonQuery requires an open and available Connection. The connection’s current state is open.
```
- Ensure each call completes before initiating another request to the same object.

Introduction to the Aprimo Reporting API​

API Basics​

API URL​

URL Components:​

Notes:​

Description: MPM Report Parameters​

Parameter Guidelines​

Parameter Types​

1. Single Value Parameters​

2. List Value Parameters​

3. Range Value Parameters​

Example URL​

Generating an Authentication Token​

Steps to Enable Web Service Access​

Basic Authentication​

Request Header Format:​

OAuth 2 Authentication​

Request Header Format:​

Request Responses: Reporting API Formats​

Example Responses​

XSD Request​

XML Request​

JSON Request Example​

Request Status Codes​

Success Codes​

Error Codes​

Best Practices​

Introduction to the Aprimo Reporting API

API Basics

API URL

URL Components:

Notes:

Description: MPM Report Parameters

Parameter Guidelines

Parameter Types

1. Single Value Parameters

2. List Value Parameters

3. Range Value Parameters

Example URL

Generating an Authentication Token

Steps to Enable Web Service Access

Basic Authentication

Request Header Format:

OAuth 2 Authentication

Request Header Format:

Request Responses: Reporting API Formats

Example Responses

XSD Request

XML Request

JSON Request Example

Request Status Codes

Success Codes

Error Codes

Best Practices