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 (and associated run strategies) gives you control over run creation depending on run states.

The Run API Service is useful for building an interface where you want to show data across multiple runs (this is easy using the filter() and query() methods). For instance, you would probably use a Run Service to build a page for a facilitator. This is because a facilitator typically wants to evaluate performance from multiple end users, each of whom have been working with their own run.

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.

If you know in advance that you would like to work with particular, existing run(s), you can optionally pass in:

  • filter: (Optional) Criteria by which to filter for existing runs.
  • id: (Optional) The run id of an existing run. This is a convenience alias for using filter, in the case where you only want to work with one run.

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. In particular, passing { id: 'a-run-id' } in this options object allows you to make calls to an existing run.

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 undefined). 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 undefined. If left undefined, taken from the URL.

project

  • String

The project id. Defaults to undefined. 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. Pass in an existing run id to interact with a particular run.

autoRestore

  • boolean

Flag determines if X-AutoRestore: true header is sent to Epicenter, meaning runs are automatically pulled from the Epicenter backend database if not currently in memory on the Epicenter servers. 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 reuse-never, 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 model or marked for saving in your model context file).

  • 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 model or marked for saving in your model context file).

  • 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 or run record 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 or saved in your 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 } });

// update 'saved' field of run record for a particular run
rs.save({ saved: true }, { id: '0000015bf2a04995880df6b868d23eb3d229' });

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 an operation from the model.

Depending on the language in which you have written your model, the operation (function or 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

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

Parameters

  • operation: String Name of operation.

  • 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 operations from the model, sequentially.

Depending on the language in which you have written your model, the operation (function or 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).

Examples

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

Parameters

  • operations: Array If none of the operations take parameters, pass an array of the operation names (strings). If any of the operations do take parameters, pass an array of objects, each of which contains an operation 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 operations from the model, executing them in parallel.

Depending on the language in which you have written your model, the operation (function or 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).

Example

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

Parameters

  • operations: Array|Object If none of the operations take parameters, pass an array of the operation names (as strings). If any of the operations do take parameters, you have two options. You can pass an array of objects, each of which contains an operation name and its own (possibly empty) array of parameters. Alternatively, you can pass a single object with the operation 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> }. Note that the runID is optional if the Run Service is already associated with a particular run (because id was passed in when the Run Service was initialized). If provided, the runID overrides the id currently associated with the Run Service.

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