JSON Item API

JSON Item Update API

A JSON Item Update API can be used to update Items in KaiNexus.

Two Line OfieREQUIRED: Your organization must have the API Module enabled to perform the actions mentioned in this article. Reach out to your Customer Success Manager if you're interested in this module.


A JSON Item Update API call lets you update the information for many Items simultaneously. This not only streamlines the process of updating Items in the system but also helps you update information in KaiNexus based on information from other systems. 

Customers use an Item Update API when they are updating Items to and from their IT systems. Much of their work involves bringing in their IT team, so communicating updates to and from their IT ticketing system is vital.

Two Line OfieIf you're looking for information on updating Charts in KaiNexus, check out this article about the JSON Chart Update API

How does it work? 

KaiNexus provides an endpoint where you can access Item information. To make a call, you will need an API Key and an API tool. 

Ofie Profile PicPro Tip: We recommend using Postman for your API calls. It's easy to use and works well with KaiNexus API. 

Authentication

API Keys are used for authenticating calls to KaiNexus API. Check out this article for instructions on how you can find your organization's API Keys and copy them to your clipboard. 

If you are using Postman, select Basic Auth as the Authorization Type.

  • Enter "api" as the username.
  • Enter the API Key as the password. 

Two Line OfieMake sure your API Key has been granted the necessary permission to "view" and edit any Items you want to update. For an API to be able to edit all Items in KaiNexus, the View, View New, View Private, and Edit permissions need to be granted and set to "Everywhere" for all Workflows. Check out this support article for more information on each of these permissions.

Updating Items 

After authentication, you can make your first JSON Item Update API call. We recommend starting with a GET request to retrieve a list of Items in proper JSON format. This will be useful as a reference for the correct JSON format when updating Items. 

To update an individual Item, make a PUT request to this URL: 

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


To update multiple Items, make a PUT request to this URL:

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


If an ID is provided, the existing Item with that ID will be updated. If no ID is provided, a new Item will be created if all required information is provided.

Two Line OfieTo learn about creating new Items with a JSON Item Creation API, check out this support article. To learn about updating existing Charts with a JSON Chart Update API, check out this support article instead.

Helpful Tips

  • By default, anyone who would be notified of updates made to an Item within KaiNexus will also be notified about changes made to the Item with the Item Update API.
    • To suppress these notifications for an Item included in your import, add the following line to that Item's code segment.
      "suppressNotifications": true
      This line must be added for each Item for which notification should be suppressed.
  • The Item(s) being updated must be referenced by ID. 
    • You can find an Item's ID to the right of its title when looking at the Item's work panel — unless it has been hidden by the Template's configuration — or by adding an ID column to an Item List in List, Tree, or Gantt View.
  • Fields, Attributes, and Attribute Values 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.
    • If you are updating a conditional Attribute (i.e. an Attribute that only appears on the Item when certain conditions are met) you must include all Attributes involved in the conditional logic in your request. 
    • Fields require a key to their value dependent on the Field's type.
      • 'dateValue' for date fields.
      • 'numericValue' for number fields.
      • 'value' for text fields.
  • Milestone Approver system Roles will be taken into account when using an API Key. Meaning, if your API Key does not have the same Role(s) as the one(s) listed as the only acceptable Approver(s) then this could result in a permissions error. 
  • Item Dates utilize ISO 8601 format. Example: "2019-04-29T16:30:40.000+0000"
  • The KaiNexus API enforces rate limits to ensure system stability. We recommend limiting your rate of API calls to no more than 5 calls per minute. However, there is no rate limit if you are updating one Item at a time. 

Updating Item Statuses

The JSON Item Update API can be used to change an existing Item's Status in KaiNexus.

You can define an Item's Status using one of the following two fields: "status" or "customStatus". 

  • "status" refers to the Status Type, which describes the general behavior of the Status and can have one of the following values: DRAFT, NEW, PLANNED, ACTIVE, RES_SUBMITTED, COMPLETE, or DEFERRED. When you update an Item's Status by defining the Status Type, the Item will default to the primary Status of that Status Type. We suggest only using this method when your organization does not have multiple Statuses with the same Status Type. 
  • "customStatus" refers to a unique Item Status. It is the Status name that appears the KaiNexus platform and can be customized by your organization. We recommend defining an Item's Status using this field because it refers to a specific Status rather than Status Type. 
  • The API will first reference the "customStatus" field while determining an Item's Status. If this field is null, it will fall back to the "status" field. 

