KPI Entries

These are the KPI data entries added by a user for a specific date based on the entry frequency. The user's group items are associated with the KPI entry on adding a new entry. KPI Entries are removed permanently with their associated group items when deleted.

List of API Actions

Get all KPI entries
Get a KPI entry
Add a KPI entry
Add/Update a list of KPI entries
Update a KPI entry
Delete a KPI entry

KPI entry object

The object has the following properties:

Name	Type	Read Only	Mandatory	Max Len.	Notes
id	integer	yes	no		Automatically generated for the KPI entry
user_id	integer	no	yes		An id of an active user to assign to the KPI entry
kpi_id	integer	no	yes		The kpi must be active and cannot be a calculated KPI. The KPI must also be assigned to the user
entry_date	datetime	no	yes		The date of the entry
actual	decimal	no	no		The actual value cannot be null if the target and notes are both null
target	decimal	no	no		The target value of the entry. This value will be ignored if the KPI has a null target
notes	string	no	no	500	The note associated with the KPI entry
created_at	datetime	yes	no		The UTC date and time the KPI entry was created
updated_at	datetime	yes	no		The UTC date and time the KPI entry was updated

JSON Example

{
      "id":         12345,
      "user_id":    1234,
      "kpi_id":     5678,
      "entry_date": "2012-06-25",
      "actual":     50.0000,
      "target":     110.0000,
      "notes":      "This is a note",
      "created_at": "2012-11-30T11:20:00",
      "updated_at": "2013-02-15T16:01:00"
    }

XML Example

<KPIEntry xmlns="http://schemas.datacontract.org/2004/07/SimpleKPI.Application.Areas.Api.Models" 
            xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
      <id>12345</id>
      <user_id>1234</user_id>
      <kpi_id>5678</kpi_id>
      <entry_date>2012-06-25</entry_date>
      <actual>50.0000</actual>
      <target>110.0000</target>
      <notes>This is a note</notes>
      <created_at>2013-02-21T10:12:00</created_at>
      <updated_at>2013-02-21T10:12:00</updated_at>
    </KPIEntry>

Get all KPI entries

The KPI entries are filtered based on the search query string. All the search criteria is optional and the dateFrom and dateTo will default to today's date if not sent. The action will return a maximum of 500 entries per page. If the result set has the amount of rows you set &rows=100, it's your responsibility to check the next page to see if there are any more -- you do this by adding &page=2 to the query, then &page=3 and so on.

GET /api/kpientries?userid=123&kpiid=456&dateFrom=YYYY-MM-DD&dateTo=YYYY-MM-DD&rows=100&page=2

Using curl

curl https://{subdomain}.simplekpi.com/api/kpientries?userid=123&kpiid=456&dateFrom=2012-01-01&dateTo=2012-02-01
          -v -u {email_address}:{token}

Example Response

Status: 200 OK
        [
          {
            "id":         12345,
            "user_id":    1234,
            "kpi_id":     5678,
            "entry_date": "2012-06-25",
            "actual":     50.0000,
            "target":     110.0000,
            "notes":      "This is a note",
            "created_at": "2012-11-30T11:20:00",
            "updated_at": "2013-02-15T16:01:00"
          },
          {
            "id":         12346,
            "user_id":    1235,
            "kpi_id":     5679,
            "entry_date": "2012-08-25",
            "actual":     55.0000,
            "target":     10.0000,
            "notes":      "This is a note",
            "created_at": "2012-11-30T11:20:00",
            "updated_at": "2013-02-15T16:01:00"
          }
        ]

Get a KPI entry

GET /api/kpientries/{id}

Using curl

curl https://{subdomain}.simplekpi.com/api/kpientries/{id}
      -v -u {email_address}:{token}

Example Response

Status: 200 OK
    {
      "id":         12345,
      "user_id":    1234,
      "kpi_id":     5678,
      "entry_date": "2012-06-25",
      "actual":     50.0000,
      "target":     110.0000,
      "notes":      "This is a note",
      "created_at": "2012-11-30T11:20:00",
      "updated_at": "2013-02-15T16:01:00"
    }

Add a KPI entry

For ease of use you are able to pass in the user's email address instead of the user_id using the property name email.

POST /api/kpientries

KPI Entry Object to POST

The object has the following properties:

