JSON Chart API

JSON Chart Export API

A JSON Chart Export API can be used to export Charts from KaiNexus.

Two Line OfieREQUIRED: 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.

Two Line OfieIf 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. 

Two Line OfiePRO 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.

Two Line OfieMake 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.

AAD28C14-B8C3-419D-868A-84DB319F7F92_1_201_a-jpeg

  • 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.

Two Line OfieIf 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. 

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
    }
}

Recommended Reading