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
}