Name	Type	Read Only	Mandatory	Max Len.	Notes
user_id	integer	no	yes if no email		The user id of an active user to assign to the KPI entry.
email	string	no	yes if no user_id		The email address of an active user to assign to the KPI entry instead of using the user_id.
kpi_id	integer	no	yes		The kpi must be active and cannot be a calculated KPI. The KPI must also be assigned to the user.
entry_date	datetime	no	yes		The date of the entry
actual	decimal	no	no		The actual value cannot be null if the target and notes are both null
target	decimal	no	no		The target value of the entry. This value will be ignored if the KPI has a null target
notes	string	no	no	500	The note associated with the KPI entry
setActual	boolean	no	no		Defaults to true and when set to false, will leave the actual value as is if you only want to update the target or notes
setTarget	boolean	no	no		Defaults to true and when set to false, will leave the target value as is if you only want to update the actual value or notes
setNotes	boolean	no	no		Defaults to true and when set to false, will leave the notes as is if you only want to update the actual or target values
addToActual	boolean	no	no		Defaults to false and when set to true, will add to your existing actual value. It can be used to increment or decrement the value as needed.

JSON POST Example

{
          "email":    "john@simplekpi.com",
          "kpi_id":     5678,
          "entry_date": "2012-06-25",
          "actual":     50.0000,
          "target":     110.0000,
          "notes":      "This is a note",
          "setActual":  true,
          "setTarget":  false,
          "setNotes":   false,
          "addToActual": true
        }

Using curl

curl https://{subdomain}.simplekpi.com/api/kpientries
          -H "Content-Type: application/json" 
          -d '{"user_id": 1234, "kpi_id": 5678, "entry_date": "2012-06-25", "actual": 50.0000, 
               "target": 110.0000, "notes": "This is a note"}'
          -v -u {email_address}:{token} -X POST

Example Response

Status: 201 Created
        Location: https://{subdomain}.simplekpi.com/api/kpientries/{id}
        {
          "id":         12345,
          "user_id":    1234,
          "kpi_id":     5678,
          "entry_date": "2012-06-25",
          "actual":     50.0000,
          "target":     110.0000,
          "notes":      "This is a note",
          "created_at": "2012-11-30T11:20:00",
          "updated_at": "2013-02-15T16:01:00"
        }

Add/Update a list of KPI entries

Post a list of KPI entries to batch load for speed.

POST /api/kpientries

KPI batch object to POST

The object has the following properties:

Name	Type	Read Only	Mandatory	Max Len.	Notes
entries	Array of KPI Entry Objects	no	yes	5000	An array of KPI Entry Objects as described in Add a KPI Entry.
hasActuals	boolean	no	no		Defaults to true and when set to false, will leave the actual values as is if you only want to update the target or notes for the batch
hasTargets	boolean	no	no		Defaults to true and when set to false, will leave the target values as is if you only want to update the actual value or notes for the batch
hasNotes	boolean	no	no		Defaults to true and when set to false, will leave the notes as is if you only want to update the actual or target values for the batch

JSON POST Example

            {
                "entries": [
                {
                  "email":    "john@simplekpi.com",
                  "kpi_id":     5678,
                  "entry_date": "2012-06-25",
                  "actual":     50.0000,
                  "target":     110.0000,
                  "notes":      "This is a note"
                },
                {
                  "email":    "john@simplekpi.com",
                  "kpi_id":     5678,
                  "entry_date": "2012-06-26",
                  "actual":     80.0000,
                  "target":     50.0000,
                  "notes":      "This is a note"
                }],
                "hasActuals": true,
                "hasTargets": true,
                "hasNotes": true
            }

Using curl

curl https://{subdomain}.simplekpi.com/api/kpientries/list
          -H "Content-Type: application/json" 
          -d '{"entries":[{"user_id": 1234, "kpi_id": 5678, "entry_date": "2012-06-25", "actual": 50.0000, 
               "target": 110.0000, "notes": "This is a note"}], "hasActuals": true}'
          -v -u {email_address}:{token} -X POST

Example Response

Status: 201 Created
        {
          "rows_added":   2
        }

Update a KPI entry

PUT /api/kpientries/{id}

Using curl

curl https://{subdomain}.simplekpi.com/api/kpientries/{id}
          -H "Content-Type: application/json" 
          -d '{"user_id": 1234, "kpi_id": 5678, "entry_date": "2012-06-25", "actual": 50.0000, 
               "target": 110.0000, "notes": "This is a note"}'
          -v -u {email_address}:{token} -X PUT

Example Response

Status: 200 OK
        {
          "id":         12345,
          "user_id":    1234,
          "kpi_id":     5678,
          "entry_date": "2012-06-25",
          "actual":     50.0000,
          "target":     110.0000,
          "notes":      "This is a note",
          "created_at": "2012-11-30T11:20:00",
          "updated_at": "2013-02-15T16:01:00"
        }

Delete a KPI entry

DELETE /api/kpientries/{id}

Using curl

curl https://{subdomain}.simplekpi.com/api/kpientries/{id}
          -v -u {email_address}:{token}

Example Response

Status: 200 OK