Jobs

Tasks that require significant time to execute or process a large amount of input or output are categorized as jobs. Job execution can be time-consuming, but its progress can be monitored.

To monitor the progress of running jobs, subscribe to the core.get_jobs event.

When a new job is initiated through a JSON-RPC 2.0 API call, its message_ids field will include the id of the call. Therefore, when starting a new job, the client should listen for the added event in the core.get_jobs subscription. Additionally, the client should monitor changed events because a changed event with a new message_ids field value may be emitted if a method call triggers a job that has already been scheduled.

Example of Calling a Job Method

The client initiates a method call:

{
    "jsonrpc": "2.0",
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "method": "filesystem.copy",
    "params": ["/mnt/tank/src", "/mnt/tank/dst"]
}

The server responds with the newly added job (e.g. id 101):

{
    "jsonrpc": "2.0",
    "method": "collection_update",
    "params": {
        "msg": "added",
        "collection": "core.get_jobs",
        "fields": {
            "id": 101,
            "message_ids": ["6841f242-840a-11e6-a437-00e04d680384"],
            ...
        }
    }
}

Then, it updates the progress:

{
    "jsonrpc": "2.0",
    "method": "collection_update",
    "params": {
        "msg": "changed",
        "collection": "core.get_jobs",
        "fields": {
            "id": 101,
            "progress": {
                "percent": 50,
                "description": "Copied 1000000 of 2000000 bytes"
            },
            ...
        }
    }
}

Finally, it sends the method execution result as usual:

{
    "jsonrpc": "2.0",
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "result": true
}

Query Job Status

Job status can be queried with the core.get_jobs method.

Request:

:::javascript {

“id”: “d8e715be-6bc7-11e6-8c28-00e04d680384”, “msg”: “method”, “method”: “core.get_jobs”, “params”: [[[“id”, “=”, 53]]]

}

Response:

:::javascript {

“id”: “d8e715be-6bc7-11e6-8c28-00e04d680384”, “msg”: “result”, “result”: [{“id”: 53, “method”: “catalog.sync_all”, “arguments”: [], “logs_path”: null, “logs_excerpt”: null, “progress”: {“percent”: 100, “description”: “Syncing TEST catalog”, “extra”: null}, “result”: null, “error”: null, “exception”: null, “exc_info”: null, “state”: “SUCCESS”, “time_started”: {“$date”: 1571300596053}, “time_finished”: null}]

}

Uploading / Downloading Files

There are some jobs which require input or output as files which can be uploaded or downloaded.

Downloading a File

If a job gives a file as an output, this endpoint is to be used to download the output file.

Request:

:::javascript {

“id”: “d8e715be-6bc7-11e6-8c28-00e04d680384”, “msg”: “method”, “method”: “core.download”, “params”: [“config.save”, [{}], “freenas-FreeNAS-11.3-MASTER-201910090828-20191017122016.db”]

}

Response:

:::javascript {

“id”: “cdc8740a-336b-b0cd-b850-47568fe94223”, “msg”: “result”, “result”: [86, “/_download/86?auth_token=9WIqYg4jAYEOGQ4g319Bkr64Oj8CZk1VACfyN68M7hgjGTdeSSgZjSf5lJEshS8M”]

}

In the response, the first value 86 is the job id for config.save. This can be used to query the status of the job. The second value is a REST endpoint used to download the file.

The download endpoint has a special format:

http://system_ip/_download/{job_id}?auth_token={token}

job_id and token are parameters being passed.

core.download takes responsibility for providing the download URI with the job_id and token values.

Note: 1) Job output is not buffered, so execution would be blocked if a file download is not started. 2) File download must begin within 60 seconds or the job is canceled. 3) The file can only be downloaded once.

Uploading a File

Files can be uploaded via HTTP POST request only. The upload endpoint is:

http://system_ip/_upload

It expects two values as form data, data and file.

data is JSON-encoded data. It must be the first parameter provided and in this format:

::: json {

“method”: “config.upload”, “params”: []

}

file is the URI of the file to download.

This example uses curl,

Request:

curl -X POST -u root:freenas -H “Content-Type: multipart/form-data” -F ‘data={“method”: “config.upload”, “params”: []}’ -F “file=@/home/user/Desktop/config” http://system_ip/_upload/

Response:

{“job_id”: 20}