Reporting API

The Aprimo Reporting API returns results from MPM reports that have been granted Web Service Access within Aprimo. The Reporting API can be used to pull data out of Aprimo in real time and is built to easily integrate with Crystal Reports and PowerBI, as well as other third party reporting tools.

Operations are expressed using the standard HTTP GET method.

API URL
Reporting API web service requests are made to a report-specific URL to elicit responses with these patterns.

URL without Parameters
URL: https://<customer_name>.aprimo.com/WebApi/api/Reports/<report_id>.<type>/
This URL is an API request of type GET. The following replacements would need to be made in the example URL above:

• <customer_name> – This would be replaced with the appropriate name for the desired Aprimo instance.
• <report_id> – This would be replaced with the ID shown when viewing the details of the report. For example, the “Tasks by Project” report has an ID of 515.
• <type> – The type entry can be one of three values: XSD, XML, or JSON. The value entered is not case-sensitive. When a type value is specified, note that the “.” character between the <report_id> and the type is required and the “/” character after the type value is also required. If no type value is specified so the URL passed in ends with just the <report_id> value, the response will default to JSON formatting.

URL with Parameters
Report parameters are sent in a query string.

Description
An MPM report defined with criteria that have a user prompt will require values to be provided in the request call. These parameters are required and if they are not included in the query string, an error response will be returned. The content of the response will contain the name of the required parameter that is missing.
The name to use for passing in the parameters will come from the Parameters tab when viewing the report details. The value in the Attribute column for the parameter is what should be used for the parameter name. If the Attribute name contains spaces, it should be passed with the spaces included, but proper encoding should be applied when the URL is created.

The value passed for the parameters should be the same as what would be selected when running the report within Aprimo. For date fields, a valid date value would be used, such as “12/15/2017”. For fields that have pre-defined choices available (such as picklist or multi-select fields), the value passed in should be something from the valid choices, such as “In Process” for a Task Status field. As with the parameter name, any spaces in the value should be included, but proper encoding should be applied.
Single value parameters are simply instances of <Parameter Name>=<Parameter Value>. Some examples include:

?Task Status=Open&MyProjectEA=100&Begin_Date=01/01/2016

List value requests are multiple instances of <Parameter Name>=<List Value One>&<Parameter Name>=<List Value Two>&etc… Examples include:

?Begin Date=01/01/2016&Begin Date=02/02/2016&Begin Date=03/03/2016&Task Status=Open&Task Status=Closed&Task Status=Pending&MySupplierID=1&MySupplierID=2&MySupplierID=3

For list value requests where the same parameter name is used for different objects, the object name needs to be added before the parameter name. Here’s an example using both activity and task begin dates:

?Activity.Begin Date=01/01/2016&Activity.Begin Date=02/02/2016&Task.Begin Date=03/03/2016

Range value requests are semi-colon delimited instances of <Range Name>=<Start Range Value>;<End Range Value>. Some examples include:

?Begin Date=01/01/2016;01/01/2017&End Date=06/01/2016;12/31/2017&MyTaskEA=50;150

This is an example of a complete URL that contains a combination of parameters specifying a range of dates for the Begin Date parameter, a range of dates for the End Date parameter, a single value for the Status parameter, and two possible values for the Type parameter. The report being requested has an ID of 503 and the desired formatting for the results is XML. Note that for readability, this is being shown without encoding applied:

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

Note: When making a call to the Reporting API, if there are additional parameters specified that are not required by the report, they will be ignored rather than causing an error response. For example, making a request for the XSD does not require any parameters included in the URL. However, if a query string is passed as part of the call, it is simply disregarded and the XSD request is processed correctly.

Generating an Authentication Token

The ability to access a report through the Reporting API must be explicitly granted from within the Aprimo application (note that this grant overrides MPM security settings such as active/inactive). During this process, an authentication token is generated that will be used as part of the authentication for the Reporting API call. To generate the token, a user must have the “Analysis, Web Service Access Administration” Domain right to access the “Web Service Access” tab where the new token is available.
1. Go to the Web Service Access tab of the report.
2. Select “Yes – Basic Authentication” or “Yes – OAuth 2 Authentication”  for the “Allow External Web Service Access?” picklist (default value is No).

Basic Authentication

Selecting “Yes – Basic Authentication” generates a value in the read-only “Web Service Authentication Token” field when the page is saved.
Note: The token will only be generated once for each report. If the flag is set to No and then back to Yes, the same token will be used.

Request Header
The request header should include an Authorization entry that is based upon enabling Basic Authentication with the following values:
Username: <report_id>
Password: <web_service_authentication_token>

OAuth 2 Authentication

Refer to the Authorization page on how to generate a token using an OAuth 2.0 flow. Once generated pass in a header as Authorization: Bearer [token].

The Reporting API supports four format types:

1. XSD – Returns the schema definition for the report specified.
2. XML – Returns report data in XML format.
3. JSON – Returns report data in JSON format.
4. PDF – Returns the report as a PDF, formatted as if someone ran the report inside of Aprimo.

As indicated above, the type of format being requested is specified in the URL after the Report ID value. It should be one of the valid types, or left out entirely to default to JSON formatting. Below are examples of responses for each of three types that return text-formatted data.

XSD Request
Example URL: https://yournamehere.aprimo.com/WebApi/Api/Reports/515.xsd/
Example Response Body:

<?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>

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 Body:

<?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>

JSON Request

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

Example Response Body:

{
   "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"
         }
      ]
   }
}

A successful Reporting API request will result in one of two possible HTTP return codes: 200 or 206, depending upon whether all of the results are allowed to be returned.
When a request cannot be processed, an appropriate HTTP status code is returned to indicate the general type of error encountered. Details of the error message are included in the response body.
This table lists status codes and their descriptions:

Example Response Body for 401 Status Code

<Error>Web Service Access is not allowed for this report.</Error>

Example Response Body for 404 Status Code

<Error>No report was found with ID = 5150.</Error>

When using the reporting API, ensure that your reports take no more than 5 minutes to return to the caller. If a report takes longer than 5 minutes, please consult with Aprimo on how to best redesign it to bring it under this time. Reports which run longer run the risk of timeouts and may not work properly.

Concurrent calls to the same underlying MPM object will likely result in a timeout or error message that reads “ExecuteNonQuery requires an open and available Connection. The connection’s current state is open.” To avoid these errors, ensure that all calls that hit an MPM object have returned before making a subsequent call to the same object.