Instruction

>>>

GET /api/v3/instructions
List all instructions

Returns a list of all instructions belonging to an account as per the specified criteria. This API is paginated and returns 20 instructions by default. An instruction is uniquely identified by an 'instruction_key'. This key should be used in all the other API referencing a particular instruction.

Params

Param name Description
page
optional

Page number of results to be fetched, Default 1


Value: Must be Integer.
per
optional

Number of things records to be returned in one page, Default 20


Value: Must be Integer.
order_by
optional

Field on which resultant things should be sorted


Value: Must be a String
order
optional

Order, asc or desc, in which results should be sorted


Value: Must be a String
timestamp_format
optional

Format, “str” or “int”, in which timestamps should be returned, Default “int”


Value: Must be a String
search
optional

Keywords based on which things should be searched. Currently you can search things on - thing_key, name or tag


Value: Must be a String
scope
optional

Matching condition if multiple keywords are specified for search. Valid values are “all” or “any”. Default is “all”


Value: Must be a String
pretty
optional

Return a pretty formatted response if true, Default is false


Value: Must be a Boolean
field_list
optional

List of fields required in the result.


Value: Must be an array of any type
fields
optional

[Deprecated]Comma separated list of fields required in the result.


Value: Must be a String
is_oem
optional

Return instructions of child accounts along with instructions of oem account if is_oem flag is true.


Value: Must be one of: <code>true</code>, <code>false</code>, <code>true</code>, <code>false</code>.

Examples

Request - listing all instructions without any criteria
  curl -X GET -H "Content-Type:application/json" -H "X-Auth-Token:olezAZXGQn9MutnfNerKDQ" https://api.datonis.io/api/v3/instructions

