meta data for this page

Back to JESS API

Run a Simulation Using Existing Model Files


Use POST /job with a command object to create a new simulation using the model files that are already on the server, either in the user's storage area or from an existing job.

Synopsis

Job Command Object

A Job Command Object has the following fields:

Field Value Description
cmd Creat In the current version, the cmd field can only be Create
caption text Caption of the job
description text Description of the job
uploadRef text The path to the folder in the user's storage area, from which the model files are to be copied
jobRef number The job ID of the reference job from which the model files are to be copied
main text For E+ jobs, main is the IDF model file name. For jEPlus project, main is the project file name
weatherRef array A list of weather file names
split boolean Applies only to E+ jobs - whether or not to use the run-period split method
subset DEFAULT default: Run the project as defined in the project file
ALL Override the run option in the project and run all the jobs instead
LIST_FILE Override the run option in the project and run the cases defined in the case list file (specified in the next field)
caseList array Case list file name to use with the LIST_FILE option of the subset field

The example below shows a command object for creating an E+ job whilst all fields are shown. 

 {
    "cmd": "Create",
    "caption": "My job",
    "description": "Example job",
    "uploadRef": "/abc/example_e+v93",
    "jobRef": 0,
    "main": "5ZoneAirCooled-v93.idf",
    "weatherRef": ["in.epw"],
    "split": false,
    "subset": "DEFAULT",
    "caseList": []
 }

From User's Uploads

Use the following command object, with a Create command, to create a new simulation job on JESS using the model files in the user's storage area. The model files should have been uploaded to the storage area using POST /files transaction in the Users API. 

 {
    "cmd": "Create",
    "uploadRef": "/abc/example_e+v93",
    "weatherRef": ["in.epw"],
    "main": "5ZoneAirCooled-v93.idf"
 }

To Run a jEPlus Project

Use the following command object with a Create command to create a new jEPlus job on JESS using the project files in the user's storage area. The files should have been uploaded to the storage area using POST /files transaction in the Users API. 

{
    "cmd": "Create",
    "uploadRef": "example_jep_v81",
    "weatherRef": [],
    "main": "project.jep"
}

From an Existing Job

Use the following command object, with a Create command, to create a new simulation job on JESS using the model files of an existing job. This is useful if you want to run a different set of cases of a jEPlus project. 

 {
    "cmd": "Create",
    "caption": "Re-run",
    "description": "re-run of job 12250",
    "jobRef": 12250,
    "main": "project.json",
    "subset": "LIST_FILE",
    "caseList": ["jobs.txt"]
 }

Return object

A successful return object contains the status flag, a message, and the job ID of the new job, as shown in the example below. 

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

Authorization Failed

An HTTP 401 - Unauthorized response will be received

Example using curl://

Assuming the session token has been saved in the cookies file using the log on command, start a simulation job using curl on Linux as below: 

curl -b cookies -H 'Content-Type: application/json' -X POST -d '{"cmd": "Create", "uploadRef": "/abc/example_e+v93", "weatherRef": ["in.epw"], "main": "5ZoneAirCooled-v93.idf"}' https://api.ensims.com/jess_web/api/job

On Windows: 

curl -b cookies -H "Content-Type: application/json" -X POST -d "{\"cmd\": \"Create\", \"uploadRef\": \"/abc/example_e+v93\", \"weatherRef\": [\"in.epw\"], \"main\": \"5ZoneAirCooled-v93.idf\"}" https://api.ensims.com/jess_web/api/job

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

Example using Python Requests

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

import requests

headers = {'Content-Type': 'application/json'}
body = {"cmd": "Create", "uploadRef": "/abc/example_e+v93", "weatherRef": ["in.epw"], "main": "5ZoneAirCooled-v93.idf"}

# 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', headers=headers, json=body, cookies=cookies)

# Show return info
r.json()