Run Persistence and APIs

In Epicenter, a "run" is a collection of interactions with the project and its model. Every time an end 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. See more information on:

• Runs in memory
• Runs in the database
• Getting runs from memory into the database
• Getting runs from the database back into memory

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.

Characteristics of a run retrieved from memory include:

• All model operations can be called on the run.
• All model variables are available in responses.
• The Pragma field of the response header is not present.
• The active field of the run record is true.

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).

Characteristics of a run retrieved from the database include:

• Model operations cannot be called on the run.
• Only model variables that have explicitly been saved are available in responses.
  • In Python you save model variables by adding an Epicenter.record() call to the model whenever the variable should be saved — for instance, at the end of a model operation.
  • In Vensim, Stella, SimLang, and Powersim, you save model variables by adding a line to your model context file. Then, the variables are saved at each step as the model advances.
• The Pragma field of the response header is present and set to persistent.
• The active field of the run record is false.

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.

Removing Runs from Memory

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.

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.

Runs can be brought back into memory using the autoRestore configuration option (defaults to true) or the X-AutoRestore header.

Additionally, runs can brought back into memory explicitly, either with the same run id or with a new run id, by means of the Model State API.

Bringing Runs into Memory (Interface Builder, JavaScript)

If you are using the Interface Builder, Flow.js, or Epicenter.js, runs are automatically restored to memory (via replay) when you:

• look up a run or its variables,
• update variables,
• or call operations.

You can turn off this default behavior by setting the Epicenter.js Run Service config option autoRestore to false.

Bringing Runs into Memory (Run API)

If you are using the RESTful Run API, runs are automatically restored to memory (via replay) when you:

• update variables (PATCH),
• or call operations (POST).

When you look up a run or its variables, 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:

// gets run from memory if available, otherwise from database
curl -G \
'https://api.forio.com/v2/run/acme/supply-chain-game/0000015c306863c1a1889316c9ab366f711d/variables?include=Price,Sales' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \

// or any request of the form: "/v2/run/team id/project id/run id/"

You can force this form of request to replay a run, bringing it back into memory, by adding the X-AutoRestore header to your request:

// gets run from memory, bringing it into memory if it's not there
curl -G \
'https://api.forio.com/v2/run/acme/supply-chain-game/0000015c306863c1a1889316c9ab366f711d/variables?include=Price,Sales' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \
--header 'X-AutoRestore: true'

However, any request that specifies a filter retrieves the runs from the database, whether or not the runs are also available in memory. This is true regardless of whether you are using an X-AutoRestore: true header. For example:

// gets run(s) from the database, always
curl -G \
    'https://api.forio.com/v2/run/acme/supply-chain-game/;saved=true/variables?include=Price,Sales' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \

// or any request of the form: "/v2/run/team id/project id/filter"