Groups / Group Items

Group items belong to groups and form part of the user grouping or company hierarchy. Possible group item examples for group 'Countries' might be United Kingdom, Australia, Brazil etc.
Group items are added to a group and can then be assigned to a user. The group items are then used as part of user access rights and to determine how the user's KPI entries are grouped for analytics and reporting purposes.

Group Item Object

The object has the following properties:

NameTypeIs Read OnlyIs MandatoryMax LengthNotes
id integer yes no   Automatically assigned when creating a group item
group_id integer (16 bit) no yes   The id of the group the item belongs in
name string no yes 100 The name of the item
sort_order integer (16 bit) no yes   The display order of the item
created_at datetime yes no   The UTC date and time the item was created
updated_at datetime yes no   The UTC date and time of the last update of the item

JSON Example

{
  "id":         2263,
  "group_id":   1,
  "name":       "Sales",
  "sort_order": 1,
  "created_at": "2011-11-20T10:40:00",
  "updated_at": "2012-11-30T11:40:00"
}

XML Example

<GroupItem xmlns="http://schemas.datacontract.org/2004/07/SimpleKPI.Application.Areas.Api.Models" 
           xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <id>2263</id>
  <group_id>1</group_id>
  <name>Sales</name>
  <sort_order>1</sort_order>
  <created_at>2012-11-30T10:41:00</created_at>
  <updated_at>2012-11-30T10:41:00</updated_at>
</GroupItem>

 

Get all Group items

GET /api/groups/{group_id}/items

Using curl

curl https://{subdomain}.simplekpi.com/api/groups/{group_id}/items 
  -v -u {email_address}:{token}

Example Response

Status: 200 OK
[
  {
"id": 2263, "group_id": 1, "name": "Sales", "sort_order": 1, "created_at": "2012-11-30T10:41:00", "updated_at": "2012-11-30T10:41:00" }, { "id": 2264, "group_id": 1, "name": "Human Resources", "sort_order": 2, "created_at": "2012-11-30T10:41:00", "updated_at": "2012-11-30T10:41:00" } ]

 

Get a Group Item

GET /api/groups/{group_id}/items/{id}

Using curl

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

Example Response

Status: 200 OK
{
  "id":         2263,
  "group_id":   1,
  "name":       "Sales",
  "sort_order": 1,
  "created_at": "2011-11-20T10:40:00",
  "updated_at": "2012-11-30T11:40:00"
}

 

Add a Group Item

POST /api/groups/{group_id}/items

Using curl

curl https://{subdomain}.simplekpi.com/api/groups/{group_id}/items
  -H "Content-Type: application/json" -d '{"name": "My Group item", "sort_order": 1}'
  -v -u {email_address}:{token} -X POST

Example Response

Status: 201 Created
Location: https://{subdomain}.simplekpi.com/api/groups/{group_id}/items/{id}
{
  "id":         2263,
  "group_id":   1,
  "name":       "Sales",
  "sort_order": 1,
  "created_at": "2011-11-20T10:40:00",
  "updated_at": "2012-11-30T11:40:00"
}

 

Update a Group Item

PUT /api/groups/{group_id}/items/{id}

Using curl

curl https://{subdomain}.simplekpi.com/api/groups/{group_id}/items/{id}
  -H "Content-Type: application/json" -d '{"name": "My Group Item", "sort_order": 1}'
  -v -u {email_address}:{token} -X PUT

Example Response

Status: 200 OK
{
  "id":         2263,
  "group_id":   1,
  "name":       "Sales",
  "sort_order": 1,
  "created_at": "2011-11-20T10:40:00",
  "updated_at": "2012-11-30T11:40:00"
}

 

Delete Group Item

DELETE /api/groups/{group_id}/items/{id}

Using curl

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

Example Response

Status: 200 OK