forio Toggle navigation

Run Persistence and APIs

In Epicenter, a "run" is a collection of interactions with the project and its model. Every time a user wants to interact with a project, you as the project author need to create a new run using one of the Epicenter APIs.

Working with runs requires some knowledge about how runs are stored.

Runs in Memory

A run that is created in the current browser session is stored in memory on the Epicenter servers.

Runs must be in memory in order for you to update variables or call operations on them.

A run is removed from memory either when the session times out, or when the run is explicitly deleted from the session. The session timeout is configurable in the project's Settings, under Model Session Timeout.

Each run is automatically restored to memory (via replay) when you update variables (PATCH) or call operations (POST).

Additionally, you can optionally replay a run, bringing it into memory, whenever you look it up (GET). To replay on GET requests, add a header to your request. (This is true by default, but can be configured, if you are using the Epicenter.js Run Service.)

Any request that specifies a particular run id directly in the URI retrieves the run from memory if available, but from the database if not in memory. For example:

  • GET /model/run/{run id}/
  • GET /run/{account id}/{project id}/{run id}

This is true for the Model APIs, the Run API, and the JavaScript frameworks Epicenter.js and Flow.js.

Characteristics

Characteristics of a run retrieved from memory include:

  • All exposed operations (e.g. for Julia models, methods that are exported) can be called on the run.
  • The Pragma field of the response header is not present.
  • The active field of the run record is true. (However, note that you can only see the active field if you add the query parameter ?include=active to your request.)
  • All exposed variables (e.g. for Julia models, variables that are exported) are available in responses. For example:
    • curl -G 'https://api.forio.com/model/variable/myRunId/myVarName' and
    • curl -G 'https://api.forio.com/run/myAccountId/myProjectId/myRunId?include=myVarName' both include exposed variable myVarName in the response body.

Runs in the Database

Any run that has at some point been persisted into the Epicenter database is available for lookup from the database (whether or not that run is also currently in memory).

Any request that specifies one or more run ids (or a filter for run ids) as query parameters retrieves the runs from the database, whether or not the runs are also available in memory. For example:

  • GET /model/run?id={run id1}&id={run id2}
  • GET /run/{account id}/{project id}/;id={run id}

Characteristics

Characteristics of a run retrieved from the database include:

  • Operations cannot be called on the run.
  • The Pragma field of the response header is present and set to persistent.
  • The active field of the run record is false. (However, note that you can only see the active field if you add the query parameter ?include=active to your request.)
  • Only variables that have explicitly been saved (e.g. for Julia models, variables that are recorded during a method that has been called on the model) are available in responses. For example:
    • curl -G 'https://api.forio.com/model/variable/myRunId/myVarName' and
    • curl -G 'https://api.forio.com/run/myAccountId/myProjectId/myRunId?include=myVarName' only include the variable myVarName in the response body if myVarName has been explicitly saved (with record, for a Julia model).

Getting Runs from Memory to the Database

All runs are persisted from memory to the Epicenter backend database immediately upon creation: the run properties (account, created, lastModified, etc.) are persisted.

Additionally, all runs in memory are periodically persisted from memory back to the Epicenter backend database approximately every 30 seconds. The frequency of the persistence interval is set by the Epicenter Distributed Model Service and is not configurable by Epicenter authors.

Runs are removed from memory (and so only available in the database) based on the Model Session Timeout, which is configurable in the project's Settings.

Getting Runs from the Database to Memory

Runs that are in the database, but are not currently in memory, can be looked up from the database. Additionally, they can brought back into memory, either with the same run id or with a new run id, by means of the Model State API.