Skip to content

Actions

Action Data Structure

A action is executed for an interface of a device, the result depends on the driver of the interface. In case of a LoRaWAN driver, this can result in a down frame being send to the device.

{
   "id":"b266b9d5-7af7-4085-ba99-e60739e44ef1",
   "state":"pending",

   // Depending on interface driver, see 'Action types and options'.
   "type":"send_down_frame",
   "opts":{
      "retries":3,
      "port":1,
      "payload":"AFFE",
      "mac_commands":[

      ],
      "immediately":false,
      "acknowledge":false
   },

   "result":null,
   "override":false,
   "order":null,

   "mandate_id":"43d657b9-a79f-4ccb-873d-be31e5fbcf13",
   "device_id":"53992923-b512-4b51-a555-4acee9a29adb", // Will be preloaded as 'device'
   "interface_id":"72d9aed3-22fd-47a0-9d18-b80af03db993", // Will be preloaded as 'interface'

   "inserted_at":"2020-10-28T14:11:31.808042Z",
   "updated_at":"2020-10-28T14:11:31.845512Z",
   "executed_at":null,
   "cancel_after":null,

   // List of events for this action.
   "events":[
      {
         "id":"1e58b4d3-440f-45f1-a51a-953102c99dea",
         "type":"created_by_user",
         "state":"info",
         "fallback_text":null,
         "meta":{
            "user_name":"Admin",
            "user_id":"0377196c-f846-4911-9aa5-bec323282881"
         },
         "recorded_at":"2020-10-28T14:11:31.807778Z",
         "inserted_at":"2020-10-28T14:11:31.808032Z",
         "updated_at":"2020-10-28T14:11:31.808032Z"
      },
      {
         "id":"62d8eab8-4410-425f-bcc7-c58f8a5fedec",
         "type":"sent_to_element_lns",
         "state":"executed",
         "fallback_text":null,
         "meta":null,
         "recorded_at":"2020-10-28T14:11:31.844904Z",
         "inserted_at":"2020-10-28T14:11:31.845470Z",
         "updated_at":"2020-10-28T14:11:31.845470Z"
      }
   ]
}1
Property Type Default Description
type* string Type of the action. In some drivers, there are multiple action types. See Action types and options.
opts* dict Options specific to the chosen type. Other than a few exceptions, there is usually a required property that has to be present in the opts dictionary. See Action types and options.
override boolean false Can be set to true when creating. Actions with override will cancel all previous pending actions in their device.
cancel_after int null Time in milliseconds after which the action is cancelled if it hasn't finished executing.
device_id uuid The ID of the device
interface_id uuid The ID of the interface
id§ uuid A unique identifier of the action, which can be used in Show single action.
state§ string pending The current state of the action. See Action state.
events§ list of dicts [] Supporting drivers will populate this list with events explaining the action's progress to the user.
inserted_at§ iso8601 Creation date
updated_at§ iso8601 Date of last update
result§ ? deprecated and unused field
order§ integer internal

* means that this property must be present when creating an action.

⌘ - this property must also be present when creating an action. Usually, this is automatically set by the Interface selection.

§ means that this property can only be viewed.

Action state

A action has a state which can be one of the following values:

  • pending - Initial state. Action is waiting to be executed. Will change to executing.
  • executing - Action is currently in progress. Will end in executed or errored.
  • executed - Action was successfully executed.
  • errored - Action has failed.
  • cancelled - Action was cancelled by user.

The state is set by the system and not be changed by the user, except when cancelling a action.

Interface selection

The URL part /by-:selector_type/:selector_identifier/ can be used to address an interface in ELEMENT using a device selector.

Most endpoints for creating actions allow the request to be unspecific about the interface that is used to execute the action. If the request only has information about the device, but not the interface, ELEMENT will reject interfaces from the device's interface for the following reasons:z

  • if the interface doesn't support the given action type, or
  • if the interface doesn't match the given selector

As long as the resulting interface list has a length of exactly one, an action can still be executed.

Action types and options

ELEMENT LNS

send_down_frame will queue a down frame in the LNS.

