Flows
Reference for IoT Logic flows: the flow and its node types, transitions, the inputs that write a whole graph, and the queries and mutations for flows.
This page describes IoT Logic flows: the graph of nodes and transitions that processes the messages of the devices in a flow, the queries that read flows and the attribute names of devices, and the mutations that create, update, and delete flows.
Queries
flow
Reads one flow. Returns null when your workspace has no flow with this ID, including a deleted flow.
flow(id: ID!): IotLogicFlowArguments
id
ID!
The flow to read.
Output types:
flows
Lists the flows of your workspace.
flows(
filter: IotLogicFlowFilter
first: Int
after: String
last: Int
before: String
orderBy: IotLogicFlowOrder = { field: TITLE, direction: ASC }
): IotLogicFlowConnection!Arguments
filter
IotLogicFlowFilter
Filtering options for the returned flows.
orderBy
IotLogicFlowOrder
The ordering options for the returned flows.
Input types:
Output types:
deviceFlowLinks
Lists which devices enter which flows in your workspace, with one link for each device in each data source. A device that is in no flow isn't listed. Use it before you delete devices: while a flow lists a device, deviceDelete returns IN_USE. See Finding the flows of a device.
Arguments
filter
IotLogicDeviceFlowLinkFilter
Filtering options for the returned links.
orderBy
IotLogicDeviceFlowLinkOrder
The ordering options for the returned links.
Input types:
Output types:
flowDebugValues
Reads the recent values of up to 10 devices of one flow, as the messages leave the flow. In each message, a value that the flow calculated for an attribute replaces the value from the device, and the value from the device stays where the flow calculated none. The result has one entry per device, in the order of deviceIds. A device that isn't in the flow, or that your roles don't let you read, is left out. A device of the flow with no values yet has empty maps. A disabled flow still returns the values recorded while it was enabled. Returns null when your workspace has no flow with this ID. See Checking what a flow calculated.
Arguments
flowId
ID!
The flow to read.
deviceIds
[ID!]!
The devices to read: at least 1 and at most 10 different IDs.
Output types:
deviceAttributes
Lists the attribute names of up to 1,000 devices: the names that each device reported, the names that flows calculated for it, and the names that flows declare. Check the names that your expressions read against this list. The query needs the read action on IoT Logic flows. The result has one entry for each device, in the order of deviceIds, and lists each device once. Devices that your roles don't let you read, or that aren't in your workspace, are left out. A device without names has an empty attributes list. See Find the attribute names of your devices.
Arguments
deviceIds
[ID!]!
The devices to read, at most 1,000 different IDs. An empty list returns an empty list.
flowId
ID
Optional. Only this flow adds its names: the names that it declares and the names that it calculated, to every device in deviceIds, whether a data source of the flow lists the device or not. Without it, every flow that lists the device in a data source adds its own names. Disabled flows count. A deleted flow, or a flow that isn't in your workspace, adds nothing. Reported names are listed either way.
Output types:
Mutations
flowCreate
Creates a flow, which starts disabled. If the graph breaks a validation rule, the mutation fails and returns every violation at once. See Flow validation errors.
Arguments
input
IotLogicFlowCreateInput!
The input fields for creating the flow.
Input types:
Output types:
flowUpdate
Updates a flow. If the flow after the update breaks a validation rule, the mutation fails, changes nothing, and returns every violation at once. See Flow validation errors.
Arguments
input
IotLogicFlowUpdateInput!
The input fields for updating the flow.
Input types:
Output types:
flowDelete
Deletes a flow and removes its devices from it. After the delete, the flow no longer keeps those devices from being deleted. A flow can always be deleted, even when its graph no longer passes validation.
Arguments
input
IotLogicFlowDeleteInput!
The input fields for deleting the flow.
Input types:
Output types:
Objects
IotLogicFlow
A graph of nodes and transitions that processes the messages of the devices attached to its data sources, and adds the attributes that it calculates.
Implements: Node, Titled, Versioned
id
ID!
A globally unique identifier. This ID is opaque and should not be parsed by clients.
version
Int!
The version number for optimistic locking. It increases by one with each update. flowUpdate and flowDelete require the current version, so a write fails if someone else changed the flow after you read it.
title
String!
The human-readable display name.
description
String
Notes about the flow. Printable ASCII and line feeds (\n).
isEnabled
Boolean!
Whether the flow processes the messages of its devices. A new flow is disabled.
deviceCount
Int!
The number of devices in the data sources of the flow that your roles let you read. A device in two data sources counts twice. In rare cases, a flow keeps a device that no longer exists, and the device still counts until the data source no longer lists it.
IotLogicFlowDebugValues
The recent values of one device. Both maps use the attribute name as the key, with the channel number if it has one, such as lls_level_0. Each attribute has at most 12 entries, newest first. Each entry is { "value": number | boolean | string | null, "messageTime": DateTime, "serverTime": DateTime }. messageTime is when the device created the message, and serverTime is when Navixy received it.
Integers larger than 2^53 − 1 or smaller than −(2^53 − 1), times, and byte arrays are returned as strings. Durations are returned in milliseconds. Attributes that hold arrays or objects aren't returned.
deviceId
ID!
The ID of the device.
allFields
JSON!
One entry per recent message of the device. A message without the attribute, or with an empty value for it, has an entry with value: null and the messageTime and serverTime of that message. In some older entries for a message without the attribute, serverTime has the same value as messageTime, because Navixy didn't record when those messages arrived. Newer messages of the device replace them as they arrive.
nonNullFields
JSON!
The recent values of the attribute that aren't null. They can be older than the messages in allFields, so this map isn't part of allFields. An attribute with no such value isn't in the map.
IotLogicDeviceAttributes
The attribute names of one device.
deviceId
ID!
The ID of the device.
attributes
Each name once, sorted by name and then by channel number, so analog_2 comes before analog_10.
IotLogicDeviceAttribute
One attribute name of a device. A name that the device reported stays in the list after the device stops sending it, for example after a sensor is removed. A name that a flow calculated stays only while the flow still declares it.
name
String!
The name with its channel number, such as lls_level_0. This is the form that expressions and attribute names in a flow use.
received
Boolean!
true when the device reported the attribute, or a flow calculated it for this device. A name of a flow that hasn't processed the device yet has false.
inFlow
Boolean!
true when a flow declares the attribute, in an Initiate Attribute node or as the expressionName of an IF/THEN Logic node.
IotLogicDeviceFlowLink
A device in a data source of a flow. The messages of the device enter the flow at this data source.
device
The device. null in rare cases, when the flow kept a device that no longer exists. The link stays until no data source of the flow lists the device.
deviceId
ID!
The ID of the device, also when device is null.
IotLogicFlowDataSourceNode
A Data Source node: the devices whose messages enter the flow at this node.
Implements: IotLogicFlowNode
id
ID!
The ID of the node. It is unique within the flow, and it stays the same when an update keeps the node.
name
String!
The name that the flow editor shows. At most 255 characters.
description
String
Notes about the node.
position
The coordinates where the flow editor draws the node. null for a node that has no stored position.
devices
[Device!]!
The devices whose messages enter the flow at this node and that your roles let you read, ordered by device ID. The list has no pagination. A device that no longer exists isn't in the list, so the list can be shorter than IotLogicFlow.deviceCount. If you only need the number of devices, read deviceCount, because it doesn't load the device records.
IotLogicFlowLogicNode
An IF/THEN Logic node: a message for which condition is true leaves by the THEN transitions, and every other message leaves by the ELSE transitions.
Implements: IotLogicFlowNode
id
ID!
The ID of the node. It is unique within the flow, and it stays the same when an update keeps the node.
name
String!
The name that the flow editor shows. At most 255 characters.
description
String
Notes about the node.
position
The coordinates where the flow editor draws the node. null for a node that has no stored position.
condition
String!
An expression in the Navixy IoT Logic Expression Language, calculated for each message.
expressionName
String
The attribute that stores the result of the check. null when the node only chooses the transition.
IotLogicFlowInitiateAttributesNode
An Initiate Attribute node: it calculates attributes and adds them to the message.
Implements: IotLogicFlowNode
id
ID!
The ID of the node. It is unique within the flow, and it stays the same when an update keeps the node.
name
String!
The name that the flow editor shows. At most 255 characters.
description
String
Notes about the node.
position
The coordinates where the flow editor draws the node. null for a node that has no stored position.
IotLogicFlowOutputEndpointNode
An Output Endpoint node: it ends a path and sends the message, with the attributes that the path calculated, to the Navixy platform.
Implements: IotLogicFlowNode
id
ID!
The ID of the node. It is unique within the flow, and it stays the same when an update keeps the node.
name
String!
The name that the flow editor shows. At most 255 characters.
description
String
Notes about the node.
position
The coordinates where the flow editor draws the node. null for a node that has no stored position.
IotLogicFlowActionNode
A Device Action node: it sends commands to devices when a message reaches it. The commands go to the device that sent the message, or to the target devices that the device mapping of the node names for that device. A message that answers a command doesn't trigger the node. See Device Action.
Implements: IotLogicFlowNode
id
ID!
The ID of the node. It is unique within the flow, and it stays the same when an update keeps the node.
name
String!
The name that the flow editor shows. At most 255 characters.
description
String
Notes about the node.
position
The coordinates where the flow editor draws the node. null for a node that has no stored position.
actions
The commands that the node sends, in the order of the last write. An empty list for a node without actions.
trackableNodeId
String
The name of the flow value that Navixy sets to 1 on each message that reaches the node and to 0 on every other message of the flow. null when the node has none.
deviceMapping
The mapping entries of the source devices that still exist and that your roles let you read. Each entry lists only the targets that still exist and that your roles let you read, and an entry with no such target is left out. So a mapping that you read and send back unchanged in an update always saves.
IotLogicSetOutputAction
Switches a digital output of the device on or off.
output
Int!
The number of the output, from 1 to 8.
enabled
Boolean!
true switches the output on, and false switches it off.
IotLogicRawCommandAction
A text command that Navixy sends to the device unchanged.
text
String!
The command text.
IotLogicDeviceMappingEntry
One entry of the device mapping of a Device Action node: messages of source send the actions of the node to each device in targets instead of to source.
IotLogicFlowWebhookNode
A Webhook node. For each message that reaches the node, Navixy sends body to url in an HTTP POST request. Navixy replaces placeholders in the body, such as {{device_id}}, with values of the message. See Webhook.
Implements: IotLogicFlowNode
id
ID!
The ID of the node. It is unique within the flow, and it stays the same when an update keeps the node.
name
String!
The name that the flow editor shows. At most 255 characters.
description
String
Notes about the node.
position
The coordinates where the flow editor draws the node. null for a node that has no stored position.
url
String!
The address that the node sends its request to.
headers
The HTTP headers that the node sends. Empty when the node has none.
body
String!
The body of the request, with its placeholders as you sent them.
trackableNodeId
String!
The name of the flow value that Navixy sets to 1 on each message that reaches the node and to 0 on every other message of the flow.
IotLogicFlowWebhookHeader
One HTTP header of a Webhook node. A read returns the header exactly as you sent it, including a secret such as an access token. Anyone whose roles let them read the flow can read the value.
key
String!
The name of the header.
value
String!
The value of the header, with the {{device_id}} placeholder as you sent it.
IotLogicFlowAttributeAssignment
One attribute that an Initiate Attribute node calculates.
name
String!
The name of the attribute.
expression
String!
An expression in the Navixy IoT Logic Expression Language, calculated for each message.
IotLogicFlowNodePosition
The coordinates where the flow editor draws a node.
x
Int!
The horizontal coordinate.
y
Int!
The vertical coordinate.
IotLogicFlowTransition
A directed connection between two nodes of the graph.
from
ID!
The ID of the node that the transition leaves.
to
ID!
The ID of the node that the transition enters.
type
The outcome that the transition follows: THEN or ELSE after a logic node, SIMPLE after every other node.
IotLogicFlowPayload
The flow as it was saved.
IotLogicFlowDeletePayload
The outcome of deleting a flow.
id
ID!
The ID of the deleted flow.
Inputs
IotLogicFlowFilter
Filtering options for flows. A flow must match every condition that you set.
titleContains
String
Only flows whose title contains this text. The match ignores letter case.
isEnabled
Boolean
Only enabled, or only disabled, flows.
deviceId
ID
Only flows that have this device in one of their data sources. No flows for a device that your roles don't let you read.
IotLogicFlowOrder
Ordering options for flows.
IotLogicDeviceFlowLinkFilter
Filtering options for device links. A link must match every condition that you set.
flowId
ID
Only the links of this flow.
deviceIds
[ID!]
Only the links of these devices, at most 1,000 IDs. An empty list returns no links. Leave the field out to list the links of every device.
IotLogicDeviceFlowLinkOrder
Ordering options for device links.
IotLogicFlowNodeInput
A node in a create or update request. key names the node inside this one request, and transitions refer to the node by its key. id is the ID of the stored node that this entry keeps. Leave out id for a new node.
Some fields below belong to one or two node types only, and the other types ignore them without an error. DATA_SOURCE uses deviceIds. LOGIC uses condition and expressionName. INITIATE_ATTRIBUTES uses attributes. ACTION uses actions, deviceMapping, and trackableNodeId. WEBHOOK uses url, headers, body, and trackableNodeId. OUTPUT_ENDPOINT nodes have no fields of their own.
key
String!
A name for the node, valid only inside this request. Each node in the request needs a different key.
id
ID
The ID of the stored node that this entry keeps. Leave it out for a new node.
name
String!
English letters, digits, underscores, dashes, and slashes, in words separated by spaces. At most 255 characters. No space at the start or end. Tabs and line breaks aren't accepted.
description
String
Printable ASCII and line feeds (\n), at most 4,000 characters. Spaces at the start and the end are kept.
deviceIds
[ID!]
DATA_SOURCE only. The devices whose messages enter the flow at this node. In an update, leave it out to keep the current devices, send [] to remove all of them, or send a list to replace them. null isn't accepted. [] and a new list change only the devices that your roles let you read, and the other devices stay attached. A new node without it has no devices. The data sources of a flow can have at most 25,000 devices together, and a device in two data sources counts twice. A device that your roles don't let you read fails with UNKNOWN_DEVICE, as a device that doesn't exist does. Validation counts every attached device, including the ones that you can't read, toward the limit and toward attribute conflicts.
condition
String
LOGIC only. The condition to check, in the Navixy IoT Logic Expression Language. Printable ASCII on one line, at most 480 characters.
expressionName
String
LOGIC only, optional. The attribute that stores the result of the check. Lowercase letters and digits in groups joined by single underscores, such as is_too_warm (^[a-z0-9]+(_[a-z0-9]+)*$). A final group of digits, such as _2, gives the channel number. At most 48 characters, not counting the channel number. Navixy reserves 12 names for the position of a device, such as position_latitude. See Initiate Attribute.
attributes
INITIATE_ATTRIBUTES only. The attributes that the node calculates. At most 50 per node, and at most 200 per flow, counting the expressionName of every logic node.
actions
ACTION only. The commands that the node sends, at most 10. Each action sets exactly one of setOutput or rawCommand. A node without actions saves and sends nothing. In an update, send the actions every time: a node without actions has none, so leaving the field out removes the stored actions.
trackableNodeId
String
Optional for ACTION, required for WEBHOOK. The name of a flow value that Navixy sets to 1 on each message that reaches the node and to 0 on every other message of the flow. The flow keeps the value in its history and doesn't send it to the Navixy platform. 1 means that the message reached the node, not that a command or a request succeeded. The name follows the rule of attribute names: lowercase letters and digits in groups joined by single underscores (^[a-z0-9]+(_[a-z0-9]+)*$), at most 48 characters, not counting a final channel number. Two Device Action or Webhook nodes of one flow can't have the same name, and a device of the flow can't report it. In an update, leaving the field out removes the stored name of a Device Action node. For a Device Action node, the flow editor fills it with action_ and 8 hexadecimal characters.
deviceMapping
ACTION only. Sends the actions to other devices: when a message of a source device reaches the node, the actions go to the target devices of its entry instead of to the source. A device without an entry receives its own commands. In an update, leave it out to keep the current mapping, send [] to remove it, or send a list to replace it. null isn't accepted. [] and a new list change only the entries and targets that your roles let you read, and the others stay. A new node without it has no mapping. At most 1,000 targets per node, counted across its entries. A source or a target can be any device of your workspace that your roles let you read, whether a data source of the flow lists it or not. A device that your roles don't let you read fails with UNKNOWN_DEVICE, as a device that doesn't exist does.
url
String
WEBHOOK only, required. The address that the node sends its request to. It starts with http:// or https:// in lowercase, has only printable ASCII characters, and is at most 255 characters long. The only placeholder that it accepts is {{device_id}}. A url with localhost, a host name that ends in .localhost, or a loopback, private, link-local, or other refused IP address fails when you save the flow. When a host name resolves to at least one such address, Navixy doesn't send the request and reports no error. See Rules for Webhook nodes.
headers
WEBHOOK only. The HTTP headers that the node sends, at most 10. A node without headers has none, so in an update, leaving the field out removes the stored headers.
body
String
WEBHOOK only, required. The body of the request, at most 4,000 characters. Navixy replaces its placeholders with values of the message. See Placeholders.
IotLogicFlowWebhookHeaderInput
One HTTP header of a Webhook node. A Content-Type header can appear once, and its value is application/json or another application media type that ends in +json, such as application/problem+json, with no charset other than utf-8. Navixy sets these headers itself, so a node can't have them: Content-Length, Transfer-Encoding, Host, Connection, Keep-Alive, Proxy-Connection, TE, Trailer, Upgrade, Expect, and X-Navixy-Webhook. Header names aren't case-sensitive.
key
String!
The name of the header, at most 255 characters. It is an HTTP token (RFC 9110): English letters, digits, and the characters ``!#$%&'*+-.^_`
value
String!
The value of the header. Printable ASCII, at most 255 characters. The only placeholder that it accepts is {{device_id}}.
IotLogicDeviceCommandActionInput
One action of a Device Action node. The input type is @oneOf: set exactly one of its two fields. A value with both fields, or with neither, fails the request.
IotLogicSetOutputActionInput
Switches a digital output of the device on or off.
output
Int!
The number of the output, from 1 to 8. The API accepts the same output in two actions of one node, although the flow editor doesn't offer it.
enabled
Boolean!
true switches the output on, and false switches it off.
IotLogicRawCommandActionInput
A text command that Navixy sends to the device unchanged.
text
String!
The command text, at most 512 characters. It can't be blank. Spaces at the start and the end are kept. Navixy sends the text as ASCII, so use only printable ASCII characters: other characters don't arrive as written.
IotLogicDeviceMappingEntryInput
One entry of the device mapping of a Device Action node: when a message of sourceDeviceId reaches the node, the actions go to each device in targetDeviceIds instead of to the source. A source can have only one entry in a node, and an entry needs at least one target.
sourceDeviceId
ID!
The device whose messages trigger the actions. It receives no commands itself, unless it is also in targetDeviceIds.
targetDeviceIds
[ID!]!
The devices that receive the actions. At least one.
IotLogicFlowAttributeAssignmentInput
One attribute that an Initiate Attribute node calculates: its name and the expression for its value.
name
String!
The name of the attribute. Lowercase letters and digits in groups joined by single underscores, such as fuel_level_l (^[a-z0-9]+(_[a-z0-9]+)*$). A final group of digits, such as _2, gives the channel number. At most 48 characters, not counting the channel number. Navixy reserves 12 names for the position of a device, such as position_latitude. See Initiate Attribute.
expression
String!
The expression that calculates the value, in the Navixy IoT Logic Expression Language. Printable ASCII on one line, at most 960 characters.
IotLogicFlowTransitionInput
A transition in a create or update request. from and to are node keys from the same request, not node IDs.
from
String!
The key of the node the transition leaves.
to
String!
The key of the node the transition enters.
type
The outcome that the transition follows: THEN or ELSE after a logic node, SIMPLE after every other node.
IotLogicFlowNodePositionInput
The coordinates where the flow editor draws the node.
x
Int!
The horizontal coordinate.
y
Int!
The vertical coordinate.
IotLogicFlowCreateInput
Input for creating a flow. The flow is created disabled.
title
String!
Printable ASCII, not blank, at most 255 characters.
description
String
Printable ASCII and line feeds (\n), at most 4,000 characters. Spaces at the start and the end are kept.
IotLogicFlowUpdateInput
Input for updating a flow. nodes and transitions are the whole new graph, not a list of changes. A node that the list leaves out is removed, together with its devices. Send both lists together. A field that you leave out keeps its stored value.
id
ID!
The flow to update.
version
Int!
The current version for optimistic locking.
title
String
Printable ASCII, not blank, at most 255 characters.
description
String
Printable ASCII and line feeds (\n), at most 4,000 characters. Spaces at the start and the end are kept.
isEnabled
Boolean
true enables the flow and validates the whole graph again. false disables the flow. An update that only sets isEnabled: false validates nothing.
IotLogicFlowDeleteInput
Input for deleting a flow.
id
ID!
The flow to delete.
version
Int!
The current version for optimistic locking.
Enums
IotLogicFlowTransitionType
The outcome of the node that a transition leaves, and so the messages that follow the transition.
SIMPLE
A transition that leaves any node other than a logic node.
THEN
Followed by the messages for which the condition of the logic node is true.
ELSE
Followed by every other message that leaves the logic node.
IotLogicFlowNodeType
The node types that a flow can have.
Values: DATA_SOURCE, LOGIC, INITIATE_ATTRIBUTES, OUTPUT_ENDPOINT, ACTION, WEBHOOK
IotLogicFlowOrderField
Fields available for ordering flows.
TITLE
Order by title.
CREATED_AT
Order by creation time.
UPDATED_AT
Order by last modification time.
IotLogicDeviceFlowLinkOrderField
Fields to order device links by: CREATED_AT, when the device was added to the data source, or FLOW_TITLE, the title of the flow.
Values: CREATED_AT, FLOW_TITLE
Interfaces
IotLogicFlowNode
A node of a flow: one step of the graph, shown as a box in the flow editor. A flow node isn't a Node, so the node and nodes queries don't return it. Read the nodes of a flow through the flow.
id
ID!
The ID of the node. It is unique within the flow, and it stays the same when an update keeps the node.
name
String!
The name that the flow editor shows. At most 255 characters.
description
String
Notes about the node.
position
The coordinates where the flow editor draws the node. null for a node that has no stored position.
Unions
IotLogicDeviceCommandAction
A command that a Device Action node sends: an IotLogicSetOutputAction or an IotLogicRawCommandAction. Read the fields of each type with an inline fragment, such as ... on IotLogicSetOutputAction { output enabled }.
One of: IotLogicSetOutputAction, IotLogicRawCommandAction
Pagination types
IotLogicFlowConnection
A paginated list of IotLogicFlow items.
Implements: Connection
IotLogicFlowEdge
An edge in the IotLogicFlow connection.
Implements: Edge
cursor
String!
An opaque cursor for this edge.
IotLogicDeviceFlowLinkConnection
A paginated list of IotLogicDeviceFlowLink items.
Implements: Connection
IotLogicDeviceFlowLinkEdge
An edge in the IotLogicDeviceFlowLink connection.
Implements: Edge
cursor
String!
An opaque cursor for this edge.
See also
Last updated
Was this helpful?