Impact Value API

JSON Impact Value API

A JSON Impact Value API can be used to create, update, and delete Impact Values and Folders in KaiNexus.

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. Organizations can have many different Impacts with a variety of Impact Values containing important information about how much currency each unit is worth, which Locations it applies to, and more. Managing updates to these Impact Values can be a time-consuming process.

A JSON Impact Value API call lets you create, update, and delete many Impact Values simultaneously. This not only streamlines the process of updating Impact Values in the system but also helps you update information in KaiNexus based on information from other systems.  

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. 

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 Quality Administrator permission so that it can complete the Impact Value API calls.

Exporting Impact Values and Folders

After authentication, you can make your first JSON Impact Value API call. We recommend starting with a GET request to retrieve a list of Impact Values and Folders in proper JSON format. This will be useful as a reference for the correct JSON format when updating Impact Values and Folders. 

KaiNexus's Impact Values Export API allows you to export:

 

To export a list of all Impact Values and Folders, make a GET request to this URL:

https://api.kainexus.com/api/public/v1/json/impactValueList

     

    To export an individual Impact Value and Folders, execute a GET request to this URL:

    https://api.kainexus.com/api/public/v1/json/impactValue?id=XXXXX&impactValueType=TYPE
    • Replace XXXXX with the Impact Value or Folder's ID.
      • You can find an Impact Value or Folder's ID by adding an ID column to the Impact's administration page.

    The Time Savings People admin page with an arrow pointing to the ID column

    • Replace TYPE with the Impact Value or Folder's Impact Type. The appropriate Impact Type must be entered as follows:
      • 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

    Importing and updating Impact Values and Folders

    After you have exported Impact Values in JSON format, you can use that code as a reference to update or create new Impact Values or Folders.

    To update or create an individual Impact Value or Folder, execute a PUT request to this URL:

    https://api.kainexus.com/api/public/v1/json/impactValue


    To update or create multiple Impact Values or Folders, execute a PUT request to this URL:

    https://api.kainexus.com/api/public/v1/json/impactValueList


    The API will recognize whether the Impact Values and Folders in your request already exist or if new Impact Values or Folders need to be created.

    • If an ID is provided, the existing Impact Value with that ID will be updated.
    • If an ID is not provided, but an Impact Value exists that matches both the given name and Impact Type, that Impact Value will be updated.
    • If no ID is specified and no matching Impact Value exists, a new Impact Value will be created.

    Two Line OfieYou can not create new Impacts through API. An Impact Type must already exist in KaiNexus for Impact Values to be created under it.

    Deleting Impact Values

    To delete an Impact Value, include "delete": true in the PUT request.

    In the following example, the Impact Value with the ID 375 will be deleted.

    {
        "item": {
          "id": 375,
           "delete": true
        }
    }

     Example: Curl Script for exporting a list of Impact Values and Folders

    curl -s -D - --user api:APIKEY == -X GET https://api.kainexus.com/api/public/v1/json/impactValueList
    • Replace APIKEY with the API Key generated in KaiNexus

    Example: JSON format for importing a list of Impact Values and Folders

    In this example, the first item in the export is an Impact Value (of the Time Savings Person Impact Type) and the second is a Folder (of the Waste Impact Type).

     {
        "items": [
            {
                "id": 2,
                "type": "PERSON",
                "name": "Billing",
                "rate": 35.0,
                "locations": [
                    {
                        "id": 16,
                    }
                ],
              "hoursInDay": 8.0,
              "daysInWeek": 5.0,
                "weeksInYear": 52.1429,
                "currencyCode": "USD",
                "folder": false,
                "default": true
            },
                    {
                "id": 375,
                "type": "WASTE",
              "name": "Natural",
                "rate": 0.0,
                "locations": [
                    {
                        "id": 1,
                    }
                ],
                "folder": true,
                "default": false
            }
        ]
    }

    Example: JSON format for importing an individual Impact Value or Folder

     {
        "item": {
            "id": 358,
            "type": "ENVIRONMENTAL_IMPACT",
            "name": "CO2",
          "rate": 15.0,
            "locations": [],
            "hoursInDay": 24.0,
            "daysInWeek": 7.0,
            "weeksInYear": 52.1429,
            "currencyCode": "USD",
            "folder": false,
            "default": false
        }
    }

    An explanation of key-value pairs

    Each Impact Value and Folder's code segment will include key information, as described in the table below:

    Key Value

    id

    The Impact Value or Folder's ID in KaiNexus.

    type

    The Impact Type to which the Impact Value or Folder belongs.
    name The Impact Value or Folder's name.
    description The tooltip that appears when users hover over the Impact Value or Folder.
    rate The currency amount one unit of the Impact Value is worth. Folders' rates will always be 0.0.
    parent Name of the Folder the Impact Value is nested under. If not present, the Impact Value is not nested under a Folder. Folders can not be nested under other Folders.
    locations id The ID of the Network Location to which the Impact  Value or Folder is assigned. Empty brackets show the Impact Value or Folder has not been assigned a Location.
    locations name The name of the Network Location to which the Impact  Value or Folder is assigned. Empty brackets show the Impact Value or Folder has not been assigned a Location.
    hoursInDay The hours per day amount used for soft savings calculations for this Impact Value. Folders can not have a hoursInDay value.
    daysInWeek The days per week amount used for soft savings calculation for this Impact Value. Folders can not have a daysInWeek value.
    weekInYear The weeks in year amount used for soft savings calculation for this Impact Value. Folders can not have a weekInYear value.
    currencyCode The currency the Impact Value uses. Folders can not have a currencyCode value.
    folder True/False status of whether the item is a Folder.
    default True/False status of the "Default" checkbox on this Impact Value in KaiNexus.