JSON Item Update API

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
```

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: 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.

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), authors (required if not P), leaders (optional), sponsors (optional), participants (optional), followers (optional)	createDate (optional), lastUpdateDate (optional), reviewDate (optional), reviewedOnDate (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), lastUpdateDate (optional), reviewDate (optional), reviewedOnDate (optional), startDate (required if Responsible exists), assignDate (required if responsible exists), dueDate (required if startDate exists and is not project/chart)
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), lastUpdateDate (optional), reviewDate (optional), reviewedOnDate (optional), assignDate (required if not P/C), startDate (required), dueDate (required), resolutionSubmitDate (required)
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), lastUpdateDate (optional), reviewDate (optional), reviewedOnDate (optional), assignDate (required if not P/C), resolutionSubmitDate (required if res enabled), dueDate (required), completeDate (required)
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: 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.