Octave

The Octave Developer Hub

Welcome to the Octave developer hub. You'll find comprehensive guides and documentation to help you start working with Octave as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

Using a Task to Periodically Pull in External Data

This topic provides information about Tasks and how to create and manage them.

A Task is an entity that can periodically pull data from external systems and "inject" it into Octave as Events. For example, a Task can periodically look for new events is an RSS feed and then inject those as Events into a Stream. A Cloud Action can then invoke Octave.Event.find() from the Octave Cloud Action Runner API to find, sort, and order Events. For example, a Cloud Action can query a stream of light readings created every five minutes, report on bad devices, and push data to an external service such as a dashboard.

A Task is created and managed programmatically from an external system using Octave's REST API.

Elements of a Task

A Task consists of a destination stream where the Events are to be placed in Octave, periodicity which specifies how often, in milliseconds, to poll for external data, and a source which specifies where to pull the data from.

The source type can be set to http to read data from a URL, or eventFind to read from a specified a streamid or streamPath.

When using http, a parser type (e.g., RSS, JSON, etc.) must be specified so Octave knows how to read/extract the source data.

You can also include a js field in which you can define a JavaScript function to execute in the task as described below.

Creating a Task

A new Task is created by invoking the POST /task endpoint. In the following example, a Task is created that reads data from an RSS feed everything 20 seconds and writes to the /task_output Stream. Octave's rss parser is used to extract the data and convert it into Stream Events:

Request

## Create Task
curl -X "POST" "https://octave-api.sierrawireless.io/v5.0/my_company/task" \
    -H 'X-Auth-Token: <token>' \
    -H 'X-Auth-User: <user>' \
    -H 'Content-Type: application/json; charset=utf-8' \
    -d $'{
    "destination": "/my_company/task_output",
    "periodicity": "20000",
    "source": {
      "http": {
        "get": {
          "url": "https://www.nasa.gov/rss/dyn/breaking_news.rss"
        },
        "parser": "rss"
      }
    },
    "displayName": "A sample task"
}'

📘

Note

You can find your username and master token on the user screen in the Octave Dashboard. These values used for the X-Auth-Token and X-Auth-User headers.

Response

The messages field indicates the result of request and the body field provides details about the new task such as its unique id:

{
   "head":{
      "status":201,
      "ok":true,
      "messages":[
         "Your request has been processed successfully. A new resource has been created."
      ],
      "errors":[

      ],
      "references":{

      }
   },
   "body":{
      "id":"t5d2df800c2b092ef7a3475d3",
      "companyId":"c5adf803aaa02b35e0cce7b2d",
      "creationDate":1563293696545,
      "creatorId":"i5adf803aaa02b35e0cce7b2a",
      "destination":"/my_company/task_output",
      "displayName":"A sample task",
      "lastRun":0,
      "nextRun":0,
      "periodicity":20000,
      "runCt":0,
      "source":{
         "http":{
            "parser":"rss",
            "get":{
               "url":"https://www.nasa.gov/rss/dyn/breaking_news.rss"
            }
         }
      },
      "status":"OK"
   }
}

Reading a Task

Information about an existing Task can be obtained at any time by invoking GET /tasks/{id} and passing the ID of the Task as a path parameter:

curl "https://octave-api.sierrawireless.io/v5.0/my_company/task/t5d2df800c2b092ef7a3475d3" \
     -H 'X-Auth-Token: <token>' \
     -H 'X-Auth-User: <user>'

Response

The body field provides details about the task:

{
  "head": {
    "status": 200,
    "ok": true,
    "messages": [],
    "errors": [],
    "references": {}
  },
  "body": {
    "id": "t5d2df800c2b092ef7a3475d3",
    "companyId": "c5adf803aaa02b35e0cce7b2d",
    "creationDate": 1563293696545,
    "creatorId": "i5adf803aaa02b35e0cce7b2a",
    "description": "A RSS news feed containing the latest NASA news articles and press releases.",
    "destination": "/my_company/task_output",
    "displayName": "A sample task",
    "lastRun": 1563296216786,
    "nextRun": 1563296236786,
    "periodicity": 20000,
    "runCt": 127,
    "source": {
      "http": {
        "parser": "rss",
        "get": {
          "url": "https://www.nasa.gov/rss/dyn/breaking_news.rss"
        }
      }
    },
    "status": "NO_NEW_DATA"
  }
}

Updating a Task

An existing Task can be updated by invoking the PUT /task/{endpoint} endpoint and passing the ID of the Task as a path parameter; the new Task property values are passed as body parameters. In the following example, the description property is updated to "My Task":

curl -X "PUT" "https://octave-api.sierrawireless.io/v5.0/my_company/task/t5d2df800c2b092ef7a3475d3" \
     -H 'X-Auth-Token: <token>' \
     -H 'X-Auth-User: <user>' \
     -d $'{
  "description": "My Task"
}'

Response