Depending on an Item's Status, certain fields are required. The following table defines the user and date fields that are required for each Status Type. These are the default requirements. Your organization/template's configuration may vary. 

Ofie Profile PicPro Tip: All Item Statuses have a Status Type. If you don't know a Status's type, we recommending exporting an Item currently in that Status to view the Status Type, which is identified by the "status" field. 

Status User Fields Date Fields
DRAFT
  • facilitators: Required if Item is an Advanced Team Type
  • authors: Required if Item is not an Advanced Team Type or if the Advanced Team Type Template has been configured to include Authors
 
NEW
  • facilitators: Required if Item is an Advanced Team Type
  • authors: Required if Item is not an Advanced Team Type or if the Advanced Team Type Template has been configured to include Authors
 
PLANNED
  • facilitators: Required if Item is an Advanced Team Type
  • authors: Required if Item is not an Advanced Team Type or if the Advanced Team Type Template has been configured to include Authors
  • assigner: Required if responsible exists)
  • startDate: Required if responsible exists
  • assignDate: Required if responsible exists
  • dueDate: Required if startDate exists and the Item is not an Advanced or Author Only Team Type
ACTIVE
  • facilitators: Required if Item is an Advanced Team Type
  • authors: Required if Item is not an Advanced Team Type or if the Advanced Team Type Template has been configured to include Authors
  • responsible: Required if the Item is not an Advanced or Author Only Team Type
  • assigner: Required if responsible exists)
  • startDate: Required if responsible exists
  • assignDate: Required if responsible exists
  • dueDate: Required if startDate exists and the Item is not an Advanced or Author Only Team Type
RES_SUBMITTED
  • facilitators: Required if Item is an Advanced Team Type
  • authors: Required if Item is not an Advanced Team Type or if the Advanced Team Type Template has been configured to include Authors
  • responsible: Required if the Item is not an Advanced or Author Only Team Type
  • assigner: Required if responsible exists)
  • startDate: Required if responsible exists
  • assignDate: Required if responsible exists
  • dueDate: Required if startDate exists and the Item is not an Advanced or Author Only Team Type
  • resolutionSubmitDate: Required
COMPLETE
  • facilitators: Required if Item is an Advanced Team Type
  • authors: Required if Item is not an Advanced Team Type or if the Advanced Team Type Template has been configured to include Authors
  • responsible: Required if the Item is not an Advanced or Author Only Team Type
  • assigner: Required if responsible exists)
  • startDate: Required if responsible exists
  • assignDate: Required if responsible exists
  • dueDate: Required if startDate exists and the Item is not an Advanced or Author Only Team Type
  • completeDate: Required
DEFERRED
  • facilitators: Required if Item is an Advanced Team Type
  • authors: Required if Item is not an Advanced Team Type or if the Advanced Team Type Template has been configured to include Authors
  • reviewDate: Required

 

Two Line OfieNOTE: Existing Items can not be transitioned back into the Draft status.

Import Examples

Example: Curl Script for importing a list of Items

curl -s -D - --user api:APIKEY https://api.kainexus.com/api/public/v1/json/itemUpdate -d @FILEPATH
  • Replace APIKEY with the API Key generated in KaiNexus

  • The file must be UTF-8 encoded.

Example: JSON Format for importing a list of Items

