Skip to content

Status create or update

In this tutorial, status entries are dynamically created or updated. The status key API is used here, because is intended to simplify integration for 'creat or update' cases.

Imagine the data source is a list of KPIs. For each KPI a status record should be maintained. The data source will update frequently and from time to time a new kpiId will appear:

[
  { "kpiId": 100, "kpiName": "Sales by Team 1", "kpiValue": 104000 },
  { "kpiId": 101, "kpiName": "Sales by Team 2", "kpiValue": 112000 },
  { "kpiId": 102, "kpiName": "Sold Bags", "kpiValue": 2420 },
  { "kpiId": 103, "kpiName": "Sold Shoes", "kpiValue": 2530 }
]

The resulting status entries created from that data should look like this:

Stativate create or update example

In this example we want to outline a logic that maintains status records based on that data structure.

To keep integration as simple as possible we created the status key API for this purpose, it allows you to:

  1. Use your own IDs
  2. Use a single endpoint to create or update

So let's walk through this step by step.

Info

Be sure to read the Getting Started guide to learn how to connect and authenticate against the API.

1. Build the status key

The concept of status keys is that the a status is made available by API using a client-side ID so that no mapping or saving of statusId is neccessary. As a first step we would define a logic that creates a unique status key for each status.

The status key for the first data source object

{ "kpiId": 100, "kpiName": "Sales by Team 1", "kpiValue": 104000 }

could become sales-kpi-status-100 (the seconds one sales-kpi-status-101 and so on).

2. Build the request body

The set a status endpoint we are going to use decides between doing a create or an update itself.

If the status key already exists the status will be updated otherwise a new one will be created. Therefore we just send the full status body with every request and let the Stativate API determine if create or update is right for that status key:

{
  "name": "Sales by Team 1",
  "type": "text",
  "value": "104K",
  "accessType": "private",
  "description": "Latest accumulated sales by team 1.",
  "colorNo": 3
}

Same-value updates

Sending the same value as before is also considered an update. See same-value updates

3. Build the URL and send the request

Based on the status key sales-kpi-status-100 from step 1 the URL to use the set a status endpoint for the first data source entry would look like this:

POST https://api.stativate.de/v1/status-keys/sales-kpi-status-100

Sending the request body from step 2 will create or update the status.

Running steps 1 to 3 for all entries in the data source will create or update each entry as a status.

That's it. If everything went well you successfully created or updated the status using the Stativate API.