The API Module

Use the API Module to create, update, delete, and export data from KaiNexus into JSON and .XLSX format.

Trim OfiREQUIRED: Reach out to your Customer Success Manager to enable the API Module.

What is API?

An Application Programming Interface (API) is a software intermediary that allows two applications to talk to each other. This "talk" is called a "call". 

How can API help me?

The API Module connects KaiNexus to other integral areas of your business. Here are how some of our customers use API: 

  • A customer is planning to connect to a project management system for higher-capacity strategic projects. Any idea that needs advanced project management features gets exported, and when it's completed, the resolution will be updated in Kainexus.
  • A few customers are planning on updating items to/from maintenance systems. Some improvements involve the maintenance team and the API will help them communicate those changes to that team and make updates in KaiNexus when the maintenance tasks are finished.
  • A customer is planning a connection to update financial data from a capital planning system.
  • A customer is planning on updating items to and from their IT systems. Many of their improvements involve bringing in their IT team, so communicating updates to and from their IT ticketing system is vital.
  • A customer automatically exports all data from every software platform in their organization (including KaiNexus) into a business analytics system so they get a holistic view of all systems.
  • A few customers are automatically feeding chart data into KaiNexus via the API from some manufacturing intelligence systems. These metrics automatically update on team boards to help show team members their progress toward their goal.

Types of API calls

Item Export API

This call will return an Item or Item List upon export. 

Item Update API

This call will update an existing Item (or multiple Items) upon import.

Item Creation API

This call will create an Item or multiple Items. 

People API

This call can create, update, or inactivate Users in the system.

Network API

This call can create, update, or delete a Network Location in the system.

Multi Chart Update API

This call can update a single Chart (or multiple Charts) within the system.

Multi Chart Export API

This call can export a Chart (or multiple Charts) from within the system.

Role Setup

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:

  • Navigate to Admin > Organization > Roles
  • Select + Create Role in the top right corner of the page.
  • In the resulting window, give the Role a name - e.g. “API Admin.”
  • Check the box next to “API Administrator."
  • Click Save.

User Setup

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 the pencil icon.
  • Click the plus icon in the top right corner of the “Roles” section. Select your API Role in the resulting drop-down menu.
  • Click Save.

NOTE: Any user granted this Role will have the ability to generate API keys containing 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 depend 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 API Admins can use in their call to the API, telling 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.

 

API Generation

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.

 

  • In the resulting window, 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.

  • In the resulting window, 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.

https://api.kainexus.com/api/public/v1/excel/ideaList?id=xxxxxx

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

Where:

  • APIKEY: The API Key generated in KaiNexus

  • xxxxxx: The ID of the Card you generated under the “Adding Cards” section.

 

NOTE: The above example specifies credentials on the command line. Appropriate steps should be taken to secure the API key. (e.g. --netrc-file)

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:

HTTP/1.1 200

X-Content-Type-Options: nosniff

X-XSS-Protection: 1; mode=block

Cache-Control: no-cache, no-store, max-age=0, must-revalidate

Pragma: no-cache

Expires: 0

X-Frame-Options: DENY

X-Application-Context: application:dev:8080

Content-disposition: attachment; filename="KaiNexus-Export-xxxxxx-11132017-161233.xlsx"

Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

Transfer-Encoding: chunked

 

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)