forio Toggle navigation

Run API Service

The Run API Service allows you to perform common tasks around creating and updating runs, variables, and data.

When building interfaces to show run one at a time (as for standard end users), typically you first instantiate a Run Manager and then access the Run Service that is automatically part of the manager, rather than instantiating the Run Service directly. This is because the Run Manager gives you control over run creation depending on run states.

However, many of the Epicenter sample projects use a Run Service, because generally the sample projects are played in one end user session and don't care about run states or run strategies. The Run API Service is also useful for building an interface for a facilitator, because it makes it easy to list data across multiple runs (using the filter() and query() methods).

To use the Run API Service, instantiate it by passing in:

  • account: Epicenter account id (Team ID for team projects, User ID for personal projects).
  • project: Epicenter project id.

For example,

  var rs = new F.service.Run({
       account: 'acme-simulations',
       project: 'supply-chain-game',
 });
 rs.create('supply_chain_game.py').then(function(run) {
        rs.do('someOperation');
 });

Additionally, all API calls take in an "options" object as the last parameter. The options can be used to extend/override the Run API Service defaults listed below.

Note that in addition to the account, project, and model, the Run Service parameters optionally include a server object, whose host field contains the URI of the Forio server. This is automatically set, but you can pass it explicitly if desired. It is most commonly used for clarity when you are hosting an Epicenter project on your own server.

  var rm = new F.manager.RunManager({
      run: {
          account: 'acme-simulations',
          project: 'supply-chain-game',
          model: 'supply_chain_game.py',
          server: { host: 'api.forio.com' }
      }
  });
  rm.getRun()
      .then(function(run) {
          // the RunManager.run contains the instantiated Run Service,
          // so any Run Service method is valid here
          var rs = rm.run;
          rs.do('someOperation');
  })

Configuration Options

token

For projects that require authentication, pass in the user access token (defaults to empty string). If the user is already logged in to Epicenter, the user access token is already set in a cookie and automatically loaded from there. (See more background on access tokens).

account

  • String

The account id. In the Epicenter UI, this is the Team ID (for team projects) or User ID (for personal projects). Defaults to empty string. If left undefined, taken from the URL.

project

  • String

The project id. Defaults to empty string. If left undefined, taken from the URL.

filter

  • String

Criteria by which to filter runs. Defaults to empty string.

id

  • String

Convenience alias for filter.

autoRestore

  • boolean

Flag determines if X-AutoRestore: true header is sent to Epicenter. Defaults to true.

success

  • function

Called when the call completes successfully. Defaults to $.noop.

error

  • function

Called when the call fails. Defaults to $.noop.

transport

  • Object

Options to pass on to the underlying transport layer. All jquery.ajax options at http://api.jquery.com/jQuery.ajax/ are available. Defaults to empty object.

Methods

create

Create a new run.

NOTE: Typically this is not used! Use RunManager.getRun() with a strategy of always-new, or use RunManager.reset(). See Run Manager for more details.

Example

 rs.create('hello_world.jl');

Parameters

  • params: String|Object If a string, the name of the primary model file. This is the one file in the project that explicitly exposes variables and methods, and it must be stored in the Model folder of your Epicenter project. If an object, may include model, scope, and files. (See the Run Manager for more information on scope and files.)

  • options: Object (Optional) Overrides for configuration options.

query

Returns particular runs, based on conditions specified in the qs object.

The elements of the qs object are ANDed together within a single call to .query().

Example

 // returns runs with saved = true and variables.price > 1,
 // where variables.price has been persisted (recorded)
 // in the model.
rs.query({
     'saved': 'true',
     '.price': '>1'
  },
  {
     startrecord: 2,
     endrecord: 5
  });

Parameters

  • qs: Object Query object. Each key can be a property of the run or the name of variable that has been saved in the run (prefaced by variables.). Each value can be a literal value, or a comparison operator and value. (See more on filtering allowed in the underlying Run API.) Querying for variables is available for runs in memory and for runs in the database if the variables are persisted (e.g. that have been recorded in your Julia model).

  • outputModifier: Object (Optional) Available fields include: startrecord, endrecord, sort, and direction (asc or desc).

  • options: Object (Optional) Overrides for configuration options.

filter

Returns particular runs, based on conditions specified in the qs object.

Similar to .query().

Parameters

  • filter: Object Filter object. Each key can be a property of the run or the name of variable that has been saved in the run (prefaced by variables.). Each value can be a literal value, or a comparison operator and value. (See more on filtering allowed in the underlying Run API.) Filtering for variables is available for runs in memory and for runs in the database if the variables are persisted (e.g. that have been recorded in your Julia model).

  • outputModifier: Object (Optional) Available fields include: startrecord, endrecord, sort, and direction (asc or desc).

  • options: Object (Optional) Overrides for configuration options.

load

