Skip to main content
Adaptive Insights
Knowledge and Support - Adaptive Insights

customReportValues

Category

Data retrieval

Description

Returns a set of data for the requested report criteria in the requested instance.

Permissions Required To Invoke

None (user must have a role assigned)

Parameters Required On Request

Credentials, Report

 

For API Version 15 and newer, call exportTime to retrieve the correct time element IDs.

This method's request contains a specification for a report that can be used to search data and return values. The API takes internal id numbers as inputs. Metadata retrieval APIs can be called to get valid ids. The results are represented by coords and values. The response also returns warnings and error messages if applicable.

This API is based on the matrix reports found in Adaptive Planning and Adaptive Consolidation. The request requires that the caller specify elements on an X-axis (columns), Y-axis (rows), and on an optional filter axis used to filter all data retrieved by the API. Matrix reports contain axes that determine which data appears on the report. Each axis defines an edge of the report. All matrix reports have three axes:

  • the X axis (the top edge). It defines the set of columns on the report.
  • the Y axis (the left edge). It defines the set of rows on a report
  • the filter axis, a global axis that defines properties that apply to all data on the report

An axis can be divided into multiple segments. A segment is a way of separating sets of dimensions on a single axis. The filter axis can only have one segment, but the other two axes can have as many segments as you wish.

Each segment can have an unlimited number of tiers. A tier represents a single logical dimension used to describe which elements of that dimension apply to the rows or columns under it. A segment can only contain at most one tier per logical dimension.

Each tier can contain one or more elements of the tier’s dimension. (All elements in the tier must belong to the dimension specified in the tier.) An element is usually an item in the dimension, such as a particular account in the account dimension, or a fiscal quarter in the time dimension. These elements are then used by the system to select and aggregate the data found on the report.

When a segment on the X or Y axis contains multiple tiers, the elements of each tier are combined with all the elements of all the other tiers to form the Cartesian product of all possible combinations of tier elements. Each column or row represents one possible combination of elements, selecting one element from each tier. For example, if a segment on the X axis--the columns along the top--contains a tier with five elements and a second tier with two elements, the segment will result in ten separate columns, representing all possible combinations of the elements on the tiers. You cannot place an element type on multiple axes. For example, if you place the account element type on rows, you cannot then add accounts on columns or filters.

A tier can have both individual elements or rollup elements. Rollup elements arbitrarily rollup all elements specified under them. Rollup elements are not allowed in the filter.

The filter axis behaves very similarly to the X and Y axes, but it has one slight difference: because the filter axis applies to all data in the report, it cannot combine its tiers to form multiple rows or columns. Instead, the filter axis combines all elements of each tier, aggregating the data from all elements together as though those elements were rolling up to a single aggregation.

See the documentation or online help about matrix reports for more information on segments, axes, and dimensional elements.

Request Format

The XML schema for the request can be found here: customReportValues REST Specification.

    <?xml version='1.0' encoding='UTF-8'?>
    <call method="customReportValues" callerName="a string that identifies your client application">
        <credentials login="sampleuser@company.com" password="my_pwd" locale="fr_FR" instanceCode="INSTANCE1"></credentials>
        <report suppress-zeroes="1"> <!-- run report suppressing blanks, but not zero values -->
            <!-- columns -->
            <axis type="X">
                <segment>
                    <!-- time columns -->
                    <tier type="time">
                        <!-- Timespan creates multiple time columns from Jan-2014 to Dec-2014.Ids specified in timespan element are retrieved from exportTime API output.  
                             'show-time' is a mandatory attribute specifying list of strata ids -->
                        <el complex-type="timespan" end="179001" start="168001" show-time="3,2,1"/>
                        <el id="180001" /> <!-- single column of Jan 2015 . This id is retrieved from exportTime API output-->
                    </tier>
                </segment>
            </axis>
            <!-- rows -->
            <axis type="Y">
                <segment>
                    <!-- There are 2 tiers with 4 elements total. This generates 4 rows of:
                         1. dimension value with id 135, account with id 51
                         2. dimension value with id 135, account with id 53
                         3. dimension value with id 199, account with id 51
                         4. dimension value with id 199, account with id 53 -->
                    <tier entity-id="13" type="dim"> <!-- dimension values with id 135 and 199 from dimension with id of 13 -->
                        <el id="135" />
                        <el id="199" />
                    </tier>
                    <tier type="acct"> <!-- account with id of 51 and 53 -->
                        <el id="51" />
                        <el id="53" />
                    </tier>
                 </segment>
            </axis>
        </report>
    </call>

Each invocation of this API call must contain exactly one element of each of the listed types:

credentials

report

credentials element

Tag Name

credentials

Description

All API calls must contain a single credentials element to identify the user invoking the API. The API call is then performed as this user (any audit trail or history of actions in the system will show that this user performed the action), and therefore the user must have the required permissions to perform the action in order for the API call to succeed.

Attributes of the Element

Attribute Name

Required?

Value

Example

login

Y

The login name of the user invoking the API method. This user must have a role containing the permissions required for the method being invoked.

sampleuser@company.com

password

Y

The password of the user invoking the API method.

my_password

locale

N

Specify the locale to be used to interpret incoming numbers and dates, and to format outgoing numbers and dates (using the proper thousands separator, month names, and date formatting). The locale is also used to specify the language in which any system messages in the response should appear. If not specified, en_US (American English) is used.

fr_FR

instanceCode

N