{
    "items": [
         {
            "templateId": 170,
            "templateName": "Define",
           "id": 6141,
            "summary": "JSON API Example 1",
            "parentId": 6613,
            "status": "NEW",
            "fields": [
                {
                    "id": 1,
                    "name": "Description",
                    "value": "This is an example of a JSON import."
                }
            ],
            "attributes": [
            ],
            "milestones": [
                {
                    "id": 7,
                    "name": "Adjust",
                    "status": "APPROVED",
                    "notes": "This milestone was automatically Approved."
                },
                {
                    "id": 19,
                    "name": "Analyze",
                    "status": "APPROVED",
                    "notes": "This milestone was automatically Approved."
                }
            ],
            "authors": [
                {
                    "id": 4
                }
            ],
            "participatingLocations": [],
            "originatingLocations": [],
            "responsibleLocations": [
                {
                    "id": 5
                }
            ],
            "createDate": "2023-02-05T16:25:16.000+0000",
            "likeCount": 0,
            "ackCount": 0,
            "voteCount": 0,
            "private": false
        },
         {
            "templateId": 170,
            "templateName": "Define",
           "id": 6142,
            "summary": "JSON API Example 2",
            "parentId": 5213,
            "status": "PLANNED",
            "fields": [
                {
                    "id": 1,
                    "value": "This is an example of a JSON import."
                }
            ],
            "attributes": [
            ],
            "milestones": [
                {
                    "id": 7,
                    "name": "Adjust",
                    "status": "APPROVED",
                    "notes": "This milestone was automatically Approved."
                }
            ],
            "authors": [
                {
                    "id": 4
                }
            ],
            "participatingLocations": [],
            "originatingLocations": [],
            "responsibleLocations": [
                {
                    "id": 5
                }
            ],
            "createDate": "2023-02-05T16:25:16.000+0000",
            "likeCount": 0,
            "ackCount": 0,
            "voteCount": 0,
            "private": false
        }
    ]
}

Example: JSON format for importing an individual Item

{
    "item": {
        "templateId": 170,
        "templateName": "Define",
       "id": 6143,
        "summary": "JSON API Example 1",
        "parentId": 6613,
        "status": "NEW",
        "fields": [
            {
                "id": 1,
                "name": "Description",
                "value": "This is an example of a JSON import."
            }
        ],
        "attributes": [],
        "milestones": [
            {
                "id": 7,
                "name": "Adjust",
                "status": "APPROVED",
                "notes": "This milestone was automatically Approved."
            },
            {
                "id": 19,
                "name": "Analyze",
                "status": "APPROVED",
                "notes": "This milestone was automatically Approved."
            }
        ],
        "authors": [
            {
                "id": 4
            }
        ],
        "participatingLocations": [],
        "originatingLocations": [],
        "responsibleLocations": [
            {
                "id": 5
            }
        ],
        "createDate": "2023-02-05T16:25:16.000+0000",
        "likeCount": 0,
        "ackCount": 0,
        "voteCount": 0,
        "private": false
    }
}

Example: Comment submission

{
 "item": {
"id": 6144,  
"comments": [
    {
      "author": {
        "username": "greg"
      },
      "comment": "This was submitted via API"
    }
]
}
}

Example: Resolution Update with Actual, Target, Forecast, and Investment metrics

{
  "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"
        }
      }
    ]
  }
}

Error Codes

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

Error Code Explanation
UNKNOWN

An UNKNOWN error 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, Attribute Type,  Attribute Value, Network Location, or user.
NOT_FOUND  

A NOT_FOUND error could be due to one of the following: 

  • An Item could not be found by ID
  • Something — an Attribute, Field, Location, user, etc. — could not be found by ID or does not exist on this Template. You will need to check the error logs.
NOT_VALID  

A NOT_VALID error could be due to one of the following: 

  • A Field Type value does not match the expected format. E.g. a numeric value is required, but a date value was entered.
  • You attempted to import a value into an Ad Hoc field. Ad Hoc Fields are not supported.
EMPTY  An EMPTY error could be due to one of the following:
  • The JSON request is empty.
  • A required field is blank.
SIZE   A field exceeded its minimum or maximum size.
INVALID_CHANGE  

An INVALID_CHANGE error could be due to one of the following:

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

An ACCESS_DENIED error could be due to one of the following:

  • The API Key in use does not have permission to view and/or edit the Item.
  • Some other permission requirement was not met. E.g. you attempted to approve a Milestone that the API Key does not have permission to approve.

    You will need to check the error logs.