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

customReportValues REST Specification

This section provides supporting information about the customReportValues call.

Request

Example

<?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">
       <axis type="X">
           <segment>
               <tier entity-id="2" type="dim">
                   <el id="8" />
               </tier>
               <tier entity-id="22" type="lAttr">
                   <el id="0" />
               </tier>
               <tier type="ver">
                   <el id="2" />
               </tier>
               <tier type="lvl">
                   <el id="2" />
               </tier>
               <tier type="time">
                   <el complex-type="timespan" start="204001" end="227001" show-time="1,2,3" />
                   <el complex-type="ptd" as-of="207001" stratum-id="3"/>
                   <el complex-type="ptd" as-of="207001" stratum-id="2"/>
                   <el id="17003" />
                   <el id="69002" />
                   <el id="210001" />
               </tier>
           </segment>
       </axis>
       <axis type="Y">
           <segment>
               <tier entity-id="11" type="dim">
                   <el id="34" />
               </tier>
               <tier entity-id="18" type="aAttr">
                   <el id="14" />
               </tier>
               <tier entity-id="29" type="dAttr" >
                   <el id="87" />
               </tier>
               <tier type="cur">
                   <el id="6600" />
               </tier>
               <tier type="acct">
                   <el id="1" />
               </tier>
           </segment>
       </axis>
   </report>
</call>

RNC (Relax NG compact) Format Specification

The following is the request schema, provided in the Relax NG Compact format.

default namespace = ""
start =
element call {
   attribute callerName { text },
   attribute method { "customReportValues" },
   element credentials {
     attribute instanceCode { text },
     attribute login { text },
     attribute locale { text }?,
     (attribute password { text } | attribute ticket{ text })
   },
   element report {
     attribute suppress-zeroes { "0" | "1" | "2" }?, #0=Nothing suppressed, 1=Suppress blank cells but not zeroes, 2=Suppress blank and zero cells(Default)
     attribute show-cell-notes { "0" | "1" }?, #0=Don't show cell notes(default), 1=show cell notes
     X-axis,  # Axes must be specified in order X, Y, (optional) FILTER
     Y-axis,
     Filter-axis?
   }
}
X-axis =
  element axis {
       attribute type { "X" },  
       segment+
     }
Y-axis =
  element axis {
       attribute type { "Y" },  
       segment+
     }
Filter-axis =
  element axis {
       attribute type { "FILTER" },  
       segment
     }
segment =
  element segment {
         (dimTier | levelTier | accTier | timeTier | versionTier | currencyTier | accAttrTier | levelAttrTier | dimAttrTier)+
       }
#Look up ids by calling the exportDimensions API
dimTier =
  element tier {
     attribute type { "dim" },
     attribute entity-id { xsd:integer }, #dimension id
     (stdRollup | stdEl)+ #stdRollup will allow for arbitrary rollups and stdEl will provide the dimension value id
   }
#Look up ids by calling the exportLevels API
levelTier =
  element tier {
     attribute type { "lvl" },
     (stdRollup | stdEl)+ #stdRollup will allow for arbitrary rollups and stdEl will provide the dimension value id
   }
 #Look up ids by calling the exportAccounts API
accTier =
  element tier {
     attribute type { "acct" },
     (acctRollup | acctEl)+ #acctRollup will allow for arbitrary rollups and acctEl will provide the account id
   }
 #Look up ids by calling the exportTime API
timeTier =
  element tier {
     attribute type { "time" },
     (timeRollup | timeEl)+ #timeRollup will allow for arbitrary rollups of single time elements
   }
 #Look up ids by calling the exportVersions API
versionTier =
  element tier {
     attribute type { "ver" },
     (stdRollup | stdEl)+
   }
#Look up ids by calling the exportActiveCurrencies API
currencyTier =
  element tier {
     attribute type { "cur" },
     stdEl+
   } 
#Look up ids by calling the exportAttributes API
accAttrTier =
  element tier {
     attribute type { "aAttr" },
     attribute entity-id { xsd:integer },#account attribute id
     (stdRollup | stdEl)+ #stdRollup will allow for arbitrary rollups and stdEl will provide the account attribute value id
   } 
 #Look up ids by calling the exportAttributes API
levelAttrTier =
  element tier {
     attribute type { "lAttr" },
     attribute entity-id { xsd:integer }, #level attribute id
     (stdRollup | stdEl)+ #stdRollup will allow for arbitrary rollups and stdEl will provide the level attribute value id
   }
 #Look up ids by calling the exportAttributes API
