What is the format of the data file required by pocketKPI?

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:

Where should the data file be located?

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 the our website. You change the server address in the Settings screen to point it 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.

How does the JSON file get created?

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 any way you prefer. The only thing pocketKPI is concerned about is if the file is formatted as valid JSON.

What is the structure of the expected JSON file?

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

KPIName

This is the name of the KPI. It should be human readable (i.e. make sense to your user). It would also be beneficial if you put any units of measure behind the name. For example a good KPI name might be "Factory Yield (%)". The percent sign at the end of the name tells the app user that the figure they can expect to see will be a percentage value.
This value should a be a string.

CurrentValue

This is the current value for the KPI.
This value should be a number and not a string.
eg. 45.2 and not "42.6"

TargetValue

This is the value that the KPI is aiming for. It is used to calculate the difference between the current value and what you are expecting the target to be.
This value should be a number and not a string.

LowIsBetter

This is a flag which indicates whether the a higher value than target is good 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.

LastUpdate

This is the last time the KPI was updated. This is used to display in pcoketKPI how long ago the KPI value was updated.
It is a string and the date should be in the following format yyyy-mm-dd hh:mm:ss.
For example, "2012-12-31 13:23:14"

Comment

This is a comment for explaining any reasons for the KPI being favourable or unfavourable.
This value should be a string.

URL

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.
This value should be a string.

MinTolerance

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.
This value should be a number.

MaxTolerance

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.

How do I create a pocketKPI JSON file?

This brief tutorial will demonstrate how to manually create a JSON file for pocketKPI. Whilst this is an example of creating such a file manually, the following steps may also be useful to those who plan on automating the creation of the file.

The basic framework of the pocketKPI JSON file looks like this:


{
"KPI" : [
]
}

This is basically defining an array of objects. The name of the array is KPI but for the moment it is empty and has no KPI objects in it.

To this basic outline we need to start adding KPIs to be displayed in the app. You can add as many KPIs as you like. pocketKPI will extend to display as many values as you put in the JSON file.

Any new KPI needs be contained within curly braces and each element of the object needs to end with a comma. In this example we are going to add a KPI for waste generated in our factory. To do this we create the following JSON object:



{
"KPIName" : "Waste(%)",
"CurrentValue" : 40.3,
"TargetValue" : 60,
"LowIsBetter" : "y",
"LastUpdate" : "2012-09-20 15:23:12",
"Comment: "Waste continues to be a challenge.",
"URL": "http://www.deadfrogstudios.com/pocketkpi"
}

This object is called Waste(%). It has a current value 0f 40.3, a target value of 60 and because a lower current value than target is better than a higher value we have have made the LowIsBetter flag say "y". This means a value lower than target will show green and a value higher than the target will show red.

We add this text after the line that reads like this.


 "KPI" : [

Our JSON file should now look like this:


{
"KPI" : [
{
"KPIName" : "Waste(%)",
"CurrentValue" : 40.3,
"TargetValue" : 60,
"LowIsBetter" : "y",
"LastUpdate" : "2012-09-20 15:23:12"
"Comment: "Waste continues to be a challenge.",
"URL": "http://www.deadfrogstudios.com/pocketkpi"
}
]
}

Congratulations, you have created your first KPI object! If we want to add another KPI we will need to create another object and make sure we add a comma after the first object to indicate there are several objects in the file.

We are now going to add an Overall Equipment Efficiency (OEE) KPI. Our new object looks like this:



{
"KPIName" : "OOE%",
"CurrentValue" : 10,
"TargetValue" : 12,
"LowIsBetter" : "n",
"LastUpdate" : "2012-09-20 12:01:30"
"Comment: "OOE means Overall Equipment Effectiveness.",
"URL": "http://www.deadfrogstudios.com/pocketkpi"
}

This object is called OOE(%). It has a current value of 10, and target value of 12 and because a value higher than the target are considered good the LowIsBetter is set to "n" meaning values higher than target will be coloured green.

Our JSON file should look like this.



{
"KPI" : [
{
"KPIName" : "Waste(%)",
"CurrentValue" : 40.3,
"TargetValue" : 60,
"LowIsBetter" : "y",
"LastUpdate" : "2012-09-20 15:23:12"
"Comment: "Waste continues to be a challenge.",
"URL": "http://www.deadfrogstudios.com/pocketkpi"
},
{
"KPIName" : "OOE%",
"CurrentValue" : 10,
"TargetValue" : 12,
"LowIsBetter" : "n",
"LastUpdate" : "2012-09-20 12:01:30"
"Comment: "OOE means Overall Equipment Effectiveness.",
"URL": "http://www.deadfrogstudios.com/pocketkpi"
}
]
}

Note the comma after the first object but the last object does not have a comma after the curly brace indicating it is the last object in the array of objects called KPI.

Our JSON file now has 2 KPI's in it. You can repeat the process using the steps above to make as many KPIs as you want. If you can get the KPI into your JSON file, pocketKPI will display it for you.

How can I make a data file using dashboards?

To create dashboards you need to modify your JSON file with a new parameter. The easiest way to do this is study the following file that shows an example of how a multiple dashboard file looks.

You can find the JSON file here.

What about adding KPI Admin Contact details?

This can be achieved by adding an object called "Contact" at the beginning of the file.

You can see an example of the contact info being implemented in a JSON file here.

Where can I download some sample JSON files?

The sample files that are used to demonstrate the app when it is first launched can be found here and here.