Getting Started with OLI Process API

Updated September 17, 2024 21:06

This guide introduces OLI ProcessAPIs, highlighting their capabilities and applications. It provides instructions for authentication, chemistry package generation and upload, input data updates, and Process simulation initiation using APIs. The guide includes an example workflow and references to developer documentation, enabling users to start using OLI ProcessAPIs in their projects.

Overview of OLI ProcessAPI

The OLI ProcessAPI offers a streamlined way for users to run process simulations within the OLI cloud environment, providing access to OLI's powerful simulation tools through a flexible and scalable API.

Key features include:

Cloud File Upload: Users can upload and store Flowsheet package files in the OLI cloud, either in private data stores or shared channels for collaboration. After uploading, users can initiate simulations using the unique package ID.
Input Data Modification: The API allows users to update simulation inputs, such as unit operations, controllers, streams, and water analysis, through a JSON specification file. The inputspec endpoint returns the default specification for the given package ID in JSON format. This file can then be modified by updating inflows and properties as needed.
Cloud Simulation Execution: Users can initiate a Process calculation by sending the updated JSON specification along with the Process package ID to the Process API endpoint. The API returns a resultLink, which can be polled through HTTP requests to retrieve the simulation results. ProcessAPI supports running multiple simulations concurrently, with the maximum number determined by the user's license type.

ProcessAPI Workflow

Follow these steps to integrate the OLI ProcessAPI into your application:

Step 1: Export the Flowsheet Case File

In the OLI Flowsheet software, export your case file as a Process API package file:

Go to File → Export
Choose Process API pkg. Files (*.pkg) as the Save as Type
Save the exported .pkg file

The Flowsheet case file contains the process simulation specification. Exporting it as a package allows it to be uploaded and used with the ProcessAPI.

Step 2: Authenticate and Get Access Token

To use the ProcessAPI, you first need to authenticate and get an access token:

Login using your username and password to the OLI API Authentication endpoint.
The response will contain an access_token. Use this token in the Authorization header for all subsequent API requests.

For more details, refer to the Authentication Documentation.

Step 3: Upload the Flowsheet Package File

Upload the exported Flowsheet package file to the ProcessAPI:

url = "<https://api.olisystems.com/channel/upload/package?status=published>"

payload = {}
files=[
  ('files',('flowsheet.pkg',open('/path/to/flowsheet.pkg','rb'),'application/octet-stream'))]
  
Authorization: Bearer {access_token}

The response will contain a process PKG id. Save this ID, as it will be used to reference your uploaded package in subsequent calculation requests.

Note: If you modify your Flowsheet case file, you'll need to re-export and re-upload it to get a new id.

For more details, refer to the Uploading Package Documentation.

Step 4: Retrieve Process Input Specifications

To get the input specification details for your uploaded process:

GET <https://api.olisystems.com/process/inputspec/{id}>
Authorization: Bearer {access_token}

The response is a JSON object reflects your process case file specification, with default values for the unit and stream inputs as defined in the Flowsheet case file.

Save this JSON object, as it will be used as the basis for configuring your simulation inputs in the next step.

For more details, refer to the Input Spec Documentation.

Step 5: Configure Simulation Inputs and Run Calculation

To run a ProcessAPI calculation:

Update the JSON object from Step 4 with your desired input values for the process units and streams. Only modify the values you want to change - any omitted properties will use the defaults from the Flowsheet case file.
The input properties for blocks, streams, and water analysis are located in the data.flowsheet.properties.input section of the JSON object. Only update the necessary properties within this section.

Send a POST request to the calculation endpoint, passing the updated properties section from the JSON object as the request body:

POST <https://api.olisystems.com/process/run/{id}>
Content-Type: application/json
Authorization: Bearer {access_token}

payload = json.dumps({
  "properties": {
    "input": {
      ...updated flowsheet properties section in JSON...
    }
  }
})

The response will contain a resultsLink URL. Use this link to poll for the calculation results in the next step.

For more details, refer to the Calculation Documentation.

Step 6: Retrieve Calculation Results

To get the results of your ProcessAPI calculation:

Poll the resultsLink URL from Step 5 until the status field changes from IN QUEUE or IN PROGRESS to one of:
- PROCESSED
- COMPLETED
- FAILED
- ERROR
```
GET {resultsLink}
Authorization: Bearer {access_token}
```
Once the status becomes PROCESSED or COMPLETED, the response will contain the full calculation results as a JSON object.

For more details, refer to the Results Documentation.

Important Considerations and Version Compatibility for OLI ProcessAPI

Process PKG Creation : A PKG file can only be generated using OLI Flowsheet desktop application at this time. The ChemBuilder API can’t be used to generate the PKG file required to run the ProcessAPI calculations.
Version Compatibility : It's important to ensure version compatibility between the OLI Flowsheet desktop application and the OLI Process API:
- The version of the OLI Flowsheet desktop application used to create the PKG file should match the version of the OLI Process API used by the user.
- You can specify the ProcessAPI version for your cloud calculation using the engineVersion header tag.

Example of setting the Process API version in an API request:

headers = {
    'Authorization': 'Bearer your_access_token',
    'Content-Type': 'application/json',
    'engineVersion': '12.0.0.11'
}

Ensuring version compatibility helps prevent potential issues with API requests.

By following these steps, you will be able to perform Process calculations using OLI APIs. If you have any questions or need the Python starter kit for EngineAPI, please contact OLI Customer Support.

Additional Resources

Related to

cloud APIs