{
   "head":{
      "status":200,
      "ok":true,
      "messages":[

      ],
      "errors":[

      ],
      "references":{

      }
   },
   "body":{
      "id":"t5d2df800c2b092ef7a3475d3",
      "companyId":"c5adf803aaa02b35e0cce7b2d",
      "creationDate":1563293696545,
      "creatorId":"i5adf803aaa02b35e0cce7b2a",
      "description":"My Task",
      "destination":"my_company/task_output",
      "displayName":"A sample task",
      "lastEditDate":1563302760142,
      "lastEditorId":"i5adf803aaa02b35e0cce7b2a",
      "lastRun":1563302756772,
      "nextRun":1563302776772,
      "periodicity":20000,
      "runCt":454,
      "source":{
         "http":{
            "parser":"rss",
            "get":{
               "url":"https://www.nasa.gov/rss/dyn/breaking_news.rss"
            }
         }
      },
      "status":"OK"
   }
}

Deleting a Task

An existing task can be deleted by invoking the DELETE /task/{id} endpoint and passing the ID of the Task as a path parameter:

curl -X "DELETE" "https://octave-api.sierrawireless.io/v5.0/my_company/task/t5d2df800c2b092ef7a3475d3" \
     -H 'X-Auth-Token: <token>' \
     -H 'X-Auth-User: <user>'

Response

The messsages field in the response indicates the result of the request:

{
   "head":{
      "status":200,
      "ok":true,
      "messages":[
         "Your request has been processed successfully. The requested resource has been deleted."
      ],
      "errors":[

      ],
      "references":{

      }
   },
   "body":{

   }
}

Simulating a Task

A Task can be "simulated" to show what an Event from a given source would look like, by invoking the POST /task/simulate endpoint. This is a way to check what the task would write to a Stream without actually writing to it. Similar to the Create Task endpoint, the simulate endpoint requires a source stream, periodicity, and destination stream. 

curl -X "POST" "https://octave-api.sierrawireless.io/v5.0/my_company/task/simulate" \
    -H 'X-Auth-Token: <token>' \
    -H 'X-Auth-User: <user>' \
     -H 'Content-Type: text/plain; charset=utf-8' \
     -d $'{
  "source": {
    "http": {
      "get": {
        "url": "https://www.nasa.gov/rss/dyn/breaking_news.rss"
      },
      "parser": "rss"
    }
  },
  "periodicity": "20000",
  "destination": "/my_company/task_output",
  "displayName": "A sample task"
}'

Response

The events field in the response provides a preview of the event JSON that would be generated by Octave from the source data:

{
   "head":{
      "status":200,
      "ok":true,
      "messages":[

      ],
      "errors":[

      ],
      "references":{

      }
   },
   "body":{
      "events":{
         "/my_company/task_out":[
            {
               "metadata":null,
               "creationDate":null,
               "lastEditDate":null,
               "generatedDate":null,
               "path":null,
               "location":null,
               "hash":"http://www.nasa.gov/press-release/nasa-scientists-engineers-honored-with-presidential-early-career-awards",
               "tags":null,
               "elems":{
                  "thumbnail":{
                     "media_type":"image",
                     "mime_type":"image/jpeg",
                     "length":189751,
                     "url":"http://www.nasa.gov/sites/default/files/styles/1x1_cardfeed/public/thumbnails/image/nasa-logo-web-rgb_0.jpg?itok=mCRPbzgr"
                  },
                  "link":"http://www.nasa.gov/press-release/nasa-scientists-engineers-honored-with-presidential-early-career-awards",
                  "publication_date":1563305489105,
                  "description":"President Trump has named 18 NASA researchers as recipients of the Presidential Early Career Award for Scientists and Engineers (PECASE).",
                  "title":"NASA Scientists, Engineers Honored with Presidential Early Career Awards",
                  "content":{
                     "type":"html",
                     "value":"President Trump has named 18 NASA researchers as recipients of the Presidential Early Career Award for Scientists and Engineers (PECASE)."
                  }
               }
            }
         ]
      }
   }
}

Adding Code to a Task

You can add a JavaScript function to be executed by a Task via the js field. The following example shows a cURL command to create a Task with a JavaScript function.

📘

Note

Note the use of '\'' as escape characters for instances of single quotes within the JavaScript function definition when passing it through cURL:

curl --location --request POST 'https://octave-api.sierrawireless.io/v5.0/my_company/task' \
--header 'X-Auth-Token: BjB...' \
--header 'X-Auth-User: df' \
--header 'Content-Type: application/json' \
--data-raw '{ 
        "destination": "/my_company/task_output", 
        "periodicity": "20000", 
        "js": "function (events, raw){var offlineThreshold = Date.now() - (5 * 60 * 1000); var alreadyReportedThreshold = Date.now() - (8 * 60 * 1000); var filterString = '\''lastSeen<'\'' + offlineThreshold + '\''&&lastSeen>'\'' + alreadyReportedThreshold; var devices = Octave.Device.find({'\''filter'\'' : filterString}); var deviceIds = _.map(devices, function (device){ return device.id; }); var result = {};       if (deviceIds.length > 0){   var event =  {    elems : {      devices : deviceIds  }   };   result['\''/my_company/offline'\''] = [event];  } return result }", 
        "displayName": "A sample task" 
}'

Updated 14 days ago

Using a Task to Periodically Pull in External Data

This topic provides information about Tasks and how to create and manage them.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.