Getting Started

Get started using the API by creating an account using the Register option on this site. All requests to this service need to be authenticated with the user name and password you create during registration.

Overview

The WITNESS.IO service allows simulation models to be submitted, executed and model results returned to the caller. A simulation is created by first submitting a model and then creating a simulation experiment that references the model requiring execution. Once the simulation is complete, model results can be downloaded. Below is an overview of the key components that makeup this service

The WITNESS.IO service allows two types of models to be submitted for execution, WITNESS and BPMN/BPSim simulation models.

WITNESS models are submitted by uploading the .mod file. If there are associated input data files these should be added to a zip file, along with the model. The zip file is then uploaded instead of a single .mod file. Simulation replications are executed in parallel. Any outputs produced by model execution are collected and can be later accessed using the REST API.

BPMN models are submitted using the standard BPMN and BPSim (www.bpsim.org) XML model interchange format. Simulation scenarios and replications are executed in parallel. The service generates a set of result outputs for each replication, as defined by the BPSim configuration. These are added to a results zip file and placed in storage where these can be accessed using the REST API.

API Flow

The Web API is used to create, submit, check status and get results for simulations. All communications is carried out over https. The typical work flow is as follows:

Get an OAuth authentication token from the “/token” authorization endpoint. This access token needs to be included as an Authorization header for each request.
Upload the simulation model. The response contains an uri to the model location.
Create the simulation using the previously uploaded model.
The simulation will run asynchronously, use the status endpoint to check progress.
When completed, get the results using the results endpoint.

Example

Get an authentication token

Request

    POST https://hostname/token HTTP/1.1
    Content-Type: application/x-www-form-urlencoded; charset=UTF-8
    Content-Length: 68
    grant_type=password&username=alice%40example.com&password=Password1!

Response

    HTTP/1.1 200 OK
    Content-Length: 691
    Content-Type: application/json;charset=UTF-8
    {
     "access_token":"Y2A3j0x-l7KmGp...",
     "token_type":"bearer",
     "expires_in":1209599,
     "userName":"...",
     ".issued":"...",
     ".expires":"..."
    }

Upload a model

Request

    POST https://hostname/api/model HTTP/1.1
    Content-Type: multipart/form-data; boundary="043aa406-5449-4062-9cdb-3b02ea767a75"
    Authorization: Bearer Y2A3j0x-l7KmGp...
    Content-Length: 9767416
    
    --043aa406-5449-4062-9cdb-3b02ea767a75
    Content-Disposition: form-data; name=file; filename=MyModel.mod; filename*=utf-8''MyModel.mod
    
    file data

Response

    HTTP/1.1 201 Created
    Content-Length: 7247
    Content-Type: application/json; charset=utf-8
    [
     {"FileName":"MyModel.mod",
      "Location":https://hostname/models/6b650c90-9b81-4fc8-8b73-d84bda6d22ac/MyModel.mod
     }
    ]

Create an BPMN/SPSim simulation

Request

    POST https://hostname/api/lsimexperiment HTTP/1.1
    Content-Type: application/x-www-form-urlencoded
    Authorization: Bearer Y2A3j0x-l7KmGp...
    Content-Length: 158
    ModelUri=https%3A%2F%2Fhostname%2Fmodels%2Ffa7a3774-e411-4a52-a064-faaf37df3a6f%2FCar%2520Repair%2520Process%2520v0.17a.xml

Response

    HTTP/1.1 201 Created
    Content-Length: 71
    Location: https://hostname/api/experiment/ID-__-252022195044487-19250f81-f800-4d63-8a3d-44866f9482db
    "ID-__-252022195044487-19250f81-f800-4d63-8a3d-44866f9482db"

Create a WITNESS simulation

Request

    POST https:///api/witnessexperiment HTTP/1.1
    Content-Type: application/x-www-form-urlencoded
    Authorization: Bearer Y2A3j0x-l7KmGp...
    Content-Length: 6090
    
    ModelUri=https%3A%2F%2Fhostname%2Fmodels%2F6b650c90-9b81-4fc8-8b73-d84bda6d22ac%2FMyModel.zip&Runlength=10020.0&Warmup=10020.0&Replications=10

Response

    HTTP/1.1 201 Created
    Content-Length: 71
    Location: https://hostname/api/experiment/ID-__-252022195044487-19250f81-f800-4d63-8a3d-44866f9482db
    "ID-__-252022195044487-19250f81-f800-4d63-8a3d-44866f9482db"

Check the simulation status

Request

    GET https://hostname/api/experiment/ID-__-252022196743881-06b3b6a0-0687-4c14-83b2-43643020344d/status HTTP/1.1
    Authorization: Bearer Y2A3j0x-l7KmGp...

Response

    HTTP/1.1 200 OK
    Completed

Download the simulation results

Request

    GET https://hostname/api/experiment/ID-__-252022196743881-06b3b6a0-0687-4c14-83b2-43643020344d/results HTTP/1.1
    Authorization: Bearer Y2A3j0x-l7KmGp...

Response

    HTTP/1.1 200 OK
    Content-Length: 40182
    Content-Type: application/xml; charset=utf-8
    <arrayofreplicationresult xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/Lanner.Server.Experimentation.Entities">
        <replicationresult>
            <modelloguri>https://hostname/MyModel_R000.log</modelloguri>
            <modelresultsuri>https://hostname/MyModel_R000.zip</modelresultsuri>
            <replication>0</replication>
            <scenario>scenario1</scenario>
        </replicationresult>
        <replicationresult>
            <modelloguri>https://hostname/MyModel_R001.log</modelloguri>
            <modelresultsuri>https://hostname/MyModel_R001.zip</modelresultsuri>
            <replication>1</replication>
            <scenario>scenario1</scenario>
        </replicationresult>
    </arrayofreplicationresult>

Endpoints

For more information on the REST endpoint available and their parameters, please see the API reference.