File Service Events

You can retrieve the following Events handled through the file service Resources as part of file-sending process:

Interface	Direction	Description	Path	Data
File-sending pending	Device → Remote Asset	A new file can be sent	`/files/download/value`	`json { "name": <file name>, "autostart": false/true, "state": "waiting", "remaining": <size in bytes>, "progress": 0 }`
File-sending progress	Device → Remote Asset	Notification with number of sent bytes	`/files/download/value`	`json { "name": "newfile.dat", "autostart": false/true, "state": "transferring", "remaining": <size in bytes>, "progress": x }` Note: During file download, this notification is sent when the progress value changes.
File-sending suspended	Device → Remote Asset	Notification when a File-sending operation is suspended	`/files/download/value`	`json { "name": "newfile.dat", "autostart": false/true, "state": "waiting", "remaining": <size in bytes>, "progress": x }`
File-sending end	Octave Edge Device → Remote Asset	Notification when a File-sending operation ends	`/files/download/value`	`json { "name": "newfile.dat", "autostart": false/true, "state": "success", "size": <size in bytes>, "progress": 100 }`
File-sending failure	Octave Edge Device → Remote Asset	Notification when a File-sending operation fails	`/files/download/value`	`json { "name": "newfile.dat", "autostart": false/true, "state": "failure", "remaining": <size in bytes>, "progress": x }`
File-sending abortion	Octave Edge Device → Remote Asset	Notification when a File-sending operation was aborted (by an asset or the server)	`/files/download/value`	`json { "name": "newfile.dat", "autostart": false/true, "state": "aborted", "remaining": 0, "progress": 0 }`
File availability	Octave Edge Device → Remote Asset	Notification when a file can be retrieved by the asset. This notification is pushed by the Octave file service when a file is fully and successfully sent and when it's deleted.	`/files/list/value`	`json { "path": <path>, "files":[ { "name": "file name 1", "hash": "hash 1", "size": 12345, "origin": 0 }, { "name": "file name 2", "hash": "hash 2", "size": 987654, "origin": 0 } ] }` origin: 0 for server origin (file download)
Accept or resume a transfer	Remote Asset → Octave Edge Device	The host accepts the pending transfer. An error could be returned if no file is available for sending.	Before 3.2.0: `/files/control/value` From 3.2.0: `/files/control`	`json { "name": "file name", "transfer": "start" }`
Suspend a transfer	Remote Asset → Octave Edge Device	The host requests to suspend the download. An error could be returned if no download is on-going. The host can resume the download.	Before 3.2.0: `/files/control/value` From 3.2.0: `/files/control`	`json { "name": "file name", "transfer": "pause" }`
Abort a transfer	Remote Asset→ Octave Edge Device	The host requests to abort the download. An error could be returned if no download is on-going. The partial file is deleted.	Before 3.2.0: `/files/control/value` From 3.2.0: `/files/control`	`json { "name": "file name", "transfer": "abort" }`
Delete a file	Remote Asset→ Octave Edge Device	The host requests to delete a file which is available (meaning, fully deleted. To delete a file which is currently downloading, first issue an "abort" before attempting to delete. You can check this via File-sending progress.) An error could be returned if the file is not present.	Before 3.2.0: `/files/control/value` From 3.2.0: `/files/control`	`json { "name": "file name", "transfer": "delete" }`

Examples of API Requests

File API

Create File

Request

curl -X "POST" " https://octave-api.sierrawireless.io/ /v5.0/{company_name}/file" \
     -H 'X-Auth-Token: XXXX' \
     -H 'X-Auth-User: username' \
     -F "[email protected]" \
     -F "params={\"description\" : \"a description\"}"

Response

{
  "head": {
    "status": 201,
    "ok": true,
    "messages": [
      "Your request has been processed successfully. A new resource has been created."
    ],
    "errors": [],
    "references": {}
  },
  "body": {
    "id": "<id>",
    "avFileId": "<id>",
    "companyId": "<id>",
    "creationDate": <date>,
    "creatorId": "<id>",
    "description": "a description",
    "filename": "yoshi.png",
    "filetype": "image/png",
    "hash": "<hash>",
    "lastEditDate": <date>,
    "lastEditorId": "<id>",
    "path": "/farm",
    "size": 642729,
    "source": "CLOUD",
    "version": 1
  }
}

