JSON Attribute Value API

A JSON Attribute Value API can be used to create, update, and delete Attribute Values and Folders in KaiNexus.

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. 

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. 

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 or Folder, 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.

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: