API Overview
Usecases
Cheatsheet

Getting Started

Create Account

First thing you need to do is create, verify and log in to your account via GraphQL playground:


mutation CREATE_ACCOUNT {
account {
register(
input: {
firstname: "admin"
lastname: "admin"
email: "admin@company.com"
password: "admin"
}
) {
activationLink
}
}
}

You should receive an email with verification code. Use this code in following mutation:

mutation VERIFY_ACCOUNT {
account {
verifyAccount(email: "admin@company.com", pincode: "123456") {
success
}
}
}


After that you can log in and start using Dimension Four:

mutation LOG_IN {
account {
login(
input: {
service: Password
params: { email: "admin@company.com", password: "admin" }
}
) {
id
}
}
}

Set up new tenant and connect to APIs

You need to setup new tenant in order to use Dimension Four and setup your devices and system structure. You can have multiple tenants but each system should use exactly one tenant.

Run following mutation to create tenant:

mutation CREATE_TENANT {
tenant {
create(input: { name: "Company Name", planPriceId: BASIC_FREE }) {
id
name
normalizedName
settings {
mqtt {
url
username
password
}
}
}
}
}

You will receive normalizedName and MQTT settings in a response. You will use these values in following operations and you can also query these values any time later.

Every tenant-specific GraphQL operation requires following HTTP header:

{ "x-tenant-id": "tenant-normalized-name" } // e.g. company-name

Create IoT system structure

You can start adding and organising devices once your tenant is ready. Every device is represented by Point entity in Dimension Four and you can organise devices/points by using Space entities. You can nest spaces and every point needs to be inside space.

For now, let’s register just one device in one space:

mutation CREATE_SPACE {
space {
create(input: { name: "All devices" }) {
id
name
normalizedName
}
}
}

and:

mutation CREATE_POINT {
point {
create(input: { spaceId: "all-devices", name: "Our device with sensors" }) {
id
}
}
}

Sending sensor data

Signals represents sensor data in Dimension Four. Every point can send multiple values with different units via GraphQL mutation or MQTT message.

GraphQL mutation:

mutation CREATE_SIGNALS {
signal {
create(
input: {
signals: [
{
name: "Name"
value: "123"
type: Temperature
unit: Celsius
timestamp: "2021-03-23T08:44:23.351000000+0000"
}
]
pointId: "607eca6ba3e82f4977b987be"
}
) {
success
}
}
}

Or MQTT topic:

POINT/PUSH

with payload:

{
"pointId":"607eca6ba3e82f4977b987be",
"tenantId":"company-name",
"tenantKey":"abcd123abcd123abcd123",
"signals":[
{
"value":"22.23",
"unit":"ºC",
"type":"Temperature",
"timestamp":"2017-07-12T12:53:27+00:00"
}
]
}

by using MQTT settings from CREATE_TENANT mutation and access token from following mutation:

mutation CREATE_ACCESS_TOKEN {
accessToken {
create(input: {name: "Data Insertion", scopes: [CREATE_SIGNAL]}) {
id
token
}
}
}

Displaying signals

It is possible to subscribe to realtime GraphQL subscription:

subscription SIGNAL_ADDED{
signalAdded(where: {pointId: "607eca6ba3e82f4977b987be"}) {
id
unit
type
data {
rawValue
numericValue
}
# ...
}
}


or query signals by some filters:

query SIGNALS_CONNECTION {
signalsConnection(
paginate: { last: 20 }
where: {
timestamp: { _LTE: "2020-10-09T15:23:21.000000000+0000" }
pointId: {_EQ: "607eca6ba3e82f4977b987be"}
}
) {
edges {
cursor
node {
id
unit
type
timestamp
data {
rawValue
}
# ...
}
}
}
}

That's not all!

Dimension Four supports many other features, e.g. check:

Ready to get started?