Update a File

Request

curl -X "PUT" " https://octave-api.sierrawireless.io/ /v5.0/{company_name}/{id]" \
     -H 'X-Auth-Token: XXXX' \
     -H 'X-Auth-User: username' \
     -F "[email protected]" \ 
     -F "params={}"

Response

{
  "head": {
    "status": 200,
    "ok": true,
    "messages": [],
    "errors": [],
    "references": {}
  },
  "body": {
    "id": "<id>",
    "avFileId": "<id>",
    "companyId": "<id>",
    "creationDate": <date>,
    "creatorId": "<id>",
    "description": "a description",
    "filename": "yoshi.png",
    "filetype": "image/png",
    "hash": "<hash>",
    "lastEditDate": <date>,
    "lastEditorId": "<id>",
    "path": "/farm",
    "size": 772642,
    "source": "CLOUD",
    "version": 2
  }
}

Get File

Request

curl -X "GET" " https://octave-api.sierrawireless.io/ /v5.0/{company_name}/{id]" \
     -H 'X-Auth-Token: XXXX' \
     -H 'X-Auth-User: username’ \
     -F "params={}"

Response

{
  "head": {
    "status": 200,
    "ok": true,
    "messages": [],
    "errors": [],
    "references": {}
  },
  "body": {
    "id": "<id>",
    "avFileId": "<id>",
    "companyId": "<id>",
    "creationDate": <date>,
    "creatorId": "<id>",
    "description": "a description",
    "filename": "yoshi.png",
    "filetype": "image/png",
    "hash": "<hash>",
    "lastEditDate": <date>,
    "lastEditorId": "<id>",
    "path": "/farm",
    "size": 772642,
    "source": "CLOUD",
    "version": 2
  }
}

Delete a File

Request

curl -X "DELETE" " https://octave-api.sierrawireless.io/ /v5.0/{company_name}/{id]" \
     -H 'X-Auth-Token: XXXX' \
     -H 'X-Auth-User: username'

Response

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

Send API

Get File

*Request

curl -X "POST" "" https://octave-api.sierrawireless.io/v5.0/farm/device/file/send"
 \
     -H 'X-Auth-Token: {token}\
     -H 'X-Auth-User: usnername' \
     -d $'{
  "fileIds" : {"fileId" : {"version" : 1}},
  "deviceIds" : ["{deviceId}","{deviceId}"]
}'

Response

{
  "head": {
    "status": 200,
    "ok": true,
    "messages": [],
    "errors": [],
    "references": {}
  },
  "body": {
    "id": "<id>",
    "action": "SEND_FILE",
    "companyId": "<id>",
    "complete": false,
    "creationDate": <date>,
    "creatorId": "<id>",
    "details": {},
    "deviceIds": [],
    "input": {
      "deviceIds": [
        "{deviceId}",
        "{deviceId}"
      ]
    },
    "lastEditDate": <date>,
    "lastEditorId": "<id>",
    "state": "STARTED",
    "status": {},
    "stepCount": 2,
    "timeout": 86400
  }
}

Operation API

Get File

Request

curl -X "GET" " https://octave-api.sierrawireless.io/ /v5.0/{company_name}/operation/{id]" \
     -H 'X-Auth-Token: XXXX' \
     -H 'X-Auth-User: username’ \

Response

{
  "head": {
    "status": 200,
    "ok": true,
    "messages": [],
    "errors": []
  },
  "body": {
    "companyId": "string",
    "creationDate": 1553558878392,
    "lastEditDate": 1553558878392,
    "id": "o5c37879220721249d5c8ffa3",
    "action": "TRANSFER_DEVICE",
    "complete": true,
    "state": "UNKOWN",
    "status": {
      "d5b73101dc4eaa254868f2e7b": {
        "PUSH_CONFIGURATION": {
          "state": "STARTED",
          "ts": 1553560620870
        }
      }
    }
  }
}