Sections

DataCollector

API

Sample code

Breakdowns

Breakdowns are also known as drill-downs, allowing users to analyze indicators even further and to drill down into deeper levels. A breakdown consists of instances.

Example: the breakdown “Country” can have three instances: “USA”, “UK” and “The Netherlands”. Commonly used breakdowns are: Locations, Customers, Products, Departments and Cost allocations.

Show

GET /breakdowns/#{id}.xml

Returns a single breakdown.

Request

curl -u TOKEN:x -X GET https://dashboard.kpilibrary.com/api/v2/breakdowns/BREAKDOWN_ID.xml

Response

Status: 200

<?xml version="1.0" encoding="UTF-8"?>
<breakdown>
  <name>Country</name>
  <id type="integer">1</id>
  <instances type="array">
    <instance-id type="integer">1</instance-id>
    <instance-id type="integer">2</instance-id>
    <instance-id type="integer">3</instance-id>
  </instances>
  <indicators type="array">
    <indicator-id type="integer">1</indicator-id>
    <indicator-id type="integer">2</indicator-id>
  </indicators>
</breakdown>

Create

POST /breakdowns.xml

Creates a new breakdown.

Request

curl -u TOKEN:x -X POST -H "Content-Type: application/xml; charset=utf-8" \
  -d "<breakdown><name>Departments</name></breakdown>" \
  https://dashboard.kpilibrary.com/api/v2/breakdowns.xml

You can immediately link the breakdown to existing indicators.

<breakdown>
  <name>Country</name>
  <indicators type='array'>
    <indicator>128</indicator>
    <indicator>130</indicator>
  </indicators>
</breakdown>

Response

Status: 201
Location: https://dashboard.kpilibrary.com/api/v2/breakdowns/NEW_BREAKDOWN_ID.xml

<?xml version="1.0" encoding="UTF-8"?>
<breakdown>
  <id type="integer">NEW_BREAKDOWN_ID</id>
</breakdown>

Update

PUT /breakdowns/#{id}.xml

Updates an existing breakdown with new details.

Request

curl -u TOKEN:x -X PUT -H "Content-Type: application/xml; charset=utf-8" \
  -d "<breakdown><name>Departments</name></breakdown>" \
  https://dashboard.kpilibrary.com/api/v2/breakdowns/BREAKDOWN_ID.xml

You can link the breakdown to existing indicators.

<breakdown>
  <name>Country</name>
  <indicators type='array'>
    <indicator>128</indicator>
    <indicator>130</indicator>
  </indicators>
</breakdown>

If you do not submit an indicators array, no indicators get unlinked from the breakdown.
If you submit an empty array, the breakdown gets removed from all indicators:

<breakdown>
  <name>Country</name>
  <indicators type='array'/>
</breakdown>

Deleting the link between a breakdown and an indicator will also delete all the scores and dashboard portal objects related that link.

Response

Status: 200

Delete

DELETE /breakdowns/#{id}.xml

Destroys the breakdown at the referenced URL. All scores and dashboard portal objects related to this breakdown will be destroyed as well.

Request

curl -u TOKEN:x -X DELETE https://dashboard.kpilibrary.com/api/v2/breakdowns/BREAKDOWN_ID.xml

Response

Status: 200

List

GET /breakdowns.xml

Returns a list of breakdowns.

Request

curl -u TOKEN:x -X GET https://dashboard.kpilibrary.com/api/v2/breakdowns.xml

Response

Status: 200

<?xml version="1.0" encoding="UTF-8"?>
<breakdowns type="array">
  <breakdown>
    <name>Country</name>
    <id type="integer">121</id>
  </breakdown>
  <breakdown>
    <name>State</name>
    <id type="integer">123</id>
  </breakdown>
  <breakdown>
    <name>Departments</name>
    <id type="integer">128</id>
  </breakdown>
</breakdowns>