The easySSP Integration API provides access for external applications to integrate with orchideo | easySSP to utilize its model editor and simulation capabilities based on SSP and related standards. The easySSP Integration API provides a collection of APIs that support dedicated integration/usage scenarios.

Currently, the following APIs are available:

  • Import-Export API: The API lets you import and export SSP-files into/from orchideo | easySSP

  • Simulation API: The API lets you simulate SSP-files with included FMI 2.0 components in the cloud

Authentication

To access the easySSP Integration API a client application needs to authenticate on behalf of an existing easySSP-User against easySSP’s authentication service. When authenticated successfully, an OpenId Connect (OIDC) Access Token is issued that must be provided when accessing an easySSP Integration API.

Acquiring Access Tokens

Authentication Flow

easySSP uses the OAuth 2.0 Authorization Code Flow with Proof Key for Code Exchange (PKCE) for authentication. We strongly recommend to use an Open Id Connect (OIDC) client library to implement the flow. You can find OIDC client libraries for different programming languages here.

The simplified authentication process is as follows:

Typical process scenario

  1. The client application uses the OIDC client library to authenticate with the PKCE authentication flow against the easySSP authentication service for a specific easySSP Integration API (e.g. Import-Export API or Simulation API)

  2. The OIDC client opens the easySSP login in the web browser where the user hase to provide his/her easySSP credentials to approve access on his/her behalf.

  3. On successful authentication the OIDC client returns an access token for the requested client-id (see info below), that the client application stores for further usage.

The access token must be provided as bearer authentication header on subsequent easySSP Integration API calls.

It is important to clarify that an access token only allows access to a specific easySSP Integration API. The concrete API is defined by a so called client-id, which has to be provided in the authentication request.

Currently, the following client-ids are available:

  • import-export-api: Provides access to the easySSP Import-Export API

  • simulation-api: Provides access to the easySSP Simulation API

This is the OIDC client configuration JSON needed to request access to the easySSP Import-Export API:

{
  "realm": "exxcellent",
  "auth-server-url": "https://easy-ssp.com/",
  "ssl-required": "external",
  "resource": "import-export-api",
  "public-client": true,
  "use-resource-role-mappings": true,
  "enable-pkce": true
}

We can provide a Java code sample that demonstrates an exemplary easySSP API integration, just contact us at easy-ssp(at)exxcellent.de.

Question & Answers

  1. How long is an access token valid?

    The access token is valid for 24 hours. That means the token can be used to access the easySSP Integration API for this period before the user has to approve access again.

  2. How can I check if an issued access token is still valid?

    The issued access token conforms to the JSON Web Token (JWT) standard. JWT libraries let you check if the token is valid or expired.

Import-Export API

The Import-Export API lets you import and export SSP-models into/from orchideo | easySSP.

Precondition

A user needs an active orchideo | easySSP Pro or Process Edition user account in order to be able to use the easySSP Import-Export API.

Typical Usage Scenario

A typical usage scenario might look like this:

A user wants to view/edit an SSP model that is stored in a data management system (here called client application) in orchideo | easySSP. When the edit is done the user imports the model again in the data management system.

The process flow for this scenario is as follows:

Typical process scenario

  1. The user triggers the edit for a SSP-model in the client application. The client application requests an access token to access the easySSP Import-Export API, if necessary (see authentication chapter)

  2. The client application imports the SSP-model as .ssp file into easySSP using the /ssp route of the easySSP Import-Export API. easySSP loads the SSP-Model and returns a Model-ID and a Model-URL for it as response

  3. The client application opens the returned Model-URL in the web browser. Now the user can view and edit the imported SSP model in orchideo | easySSP.

  4. When the edit is done, the user triggers the reimport of the model in the client application. The client application loads the current model state using the /ssp/{Model-ID} route of the easySSP Import-Export API and stores the data.

API Documentation

Here you can find the API documentation of the Import-Export API:

Import-Export API Documentation

Question & Answers

  1. Is it possible to download an imported SSP-Model more than once using the /ssp/{Model-ID} route?

    Yes this is possible, as long as the model storage duration is not exceeded (see next question).

  2. How long does easySSP provide access to an imported model?

    An SSP-Model is automatically deleted if the last change was more than 24 hours ago.

Simulation API

The Simulation API lets you simulate SSP-files with included FMI 2.0 components in the cloud.

Precondition

  • A user needs an active orchideo | easySSP Pro Edition account in order to be able to use the easySSP Simulation API.

  • easySSP’s simulation engine works quota based. Before you can start a simulation the simulation credits needed are calculated depending on the number of selected simulation runs, the selected hardware resources, the selected maximum simulation duration and other internal factors like compute-, traffic- and storage costs for simulation creation and execution. The simulation can only be started, if the user has sufficient simulation quota and when started, the calculated simulation costs are deducted from the user’s simulation quota. If the simulation finishes before the predefined maximum simulation duration, e.g. because the simulation terminated on it‘s own or the user stopped the simulation, unconsumed simulation credits are automatically refunded to the user’s simulation quota and can be used in new simulations again. If you want to receive more simulation credits, those can be obtained at the moment by contacting easy-ssp@exxcellent.de.

Usage Scenario

A common usage scenario might look like this:

A user wants to execute several simulations in parallel with no load on the computer and evaluate/compare the results.

This can incorporate:

  • Simulation of different model variants (e.g. for high/low fidelity implementation or different parameterization)

  • Simulation of a model with different input stimuli

  • Simulation of a model for different targets (Windows 32, Windows 64, Linux 32 and Linux 64)

The Simulation API allows to freely combine these aspects by so-called simulation runs with dedicated hardware resources per run.

A typical simulation execution flow is as follows:

Typical process scenario

  1. The user prepares a SSP-file containing all models and FMUs he wants to simulate.

  2. The simulation client requests an access token to access the easySSP Simulation API, if necessary (see authentication chapter) and requests the available simulation options.

  3. The user configures the simulation and its runs for the SSP-file based on the available simulation options. The simulation client starts the simulation through the Simulation API.

  4. During execution the user can see simulation details, like status, logs and intermediate results by requesting them from the Simulation API.

  5. Optional: The user can view and manage the created simulations in the Simulation Integration UI or can stop them through the API.

  6. When the simulation (or a run) is finished, its result can be downloaded through the Simulation API.

  7. Optional: The user can delete finished simulations (or runs). Otherwise, they are automatically deleted, if the storage period has expired (see Q&A).

API Documentation

Here you can find the API documentation of the Simulation API:

Simulation API Documentation

Question & Answers

  1. How long does easySSP provide access to a simulation?

    A simulation is automatically deleted 5 days after it was created.