forio Toggle navigation

Run Manager Strategies

The Run Manager gives you control over run creation, depending on run state. You can select run creation stratgies (rules) for which runs end users of your project work with when they log in to your project.

There are several strategies included in Epicenter.js:

You can also create your own strategy and see more details on working with Run Strategies.

reuse-never

a.k.a always-new

The reuse-never strategy always creates a new run for this end user irrespective of current state. This is equivalent to calling F.service.Run.create() from the Run Service every time.

This strategy means that every time your end users refresh their browsers, they get a new run.

This strategy can be useful for basic, single-page projects. This strategy is also useful for prototyping or project development: it creates a new run each time you refresh the page, and you can easily check the outputs of the model. However, typically you will use one of the other strategies for a production project.

reuse-per-session

a.k.a new-if-missing

The reuse-per-session strategy creates a new run when the current one is not in the browser cookie.

Using this strategy means that when end users navigate between pages in your project, or refresh their browsers, they will still be working with the same run. However, if end users log out and return to the project at a later date, a new run is created.

This strategy is useful if your project is structured such that immediately after a run is created, the model is executed completely (for example, a Vensim model that is stepped to the end as soon as it is created). In contrast, if end users play with your project for an extended period of time, executing the model step by step, the reuse-across-sessions strategy is probably a better choice (it allows end users to pick up where they left off, rather than starting from scratch each browser session).

Specifically, the strategy is:

  • Check the sessionKey cookie.
    • This cookie is set by the Run Manager and configurable through its options.
    • If the cookie exists, use the run id stored there.
    • If the cookie does not exist, create a new run for this end user.

reuse-across-sessions

a.k.a persistent-single-player

The reuse-across-sessions strategy returns the latest (most recent) run for this user, whether it is in memory or not. If there are no runs for this user, it creates a new one.

This strategy is useful if end users are using your project for an extended period of time, possibly over several sessions. This is most common in cases where a user of your project executes the model step by step (as opposed to a project where the model is executed completely, for example, a Vensim model that is immediately stepped to the end).

Specifically, the strategy is:

  • Check if there are any runs for this end user.
    • If there are no runs (either in memory or in the database), create a new one.
    • If there are runs, take the latest (most recent) one.

multiplayer

The multiplayer strategy is for use with multiplayer worlds. It checks the current world for this end user, and always returns the current run for that world. This is equivalent to calling getCurrentWorldForUser() and then getCurrentRunId() from the World API Adapater. If you use the World Manager, you are automatically using this strategy.

Using this strategy means that end users in projects with multiplayer worlds always see the most current world and run. This ensures that they are in sync with the other end users sharing their world and run. In turn, this allows for competitive or collaborative multiplayer projects.

none

The none strategy never returns a run or tries to create a new run. It simply returns the contents of the current Run Service instance.

This strategy is useful if you want to manually decide how to create your own runs and don't want any automatic assistance.

new-if-initialized

DEPRECATED

The new-if-initialized strategy creates a new run if the current one is in memory or has its initialized field set to true. The initialized field in the run record is automatically set to true at run creation, but can be changed.

This strategy is useful if your project is structured such that immediately after a run is created, the model is executed completely (for example, a Vensim model is stepped to the end). It is similar to the new-if-missing strategy, except that it checks a field of the run record.

Specifically, the strategy is:

  • Check the sessionKey cookie.
    • This cookie is set by the Run Manager and configurable through its options.
    • If the cookie exists, check whether the run is in memory or only persisted in the database. Additionally, check whether the run's initialized field is true.
      • If the run is in memory, create a new run.
      • If the run's initialized field is true, create a new run.
      • Otherwise, use the existing run.
    • If the cookie does not exist, create a new run for this end user.

new-if-persisted

DEPRECATED

The new-if-persisted strategy creates a new run when the current one becomes persisted (end user is idle for a set period), but otherwise uses the current one.

