A JSON Item Creation API can be used to import and create Items 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.
A JSON Item Creation API call lets you import and create new Items in KaiNexus. It is especially useful when you generate new work or ideas outside of KaiNexus and want to bring them into the system for tracking and reporting.
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/Ofie%20Profile%20Pic.png?width=50&height=50&name=Ofie%20Profile%20Pic.png)
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.
Creating New Items
After authentication, you can make your first JSON Item Creation 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 creating Items.
To create an individual Item, make a PUT request to this URL:
https://api.kainexus.com/api/public/v1/json/item
To create 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.
To learn about updating existing Items with a JSON Item Update 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 a new Item created within KaiNexus will also be notified about new Items made with the Item Creation 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.
- To suppress these notifications for an Item included in your import, add the following line to that Item's code segment.
- 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.
- 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.
- 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 create an Item by defining the Status Type, the new 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 the unique 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.
- Comments cannot be posted while creating an Item through API. You can only post new comments via API while updating an existing Item.
- 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 only creating one Item at a time.
Example: Curl Script for importing a list of Items
curl -s -D - --user api:APIKEY https://api.kainexus.com/api/public/v1/json/itemList -d @FILEPATH -X PUT -H "Content-Type: application/json"
- 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",
"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",
"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",
"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
}
}