Bug fix: World API pass in files

Bug fix for allowing passing in 'files' while creating a run from world api

Patch fix allowing for changing ping interval

Used only by wharton-art to allow customizing the ping interval

Cinfile support

Bug Fixes:

• reuse-last-initialized strategy used to select the last initialized run even if it was trashed; now it ignores trashed runs.

Improvements:

• reuse-last-initialized, reuse-last-unsaved, reuse-across-sessions only query for the last run, instead of querying for every run and picking the last one. Should have no practical impact, except it'll be faster if you have a lot of runs.

Features:

• For Vensim models you can now pass in cinFiles as an option while creating a run. e.g.

    var rs = new F.service.Run();
    rs.create({
        model: 'hello_world.jl',
        cinFiles: ['a.cin', 'b.cin']
    });

v2.4.0

Bug Fixes:

• AuthManager incorrectly threw an "Invalid Password" error if you had an account for a project but weren't part of a group. It now correctly throws a NO_GROUPS error.

Features:

• AuthManager now includes a isLoggedIn helper method to check if you're currently logged in.

• AuthManager now supports logging into Private projects with your author account

• The RunManager and ScenarioManager now scope cookies by account, project, and model name. This helps differentiate cookies for different projects when you're working locally, and also eases workflow for working with multiple models within a project.

• reuse-last-initialized strategy, as well as all the ScenarioManager strategies now scope runs by model name.

• RunService now includes a removeFromMemory method as a performance optimization.

Bug fix release

Bug fixes:

• Fix inconsistent format for getDataChannel
  Due to a bad falsy check, boolean values used to be incorrectly returned under data.data if it was false and under data for anything else. It's consistently returned under data now. Note that this is a breaking change if you were relying on the older incorrect format.

• Pass through userIds for the autoAssign method in the World API Adapter. It was being ignored before.

v2.3.0

Features:

The sessionKey parameter of the RunManager can now optionally be provided a function instead of a string.

This is useful if you want to optionally skip setting/over-writing a cookie based on an external flag. For instance, maybe you'd rather not save a cookie while impersonating another user:

new F.manager.RunManager({
    sessionKey: function() {
        var session = window.getSession();
        return (session.isImpersonating) ? false : 'epicenterjs.session';
    }
});

Current session information now includes the userName of the currently logged in user.

var am = new F.manager.AuthManager();
var session = am.getCurrentUserSessionInfo();
console.log(session.userName)

2.2.1

2.2.1

This is a minor bugfix release. In previous releases, calls to newRunForWorld were not correctly picking up the configuration passed in to the WorldService constructor. This has been resolved.

2.2.0

2.2.0

This is one of our biggest releases of Epicenter.js in a while. It includes:

• Several major changes to the run strategies and Run Manager.
• A new Scenario Manager for working with time-based projects involving run comparisons.
• A new Presence Service for tracking end users status (online, offline) in multiplayer games.
• A change in the jQuery version required.
• Several bug fixes.

Run Strategy Changes: Consolidating Strategies

Over time we've added a lot of strategies to Epicenter.js to cover different use cases; as our platform grew, some of those strategies became redundant, and made it more difficult to choose which strategy to use. We're addressing this with some efficiency and usability improvements across strategies, namely:

Renamed Strategies

The following strategies have been renamed for clarity:

• persistent-single-player has been renamed to reuse-across-sessions
• always-new has been renamed to reuse-never
• new-if-missing has been renamed to reuse-per-session

The older names will continue to work, but may be removed in a future release.

Deprecated Strategies

The following strategies are now considered deprecated:

• new-if-initialized: All runs now default to being initialized by default, making this redundant.
• new-if-persisted: The Run Service now sets a header (the autoRestore configuration option) to automatically bring back runs into memory, making this redundant.

You can still use these strategies, but they may not accomplish what you expect, and will be removed in a future release.

New 'reuse-last-initialized' Strategy

This release adds a new reuse-last-initialized strategy. It is intended to be a more flexible replacement for the new-if-initialized strategy (which is now deprecated).

This strategy looks for the most recent run that matches particular criteria; if it cannot find one, it creates a new run and immediately executes a set of "initialization" operations.

Examples:

• You have a time-based model and always want the run you're operating on to be at step 10:

       var rm = new F.manager.RunManager({
           strategy: 'reuse-last-initialized',
           strategyOptions: {
               initOperation: [{ step: 10 }]
           }
       })

• You have a custom initialization function in your model, and want to make sure it's always executed for new runs.

strategyOptions is a field you can generally use to pass options to different strategies; while reuse-last-initialized is currently the only strategy which uses it, you can also use this field when creating your own strategies.

Summary

The benefit of this consolidation is that deciding what strategy to use easier than ever:

• reuse-per-session: You reuse the same run until each time you use the Authentication Manager to log out; you get a new run the next time you log back in. Useful for projects designed to be completed in a single session.
• reuse-across-sessions: You reuse the same run until it is explicitly reset. Useful for projects designed to be played across a multiple sessions.
• reuse-never: You get a new run each time you refresh the page.
• multiplayer: The only strategy available for multiplayer projects. A run is shared by the end users in a multiplayer world.

Run Manager Changes

New in this release, there are several changes to the Run Manager, primarily to support Run Strategy changes (described above) and the new Scenario Manager (described below).

getRun Allows Populating Run with Variables

The Run Manager's getRun function now takes in an array of variables as an argument; if provided, it populates the run it gets with the provided variables.

    rm.getRun(['Price', 'Sales'], function (run) {
        console.log(run.variables.Price, run.variables.Sales);
    });

Note: The getRun method will NOT throw an error if you try to get a variable which doesn't exist. Instead, the variables list is empty, and any errors are logged to the console.

