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
andX-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 3 months ago