A JSON Attribute Value API can be used to create, update, and delete Attribute Values and Folders in KaiNexus.
REQUIRED: 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.
Attribute Values are the various options a user sees when they click on an Attribute on an Item. Organizations have a wide variety of Attributes used on their Templates and may need to frequently update Attribute Values in the Administration section of KaiNexus. This can be a time-consuming process depending on the number and complexity of Attribute Values.
A JSON Attribute Value API call lets you create, update, and delete many Attribute Values and Folders simultaneously. This not only streamlines the process of updating Attribute Values in the system but also helps you update information in KaiNexus based on information from other systems.
How does it work?
KaiNexus provides an endpoint where you can access Attribute Value information. To make a call, you will need an API Key and an API tool.
Pro 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.
Make sure your API Key has been granted the Quality Administrator permission so that it can complete the Attribute Value API calls.
Exporting Attribute Values and Folders
After authentication, you can make your first JSON Attribute Value API call. We recommend starting with a GET request to retrieve a list of Attribute Values and Folders in proper JSON format. This will be useful as a reference for the correct JSON format when updating Attribute Values and Folders.
KaiNexus's Attribute Values Export API allows you to export:
- A list of all Attribute Values and Folders in the organization
- An individual Attribute Value or Folder
To export a list of all Attribute Values and Folders, make a GET request to this URL:
https://api.kainexus.com/api/public/v1/json/itemAttributeValueList
To export an individual Attribute Value and Folders, execute a GET request to this URL:
https://api.kainexus.com/api/public/v1/json/itemAttributeValue?id=XXXXX
- Replace XXXXX with the Attribute Value or Folder's ID.
- You can find an Attribute Value or Folder's ID by adding an ID column to the Attribute's administration page.
Importing and updating Attribute Values and Folders
After you have exported Attribute Values in JSON format, you can use that code as a reference to update or create new Attribute Values or Folders.
To update or create an individual Attribute Value or Folder, execute a PUT request to this URL:
https://api.kainexus.com/api/public/v1/json/itemAttributeValue
To update or create multiple Attribute Values or Folders, execute a PUT request to this URL:
https://api.kainexus.com/api/public/v1/json/itemAttributeValueList
The API will recognize whether the Attribute Values and Folders in your request already exist or if new Attribute Values or Folders need to be created.
- If an ID is provided, the existing Attribute Value with that ID will be updated.
- If an ID is not provided, but an Attribute Value exists that matches both the given name and Attribute Type, that Attribute Value will be updated.
- If no ID is specified and no matching Attribute Value exists, a new Attribute Value will be created.
You can not create a new Attribute Type — the Attribute itself, under which the Attribute Values are listed — through API or in KaiNexus yourself. For help creating new Attribute Types, reach out to your Customer Success Manager.
Deleting Attribute Values
To delete an Attribute Value, include "delete": true in the PUT request.
In the following example, the Attribute Value with the ID 1402 will be deleted.
{
"item": {
"id": 1402,
"delete": true
}
}
Example: Curl Script for exporting a list of Attribute Values and Folders
curl -s -D - --user api:APIKEY == -X GET https://api.kainexus.com/api/public/v1/json/itemAttributeValueList
- Replace APIKEY with the API Key generated in KaiNexus
Example: JSON format for importing a list of Attribute Values and Folders
In this example, the first item in the export is an Attribute Value and the second is a Folder.
{
"items": [
{
"id": 1402,
"name": "Safety",
"color": "242424",
"type": {
"id": 2,
"name": "Category"
},
"rank": 17.0,
"includeNote": false,
"requireNote": false,
"archived": false,
"locations": [],
"groups": [
{
"id": 6,
"name": "Group 1"
},
{
"id": 7,
"name": "Group 2"
},
{
"id": 8,
"name": "Group 3"
}
],
"folder": false
},
{
"id": 1074,
"name": "Metrics",
"description": "",
"glyphIcon": "fas fa-adjust",
"color": "ff6666",
"type": {
"id": 2,
"name": "Category"
},
"rank": 8.0,
"includeNote": false,
"requireNote": false,
"archived": false,
"locations": [],
"groups": [
{
"id": 8,
"name": "Group 3"
}
],
"folder": true
}
]
}
Example: JSON format for importing an individual Attribute Value or Folder
{
"item": {
"id": 1402,
"name": "Safety",
"color": "242424",
"type": {
"id": 2,
"name": "Category"
},
"rank": 17.0,
"includeNote": false,
"requireNote": false,
"archived": false,
"locations": [],
"groups": [
{
"id": 6,
"name": "Group 1"
},
{
"id": 7,
"name": "Group 2"
},
{
"id": 8,
"name": "Group 3"
}
],
"folder": false
}
}
An explanation of key-value pairs
Each Attribute Value and Folder's code segment will include key information, as described in the table below:
Key | Value |
id | The Attribute Value or Folder's ID in KaiNexus. |
name | The Attribute Value or Folder's name. |
description | The description that appears as a tooltip when users hover over the Attribute Value or Folder. |
glyphIcon | The icon associated with the Attribute Value or Folder. |
color | The hexcode for the color of the Attribute Value or Folder's icon. |
type id | The Attribute Value or Folder's Attribute Type's ID. |
type name | The Attribute Value or Folder's Attribute Type's name. |
rank | The order in which the Attribute Value or Folder appears within the list of Attribute Values in KaiNexus. |
includeNote | True/False status of the "Include Note" checkbox. |
requireNote | True/False status of the Require Note checkbox. If includeNote is False, requireNote will be False. |
archived | True/False status of the Attribute Value or Folder being archived. |
location id | The ID of the Network Location to which the Attribute Value or Folder is assigned. Empty brackets show the Attribute Value or Folder has not been assigned a Location. |
location name | The name of the Network Location to which the Attribute Value or Folder is assigned. Empty brackets show the Attribute Value or Folder has not been assigned a Location. |
group id | The ID of the Group to which the Attribute Value or Folder is assigned. Empty brackets show the Attribute Value or Folder has not been assigned a Group. |
group name | The name of the Group to which the Attribute Value or Folder is assigned. Empty brackets show the Attribute Value or Folder has not been assigned a Group. |
folder | True/False status of whether the item is a Folder |
parent | Name of the Folder the Attribute Value is nested under. If not present, the Attribute Value is not nested under a Folder. Folders can not be nested under other Folders. |