Upload and Run a Simulation Job Directly

Use POST /job with multi-part form data to upload model files and set up a new simulation in one transaction.

• Method: POST
• Target: https://api.ensims.com/jess_web/api/job
• Cookies: JWT session token
• Header: none
• Body: Submission form data (encoding: multi-part form data)
• Success: Return object
• Failed: Submision failed object or HTTP 401 - Unauthorized

The direct submit and run transaction can be used to run both EnergyPlus simulations and jEPlus projects. The form's data fields vary for different jobs to run. Files can be uploaded directly, or in a pre-packed zip archive.

You can upload both files are they are, using multiple file fields, or packed the files in a zip archive first, and then upload the zip file. The latter is particularly useful for a jEPlus project where more than a handful of files are involved. JESS will unpack the zip archive once it is received.

To create an EnergyPlus simulation job, at least one IDF and one EPW files need to be uploaded.

The relevant fields include:

To create a jEPlus job, all files that the jEPlus project contains must be uploaded, hence it is easier to pack them in a zip archive rather than using multiple file fields.

JESS supports Radiance Rtrace and Rpict jobs. To create a Radiance job, all files that the simulation job depends on must be uploaded. They can be uploaded using multiple file fields or as a packed zip archive.

JESS supports DaySim jobs. To create a DaySim job, all files that the simulation job depends on must be uploaded. These typically include various Radiance model files (.rad), a weather file, sensors grid, and occupancy schedule etc. It would be easier to upload a zip archive rather than using multiple file fields.

A successful return object contains the status flag, a message, and a data field containing the ID of the newly created job, as shown in the example below.

{
    "ok": true,
    "status": "Job 12248 is created",
    "data": 12248
}

The returned object does not show whether or not the job will simulate successfully. To get the information on the job's status, use GET /job/status.

An HTTP 401 - Unauthorized response will be received

Assuming the session token has been saved in the cookies file using the log on command, send the confirm command using curl on Linux as below:

curl -b cookies -F 'file=@job_example/5ZoneAirCooled-v93.idf' -F 'file=@job_example/in.epw' -F 'title=Test job' -F 'desc=Test upload and run' -F 'model=5ZoneAirCooled-v93.idf' -F 'weather=in.epw' -F 'split=FALSE' https://api.ensims.com/jess_web/api/job

On Windows:

curl -b cookies -F "file=@job_example/5ZoneAirCooled-v93.idf" -F "file=@job_example/in.epw" -F "title=Test job" -F "desc=Test upload and run" -F "model=5ZoneAirCooled-v93.idf" -F "weather=in.epw" -F "split=FALSE" https://api.ensims.com/jess_web/api/job

Or, to pack the input files in a zip archive and upload with one -F 'file=@…' on Linux:

zip -j upload.zip job_example/*
curl -b cookies -F 'file=@upload.zip' -F 'title=Test job' -F 'desc=Test upload and run' -F 'model=5ZoneAirCooled-v93.idf' -F 'weather=in.epw' -F 'split=FALSE' https://api.ensims.com/jess_web/api/job

On Windows:

zip -j upload.zip job_example/*
curl -b cookies -F "file=@upload.zip" -F "title=Test job" -F "desc=Test upload and run" -F "model=5ZoneAirCooled-v93.idf" -F "weather=in.epw" -F "split=FALSE" https://api.ensims.com/jess_web/api/job

If the submission is successful, a confirmation object will be returned with the new job ID. If the session token is invalid, an HTTP 401 code will be returned.

This example shows how to run a jEPlus project with a job-list file, on Linux:

curl -b cookies -F 'file=@upload_jep.zip' -F 'title=Test jE+ job' -F 'desc=Test upload and run' -F 'model=project.json' -F 'subset=LIST_FILE' -F 'cases=jobs.txt' https://api.ensims.com/jess_web/api/job

On Windows:

curl -b cookies -F "file=@upload_jep.zip" -F "title=Test jE+ job" -F "desc=Test upload and run" -F "model=project.json" -F "subset=LIST_FILE" -F "cases=jobs.txt" https://api.ensims.com/jess_web/api/job

Or, if the zip file contains the root folder, it should be run as this, on Linux:

curl -b cookies -F 'file=@Shoebox_v8.9.zip' -F 'title=Test jE+ job' -F 'desc=Test upload and run' -F 'model=Shoebox_v8.9/project.json' -F 'subset=LIST_FILE' -F 'cases=Shoebox_v8.9/jobs.txt' https://api.ensims.com/jess_web/api/job

On Windows:

curl -b cookies -F "file=@Shoebox_v8.9.zip" -F "title=Test jE+ job" -F "desc=Test upload and run" -F "model=Shoebox_v8.9/project.json" -F "subset=LIST_FILE" -F "cases=Shoebox_v8.9/jobs.txt" https://api.ensims.com/jess_web/api/job

Make sure Requests is correctly installed in your Python environment, and run the following lines:

import requests

files = [
    ('file', ('5ZoneAirCooled-v93.idf', open('job_example\\5ZoneAirCooled-v93.idf', 'rb'), 'text/plain')),
    ('file', ('in.epw', open('job_example\\in.epw', 'rb'), 'text/plain')),
    ('title', 'Test job'),
    ('desc', 'This is test submission made from python example'),
    ('model', '5ZoneAirCooled-v93.idf'),
    ('split', 'FALSE'),
    ('weather', 'in.epw')
]

# Make a post request. Session token must be available in the saved cookies during log-on
r = requests.post('https://api.ensims.com/jess_web/api/job', files=files, cookies=cookies)

# Show return info
r.json()