Get data for a specific run. This includes standard run data such as the account, model, project, and created and last modified dates. To request specific model variables, pass them as part of the filters parameter.

Note that if the run is in memory, any model variables are available; if the run is in the database, only model variables that have been persisted — that is, recorded in your Julia model — are available.

Example

rs.load('bb589677-d476-4971-a68e-0c58d191e450', { include: ['.price', '.sales'] });

Parameters

  • runID: String The run id.

  • filters: Object (Optional) Object containing filters and operation modifiers. Use key include to list model variables that you want to include in the response. Other available fields include: startrecord, endrecord, sort, and direction (asc or desc).

  • options: Object (Optional) Overrides for configuration options.

save

Save attributes (data, model variables) of the run.

Examples

// add 'completed' field to run record
rs.save({ completed: true });

// update 'saved' field of run record, and update values of model variables for this run
rs.save({ saved: true, variables: { a: 23, b: 23 } });

Parameters

  • attributes: Object The run data and variables to save.

  • attributes.variables: Object Model variables must be included in a variables field within the attributes object. (Otherwise they are treated as run data and added to the run record directly.)

  • options: Object (Optional) Overrides for configuration options.

do

Call a method from the model.

Depending on the language in which you have written your model, the method may need to be exposed (e.g. export for a Julia model) in the model file in order to be called through the API. See Writing your Model).

The params argument is normally an array of arguments to the operation. In the special case where operation only takes one argument, you are not required to put that argument into an array.

Note that you can combine the operation and params arguments into a single object if you prefer, as in the last example.

Examples

 // method "solve" takes no arguments
rs.do('solve');
 // method "echo" takes one argument, a string
rs.do('echo', ['hello']);
 // method "echo" takes one argument, a string
rs.do('echo', 'hello');
 // method "sumArray" takes one argument, an array
rs.do('sumArray', [[4,2,1]]);
 // method "add" takes two arguments, both integers
rs.do({ name:'add', params:[2,4] });

Parameters

  • operation: String Name of method.

  • params: Array (Optional) Any parameters the operation takes, passed as an array. In the special case where operation only takes one argument, you are not required to put that argument into an array, and can just pass it directly.

  • options: Object (Optional) Overrides for configuration options.

serial

Call several methods from the model, sequentially.

Depending on the language in which you have written your model, the methods may need to be exposed (e.g. export for a Julia model) in the model file in order to be called through the API. See Writing your Model).

Examples

 // methods "initialize" and "solve" do not take any arguments
rs.serial(['initialize', 'solve']);
 // methods "init" and "reset" take two arguments each
rs.serial([  { name: 'init', params: [1,2] },
             { name: 'reset', params: [2,3] }]);
 // method "init" takes two arguments,
 // method "runmodel" takes none
rs.serial([  { name: 'init', params: [1,2] },
             { name: 'runmodel', params: [] }]);

Parameters

  • operations: Array If none of the methods take parameters, pass an array of the method names (strings). If any of the methods do take parameters, pass an array of objects, each of which contains a method name and its own (possibly empty) array of parameters.

  • params: ** Parameters to pass to operations.

  • options: Object (Optional) Overrides for configuration options.

parallel

Call several methods from the model, executing them in parallel.

Depending on the language in which you have written your model, the methods may need to be exposed (e.g. export for a Julia model) in the model file in order to be called through the API. See Writing your Model).

Example

 // methods "solve" and "reset" do not take any arguments
rs.parallel(['solve', 'reset']);
 // methods "add" and "subtract" take two arguments each
rs.parallel([ { name: 'add', params: [1,2] },
              { name: 'subtract', params:[2,3] }]);
 // methods "add" and "subtract" take two arguments each
rs.parallel({ add: [1,2], subtract: [2,4] });

Parameters

  • operations: Array|Object If none of the methods take parameters, pass an array of the method names (as strings). If any of the methods do take parameters, you have two options. You can pass an array of objects, each of which contains a method name and its own (possibly empty) array of parameters. Alternatively, you can pass a single object with the method name and a (possibly empty) array of parameters.

  • params: ** Parameters to pass to operations.

  • options: Object (Optional) Overrides for configuration options.

introspect

Shortcut to using the Introspection API Service. Allows you to view a list of the variables and operations in a model.

Example

rs.introspect({ runID: 'cbf85437-b539-4977-a1fc-23515cf071bb' }).then(function (data) {
     console.log(data.functions);
     console.log(data.variables);
});

Parameters

  • options: Object Options can either be of the form { runID: <runid> } or { model: <modelFileName> }.

  • introspectionConfig: Object (Optional) Service options for Introspection Service

variables

Returns a Variables Service instance. Use the variables instance to load, save, and query for specific model variables. See the Variable API Service for more information.

Example

 var vs = rs.variables();
 vs.save({ sample_int: 4 });

Parameters

  • config: Object (Optional) Overrides for configuration options.