JSON Guide

Whilst pocketKPI is designed to be as easy as possible for your people, it can be challenging setting up the data for use with the app. This guide explains the format of the JSON data file and has a small tutorial that walks you through creating a data file for pocketKPI.

Contents

The Basics

What is JSON?

pocketKPI expects that the data file is a valid JSON document. JSON is an easy and convenient way to exchange information via text file and is easier to work with than other formats like XML.

To learn more about JSON visit these links:

json.orgWikipedia article on JSONW3 Specification

Where should the JSON data file live?

The file can be hosted on any file server than can be accessed using a URL. Alternatively, you can create a webservice that returns JSON when you point pocketKPI to a specified URL.

pocketKPI ships with a default example file that is hosted on our web server. You can change the server address in the Apps Settings screen to point to the data file that lives on a server for your organisation or company. The server can be on the Internet or within your own corporate network. You simply need to ensure that the iPhone can connect to your internal servers, provide a correct URL and pocketKPI will do the rest.

It is also possible to host the JSON file on Dropbox. However, until specific Dropbox functionality is implemented in the app, the JSON file will need to live in your Dropbox “public” folder. See the Dropbox section for more information on how to set this up.

Creating a Data File for pocketKPI

Making a data file

There are 3 ways of creating a JSON file suitable for pocketKPI:

1. Create a JSON file manually using a text editor and place it on a server accessible by a URL.

2. Have a company system generate the JSON file periodically and place it on a server accessible by a URL.

3. Create a web service within your company that generates JSON data when a URL is sent to it. (eg. http://mykpiserver.com?givemedata=true)

What should the file extension be?

Usually JSON files have the extension .json (eg. mykpis.json) but in fact, the file can be named in anything you want. The only thing pocketKPI cares about is that the file is formatted as valid JSON.

JSON Data File Structure

Each KPI you want to create requires certain information in order for pocketKPI to process it correctly. The following is an explanation of the required fields for a KPI.

KPIName

Description
This is the name of the KPI. It should be human readable (i.e. it should make sense to the person using the app).

JSON Type
String

Example
“KPIName” : “Waste(%)”,

CurrentValue

Description
This is the current value for the KPI.

JSON Type
Number

Example
“CurrentValue” : 45.2,

TargetValue

Description
This is the value that the KPI is aiming for. It is used to calculate the variance between the current value and what you are expecting the target to be and will color badges appropriately based the tolerances you define.

JSON Type
Number

Example
“TargetValue” : 50.67,

LowIsBetter

Description
This is a flag which indicates whether a higher value than the target is better or whether a lower number than the target is better.

For example, a productivity increase over the target would be a good thing (ie. high is better), however a injury rate increase above the target would be bad, therefore low is better.

This is a string that should just contain “y” for lower value is better or “n” if a higher value is better. If this field is left out from the file the app will default to “n”. (ie. higher than target is better)

JSON Type
String

Example
“LowIsBetter” : “y”,

LastUpdate

Description
This is the last time the KPI was updated. This is used to display in pocketKPI how long ago the KPI value was updated in the data file.

It is a string and the date should be in the following format yyyy-mm-dd hh:mm:ss.

JSON Type
String

Example
“LastUpdate” : “2015-12-31 13:23:14”,

Comment

Description
This is a comment for explaining any reasons for the KPI being favourable or unfavourable.

New paragraphs for comments text can be denoted with \n. See example.

JSON Type
String

Example
“Comment” : “This KPI is improving after focus.\nThis is now a new paragraph.”,

URL

Description
This is a link to any kind of webpage, web based system or document on your Intranet/Internet that offers more information about the KPI.

It is used on the KPI detail screen.

JSON Type
String

Example
“URL” : “http://www.deadfrogstudios.com.”,

MinTolerance

Description
This is the minimum tolerance for the KPI. It can be negative or positive and indicates the minimum percentage change that will force a KPI badge to turn red.

For example -10 would indicate that the badge would turn red if there was more than a -10% variation from the target.

JSON Type
Number

Example
“MinTolerance” : 12,

MaxTolerance

Description
This is the maximum tolerance for the KPI. It can be negative or positive and indicates the maximum percentage change that will force a KPI badge to turn green.

For example +10 would indicate that the badge would turn green if there was more than a 10% variation from the target.This value should be a number.

JSON Type
Number

Example
“MaxTolerance” : 15,

IsPercentage

Note:
This field is new as of pocketKPI v.1.5 and is only supported by this version and above.


Description

This indicates whether the KPI is a percentage value or not. If it is a percentage it will be subject to slightly different variance calculation.

Essentially, this prevents pocketKPI trying to calculate the percentage variance of a percentage KPI which is not a valid calculation.

Valid values include “y” (the value is a percentage) or “n” (the value is not a percentage). If not specified it defaults to “n”.

JSON Type
String

Example
“IsPercentage” : “y”,

UnitOfMeasure

Note:
This field is new as of pocketKPI v.1.5 and is only supported by this version and above.

Description

This defines the symbol or text that represent the unit of measure for the KPI.

For example, you could specify kgs, miles, USD, points, etc. It enables you to remove the unit of measure from the title of the KPI.

JSON Type
String

Example
“UnitOfMeasure” : “kgs”,