Write data to signals

All integration in Clarify can write time-series data into signals. Each signal represent the storage of a single time-series, and is uniquly identified by an input ID that is scoped to the integration. When we start insert data to Clarify, signals are created automatically for each input ID. We can also add meta-data to signals, allowing the data to make more sense.

Inserting data

With an integration and a set of credentials created, we are ready to start writing data to Clarify.

info

In our examples we will be using Basic Auth for examples using cURL and OAuth 2.0 credentials for the other ones. If you generated the wrong kind of credentials, just go back to the credentials step and generate a new set.

cURL

# BASIC_AUTH_USERNAME=<Username from Basic Auth credentials>
# BASIC_AUTH_PASSWORD=<Password from Basic Auth credentials>
# INTEGRATION_ID=${BASIC_AUTH_USERNAME}
curl -u ${BASIC_AUTH_USERNAME}:${BASIC_AUTH_PASSWORD} \
  --request POST \
  --url https://api.clarify.io/v1/rpc \
  --header 'Content-Type: application/json' \
  --header 'X-API-Version: 1.0' \
  --data \
  '
    {
      "jsonrpc" : "2.0",
      "method": "integration.Insert",
      "id": "1",
      "params": {
        "integration": "'${INTEGRATION_ID}'",
        "data":{
          "times" : ["2021-03-11T21:00:00Z", "2021-03-11T22:00:00Z"],
          "series": {
            "a": [1.0, 1.2],
            "b": [2.0, null]
          }
        }
      }
    }
  '

Python

from pyclarify.client import APIClient
from pyclarify.data import DataFrame
from datetime import datetime

client = APIClient(credentials=open("credentials.json"))

t1 = datetime.now()
t2 = t1 + datetime.timedelta(hours=1)
df = DataFrame(
    times=[t1, t2],
    series={
        "a":[1.0, 1.2],
        "b":[2.0, None],
    },
)

client.insert(df)

Go

package main

import (
    "context"
    "time"

    clarify "github.com/clarify/clarify-go"
    "github.com/clarify/clarify-go/data"
)

func main() {
    creds, err := clarify.CredentialsFromFile("credentials.json")
    if err != nil {
        panic(err)
    }

    ctx := context.Background()
    client := creds.Client(ctx)

    t1 := data.AsTimestamp(time.Now())
    t2 := t1.Add(data.Hour)
    df := data.Frame{
        "a": {t1: 1.0, t2: 1.2},
        "b": {t1: 2.0},
    }

    if _, err := client.Insert(df).Do(ctx); err != nil {
        panic(err)
    }
}

See reference docs for more details.

Adding meta-data

Adding meta-data to a signal makes it easier to understand what the signal contains. For example, if we are integrating data from OPC UA, we might want to create a signal for each tag and then label the signal with the address of the tag. To add meta-data through the API, we are going to use a method called integration.SaveSignal. It is recommended that we only write meta-dat on changes, or at least less often then we write data.

cURL

# BASIC_AUTH_USERNAME=<Username from Basic Auth credentials>
# BASIC_AUTH_PASSWORD=<Password from Basic Auth credentials>
# INTEGRATION_ID=${BASIC_AUTH_USERNAME}
curl -u ${BASIC_AUTH_USERNAME}:${BASIC_AUTH_PASSWORD} \
  --request POST \
  --url https://api.clarify.io/v1/rpc \
  --header 'content-type: application/json' \
  --header 'X-API-Version: 1.0' \
  --data \
  '
    {
      "jsonrpc": "2.0",
      "method": "integration.SaveSignals",
      "id": "1",
      "params": {
        "integration": "'${INTEGRATION_ID}'",
        "inputs": {
          "a" : {
            "name": "Signal A",
            "labels": {
              "data-source": ["<your data-source name>"],
              "location": ["<your location name>"]
            }
          }
        }
      }
    }
  '

Python

from pyclarify.client import APIClient
from pyclarify.data import DataFrame
from datetime import datetime

client = APIClient(credentials=open("credentials.json"))

a = SignalInfo(
   name="Signal A",
   labels={"data-source": ["<your data-source name>"], "location": ["<your location name>"]},
)
b = SignalInfo(
   name="Signal B",
   labels={"data-source": ["<your data-source name>"], "location": ["<your location name>"]},
)
params = {"inputs": {"a": a , "b":b}, "createOnly": False}

client.save_signals(params= params)

Go

package main

import (
    "context"

    clarify "github.com/clarify/clarify-go"
    "github.com/clarify/clarify-go/resource"
)

func main() {
    creds, err := clarify.CredentialsFromFile("credentials.json")
    if err != nil {
        panic(err)
    }

    ctx := context.Background()
    client := creds.Client(ctx)

    inputs := map[string]clarify.SignalSave{
        "a": {
            SignalAttributes: clarify.SignalAttributes{
                Name: "Signal A",
                Labels: resource.Labels{
                    "data-source": {"<your data-source name>"},
                    "location":    {"<your location name>"},
                },
            },
        },
        "b": {
            SignalAttributes: clarify.SignalAttributes{
                Name: "Signal B",
                Labels: resource.Labels{
                    "data-source": {"<your data-source name>"},
                    "location":    {"<your location name>"},
                },
            },
        },
    }
    if _, err := client.SaveSignals(inputs).Do(ctx); err != nil {
        panic(err)
    }
}

See reference docs for more details.

Seeing the results

We should now be able to see the signals we've added by navigating to the integration in the admin panel and opening its signals view.

To see the data that the signal contains we'll need to publish some items, so go ahead and head over to the next step.