{
    "type": "send_down_frame",
    "opts": {
      "payload": "AFFE", // Binary payload in HEX
      "port": 1, // DOWN frame port
      "retries": 3,
      "mac_commands": [],
      "immediately": false, // Send now with class C devices
      "acknowledge": false // Add a 'confirm' flag to DOWN packet
    }
}

Manual driver

create_packet will create a packet with the given options as the packet's fields.

{
    "type": "create_packet",
    "opts": {
        "payload": "2C", // Payload in format of encoding
        "encoding": "hex", // can be 'hex', 'utf8' or 'json'
        "packet_type": "up", // Value for packet.packet_type
        "meta": {
          "frame_port": 1
        }
    }
}

ELEMENT Gateway Management System (GMS)

The available action types depend on the supported actions provided by Probe for that gateway.

These action types are available on all gateways:

  • ping - Probe will answer with a "pong".
  • reboot - Probe will reboot the gateway.
  • force_stats - Will force probe to send the latest statistics.
  • get_supported_commands - Probe will send the list of supported commands, so they become available.

Hessware Gateway Management System

There are 2 action types with no options:

  • reboot
  • disconnect

Loriot HTTP

send_down_frame will queue a down frame in the LNS.

{
    "type": "send_down_frame",
    "opts": {
        "payload": "CAFE",
        "port": 1,
        "confirmed": false
    }
}

MQTT Client

publish sends payload to the MQTT Broker.

{
    "type":"publish",
    "opts":{
        "topic": "example1234",
        "payload": "CAFE",
        "use_same_topic": false // Will use topic from interface instead of given one.
    }
}

Sigfox HTTP

send_down_frame schedules down frames for sigfox devices.

{
    "type":"send_down_frame",
    "opts":{
        "payload": "CAFE"
    }
}

List all actions

Method: GET

Endpoints:

  • /actions/ - Listing all actions of a mandate.
  • /devices/by-:selector_type/:selector_identifier/actions - Listing by selector.
  • /devices/:device_id/actions - Listing all actions for a device.
  • /devices/:device_id/interfaces/:interface_id/actions - Listing for a device interface.

This endpoint returns a paginated list of actions.

The list is sorted from newest to oldest inserted_at by default, and can be changed to executed_at or updated_at.

Example Requests

GET https://element-iot.com/api/v1/actions?auth=46cb688e2c0b468e26e914235d4b73ea

GET https://element-iot.com/api/v1/devices/by-eui/F05FEFEC6488E9C6/actions?auth=46cb688e2c0b468e26e914235d4b73ea

GET https://element-iot.com/api/v1/devices/53992923-b512-4b51-a555-4acee9a29adb/actions?auth=46cb688e2c0b468e26e914235d4b73ea

GET https://element-iot.com/api/v1/devices/53992923-b512-4b51-a555-4acee9a29adb/interfaces/72d9aed3-22fd-47a0-9d18-b80af03db993/actions?auth=46cb688e2c0b468e26e914235d4b73ea

Example Response

{
  "status": 200,
  "retrieve_after_id": "b266b9d5-7af7-4085-ba99-e60739e44ef1",
  "ok": true,
  "body": [
    // Contains an array of actions
  ]
}

Show single action

Method: GET

Endpoints:

  • /actions/:action_id
  • /devices/:device_id/actions/:action_id
  • /devices/:device_id/interfaces/:interface_id/actions/:action_id

Example Requests

GET https://element-iot.com/api/v1/actions/b266b9d5-7af7-4085-ba99-e60739e44ef1?auth=46cb688e2c0b468e26e914235d4b73ea

GET https://element-iot.com/api/v1/devices/53992923-b512-4b51-a555-4acee9a29adb/actions/b266b9d5-7af7-4085-ba99-e60739e44ef1?auth=46cb688e2c0b468e26e914235d4b73ea

GET https://element-iot.com/api/v1/devices/53992923-b512-4b51-a555-4acee9a29adb/interfaces/72d9aed3-22fd-47a0-9d18-b80af03db993/actions/b266b9d5-7af7-4085-ba99-e60739e44ef1?auth=46cb688e2c0b468e26e914235d4b73ea

