Update existing Items, including their names, statuses, Attribute values, and Field values.
PRO TIP: If you're looking for information on importing new Items into KaiNexus instead of updating existing ones, check out this article about the JSON Item Creation API instead.
Making Requests
Requests to KaiNexus Item API are sent to different variations of the following URL:
api.kainexus.com/api/public/v1/json/item
PUT requests to the URL allows you to update Items in KaiNexus.
Updating multiple Items
To update a List of Items with JSON, execute a PUT request to this URL:
https://api.kainexus.com/api/public/v1/json/itemList
Updating an individual Item
To update an individual Item with JSON, execute a PUT request to this URL:
https://api.kainexus.com/api/public/v1/json/item
Authentication
The username will be "api" and the password will be the API Key. See this article for information on obtaining the API Key.
If you are using Curl to make the API call, refer to the following Curl script example:
curl -s -D - --user api:APIKEY https://api.kainexus.com/api/public/v1/json/itemUpdate -d @FILEPATH
Things to note:
- By default, anyone who would be notified a new Item created within KaiNexus will also be notified about new Items made with the Item Creation API.
- To suppress these notifications for an Item included in your import, add the following line to that Item's code segment. This line must be added for each Item for which notification should be suppressed.
"suppressNotifications": true
- To suppress these notifications for an Item included in your import, add the following line to that Item's code segment. This line must be added for each Item for which notification should be suppressed.
- The Item(s) being updated must be referenced by ID.
- Fields, Attributes, and Attribute Values can be referenced by name or ID.
- Person Attributes can be referenced by username or ID.
- Location Attributes can be referenced by name or ID.
- To update an Attribute that belongs to a Weighted Score, the name or ID of the Weighted Score must be provided.
- A note can be included on Attribute Values that support notes.
- Fields require a key to their value. This key is dependent on the Field's type.
- 'dateValue' for date fields.
- 'numericValue' for number fields.
- '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:
|
NOT_FOUND |
If receiving an error of NOT_FOUND, this could be due to one of the following:
|
NOT_VALID |
If receiving an error of NOT_VALID, this could be due to one of the following:
|
EMPTY |
If receiving an error of EMPTY, this could be due to one of the following:
|
SIZE |
If receiving an error of SIZE, this could be due to one of the following:
|
INVALID_CHANGE |
If receiving an error of INVALID_CHANGE, this could be due to one of the following:
|
ACCESS_DENIED |
If receiving an error of ACCESS_DENIED, this could be due to one of the following:
|
The JSON Item update can be used to change existing Items' Status in KaiNexus.
Status Requirements
Status | User Fields | Date Fields |
DRAFT |
facilitators (required if P), |
createDate (optional), |
NEW | facilitators (required if P), authors (required if not P), leaders (optional), sponsors (optional), participants (optional), followers (optional) |
createDate (optional), lastUpdateDate (optional), reviewDate (optional), reviewedOnDate (optional) |
PLANNED | facilitators (required if P), authors (required if not P), responsible (optional), assigner (required if responsible present), leaders (optional), sponsors (optional), participants (optional), followers (optional) |
createDate (optional), |
ACTIVE | facilitators (required if P), authors (required if not P), responsible (required if not P/C), assigner (required if not P/C), leaders (optional), sponsors (optional), participants (optional), followers (optional) |
createDate (optional), lastUpdateDate (optional), reviewDate (optional), reviewedOnDate (optional), startDate (required), dueDate (required if not project/chart), assignDate (required if not P/C), |
RES_SUBMITTED | facilitators (required if P), authors (required if not P), responsible (required if not P/C), assigner (required if not P/C) , leaders (optional), sponsors (optional), participants (optional), followers (optional) |
createDate (optional), |
COMPLETE | facilitators (required if P), authors (required if not P), responsible (required if not P/C), assigner (required if not P/C), leaders (optional), sponsors (optional), participants (optional), followers (optional) |
createDate (optional), |
DEFERRED | facilitators (required if P), authors (required if not P), leaders (optional), sponsors (optional), participants (optional), followers (optional) |
createDate (optional), lastUpdateDate (optional), reviewDate (required) |
When changing status:
- Some status changes require the necessary team members and dates to be included.
- Existing items cannot transition back into Draft status.
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": [],
"responsibleLocations": [
{
"name": "Austin"
},
{
"name": "Corporate"
}
],
"originatingLocations": [
{
"name": "Austin"
},
{
"name": "Development"
}
]
}
}
Example new Item submission:
{
"templateName": "A3",
"summary": "API created A3",
"status": "NEW",
"createDate": "2020-07-08T05:00:00.000+0000",
"lastUpdateDate": "2020-07-08T05:00:00.000+0000",
"authors": [
{
"username": "greg"
},
{
"username": "abby"
}
]
}
Example Status change:
{
"id": 3670,
"summary": "JSON updated item",
"status": "ACTIVE",
"responsible": {
"username": "abby"
},
"assigner": {
"id": 4
},
"lastUpdateDate": "2020-07-08T05:00:00.000+0000",
"startDate": "2020-07-08T05:00:00.000+0000",
"assignDate": "2020-07-08T05:00:00.000+0000",
"dueDate": "2020-07-31T05:00:00.000+0000"
}
Example Comment submission:
{
"id": 3670,
"comments": [
{
"author": {
"username": "greg"
},
"comment": "This was submitted by api"
}
]
}
Example Resolution Update with Actual, Target, Forecast, and Investment:
{
"item": {
"id": 12345,
"resolutionActual": {
"result": "CHANGE",
"impacts": [
{
"typeName": "Satisfaction",
"comment": "",
"pastCount": 10,
"pastUnit": "DAY",
"futureCount": 5,
"futureUnit": "DAY",
"decreasedChance": "YES",
"classification": "SIGNIFICANT"
},
{
"typeName": "Time Savings",
"comment": "Math",
"valueType": "RECURRING",
"amount": 5.0,
"amountTimeUnit": "HOUR",
"currencyCode": "USD",
"recurringInterval": "DAY",
"personProductServiceResource": "Engineer",
"numberOfPeople": 4.0
},
{
"typeName": "Revenue Generation",
"title": "Revenue Generation",
"comment": "Math",
"valueType": "RANGE",
"amount": 150.0,
"currencyCode": "USD",
"rangeStart": "2020-01-15T06:00:00.000+0000",
"rangeEnd": "2020-10-15T05:00:00.000+0000"
},
{
"typeName": "Quality Improvement"
},
{
"typeId": 3,
"typeName": "Satisfaction - Customer",
"locations": [
{
"id": 3,
"name": "Development"
},
{
"id": 1,
"name": "Executive"
}
],
"attributes": [
{
"id": 2,
"name": "Category",
"values": [
{
"id": 3629,
"name": "General Process"
}
]
}
]
},
{
"typeName": "Takt",
"comment": "Math",
"valueType": "ONE_TIME",
"amount": 5.0,
"amountTimeUnit": "HOUR",
"locations": [
{
"id": 1,
"name": "Executive"
}
]
},
{
"typeName": "Cost Savings",
"title": "Cost Savings",
"comment": "Math",
"valueType": "CUSTOM",
"currencyCode": "USD",
"monthlyValues": [
{
"year": 2020,
"month": 3,
"value": 200.0
},
{
"year": 2020,
"month": 1,
"value": 100.0
},
{
"year": 2020,
"month": 2,
"value": 500.0
},
{
"year": 2020,
"month": 4,
"value": 200.0
}
]
}
],
"investments": [
{
"typeId": 1469,
"typeName": "Financial",
"id": 253691,
"title": "Financial",
"comment": "Math",
"valueType": "ONE_TIME",
"amount": 1000.0,
"currencyCode": "USD",
"realizedDate": "2020-07-17T05:00:00.000+0000"
}
]
},
"resolutionTarget": {
"investments": [
{
"typeId": 1469,
"typeName": "Financial",
"id": 253697,
"title": "Cost Savings",
"comment": "Math",
"valueType": "RECURRING",
"amount": 1000.0,
"currencyCode": "USD",
"recurringInterval": "WEEK",
"realizedDate": "2020-07-17T18:32:01.000+0000"
}
]
},
"resolutionForecast": {
"investments": [
{
"typeId": 1469,
"typeName": "Financial",
"id": 253696,
"title": "Cost Savings",
"comment": "Math",
"valueType": "ONE_TIME",
"amount": 10000.0,
"currencyCode": "USD",
"realizedDate": "2020-07-17T18:31:52.000+0000",
"monthlyValues": [
{
"year": 2020,
"month": 7,
"value": 10000.0
}
]
}
]
}
}
}
Example Updating Milestones:
{
"item": {
"id": 12345,
"milestones": [
{
"name": "Committee Approval",
"status": "APPROVED",
"notes": "This looks great.",
"lastUpdatedBy": {
"username": "user12456"
}
},
{
"name": "Finance Approval",
"status": "NOT_APPROVED",
"notes": "We need a little more information.",
"lastUpdatedBy": {
"username": "user12456"
}
}
]
}
}
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:
|
NOT_FOUND |
If receiving an error of NOT_FOUND, this could be due to one of the following:
|
NOT_VALID |
If receiving an error of NOT_VALID, this could be due to one of the following:
|
EMPTY |
If receiving an error of EMPTY, this could be due to one of the following:
|
SIZE |
If receiving an error of SIZE, this could be due to one of the following:
|
INVALID_CHANGE |
If receiving an error of INVALID_CHANGE, this could be due to one of the following:
|
ACCESS_DENIED |
If receiving an error of ACCESS_DENIED, this could be due to one of the following:
|