Using this strategy means that when end users navigate between pages in your project, or refresh their browsers, they will still be working with the same run.

However, if they are idle for longer than your project's Model Session Timeout (configured in your project's Settings), then their run is persisted; the next time they interact with the project, they will get a new run. (See more background on Run Persistence.)

This strategy is useful for multi-page projects where end users play through a simulation in one sitting, stepping through the model sequentially (for example, a Vensim model that uses the step operation) or calling specific functions until the model is "complete." However, you will need to guarantee that your end users will remain engaged with the project from beginning to end — or at least, that if they are idle for longer than the Model Session Timeout, it is okay for them to start the project from scratch (with an uninitialized model).

Specifically, the strategy is:

  • Check the sessionKey cookie.
    • This cookie is set by the Run Manager and configurable through its options.
    • If the cookie exists, check whether the run is in memory or only persisted in the database.
      • If the run is in memory, use the run.
      • If the run is only persisted (and not still in memory), create a new run for this end user.
      • If the cookie does not exist, create a new run for this end user.

Create your Own

You can create your own strategy by passing in a function as the strategy parameter to the F.manager.RunManager() instantiation call. Strategy functions must return objects of the form:

{
    getRun: function() {},
    reset: function() {}
}

Some strategies have options you can specify through strategyOptions in the Run Manager. If you create your own strategy, this options object is passed in to your strategy function constructor.

For example:

// example create-your-own strategy provides a new run every minute

var ConditionalStrategy = F.manager.RunManager.strategies.byName('conditional-creation');
var myNewStrategy = new ConditionalStrategy(function (run, headers, usersession, runsession) { 
    var created = (new Date(run.created)).valueOf();
    var timeAgo = Date.now() - created;
    var runLifetime = 1;
    var minsAgo = timeAgo / (1000 * 60);
    return minsAgo > runLifetime;
});

var rm = new F.manager.RunManager({
    strategy: myNewStrategy,
    run: { ... }
});

Working with Run Strategies

You can access a list of available strategies using F.manager.RunManager.strategies.list. You can also ask for a particular strategy by name.

If you decide to create your own run strategy, you can register your strategy. Registering your strategy means that:

  • You can pass the strategy by name to a Run Manager (as opposed to passing the strategy function): new F.manager.RunManager({ strategy: 'mynewname'}).
  • You can pass configuration options to your strategy.
  • You can specify whether or not your strategy requires authorization (a valid user session) to work.

Configuration Options

list
  • Object

List of available strategies. Within this object, each key is the strategy name and the associated value is the strategy constructor.

Methods

byName

Gets strategy by name.

Example

 var reuseStrat = F.manager.RunManager.strategies.byName('reuse-across-sessions');
 // shows strategy function
 console.log('reuseStrat = ', reuseStrat);
 // create a new run manager using this strategy
 var rm = new F.manager.RunManager({strategy: reuseStrat, run: { model: 'model.vmf'} });

Parameters

  • strategyName: String Name of strategy to get.
register

Adds a new strategy.

Example

 // this "favorite run" strategy always returns the same run, no matter what
 // (not a useful strategy, except as an example)
 F.manager.RunManager.strategies.register(
     'favRun', 
     function() { 
         return { getRun: function() { return '0000015a4cd1700209cd0a7d207f44bac289'; },
                 reset: function() { return '0000015a4cd1700209cd0a7d207f44bac289'; } 
         } 
     }, 
     { requiresAuth: true }
 );

 var rm = new F.manager.RunManager({strategy: 'favRun', run: { model: 'model.vmf'} });

Parameters

  • name: String Name for strategy. This string can then be passed to a Run Manager as new F.manager.RunManager({ strategy: 'mynewname'}).

  • strategy: Function The strategy constructor. Will be called with new on Run Manager initialization.

  • options: Object Options for strategy.

  • options.requiresAuth: Boolean Specify if the strategy requires a valid user session to work.