The API Add-On provides the ability to download a list of KaiNexus records displayed one any Card on a Board into an .xls Excel file. Directions for configuring everything needed for an API call are below.
A Role must be configured to include the “API Administrator” permission. We suggest you create a new Role, which can then be assigned to any users who will be configuring the API Board or generating API Keys.
To create the Role in KaiNexus:
- Click “Admin” on the left navigation bar.
- Select “Roles” under the “Organization” heading.
- Click in the top right corner of the page.
- Give the Role a name - e.g. “API Admin.”
- Check the box next to “API Administrator” near the bottom of the window.
- Click .
The Role that was created during the previous step will now need to be granted to any users who will be managing the API lists or generating API keys. To do this, you will need to have the appropriate User Administrator permission.
To add the Role to a user:
- Click “People” on the left navigation bar
- Hover over the user to whom you would like to add the Role and click to the right.
- Click in the top right corner of the “Roles” section. Select your API Role in the resulting drop-down menu.
- Click .
NOTE: Any user granted this Role will have the ability to generate API keys with any permissions.
If you give a user a new Role such as the API Role, they will need to log out and back into the system before they will see the changes.
Board / Card Setup
The different lists of items the API can download depends on the configuration of Boards and their Cards. You can filter any Card to have it display only those items you would like to have downloaded when that list is called from the API.
Each Card has a unique identifying number that anyone with the API Administrator permission can access, which they can use in their call to the API to tell the system which list to download. When a particular list/card is called, all items that meet the requirements of the Card and which are accessible by the Locations and Roles associated with the entered API Key will be downloaded.
To get a Card’s ID number, make sure you have the API Administrator permission and then hover over the Card’s title. A tooltip will appear containing the Card’s full title and its ID number.
The ID number of the "SAFETY" Card in this example is 47.
We recommend creating a Board or Boards which are only accessible by the people who will be using the API Keys to keep the list of Boards from getting cluttered for other users, but that is up to you.
For more information on creating a new Board, check out this support page.
For more information on creating a new Card on an existing Board, check out this support page.
Generating API Keys
An API key will need to be generated before a call to the API can be made. An API key is much like a KaiNexus user, in that it will have Network Locations and Roles assigned to it.
As mentioned above, the Network Location and Role assigned to an API key will define what that key can access when it pulls data. If the key can’t access an item that meets the filter requirements of the list it’s downloading, that item will not be included.
For example, if a key is assigned a particular Network Location and the associated Role says it can only access items in that location, that particular key will only be able to pull data for that location.
NOTE: An API key is sensitive information and should be treated just like a password.
You can grant your IT team - or whoever is going to be using API - access to KaiNexus and let them generate their own API keys, or you can provide the API key to them.
You must have the API Administrator permission to continue!
First, if you haven’t logged out since being granted the API Role, sign out and back in. Otherwise, you will be unable to access the API Keys admin page.
To generate a new API key:
- Click “Admin” in the left navigation bar.
- Click “API Keys” under the “System” heading.
- Click in the top right corner of the page.
- You are required to enter a name for this key and assign it to at least one Network Location. You also have the option of granting any Roles you’d like. Again, the Locations and Roles determine what items a key can access.
- Click .
This will immediately be added to the list of existing API keys.
To retrieve the key itself:
- Locate the key you want on the list of API keys.
- Under the “API Key” column, you’ll see a list of symbols. This is not the key. Click that string of symbols and the true key will appear.
- Click and save the key somewhere secure for later.
Testing the API
You can test the API connection by calling it using the link below. Going to this URL will download the export file.
NOTE: You will need to replace “xxxxxx” at the end of the URL with target Card’s ID number. See the Board / Card Setup section above if you need a reminder on how to find this number.
When going to that URL, your browser will ask for a username and password.
- The username will always be “api”
- The password will be the API key you copied during the last step of the “API Generation” section above.
Generating API Calls
You can use whichever application you prefer to call the API; how you must configure the call will vary depending on the application you use.
A common application to make API calls is Curl. An example of a Curl script can be seen below. You will need to replace the red areas with the correct values.
curl -s -D - --user 'api:APIKEY' https://api.kainexus.com/api/public/v1/excel/ideaList?id=xxxxxx --output excel.xls
- APIKEY: The API Key generated in KaiNexus
- xxxxxx: The ID of the Card you generated under the “Adding Cards” section.
The call example above would download the specified list ID to excel.xls.
The output file name is customizable.
The script will print the http headers (including status code) to the console.
Here’s a console print example:
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Content-disposition: attachment; filename="KaiNexus-Export-xxxxxx-11132017-161233.xlsx"
The first line of the console print contains the Status Code (in bold). Important codes include;
- 200 (success, this is what you are looking for)
- 401 (authorization error... confirm your API key is correct)
- 400 (another type of error, view the response for more info, confirm the ID of the filter)