Response (returns first 20 records)
{
  "total_count": 9,
  "page": 1,
  "instructions": [
    {
      "definition": {
        "val": "off"
      },
      "description": "Turn the sensor off",
      "instruction_key": "t9t2a63b4f",
      "max_retries": 0,
      "name": "TURNOFF",
      "timeout": 30,
      "created_at": 1425912572,
      "updated_at": 1425912572
    },
    {
      "definition": {
        "value": "on"
      },
      "description": "Turn the machine on",
      "instruction_key": "e23t78333c",
      "max_retries": 0,
      "name": "TURNON",
      "timeout": 30,
      "created_at": 1425984214,
      "updated_at": 1427986515
    },
    {
      "definition": {
        "temp": 50,
        "humidity": 65
      },
      "description": "Turn up the thermostat",
      "instruction_key": "e661ctd8fa",
      "max_retries": 0,
      "name": "TURNUP",
      "timeout": 30,
      "created_at": 1426142755,
      "updated_at": 1426142755
    },
    {
      "definition": {
        "address": "gfff",
        "value": "foo"
      },
      "description": "",
      "instruction_key": "11aae44468",
      "max_retries": 0,
      "name": "MODBUSOFF",
      "timeout": 30,
      "created_at": 1434350522,
      "updated_at": 1434350522
    },
    {
      "definition": {
        "status": "on"
      },
      "description": "start machine",
      "instruction_key": "ea96tc6c57",
      "max_retries": 0,
      "name": "Start Machine",
      "timeout": 30,
      "created_at": 1448429915,
      "updated_at": 1448429915
    },
    {
      "definition": {
        "status": "off"
      },
      "description": "stop machine",
 ...
Request - listing instructions by specifying number of instructions to be returned at a time (page size) and specific set to be returned (page)
  curl -X GET -H "Content-Type:application/json" -H "X-Auth-Token:olezAZXGQn9MutnfNerKDQ" -d '{"per":"2","page":"2"}' https://api.datonis.io/api/v3/instructions

Response (returns page 2 with 2 instructions per page)
{
  "total_count": 9,
  "page": "2",
  "instructions": [
    {
      "definition": {
        "temp": 50,
        "humidity": 65
      },
      "description": "Turn up the thermostat",
      "instruction_key": "e661ctd8fa",
      "max_retries": 0,
      "name": "TURNUP",
      "timeout": 30,
      "created_at": 1426142755,
      "updated_at": 1426142755
    },
    {
      "definition": {
        "address": "gfff",
        "value": "foo"
      },
      "description": "",
      "instruction_key": "11aae44468",
      "max_retries": 0,
      "name": "MODBUSOFF",
      "timeout": 30,
      "created_at": 1434350522,
      "updated_at": 1434350522
    }
  ]
}
Request - listing instructions ordered by a field
  curl -X GET -H "Content-Type:application/json" -H "X-Auth-Token:olezAZXGQn9MutnfNerKDQ" -d '{"order_by":"name","order":"desc"}' https://api.datonis.io/api/v3/instructions

Response (returns instructions in the reverse order of their name)
{
  "total_count": 9,
  "page": 1,
  "instructions": [
    {
      "definition": {
        "temp": 50,
        "humidity": 65
      },
      "description": "Turn up the thermostat",
      "instruction_key": "e661ctd8fa",
      "max_retries": 0,
      "name": "TURNUP",
      "timeout": 30,
      "created_at": 1426142755,
      "updated_at": 1426142755
    },
    {
      "definition": {
        "value": "on"
      },
      "description": "Turn the machine on",
      "instruction_key": "e23t78333c",
      "max_retries": 0,
      "name": "TURNON",
      "timeout": 30,
      "created_at": 1425984214,
      "updated_at": 1427986515
    },
    {
      "definition": {
        "val": "off"
      },
      "description": "Turn the sensor off",
      "instruction_key": "t9t2a63b4f",
      "max_retries": 0,
      "name": "TURNOFF",
      "timeout": 30,
      "created_at": 1425912572,
      "updated_at": 1425912572
    },
    {
      "definition": {
        "status": "off"
      },
      "description": "stop machine",
      "instruction_key": "767dte9eeb",
      "max_retries": 0,
      "name": "Stop Machine",
      "timeout": 30,
      "created_at": 1448429947,
      "updated_at": 1448429947
    },
    {
      "definition": {
        "status": "on"
      },
      "description": "start machine",
      "instruction_key": "ea96tc6c57",
      "max_retries": 0,
      "name": "Start Machine",
      "timeout": 30,
      "created_at": 1448429915,
      "updated_at": 1448429915
    },
    {
      "definition": {
        "reduce_pressure": 10
      },
      "description": "",
     ...
Request - listing instructions based on some search criteria with all keywords matching
  curl -X GET -H "Content-Type:application/json" -H "X-Auth-Token:olezAZXGQn9MutnfNerKDQ" -d '{"search":"start machine"}' https://api.datonis.io/api/v3/instructions

Response (returns instructions containing both keywords 'start' as well as 'machine')
{
  "total_count": 1,
  "page": 1,
  "instructions": [
    {
      "definition": {
        "status": "on"
      },
      "description": "start machine",
      "instruction_key": "ea96tc6c57",
      "max_retries": 0,
      "name": "Start Machine",
      "timeout": 30,
      "created_at": 1448429915,
      "updated_at": 1448429915
    }
  ]
}
Request - listing instructions based on some search criteria with any of the keywords matching
  curl -X GET -H "Content-Type:application/json" -H "X-Auth-Token:olezAZXGQn9MutnfNerKDQ" -d '{"search":"start machine", "scope":"any"}' https://api.datonis.io/api/v3/instructions

Response (returns instructions containing either of the keywords 'start' or 'machine')
{
  "total_count": 2,
  "page": 1,
  "instructions": [
    {
      "definition": {
        "status": "off"
      },
      "description": "stop machine",
      "instruction_key": "767dte9eeb",
      "max_retries": 0,
      "name": "Stop Machine",
      "timeout": 30,
      "created_at": 1448429947,
      "updated_at": 1448429947
    },
    {
      "definition": {
        "status": "on"
      },
      "description": "start machine",
      "instruction_key": "ea96tc6c57",
      "max_retries": 0,
      "name": "Start Machine",
      "timeout": 30,
      "created_at": 1448429915,
      "updated_at": 1448429915
    }
  ]
}
>>>

POST /api/v3/instructions
Create an instruction

Creates an instruction with given parameters

Params

Param name Description
instruction
required

Object containing information about the instruction to be created


Value: Must be a Hash
pretty
optional

Return a pretty formatted response if true, Default is false


Value: Must be a Boolean
is_oem
optional

Create instruction in child account by oem user if is_oem flag is true.


Value: Must be a Boolean
child_organisation_key
optional

Organisation key of child account where oem user wants to create instruction. Required field if is_oem is present.


Value: Must be a String

Examples

Request - create instruction with parameters - name, definition and description
  curl -X POST -H "Content-Type:application/json" -H "X-Auth-Token:olezAZXGQn9MutnfNerKDQ"  -d '{"instruction":{"name":"Increase Pressure 20 PSI","definition":{"add_pressure":20},"description":"Increases pressure by 20 PSI"}}' https://api.datonis.io/api/v3/instructions

Response (containing details of the instruction created )
{
  "instruction": {
    "definition": {
      "add_pressure": 20
    },
    "description": "Increases pressure by 20 PSI",
    "instruction_key": "2ab8dfe1b4",
    "max_retries": 0,
    "name": "Increase Pressure 20 PSI",
    "timeout": 15,
    "created_at": 1448430636,
    "updated_at": 1448430636
  }
}
Request - create instruction with parameters - name, definition, description, max_retries (execution retries) and timeout (timeout in seconds for instruction acknowledgement)
  curl -X POST -H "Content-Type:application/json" -H "X-Auth-Token:olezAZXGQn9MutnfNerKDQ"  -d '{"instruction":{"name":"Increase Pressure 20 PSI","definition":{"add_pressure":20},"description":"Increases pressure by 20 PSI","max_retries":3,"timeout":30}}' https://api.datonis.io/api/v3/instructions

Response (containing details of the instruction created)
{
  "instruction": {
    "definition": {
      "add_pressure": 20
    },
    "description": "Increases pressure by 20 PSI",
    "instruction_key": "2ab8dfe1b4",
    "max_retries": 3,
    "name": "Increase Pressure 20 PSI",
    "timeout": 30,
    "created_at": 1448430636,
    "updated_at": 1448430636
  }
}
>>>

GET /api/v3/instructions/:instruction_key
Fetch an instruction

Get details of an instruction

Params

Param name Description
pretty
optional

Return a pretty formatted response if true, Default is false


Value: Must be a Boolean
is_oem
optional

Show instruction of child account if is_oem flag is true.


Value: Must be one of: <code>true</code>, <code>false</code>, <code>true</code>, <code>false</code>.

Examples

Request
  curl -X GET -H "Content-Type:application/json" -H "X-Auth-Token:olezAZXGQn9MutnfNerKDQ"  https://api.datonis.io/api/v3/instructions/767dte9eeb

Response (containing details of the instruction)
{
  "instruction": {
    "definition": {
      "status": "off"
    },
    "description": "stop machine",
    "instruction_key": "767dte9eeb",
    "max_retries": 0,
    "name": "Stop Machine",
    "timeout": 30,
    "created_at": 1448429947,
    "updated_at": 1448429947
  }
}
>>>

PUT /api/v3/instructions/:instruction_key
Update an instruction

Updates an instruction with given parameters

Params

Param name Description
instruction
required

Object containing information about the instruction to be updated


Value: Must be a Hash
pretty
optional

Return a pretty formatted response if true, Default is false


Value: Must be a Boolean
is_oem
optional

Update instruction in child account by oem user if is_oem flag is true.


Value: Must be a Boolean

Examples

Request - update parameters - name, definition and description
  curl -X PUT -H "Content-Type:application/json" -H "X-Auth-Token:olezAZXGQn9MutnfNerKDQ"  -d '{"instruction":{"name":"Increase Pressure 10 PSI","definition":{"add_pressure":10},"description":"Increases pressure by 10 PSI"}}' https://api.datonis.io/api/v3/instructions/2ab8dfe1b4

Response (containing details of the instruction updated )
{
  "instruction": {
    "definition": {
      "add_pressure": 10
    },
    "description": "Increases pressure by 10 PSI",
    "instruction_key": "2ab8dfe1b4",
    "max_retries": 0,
    "name": "Increase Pressure 10 PSI",
    "timeout": 15,
    "created_at": 1448430636,
    "updated_at": 1448430747
  }
}
Request - update  parameters - name, definition, description, max_retries (execution retries) and timeout (timeout in seconds for instruction acknowledgement)
  curl -X PUT -H "Content-Type:application/json" -H "X-Auth-Token:olezAZXGQn9MutnfNerKDQ"  -d '{"instruction":{"name":"Increase Pressure 10 PSI","definition":{"add_pressure":10},"description":"Increases pressure by 10 PSI","max_retries":2,"timeout":10}}' https://api.datonis.io/api/v3/instructions

Response (containing details of the instruction updated)
{
  "instruction": {
    "definition": {
      "add_pressure": 10
    },
    "description": "Increases pressure by 10 PSI",
    "instruction_key": "2ab8dfe1b4",
    "max_retries": 2,
    "name": "Increase Pressure 10 PSI",
    "timeout": 10,
    "created_at": 1448430636,
    "updated_at": 1448430636
  }
}
>>>

DELETE /api/v3/instructions/:instruction_key
Delete an instruction

Deletes an instruction from the system

Params

Param name Description
pretty
optional

Return a pretty formatted response if true, Default is false


Value: Must be a Boolean
is_oem
optional

Delete instruction in child account by oem user if is_oem flag is true.


Value: Must be a Boolean

Examples

Request
  curl -X DELETE -H "Content-Type:application/json" -H "X-Auth-Token:olezAZXGQn9MutnfNerKDQ"  https://api.datonis.io/api/v3/instructions/2ab8dfe1b4

Response
{
}
>>>

PUT /api/v3/instructions/:instruction_key/execute
Execute an instruction

Executes the specified instruction against given input objects

Params

Param name Description
instruction_applicability
required

Whether to execute an instruction on:

2: things belonging to specified thing_template
3: specified things

Value: Must be Integer.
instruction_applicability_value
required

thing_template or a thing_key or an array of thing keys depending on the value of instruction_applicability


Value: Must be an array of any type
json_map
optional

Map of configurable parameters


Value: Must be a Hash
pretty
optional

Return a pretty formatted response if true, Default is false


Value: Must be a Boolean
is_oem
optional

Execute an instruction in child account by oem user if is_oem flag is true.


Value: Must be a Boolean
child_organisation_key
optional

Organisation key of child account where oem user wants to execute instruction. Required field if is_oem is present.


Value: Must be a String

Examples

Request - execute an instruction against all sensors of type 'Energy Meter'
  curl -X PUT -H "Content-Type:application/json" -H "X-Auth-Token:olezAZXGQn9MutnfNerKDQ" -d '{"instruction_applicability":"2","instruction_applicability_value":"Energy Meter"}' https://api.datonis.io/api/v3/instructions/a5ad49t441/execute

Response (list of sensor alert keys describing execution status of the instruction against each sensor)
{
  "status": [
    "af1b856c7t",
    "e5688474t6",
    "bf72966t3b"
  ]
}
Request - execute an instruction against specified sensors
  curl -X PUT -H "Content-Type:application/json" -H "X-Auth-Token:olezAZXGQn9MutnfNerKDQ" -d '{"instruction_applicability":"3","instruction_applicability_value":["4dc7t6fe93","t6fd4btb5e"]}' https://api.datonis.io/api/v3/instructions/767dte9eeb/execute

Response (list of sensor alert keys describing execution status of the instruction against each sensor)
{
  "status": [
    "af1b856c7t",
    "e5688474t6",
    "bf72966t3b"
  ]
}