Show available action types

Method: GET Endpoint: /devices/:device_id/interfaces/:interface_id/actions/types

Listing available action types for a given interface.

Example Requests

GET https://element-iot.com/api/v1/devices/53992923-b512-4b51-a555-4acee9a29adb/interfaces/72d9aed3-22fd-47a0-9d18-b80af03db993/actions/types?auth=46cb688e2c0b468e26e914235d4b73ea

Example Response

{
  "status": 200,
  "ok": true,
  "body": [
    {
        "display": "Send down frame",
        "type": "send_down_frame"
    }
  ]
}

Create a new action

Method: POST

Endpoints:

  • /actions

  • /devices/:device_id/actions/

  • /devices/:device_id/actions/:type

  • /devices/:device_id/interfaces/:interface_id/actions/

  • /devices/:device_id/interfaces/:interface_id/actions/:type

  • /devices/by-:selector_type/:selector_identifier/actions - Selection by selector.

  • /devices/by-:selector_type/:selector_identifier/actions/:type

Example Requests

POST https://element-iot.com/api/v1/actions?auth=46cb688e2c0b468e26e914235d4b73ea
{
    "device_id":"53992923-b512-4b51-a555-4acee9a29adb",
    "interface_id":"72d9aed3-22fd-47a0-9d18-b80af03db993",

    "type":"send_down_frame",
    "opts":{"payload":"BABE","port":1}
}
POST https://element-iot.com/api/v1/devices/by-eui/F05FEFEC6488E9C6/actions/send_down_frame?auth=46cb688e2c0b468e26e914235d4b73ea
{
    "opts":{"payload":"BABE","port":1}
}

Cancel an action

Only actions in state pending or executing can be cancelled.

Method: POST

Endpoints:

  • /actions/:action_id/cancel
  • /devices/:device_id/actions/:action_id/cancel
  • /devices/:device_id/interfaces/:interface_id/actions/:action_id/cancel

Example Requests

POST https://element-iot.com/api/v1/actions/b266b9d5-7af7-4085-ba99-e60739e44ef1/cancel?auth=46cb688e2c0b468e26e914235d4b73ea
{
    "body": {
        "id": "b266b9d5-7af7-4085-ba99-e60739e44ef1",
        "state": "cancelled"
    }
}

Scheduled actions

Actions can be scheduled to be executed at a later date or regularly using a crontab expression.

Properties

Action schedules are represented by JSON Objects with these properties:

Property Type Default Description
id§ uuid Unique identifier for the schedule.
device_id uuid ID of the device that this schedule creates actions in.
interface_id uuid ID of the interface that this schedule creates actions in.
schedule crontab null Crontab expression that schedules actions in regular intervals.
schedule_tz string null Timezone the schedule should run in (use Europe/Berlin for Germany).
execute_at iso8601 null A date when the action should be created.
type* string Type of the action. In some drivers, there are multiple action types. See Action types and options.
opts* dict Options specific to the chosen type. Other than a few exceptions, there is usually a required property that has to be present in the opts dictionary. See Action types and options.
override boolean false Can be set to true when creating. Actions with override will cancel all previous pending actions in their device.
cancel_after int null Time in milliseconds after which the action is cancelled if it hasn't finished executing.

Either schedule or execute_at must be present when creating a schedule, but not both.

When schedule is present, schedule_tz must also be present.

* - this property must be present when creating a schedule.

⌘ - this property must also be present when creating an action. Usually, this is automatically set by the Interface selection.

§ - this property is read-only.

Create a schedule

Method: POST

Endpoints:

  • /actions/schedules
  • /devices/:device_id/actions/schedules
  • /devices/:device_id/interfaces/:interface_id/actions/schedules
  • /devices/by-:selector_type/:selector_identifier/actions/schedules - Selection by selector.

Example request with execute_at:

POST /api/v1/by-eui/AABBCCDD00112233/actions/schedules?auth=xy