If the user specified in the credentials has access to more than one instance of Adaptive Planning, this attribute can be used to specify that the user is intending to access an instance other than their default instance. If not specified, the user's default instance will be used. To determine the available instance codes, use the exportInstances API.

MYINSTANCE1

Contents of the Element

(none)

 

report element

Tag Name

report

Description

Specifies the elements that make up the report.

Attributes of the Element

Attribute Name

Required?

Value

Example

suppress-zeroes

N

Specifying this attribute suppresses data in different ways. The valid values for this attribute are 0, 1, 2. 0=Nothing suppressed, 1=Suppress blank cells but not zeroes, 2=Suppress blank and zero cells(Default). A cell is considered blank if the cell explorer value for that cell is empty. Cells that roll up to an empty text value are not considered blank.

0

show-cell-notes

N

When given, this attribute either shows or hides cell notes. 0=Don't show cell notes(default), 1=show cell notes

1

suppress-rollups N When given, this attribute either shows or hides rollup rows and columns.Rollup rows and columns are suppressed only for those parents whose children are present on the report. Valid values are 0 (Don't suppress rollups), or 1 (Suppress rollups). The default value is 0. 1

Contents of the Element

(none)

Response Format

The XML schema for the response can be found in customReportValues REST Specification.

   <?xml version="1.0" encoding="utf-8"?>
   <response success="true">
       <messages>
           <!-- Dimension value id 13 is invalid. Rows with value id 13 has been removed from the report. -->
           <message type="WARNING" key="invalid-dim-attr-id" values="199,13">Invalid value Id
               199 for dimension/attribute type id 13
           </message>
       </messages>
       <!-- Global filters. Although the request did not supply any filters, defaults are used when dimension types are not
           specified. Reporting against version with id 2 which is the current version. Level with id 1 is the top most level this user
           has access to. -->
       <filters>
           <coords>
               <coord type="ver" rollup="1">
                   <el id="2" />
               </coord>
               <coord type="lvl" rollup="1">
                   <el id="1" />
               </coord>
           </coords>
       </filters>
       <!-- Only two time columns Dec-2014 and Jan-2015 have data, all other columns have been removed -->
       <cols>
           <col id="1">
               <coords>
                   <coord type="time">
                       <el id="179001" />
                   </coord>
               </coords>
           </col>
           <col id="2">
               <coords>
                   <coord type="time">
                       <el id="180001" />
                   </coord>
               </coords>
           </col>
       </cols>
       <rows>
           <row>
               <!-- Row coordinates are account with id 51 and dimension value with id of 135 from dimension with id of 13 -->
               <coords>
                   <coord type="acct">
                       <el id="51" />
                   </coord>
                   <coord type="dim" entity-id="13">
                       <el id="135" />
                   </coord>
               </coords>
               <cell value="2.345" col="1" /> <!-- This value’s coordinates are the row coordinates listed above, matches column position 1 and the global filters. -->
               <cell value="2.345" col="2" /> <!-- This value’s coordinates are the row coordinates listed above, matches column position 2 and the global filters. -->
           </row>
           <row>
               <!-- Row coordinates are account with id 53 and dimension value with id of 135 from dimension with id of 13 -->
               <coords>
                   <coord type="acct">
                       <el id="53" />
                   </coord>
                   <coord type="dim" entity-id="13">
                       <el id="135" />
                   </coord>
               </coords>
               <cell value="5.34" col="1" /> <!-- This value’s coordinates are the row coordinates listed above, matches column position 1 and the global filters. -->
               <cell value="7.44" col="2" /> <!-- This value’s coordinates are the row coordinates listed above, matches column position 2 and the global filters. -->
           </row>
       </rows>
   </report>
   </output>
   </response>

response element

Tag Name

response

Attributes of the Element

Attribute Name

Required?

Value

Example

success

Y

Either true or false, indicating whether the API call was successful or not. Even successful calls may contain warning messages in their response.

true

obsolete

N

If present on the response tag and set to true, this attribute indicates that the version of the method or API which is being invoked has become obsolete and is officially deprecated by Adaptive Planning. While it continues to function at this time, it may cease functioning in a short while. Typically, this attribute is not present.

false

Contents of the Element

A single optional messages element, and exactly one required output element.

 

messages element

Tag Name

messages

Description

Container for one or more message elements.

Attributes of the Element

(none)

Contents of the Element

One or more message elements.

 

message element

Tag Name

message

Description

Represents a message being sent from the system back to the caller. Messages are used for error messages when requests do not succeed, for warning messages when requests do succeed, and for confirmation messages upon success.

Attributes of the Element

Attribute Name

Required?

Value

Example

type

Y

Type is a way to identify the type of message. The different types are INFO, WARNING and ERROR. Type "ERROR" means that this request was not processed.

WARNING

key

Y

A key is a way to identify a particular message or type of message, useful for purposes of auto- mated error logging and recovery in client pro- grams. Keys do not change under different locales of requests, even when the language of the message changes. Keys also are unlikely to change in the future due to wording adjustments or terminology changes.

warning-invalid-time-
span-start

values

N

When given, the values represents variables that are used in the message text.

199,12

Contents of the Element

The text of the message. This text is in the language of the locale specified on the request (assuming that locale is supported). The text may also contain variable information such as the number of rows which were processed, or the particular column or value which caused an error.

 

output element

Tag Name

output

Description

 

Attributes of the Element

(none)

Contents of the Element

Refer to the Response XML for more details

  • Was this article helpful?