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 Chart Export API call will export the information, including data points, for an individual Chart or multiple Charts.
Customers often utilize Chart Export API to pull data from Charts in KaiNexus and enter it into a business analytics system.
If you're not interested in including your Charts' data in the export, you can use a regular JSON Item Export API instead. To learn about JSON Item Export APIs, check out this support article.
How does it work?
KaiNexus provides an endpoint where you can access Chart 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.
/Ofie/Ofie%20Profile%20Pic.png?width=50&height=50&name=Ofie%20Profile%20Pic.png)
Important: If your organization uses the EU server, replace the base URL shown in this support page’s examples with the EU server URL.
https://eu-prod.kainexus.com
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 necessary permission to "view" any Charts you want to export. For an API to be able to export all Charts in KaiNexus, the View, View New, and View Private 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.
Exporting Charts
After authentication, you can make your first JSON Chart Export API call.
To export an individual Chart and all its data in JSON format, execute a GET request to this URL:
https://api.kainexus.com/api/public/v1/json/item?id=XXXXX&includeCharts=TRUE
- The addition of “&includeCharts=TRUE” will cause the Chart's data to be included in your JSON export.
- Replace "xxxxx" with the Chart's ID.
- You can find a Chart's ID to the right of its title when looking at the Chart'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.
To export a specific Item List Card, including any Charts' data, in JSON format, execute a GET request to this URL:
https://api.kainexus.com/api/public/v1/json/itemList?id=XXXXX&includeCharts=TRUE
- The addition of “&includeCharts=TRUE” will cause the data of any Charts in the Card to be included in your JSON export.
- Replace "xxxxx" with the Item List Card's ID.
- You can find an Item List Card's ID by hovering over the Card's header. A tooltip will appear that shows the Card's ID.
- If the Card includes fewer than 30,000 Items, this call will retrieve a list of all its Items in JSON format.
- If the Card includes more than 30,000 Items, this call will retrieve a list of its first 30,000 Items.
If the Card includes more than 30,000 Items, and you want to export all its Items, reference the pagination information included in this article.
Helpful Tips
- All dates use ISO 8601 format. Example: "2019-04-29T16:30:40.000+0000"
- If a key's value is null, blank, or an empty array, it is generally omitted entirely from the JSON object.
Pagination
For Item and Chart Exports, two parameters can be specified to control paging:
- offset: The (zero-based) offset of the first Item in the collection to return. Offset is optional and defaults to 0.
- limit: The maximum number of Items to return. The limit is optional and defaults to 30,000, which is the maximum number of Items that can be exported in one call. It cannot exceed 30,000.
Example:
To retrieve the first 1000 Items in a List:
https://api.kainexus.com/api/public/v1/json/itemList?id=xxxxx&includeCharts=TRUE&offset=0&limit=1000
- Replace "xxxxx" with the Item List Card's ID.
To retrieve the second 1000 Items in a List:
https://api.kainexus.com/api/public/v1/json/itemList?id=xxxxx&includeCharts=TRUE&offset=1000&limit=1000
- Replace "xxxxx" with the Item List Card's ID.
To retrieve the third 1000 in a List:
https://api.kainexus.com/api/public/v1/json/itemList?id=xxxxx&includeCharts=TRUE&offset=2000&limit=1000
- Replace "xxxxx" with the Item List Card's ID.
What Chart data is included in the export?
When you export a Chart through the JSON Chart API, the export will include data for the Item and the Chart itself.
Reference this support page for which Item data is included in the export.
The following tables describes which Chart data is included in JSON Chart API exports:
General Chart Data
| Key | Description |
| id | The Chart's ID. Note that this is a different ID than the Chart Item. |
| useDate | The True/False status of whether the Chart uses dates instead of categories for data rows. |
| chartState | Included for Threshold, Control, and Bowling Charts. Indicates whether the Chart has met its Thresholds or Targets and whether it is in or out of control |
| chartType | Indicates whether the Chart is a Bar/Line, Threshold, Control, Bowling, or Pareto Chart. |
Data Series
This is the information included for each Data Series in the Chart.
| Key | Description |
| id | The Data Series' ID. |
| name | The name of the Data Series. |
| format | Indicates the formatting applied to the Data Series. |
| type | Indicates whether the Data Series is formatted as a Bar or Line or is a special type of Data Series, such as a Control Limit or Threshold. |
Data Points
This is the information included for each data point within a Series.
| Key | Description |
| id | The data point's ID. |
| value | The data point's numerical value. |
| date | The date the data point is associated with. Only contains a value if the Chart uses dates instead of categories. |
| category | The category the data point is associated with. Only contains a value if the Chart uses categories instead of dates. |
| annotations |
The Annotation added to the data point, including the Annotation's ID, the Annotation's text, and the Item ID if the Annotation links to another Item in the platform. |
Example: JSON format of an export Chart
{
"item": {
"templateId": 40,
"templateName": "Chart",
"id": 5067,
"summary": "Challenge Metric",
"link": "https://preview.kainexus.com/link/i/5067",
"chart": {
"id": 481,
"useDate": true,
"chartState": "BASELINE_MET",
"chartType": "THRESHOLD",
"series": [
{
"id": 1341,
"name": "Goal",
"format": "AUTOMATIC",
"type": "THRESHOLD_PRIMARY",
"dataPoints": [
{
"id": 26284,
"value": 100.0,
"date": "2020-12-07T05:00:00.000+0000",
"category": "",
"annotations": []
},
{
"id": 26288,
"value": 100.0,
"date": "2020-12-08T05:00:00.000+0000",
"category": "",
"annotations": []
},
{
"id": 26289,
"value": 100.0,
"date": "2020-12-09T05:00:00.000+0000",
"category": "",
"annotations": []
},
{
"id": 26286,
"value": 100.0,
"date": "2020-12-10T05:00:00.000+0000",
"category": "",
"annotations": []
},
{
"id": 26287,
"value": 100.0,
"date": "2020-12-11T05:00:00.000+0000",
"category": "",
"annotations": []
},
{
"id": 26285,
"value": 100.0,
"date": "2020-12-12T05:00:00.000+0000",
"category": "",
"annotations": []
},
{
"id": 60052,
"value": 100.0,
"date": "2020-12-13T05:00:00.000+0000",
"category": "",
"annotations": []
},
{
"id": 60053,
"value": 100.0,
"date": "2020-12-14T05:00:00.000+0000",
"category": "",
"annotations": []
},
{
"id": 60352,
"value": 100.0,
"date": "2020-12-15T05:00:00.000+0000",
"category": "",
"annotations": []
}
]
},
{
"id": 1340,
"name": "Goal -THRESHOLD_BASELINE-",
"format": "AUTOMATIC",
"type": "THRESHOLD_BASELINE",
"dataPoints": [
{
"id": 26280,
"value": 50.0,
"date": "2020-12-07T05:00:00.000+0000",
"category": "",
"annotations": []
},
{
"id": 26283,
"value": 50.0,
"date": "2020-12-08T05:00:00.000+0000",
"category": "",
"annotations": []
},
{
"id": 26279,
"value": 50.0,
"date": "2020-12-09T05:00:00.000+0000",
"category": "",
"annotations": []
},
{
"id": 26281,
"value": 50.0,
"date": "2020-12-10T05:00:00.000+0000",
"category": "",
"annotations": []
},
{
"id": 26282,
"value": 50.0,
"date": "2020-12-11T05:00:00.000+0000",
"category": "",
"annotations": []
},
{
"id": 26278,
"value": 50.0,
"date": "2020-12-12T05:00:00.000+0000",
"category": "",
"annotations": []
},
{
"id": 60055,
"value": 50.0,
"date": "2020-12-13T05:00:00.000+0000",
"category": "",
"annotations": []
},
{
"id": 60054,
"value": 50.0,
"date": "2020-12-14T05:00:00.000+0000",
"category": "",
"annotations": []
},
{
"id": 60353,
"value": 50.0,
"date": "2020-12-15T05:00:00.000+0000",
"category": "",
"annotations": []
}
]
},
{
"id": 1342,
"name": "Actual",
"format": "AUTOMATIC",
"type": "LINE",
"dataPoints": [
{
"id": 26295,
"value": 60.0,
"date": "2020-12-07T05:00:00.000+0000",
"category": "",
"annotations": []
},
{
"id": 26292,
"value": 70.0,
"date": "2020-12-08T05:00:00.000+0000",
"category": "",
"annotations": []
},
{
"id": 26294,
"value": 80.0,
"date": "2020-12-09T05:00:00.000+0000",
"category": "",
"annotations": []
},
{
"id": 26293,
"value": 90.0,
"date": "2020-12-10T05:00:00.000+0000",
"category": "",
"annotations": []
},
{
"id": 26290,
"value": 100.0,
"date": "2020-12-11T05:00:00.000+0000",
"category": "",
"annotations": []
},
{
"id": 26291,
"value": 110.0,
"date": "2020-12-12T05:00:00.000+0000",
"category": "",
"annotations": []
},
{
"id": 60057,
"value": 55.0,
"date": "2020-12-13T05:00:00.000+0000",
"category": "",
"annotations": []
},
{
"id": 60056,
"value": 26.0,
"date": "2020-12-14T05:00:00.000+0000",
"category": "",
"annotations": []
},
{
"id": 60354,
"value": 54.0,
"date": "2020-12-15T05:00:00.000+0000",
"category": "",
"annotations": []
}
]
}
]
},
"status": "NEW",
"chartType": "THRESHOLD",
"fields": [],
"attributes": [
{
"id": 3,
"name": "Strategic Initiative",
"values": [
{
"id": 25,
"name": "Mission and Culture"
}
]
}
],
"milestones": [
{
"id": 7,
"name": "Adjust",
"status": "NOT_READY"
}
],
"authors": [
{
"id": 26,
"username": "blake",
"firstName": "Blake",
"lastName": "Wheeler",
"email": ""
}
],
"followers": [
{
"id": 58,
"username": "abby",
"firstName": "Abby",
"lastName": "Lane",
"email": ""
}
],
"participatingLocations": [],
"originatingLocations": [],
"responsibleLocations": [
{
"id": 31
},
{
"id": 29
}
],
"createDate": "2020-07-08T16:46:59.000+0000",
"lastUpdateDate": "2023-06-06T21:12:45.000+0000",
"likeCount": 0,
"ackCount": 0,
"voteCount": 0,
"downstreamDependencies": [
{
"id": 5064
}
],
"private": false
}
}