Better Validation

The Run Manager now catches common errors, such as passing in invalid strategy names, or missing run options.

More Context Available for Strategy Implementations

The original purpose of the Run Manager was to just find the right strategy and call it, leaving all the 'heavy lifting' (e.g. of authentication) to each individual strategy. Now, the Run Manager does more work up front and just passes in the appropriate information to each strategy, namely:

• Each strategy is mandated to have getRun() and reset() functions. These functions were initially called by the Run Manager with no arguments, but now their signature is:

/**
 + Gets the 'correct' run (the definition of 'correct' depends on strategy implementation)
 + @param  {RunService} runService A Run Service instance for the 'correct' run as determined by the Run Manager
 + @param  {Object} userSession Information about the current user session. See AuthManager#getCurrentUserSession for format
 + @param  {Object} runSession The Run Manager serializes the 'last accessed' run in a cookie and provides it each time `getRun()` is called
 + @return {Promise}             
 */
getRun: function (runService, userSession, runSession){}


/**
 + Resets current run
 + @param  {RunService} runService  A Run Service instance for the 'correct' run as determined by the Run Manager
 + @param  {Object} userSession Information about the current user session. See AuthManager#getCurrentUserSession for format
 + @return {Promise}             
 */
reset: function (runService, userSession){}

• The run returned by the getRun() method is now serialized and stored in a session by the Run Manager, taking over the burden of session management from the individual strategies. This run is provided as a parameter to the next call to strategy.getRun(); the strategy can opt to validate this run (based on run id or any other parameters) and return it, or ignore it altogether depending on its goal.

• Each strategy can register itself as requiring authentication or not (see next section for how to register); if a strategy does so the Run Manager takes care of ensuring there's a valid user session before any of the methods on the strategy are called. This moves the responsibility from the strategy to the Run Manager. The strategy can still opt to handle this itself by not declaring requiresAuth, and do its own validation of the userSession object which is passed to its getRun() and reset() methods.

F.manager.RunManager.strategies

You can access a list of available strategies via F.manager.RunManager.strategies.list.

This behavior mirrors getting the list through F.manager.strategy; however, F.manager.strategy is now considered Deprecated and may be removed in a future release.

The F.manager.RunManager.strategies.register() interface now introduces a new way to register named Run Strategies for use with the Run Manager. Note you can still bypass registering by calling the RunManager with a function, i.e., new F.manager.RunManager({ strategy: function(){}}), so this is a backwards compatible change which just additionally allows naming.

See the run strategies page for more on strategies.

Scenario Manager

This release introduces a new Scenario Manager, accessible as F.manager.ScenarioManager.

Each Scenario Manager allows you to compare the results of several runs. This is mostly useful for time-based models (Vensim, Powersim, SimLang, Stella), but can be adapted to working with other languages as well.

The Scenario Manager can be thought of as a collection of Run Managers with pre-configured strategies. Just as the Run Manager provides use case -based abstractions and utilities for managing the Run Service, the Scenario Manager does the same for the Run Manager.

There are typically three components to building a run comparison:

• A current run in which to make decisions;
• A list of saved runs, that is, all runs that you want to use for comparisons;
• A baseline run to compare against (optional).

See the Scenario Manager docs for examples and more details.

To satisfy these needs a Scenario Manager instance has three Run Managers:

Baseline

var sm = new F.manager.ScenarioManager();
sm.baseline // An instance of a Run Manager with a strategy which locates the most recent baseline run (that is, flagged as `saved` and not `trashed`), or creates a new one.
sm.baseline.reset() // Reset the baseline run. Useful if the model has changed since the baseline run was created.
sm.baseline.getRun() // Typical Run Manager operation which retrieves the baseline run.

If you don't need a baseline for your particular case, you can disable auto-creation of baseline runs by passing in includeBaseline: false to your Scenario Manager options.

Current

var sm = new F.manager.ScenarioManager();
sm.current // An instance of a Run Manager with a strategy which picks up the most recent run (`unsaved` implies a run which hasn't been advanced)
sm.current.reset() // Reset the decisions made on the current run
sm.current.getRun() // Typical Run Manager operation which retrieves the current run

The current Run Manager also has an additional utility method saveAndAdvance. This method clones the current run, then advances and saves this clone (it becomes part of the saved runs list). The current run is unchanged and can continue to be used to store decisions being made by the end user.

Saved Runs

var sm = new F.manager.ScenarioManager();
sm.savedRuns // An instance of a Saved Runs Manager
``...

2.1.0

This release introduces the WebSocket protocol of the channel manager.

• Improvement: Epicenter.js now supports the websockets protocol for the cometd library used in the Channel Manager.
  • By default, websocket support is enabled. You can change this in the Channel Manager configuration options.
  • When websocket support is enabled, the Channel Manager attempts to connect using websockets, and if it cannot, falls back to using the long poll transport.
• Bug fix: Epicenter.js now consistently uses the access token available in epicenter.token as part of the Authorization header for calls to the underlying Epicenter RESTful APIs. This was not working for some cases starting in Epicenter.js 1.8.0 but is now resolved.
• Bug fix: Epicenter.js now gets its protocol (http vs. https) from the URL of the page it is being run on.
• Internal: The automated test framework is updated; it no longer relies on bower and now supports Mac OS X through Sierra.

2.0.1

This is a minor release, and includes two significant improvements:

• The library file size has been significantly reduced. In particular, epicenter.min.js is now less than 90KB.
• Development both in local environments and on custom domains has been streamlined. Previously, there were a few bugs in the checks for localhost and for local sessions/cookies; these have been resolved.