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.

 

 

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:

  1. Some status changes require the necessary team members and dates to be included.
  2. 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.

 

Have more questions? Submit a request