ARES CLI - Execute bim2pdf Jobs via API

This document explain what steps are required to setup and call jobs that allow use CLI Service API to input a BIM model (Revit or IFC files) and produce the PDF with 2D drawings with annotations (dimensions, labels and materials).

1. Generate API Token

Access the Tokens tab after logging in to https://arescli.graebert.com/ platform. If this is your initial login to Graebert’s portal, you might have to register and revisit the https://arescli.graebert.com/ page post email verification. Proceed by clicking on 'Generate new API key,' then copy and apply it to the designated API endpoints.

2. Load Environment

Call the POST method on /{type}/upload, specifying type = environment to upload the .zip file. Retrieve the response environment ID for utilization in job execution. Upon successful loading of this environment, reloading is unnecessary unless customization is needed.

The complete API CLI Service documentation can be find here.

3. Load File

Call the POST endpoint /{type}/upload, where type = file, to upload the file that needs to be processed (either .rvt file or .ifc). Obtain the response file ID for use during job execution. Remember, each time you have a new file that needs processing, it must be uploaded before executing the job.

4. Execute Job

Call the POST /execute method to establish and execute a fresh task.
Complete the following fields:

Set "environment:" to the corresponding environment ID.
Assign "configuration:" with the configuration string (refer to the details displayed in the right panel).
Specify "files:" as per file ID.

Within the configuration string, ensure that you substitute BIM_Input variable's value with the specific name of the file intended for processing (the uploaded file dispatched via files for execution endpoint).

{
    "Inputs": {
        "comment": "the input file format as uploaded on the ARESCLI portal Environment NOTE: should be same of script var BIM_input in the script section for this script",
        "inputfileformat": "rvt",
        "script": {
            "comment": "location and extension of the script as uploaded on the ARESCLI portal Environment. Also the variables used the script are defined in this section",
            "scriptpath": "scripts/bim2pdf.scr",
            "scriptformat": "scr",
            "scriptvariables": [{
                "name": "OUTPUTDIR",
                "value": "output.dwg",
                "comment":"name of the desired output file, NOTE: this name should be same as the first name of the outputfilename(extension should be dwg) in Outputs section"
            },
            {
                "name": "BIM_input",
                "value": "input.rvt",
                "comment":"name of the rvt file as uploaded on the ARESCLI portal, NOTE:this is not the fileId" 
            },
            {
                "name": "BIM_AUTO_TEMPLATE",
                "value": "templates/bimautotemplates/ISO_A1_Landscape(1_100)_Header_wfields.dwg",
                "comment":"location of the bim templates in zip uploaded on the ARESCLI portal Environment"

            }]
        },
        "templates": {
            "comment": "location of the templates in zip and their extensions as uploaded on the ARESCLI portal Environment",
            "drawingtemplate": "templates/drawingtemplates/standardiso_mm.dwt",
            "drawingtemplateformat": "dwt",
            "bimautotemplates": "templates/bimautotemplates/ISO_A1_Landscape(1_100)_Header_wfields.dwg", 
            "bimautotemplatesformat": "dwg"
        }
    },
    "Outputs": {
        "outputfileformat": "pdf",
        "outputfilename": "output.pdf",
        "comment": "name of the desired output file NOTE: the name of file without the extension should be same as the script var OUTPUTDIR for this bim2pdf script"
    }
}

6. How to track Job status

Call the endpoint GET /jobs/{jobId}/download/{type}/{jobid} to monitor the progress of the job.

The possible status are:

PENDING
COMPLETE
FAILURE

7. Download job result

Call the endpoint GET /jobs/{jobId}/download/{type} endpoint by specifying type = result to retrieve the output file. If the job encountered an issue, access files with type = log and type = zip to analyze the error further.