integration.saveSignals

A resource save method that create or update signals using an input key that's unique in combination with an integration ID. If no signal with a given key exists for the integration, it's automatically created. The input is made available on each signal as a read-only attribute. An integration can only interact with it's own signals using this call.

Method parameters

Parameter	Properties	Description
integration Integration ID	required	The integration to save signals for.
signalsByInput map(Series key => Signal save view)	required	Map of input keys to signal meta-data.
createOnly bool	default=false	If set to true, skip update of for existing signals.

Result

The result contain a map that links each input key in the request to a signal save summary, which include a globally unique signal ID.

type: object

Field	Description
signalsByInput map(Series key => Save summary)	Save summary for signals mapped by signal ID.

Limits

Billing:

• Signals above the amount allowed by your selected plan, may be charged.

Example

cURL

The curl example uses Basic Auth for simplicity.

# 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.1' \
  --data '
{
  "jsonrpc": "2.0",
  "method": "integration.saveSignals",
  "id": "1",
  "params": {
    "integration": "'${INTEGRATION_ID}'",
    "signalsByInput": {
      "banana-stand/amount": {
        "annotations": {
          "docs-clarify-io/example/name": "save_signals",
        },
        "name": "Amount",
        "description": "Amount at location, counted manually.",
        "labels": {
          "data-source": ["manual"],
          "location": ["banana stand", "pier"]
        },
        "engUnit": "USD"
      },
      "banana-stand/status": {
        "annotations": {
          "docs-clarify-io/example/name":    "save_signals",
          "docs-clarify-io/example/publish": "true"
        },
        "name": "Building status",
        "description": "Overall building status, aggregated from environmental sensors."
        "labels": {
          "data-source": ["manual"],
          "location": ["banana stand", "pier"]
        },
        "sourceType": "aggregation"
        "valueType": "enum".
        "enumValues": {
          "0": "not on fire",
          "1": "on fire"
        },
        "sampleInterval": "PT15M",
        "gapDetection": "PT2H"
      }
    }
  }
}'

Python

from pyclarify import Client, Signal

signal_amount = Signal(
    annotations={"annotations.docs-clarify-io/example/name": "save_signals"},
    name="Amount",
    description="Amount at location, counted manually.",
    labels={
      "data-source": ["manual"],
      "location": ["banana stand", "pier"],
    },
    engUnit="USD"
)

signal_status = Signal(
    annotations={
        "annotations.docs-clarify-io/example/name": "save_signals",
        "annotations.docs-clarify-io/example/publish": "true"
    },
    name="Building status",
    description="Overall building status, aggregated from environmental sensors.",
    labels={
        "data-source": ["environmental sensors"],
        "location":    ["banana stand", "pier"],
    },
    sourceType="aggregation",
    valueType="enum"
    enumValues={
        "0" : "not on fire",
        "1" : "on fire",
    }
    sampleInterval="PT15M"
    gapDetection="PT2H"
)

input_dict = {
    "input_id_amount": signal_amount,
    "input_id_status": signal_status
}

client.save_signals(signals_by_input=input_dict)

Go

package main

import (
	"context"
	"encoding/json"
	"os"
	"time"

	clarify "github.com/clarify/clarify-go"
	"github.com/clarify/clarify-go/fields"
	"github.com/clarify/clarify-go/views"
)

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

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

	inputs := map[string]views.SignalSave{
		"banana-stand/amount": {
			MetaSave: views.MetaSave{
				Annotations: fields.Annotations{
					// Annotation keys should be prefixed to avoid collision.
					"annotations.docs-clarify-io/example/name": "save_signals",
				},
			},
			SignalSaveAttributes: views.SignalSaveAttributes{
				Name:        "Amount",
				Description: "Amount at location, counted manually.",
				Labels: fields.Labels{
					// Label keys generally does not need to be prefixed.
					"data-source": {"manual"},
					"location":    {"banana stand", "pier"},
				},
				EngUnit: "USD",
			},
		},
		"banana-stand/status": {
			MetaSave: views.MetaSave{
				Annotations: fields.Annotations{
					// Annotation keys should be prefixed to avoid collision.
					"annotations.docs-clarify-io/example/name":    "save_signals",
					"annotations.docs-clarify-io/example/publish": "true",
				},
			},
			SignalSaveAttributes: views.SignalSaveAttributes{
				Name:        "Building status",
				Description: "Overall building status, aggregated from environmental sensors.",
				Labels: fields.Labels{
					// Label keys generally does not need to be prefixed.
					"data-source": {"environmental sensors"},
					"location":    {"banana stand", "pier"},
				},
				SourceType: views.Aggregation,
				ValueType:  views.Enum,
				EnumValues: fields.EnumValues{
					0: "not on fire",
					1: "on fire",
				},
				SampleInterval: fields.AsFixedDuration(15 * time.Minute),
				GapDetection:   fields.AsFixedDuration(2 * time.Hour),
			},
		},
	}
	result, err := client.SaveSignals(inputs).Do(ctx)
	if err != nil {
		panic(err)
	}
	enc := json.NewEncoder(os.Stdout)
	enc.SetIndent("", "  ")
	enc.Encode(result)
}