dimAttrTier =
  element tier {
     attribute type { "dAttr" },
     attribute entity-id { xsd:integer }, #dimension attribute id
     (stdRollup | stdEl)+ #stdRollup will allow for arbitrary rollups and stdEl will provide the dimension attribute value id
   }
 #All tiers except account and time have stdEl
stdEl =
element el {
   attribute id { xsd:integer }, # For custom dimensions and attributes, the root is represented by id = 0. Ex: for Dimension Region(entity-id=3), Region(rollup) will have id=0, Region(Uncat) will be id=0 and rollup-mode="U"
   attribute rollup-mode { "R" | "U" | "C" }? # R=Rollup or Leaf (as appropriate) (default), U=Uncat, C=Me & my immediate Children(not valid with arbitrary rollup)
}
stdRollup =
  element rollup {
stdEl+
}
 timeEl = (singleTimeEl | timespanEl | ptdEl)
singleTimeEl =
element el {
   attribute id { timeId }
}
timespanEl =
element el {
   attribute complex-type { "timespan" },
   attribute start { timeId }?, #Not specifying start or end means start or end of the 'Range of the versions in this export'.
   attribute end { timeId }?,
   attribute show-time { comma separated list of stratum ids }, # List of stratum ids that has show time enabled. Defaults to all strata being enabled.
}
ptdEl =
element el {
   attribute complex-type { "ptd" }
   attribute stratum-id { stratumId }, # Stratum id of the stratum used in "stratum to date"
   attribute as-of { timeId }
}
timeRollup = element rollup {
(singleTimeEl)+
}
timeId = xsd:integer # Unique time period id
acctEl =
element el {
   attribute id { xsd:integer },
   ( attribute rollup-mode { "R" | "C" } |
     attribute show-acct-splits { "0" | "1" } #0=don't show splits in account(default), 1=show splits in accounts (not valid with arbitrary rollup)
   )?
}
acctRollup =
  element rollup {
acctEl+
} 

Assumptions

  • Credentials can be login or ticket (as currently).
  • Axes must be specified in the following order: X, Y, (optional) FILTER.
  • Invalid values will always be marked. In the response, there is an invalid attribute flag on the cell.
  • Timespan, qtd and ytd specified in the filter will appear as timeranges in the filters in the response.
  • A cell is considered blank if the value for that cell in the cell explorer is empty. Cells that roll up to an empty text value are not considered blank.
  • TimeId construction:
    • Year: 4 digit year followed by 00. Ex: FY-2014 would have timeId:201400
    • Quarter: 4 digit year followed by '9' followed by 1 digit quarter number(1-4). Ex: Q3-2014 would have timeId: 201493
    • Month/Period: 4 digit year followed by the 2 digit month(01-12) or period number(01-13). Ex: Jan 2014 would be timeId: 201401, Period 3 2014 would be timeId: 201403

Response

Example

<?xml version="1.0" encoding="utf-8"?>
<response success="true">
  <messages>
      <message type="INFO" key="warning-invalid-timespan">Ignoring start of timespan, which precedes start of version</message>
      <message type="INFO" key="removed-by-qualification">Account "fred" was removed.</message>
      <message type="ERROR" key="exception-happened">Exception message</message>
  </messages>
  <output>
    <report>
      <filters>
        <coords>
          <coord type="ver" rollup="1">
              <el id="3" />
          </coord>
          <coord type="aAttr" entity-id="85" rollup="1">
              <el id="45" />
          </coord>
        </coords>
      </filters>
      <cols>
        <col id="1">
          <coords>
              <coord type="time">
                  <el id="204001" />
              </coord>
              <coord type="lvl">
                  <el id="4" />
              </coord>
          </coords>
        </col>
        <col id="2">
          <coords>
              <coord type="time">
                  <el id="205001" />
              </coord>
              <coord type="lvl">
                  <el id="4" />
              </coord>
          </coords>
        </col>
        <col id="3">
          <coords>
              <coord type="time">
                  <el id="204001" />
              </coord>
              <coord type="lvl">
                  <el id="5" rollup-mode="U" />
              </coord>
          </coords>
        </col>
        <col id="4">
          <coords>
              <coord type="time">
                  <el id="204002" />
              </coord>
              <coord type="lvl">
                  <el id="5" rollup-mode="U" />
              </coord>
          </coords>
        </col>
      </cols>
      <rows>
        <row>
          <coords>
             <coord type="acct">
                  <el id="45" />
              </coord>
          </coords>
          <cell value="2.345" col="1" />
          <cell value="4.567" col="2" />
          <cell value="3.397" col="3" />
          <cell value="5.274" col="4" />
        </row>
        <row>
          <coords>
             <coord type="acct">
                  <el id="46" />
              </coord>
          </coords>
          <cell value="5.6" col="1" />
          <cell value="2.7" col="2" />
          <cell value="1.9" col="3" />
          <cell value="9.4" col="4" />
        </row>
      </rows>
    </report>
  </output>