{
  "type": "send_down_frame",
  "execute_at": "2023-03-01T00:00:00Z",
  "cancel_after": 60000,
  "opts": {
    "payload": "AA",
    "port": 1
  }
}

Example request with schedule:

POST /api/v1/by-eui/AABBCCDD00112233/actions/schedules?auth=xy

{
  "type": "send_down_frame",
  "schedule": "0 3 * * *",
  "schedule_tz": "Europe/Berlin",
  "cancel_after": 60000,
  "opts": {
    "payload": "AA",
    "port": 1
  }
}

List schedules

The GET .../schedules endpoints will return all schedules, filtered by device or interface depending on the exact endpoint used.

Method: GET

Endpoints:

  • /actions/schedules
  • /devices/:device_id/actions/schedules
  • /devices/:device_id/interfaces/:interface_id/actions/schedules
  • /devices/by-:selector_type/:selector_identifier/actions/schedules - Selection by selector.

Example request:

GET /api/v1/by-eui/AABBCCDD00112233/actions/schedules?auth=xy

Response (device and interface details truncated):

{
    "body": [
        {
            "cancel_after": null,
            "device": ...,
            "device_id": "078e38f5-67c0-44aa-b4a2-472662b5be21",
            "execute_at": "2024-12-31T23:00:00.000000Z",
            "id": "34ced76e-eb61-4881-9737-31704cd39666",
            "inserted_at": "2023-02-01T10:25:26.234634Z",
            "interface": ...,
            "interface_id": "dbaec844-cff3-4500-b1b8-0d0a361203e7",
            "mandate_id": "3580d2ce-fc84-4f0d-ae6d-d5d59a2171bd",
            "opts": {
                "acknowledge": false,
                "immediately": false,
                "mac_commands": [],
                "payload": "AAABBB",
                "port": 1,
                "retries": 3
            },
            "override": false,
            "schedule": null,
            "schedule_tz": "Europe/Berlin",
            "timer_id": "793b1182-2a52-4a20-a06f-ae39fcdd5e57",
            "type": "send_down_frame",
            "updated_at": "2023-02-01T10:25:26.258874Z"
        }
    ],
    "ok": true,
    "retrieve_after_id": "34ced76e-eb61-4881-9737-31704cd39666",
    "status": 200
}

Delete a schedule

The DELETE /actions/schedules/:schedule_id endpoint will remove the schedule with the given ID.

Example:

DELETE https://element-iot.com/api/v1/actions/schedules/459e8ad4-d5e4-4f12-9996-ade82f6daa4a?auth=xy

Response:

{
  "ok": true,
  "status": 200
}

View a schedule

The GET /actions/schedules/:schedule_id endpoint will show the schedule with the given ID.

Example:

GET GET https://element-iot.com/api/v1/actions/schedules/0b698fbc-0bb2-4a47-aea1-5cc65f4d8419?auth=xy

Response (device, interface and timer associated objects truncated for brevity):

{
  "body": {
    "cancel_after": null,
    "device": ...,
    "device_id": "078e38f5-67c0-44aa-b4a2-472662b5be21",
    "execute_at": null,
    "id": "0b698fbc-0bb2-4a47-aea1-5cc65f4d8419",
    "inserted_at": "2023-02-01T10:54:20.471520Z",
    "interface": ...,
    "interface_id": "dbaec844-cff3-4500-b1b8-0d0a361203e7",
    "mandate_id": "3580d2ce-fc84-4f0d-ae6d-d5d59a2171bd",
    "opts": {
      "acknowledge": false,
      "immediately": false,
      "mac_commands": [],
      "payload": "ABCDEF",
      "port": 3,
      "retries": 3
    },
    "override": false,
    "schedule": "0 0 1 * *",
    "schedule_tz": "Europe/Berlin",
    "timer": ...,
    "timer_id": "65519e7f-5f8f-463a-b36e-fd842179cb5f",
    "type": "send_down_frame",
    "updated_at": "2023-02-01T10:54:20.475009Z"
  },
  "ok": true,
  "status": 200
}