Indicators

Indicators are the definitions by which the performances of organizations, business units, and their division, departments and employees are to be periodically assessed. These assessments are recorded as Scores.

Indicators have a couple of properties with values that are fixed:

Direction

Frequency

Show

GET /indicators/#{id}.xml

Returns a single indicator.

To get all the scores of an indicator see the Scores section.

Request

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

To include all the breakdown indicators that belong to this indicator add ?include_breakdowns=1:

To include all the aggregate indicators that belong to this indicator add ?include_aggregates=1

curl -u TOKEN:x -X GET \
  https://dashboard.kpilibrary.com/api/v2/indicators/INDICATOR_ID.xml?include_breakdowns=1

Response

Status: 200

<?xml version="1.0" encoding="UTF-8"?>
<indicator>
  <id type="integer">98</id>
  <name>Mean Time to Repair (MTTR)</name>
  <unit-id type="integer" nil="true"/>
  <exclude type="boolean">false</exclude>
  <authorization type="integer">0</authorization>
  <owner-id type="integer">129</owner-id>
  <direction-id type="integer">10</direction-id>
  <description>Average time to resolve an incident.</description>
  <frequency-id type="integer">40</frequency-id>
  <precision type="integer">2</precision>
  <target type="float" nil="true"/>
  <key type="boolean">false</key>
  <automated type="boolean">true</automated>
  <tags>
    <tag>customer</tag>
    <tag>service desk</tag>
  </tags>
  <breakdowns type="array">
    <breakdown-id type="integer">3</breakdown-id>
    <breakdown-id type="integer">8</breakdown-id>
  </breakdowns>
  <indicators>
    <indicator-id type="integer">923</indicator-id>
    <indicator-id type="integer">924</indicator-id>
    <indicator-id type="integer">1078</indicator-id>
    <indicator-id type="integer">1088</indicator-id>
  </indicators>
</indicator>

Create

POST /indicators.xml

Creates a new indicator.

Request

curl -u TOKEN:x -X POST -H "Content-Type: application/xml; charset=utf-8" \
  -d "<indicator><name>MTTR</name><tags>customer, service desk</tags></indicator>" \
  https://dashboard.kpilibrary.com/api/v2/indicators.xml

You can immediately link the indicator to existing breakdowns.

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

Response

Status: 201
Location: https://dashboard.kpilibrary.com/api/v2/indicators/NEW_INDICATOR_ID.xml

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

Update

PUT /indicators/#{id}.xml

Updates an existing indicator with new details.

Request

curl -u TOKEN:x -X PUT -H "Content-Type: application/xml; charset=utf-8" \
  -d "<indicator><name>MTTR</name><tags>customer, service desk</tags></indicator>" \
  https://dashboard.kpilibrary.com/api/v2/indicators/INDICATOR_ID.xml

Or for example:

<indicator>
  <name>Mean Time to Repair</name>
  <frequency-id>20</frequency-id>
  <precision>0</precision>
  <target>160</target>
  <tags>
    <tag>customer</tag>
    <tag>service desk</tag>
  </tags>
</indicator>

You can link the indicator to existing breakdowns.

<indicator>
  <name>Mean Time to Repair</name>
  <breakdowns type='array'>
    <breakdown>128</breakdown>
    <breakdown>130</breakdown>
  </breakdowns>
</indicator>

If you do not submit a breakdowns array, no breakdowns get unlinked from the indicator.
If you submit an empty array, the indicator gets removed from all breakdowns:

<indicator>
  <name>Mean Time to Repair</name>
  <breakdowns type='array'/>
</indicator>

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

Response

Status: 200

Delete

DELETE /indicators/#{id}.xml

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

Request

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

Response

Status: 200

List

GET /indicators.xml

Returns a list of indicators.

Request

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

The following parameters can be added to the query string to search for indicators:

• name
• matches_name
• key
• automated
• owner_id
• tag
• breakdown_id
• has_scores
• include_breakdowns
• include_aggregates

To list only the Key Indicators add e.g. ?key=1.

To list only the Automated Indicators add e.g. ?automated=1.

To list only indicators that have scores add e.g. ?has_scores=1.

To include all the breakdown indicators add e.g. ?include_breakdowns=1.

To include all the aggregate indicators add e.g. ?include_aggregates=1.

curl -u TOKEN:x -X GET \
  https://dashboard.kpilibrary.com/api/v2/indicators.xml?key=1&include_breakdowns=1

Response

Status: 200

<?xml version="1.0" encoding="UTF-8"?>
<indicators type="array">
  <indicator>
    <id type="integer">98</id>
    <name>Mean Time to Repair (MTTR)</name>
    <unit-id type="integer" nil="true"/>
    <exclude type="boolean">false</exclude>
    <authorization type="integer">1</authorization>
    <owner-id type="integer">129</owner-id>
    <direction-id type="integer">10</direction-id>
    <description>Average time to resolve an incident.</description>
    <frequency-id type="integer">40</frequency-id>
    <precision type="integer">2</precision>
    <target type="float" nil="true"/>
    <key type="boolean">false</key>
    <automated type="boolean">true</automated>
    <tags>
      <tag>customer</tag>
      <tag>service desk</tag>
    </tags>
    <breakdowns type="array">
      <breakdown-id type="integer">3</breakdown-id>
      <breakdown-id type="integer">8</breakdown-id>
    </breakdowns>
  </indicator>
  <indicator>
    ...
  </indicator>
</indicators>