</response>

RNC (Relax NG compact) Format Specification

The following is the response schema, provided in the Relax NG Compact format.

default namespace = ""
 start =
element response {
   attribute success { xsd:boolean },
   element messages {
     element message {
       attribute key { text }?,
       attribute type { "INFO" | "ERROR" }?,
       attribute values { text }?,
       text
     }+
   }?,
   element output {
     element report {
       element filters {
         coords
       }?,
       element cols {
         element col {
           attribute id { xsd:integer },
           coords
         }+
       },
       element rows {
         element row {
           coords,
           element cell {
             attribute col { xsd:integer },
             attribute value { xsd:decimal },
             attribute text-rollup { xsd:string }?, # shows up only for text rollups
             attribute invalid { "0" | "1" }?, # 0=value is valid(default), 1=value is invalid
             attribute blank { "0" | "1" }?,  # 0=value is not blank(default), 1=value is blank
             element note { xsd:string }? # shows up only if show-cell-notes in the request is "1" and there is a note at this location.
           }+
         }*
       }
     }
   }?
}
 coords = element coords {
   coord+
}
coord = (stdCoord | dimCoord | acctCoord | timeCoord)
stdCoord =
element coord {
   attribute type { "lvl" | "ver" | "cur" },
   attribute rollup { "0" | "1" }?, # 0=not a rollup(default), 1=arbitrary rollup/filter
   coordEl+ #More than 1 indicates arbitrary rollup
}
dimCoord =
element coord {
   attribute entity-id { xsd:integer }, # This is the dimId/accAttrId/lvlAttrId/dimAttrId.
   attribute type { "dim" | "aAttr" | "lAttr" },
   attribute rollup { "0" | "1" }?, # 0=not a rollup(default), 1=arbitrary rollup/filter
   coordEl+ #More than 1 indicates arbitrary rollup
}
acctCoord =
element coord {
   attribute type { "acct" },
   attribute rollup { "0" | "1" }?, # 0=not a rollup(default), 1=arbitrary rollup/filter
   coordAcctEl+ #More than 1 indicates arbitrary rollup
}
timeCoord =
element coord {
   attribute type { "time" },
   attribute rollup { "0" | "1" }?, # 0=not a rollup(default), 1=arbitrary rollup/filter
   coordTimeEl+ #More than 1 indicates arbitrary rollup
}
 coordEl =
element el {
   attribute id { xsd:integer }, #This is the dimValId/accAttrValId/lvlAttrValId/dimAttrValId. Id = 0, indicates the root
   attribute rollup-mode { "U" }? # rollup-mode=U means categorized value
}
 coordAcctEl =
element el {
   attribute id { xsd:integer },
   attribute split-label { xsd:string }? #Will only be emitted if this corresponds to an account split.
}
 coordTimeEl = (singleTimeEl | ptdEl | timerangeEl)
singleTimeEl =
element el {
   attribute id { timeId }
}
ptdEl =
element el {
   attribute complex-type { "ptd"  },
   attribute stratum-id { stratumId } # Stratum id of the stratum used in "stratum to date"
   attribute as-of { timeId }
}
timerangeEl =
element el {
  attribute complex-type { "timespan" },
  attribute start { timeId },
  attribute end { timeId }
}
timeId = xsd:integer # Unique time period id
  • If a coord in a filter, col or row contains more than 1 element, it means that it represents the arbitrary rollup of all the elements in the coord.
  • If a timespan, qtd or ytd is passed in the filter, the response contains the corresponding timerange element in the filter.
  • In the filter axis, dimensions of the same type will be combined into an arbitrary rollup, except for dimensions, account attributes, and level attributes, which will be combined if both the type and the entity-id match.
  • Rollup mode of C in the response for an element on the filter gets turned into a single rollup element in the response.
  • If there are no filter coordinates, then the response will not include a filters element.
  • If there is an error and the report could not be run, then there will not be an output element and the messages element will include a message with type error.
  • If a cell is a text rollup, then the value attribute will be 0.
  • Was this article helpful?