Powered by Temper

JSON Item Update API

KaiNexus 2.4.5 adds support for updating Items using JSON.

The JSON Item update can be used to change an Item's Summary, Attribute Values, and Field Values. Attributes and Fields must already exist on the Item's Template. Attribute Values must exist in your KaiNexus instance. The JSON Item update cannot be used to add new Items to KaiNexus.

 

To update a list of Items with JSON use the URL:

https://api.kainexus.com/api/public/v1/json/itemList

 

To update an individual Item use the URL:

https://api.kainexus.com/api/public/v1/json/item

 

Example Curl Script:

curl -s -D - --user api:APIKEY https://api.kainexus.com/api/public/v1/json/itemUpdate -d @FILEPATH -X PUT -H "Content-Type: application/json"

 See The API Module for more information on how to configure API keys.

 

Things to note:

  1. The item(s) being updated must be referenced by ID. Fields, Attributes, and Attribute Values can be referenced by name or ID.

  2. Person Attributes can be referenced by username or ID.

  3. Location Attributes can be referenced by name or ID.

  4. To update an Attribute that belongs on a Weighted Score, the name or ID of the Weighted Score must be provided. 

  5. A note can be included on Attribute Values that support notes.

  6. Fields require a key to their value dependent on the Field's type. 

    1. 'dateValue' for date fields.
    2. 'numericValue' for number fields.
    3. 'value' for text fields.

 

Example JSON format for a list of items:

{
"items": [
{
"summary": "JSON updated item",
"id": 3670,
"attributes": [
{
"id": 33677,
"values": [
{
"name": "On Track",
"note": "This is a note"
}
]
},
{
"name": "Impact",
"score": "Priority Score",
"values": [
{
"name": "High"
}
]
},
{
"name": "Location",
"values": [
{
"name": "Accounting"
},
{
"id": 1035
}
]
}
],
"fields": [
{
"id": "972",
"value": "See fishbone"
},
{
"name": "Analysis Date",
"dateValue": "2020-04-15T05:00:00.000+0000"
},
{
"name": "Analysis Time (Hours)",
"numericValue": 3
}
]
}
]
}

 

Example JSON format for an individual item:

{
"item": {
"summary": "JSON updated item",
"id": 3670,
"attributes": [],
"fields": []
}
}

 

Failed updates will return an error containing a code and message that can be reference below:

Error Code Explanation
UNKNOWN

If receiving an error of UNKNOWN, this could be due to one of the following:

  • A generic failure while validating or saving. You will need to check the error logs.
  • An error while saving a specific Item ID.
  • An error while searching for a Field Type, an Attribute Type, an Attribute Value, a Network Location, or a User.
NOT_FOUND  

If receiving an error of NOT_FOUND, this could be due to one of the following:

  • Could not find an Item by ID.
  • Something couldn't be matched while saving Item with ID. You will need to check the error logs.
  • An Attribute Type was not found in your KaiNexus instance.
  • An Attribute Type was not found on a Template in your KaiNexus instance.
  • A Weighted Score Group was not found in your KaiNexus instance.
  • An Attribute value was not found in your KaiNexus instance.
  • A Network Location was not found in your KaiNexus instance.
  • A User was not found in your KaiNexus instance.
  • A Field Type was not found in your KaiNexus instance.
NOT_VALID  

If receiving an error of NOT_VALID, this could be due to one of the following:

  • A Field Type value does not match (date, numeric, text)
  • If the Field is an Ad Hoc Field, Ad Hoc Fields are not supported.
EMPTY  

If receiving an error of EMPTY, this could be due to one of the following:

  • The Item entry has no ID. You most likely will need to add the Item ID.
  • The JSON is empty.
  • The Summary is blank. The Summary refers to the Title of the Item.
SIZE  

If receiving an error of SIZE, this could be due to one of the following:

  • There was an invalid size while saving Item by ID. You will need to check the error logs.
  • The Summary is over 150 characters.
  • There is more than one Attribute Value included for a single-select Attribute Type.
INVALID_CHANGE  

If receiving an error of INVALID_CHANGE, this could be due to one of the following:

  • There was an invalid change while saving Item with ID. You will need to check the error logs.
  • A Note was included with an Attribute Value that does not support Notes.
ACCESS_DENIED  

If receiving an error of ACCESS_DENIED, this could be due to one of the following:

  • The API User does not have permission to edit Item with ID.
  • There was some permission that was not met when saving Item with ID. You will need to check the error logs.

 

Have more questions? Submit a request