Sections

DataCollector

API

Sample code

Breakdown Instances

Breakdown Instances are the instance values of a Breakdown. Each Breakdown Instance that is linked to an Indicator via its Breakdown can have Scores collected which can be shown in a dashboard.

Example: given the breakdown “Country” you might have three breakdown instances: “USA”, “UK” and “The Netherlands”.

Show

GET /breakdowns/#{breakdown_id}/instances/#{instance_id}.xml

Returns a single breakdown instance.

Request

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

Response

Status: 200

<?xml version="1.0" encoding="UTF-8"?>
<breakdown-instance>
  <id type="integer">1</id>
  <name>USA</name>
  <exclude type="boolean">false</exclude>
  <indicators type="array">
    <indicator>
      <id type="integer">5</id>
      <target>23</target>
      <exclude type="boolean">false</exclude>
    </indicator>
    <indicator>
      <id type="integer">8</id>
      <target>99.99</target>
      <exclude type="boolean">false</exclude>
    </indicator>
  </indicators>
</breakdown-instance>

Create

POST /breakdowns/#{breakdown_id}/instances.xml

Creates a new breakdown instance. When the breakdown for which you create this instance is linked to an indicator this will also automatically create an indicator for which scores can be collected.

Request

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

Response

Status: 201
Location: https://dashboard.kpilibrary.com/api/v2/breakdowns/BREAKDOWN_ID/instances/NEW_INSTANCE_ID.xml

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

Update

PUT /breakdowns/#{breakdown_id}/instances/#{instance_id}.xml

Updates the name of an existing breakdown instance.

Request

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

Response

Status: 200

Delete

DELETE /breakdowns/#{breakdown_id}/instances/#{instance_id}.xml

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

Request

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

Response

Status: 200

List

GET /breakdowns/#{breakdown_id}/instances.xml

Returns a list of breakdown instances for a given breakdown.

Request

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

Response

Status: 200

<?xml version="1.0" encoding="UTF-8"?>
<breakdown-instances type="array">
  <breakdown-instance>
    <id type="integer">1</id>
    <name>USA</name>
    <exclude type="boolean">false</exclude>
  </breakdown-instance>
  <breakdown-instance>
    <id type="integer">2</id>
    <name>UK</name>
    <exclude type="boolean">false</exclude>
  </breakdown-instance>
  <breakdown-instance>
    <id type="integer">3</id>
    <name>Germany</name>
    <exclude type="boolean">false</exclude>
  </breakdown-instance>
</breakdown-instances>