Use API to create, update, and delete Impact Values
Impact Values are additional classifications within an Impact Type. For example, your organization might have a Time Savings Impact. Within that Impact, there could be Engineer Time Savings, IT Time Savings, and more. These additional variations are Impact Values.
Organizations can have many different Impacts with a variety of Impact Values. These Impact Values contain important information about how much currency each unit is worth, which Locations it applies to and more. These details can be difficult to manage if you have a lot of Impact Values.
Example of an Impact with three Impact Values in the Admin section of KaiNexus
JSON Impact Value API helps you automate the creation, upkeep, and removal of Impact Values to save maintenance time.
Pro Tip: If you are unfamiliar with KaiNexus API, then we recommend learning more about our API capabilities in this article.
What can Impact Value API do?
Export
Use Impact Value API to export a list of your organization's Impact Values in JSON format. Exporting is useful when you want to:
- Reference the correct JSON format before creating or updating Impact Values.
- Transfer Impact Value information to another application.
Update
Use Impact Value API to update your organization's Impact Values. This includes changing Impact Value information such as description, rate, currency, Location, and more.
Create
Use Impact Value API to create new Impact Values for your organization.
Warning: You cannot create new Impacts through API. There must be an existing Impact in KaiNexus to create new Impact Values.
How does it work?
KaiNexus provides an endpoint where you can access Impact Value 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.
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 and the API Key as the password.
Exporting Impact Values
After authentication, you can make your first Impact Value API call. We recommend starting with a GET request to retrieve a list of Impact Values in JSON format. This will be useful as a reference of the correct JSON format when updating or creating Impact Values.
Make the GET request to the following URL:
api.kainexus.com/api/public/v1/json/impactValueList
- This call will retrieve information for all Impact Values in your organization in JSON format.
Exporting specific Impact Values
If you rather export a specific Impact Value instead of all Impact Values in your organization, you must know the Impact Value's ID.
The easiest way to find the ID is by navigating to the Admin section in KaiNexus. Beneath the Organization header, there are Impact Categories for each of your organization's Impacts that support Impact Values. For example, if you want to update Time Savings People Impact Values, you would navigate to Admin > Organization > Time Savings People.
- Hover your mouse over a column header. A dropdown arrow will appear.
- Select the dropdown arrow
- Select Columns
- Select the checkbox next to ID to add an ID column to the list of Impact Values. You will now see the unique identifier for each Impact Value in the list.
When you have the ID, you can export a specific Impact Value in JSON format by executing a GET request to the following URL:
api.kainexus.com/api/public/v1/json/impactValue?id=XXX&impactValueType=TYPE
- Replace XXX with the Impact Value ID
- Replace TYPE with the Impact Category that corresponds to your Impact Value:
- Time Savings People = "PERSON"
- Products = "PRODUCT"
- Resources = "RESOURCE"
- Wastes = "WASTE"
- Environmental Impacts = "ENVIRONMENTAL_IMPACT"
- Cycle Time = "CYCLE_TIME"
- Lead Time = "LEAD_TIME"
- Takt Time = "TAKT_TIME"
Updating or Creating Impact Values
After you have exported an Impact Value in JSON format, you can use that code as a reference to update or create new Impact Values. To update or create a new Impact Value, execute a PUT request to the following URL:
api.kainexus.com/api/public/v1/json/ImpactValueList
The API will recognize if the Impact Value already exists or if a new one needs to be created.
- If an ID is provided in the body of your code, the existing Impact Value with that ID will be updated.
- If an Impact Value exists with the name and Impact Category specified in the body of your code, the Impact Value will be updated.
- If no ID is specified in the body of your code and no Impact Value exists with the specified name and Impact Category, a new Impact Value will be created.
Pro Tip: To delete an Impact Value, include "delete":true in the request.
Example JSON format
{
"item": {
"id": 33,
"type": "CYCLE_TIME",
"name": "Time-to-Market Time",
"description": "Length of time before product is available on the market.",
"rate": 40.0,
"parent": {
"id": 37,
"name": "Admin"
},
"locations": [
{
"id": 544,
"name": "Houston"
}
],
"hoursInDay": 24.0,
"daysInWeek": 7.0,
"weeksInYear": 52.14,
"currencyCode": "USD",
"folder": false,
"default": true
}
Here is a table explaining which KaiNexus element each Key:Value pair represents:
Key | Value |
id |
The Impact Value unique identifier |
type |
The Impact Category that the Impact Value belongs to |
name | The name of the Impact Value |
description | The tooltip that appears when users hover over the Impact Value |
rate | The currency amount one unit of the Impact Value is worth |
parent | The name of the folder the Impact Value is in |
locations | The Network Locations the Impact Value is assigned to |
hoursInDay | Hours per day amount used for soft savings calculation in Advanced Impact Value settings |
daysInWeek | Days per week amount used for soft savings calculation in Advanced Impact Value settings |
weekInYear | Weeks in year amount used for soft savings calculation in Advanced Impact Value settings |
currencyCode | The currency the Impact Value is recorded in |
folder | True/False status of whether the Impact Value is a folder |
default | True/False status of checkbox that determines whether this Impact Value is the default |