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

Method: POST
Target: https://api.ensims.com/jess_web/api/job
Cookies: JWT session token
Header: Set Content-Type to application/json
Body: Job command object
Success: Job creation return object
Failed: HTTP 401 - Unauthorized

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()

Table of Contents