JSON Item Update API

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

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.

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. 

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. 

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.

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. 

 

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: