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');
    });

Constructor options

Required? Name Type Description
Yes filter string Criteria by which to filter runs.
  id string Convenience alias for filter. Pass in an existing run id to interact with a particular run.
  autoRestore string 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.
  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, parsed from the URL.
  token string 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). @see Authentication API Service for getting tokens.
  transport JQueryAjaxOptions Options to pass on to the underlying transport layer. All jquery.ajax options are supported.
  server object
  server.host string The value of host is usually the string api.forio.com, the URI of the Forio API 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
  server.protocol https / http Defaults to https

Methods

create(params[, options])

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.

Parameters

Required? Name Type Description
Yes 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 Overrides for configuration options.

Example

rs.create('hello_world.jl');

query(qs[, outputModifier, options])

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

Parameters

Required? Name Type Description
Yes 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 Available fields include: startrecord, endrecord, sort, and direction (asc or desc).
  options Object Overrides for configuration options.

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
});

filter(filter[, outputModifier, options])

Returns particular runs, based on conditions specified in the qs object. Similar to .query().

Parameters

Required? Name Type Description
Yes 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 Available fields include: startrecord, endrecord, sort, and direction (asc or desc).
  options Object Overrides for configuration options.

load(runID[, filters, options])

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.

Parameters

Required? Name Type Description
Yes runID String The run id.
  filters Object 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 Overrides for configuration options.

Example

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

removeFromMemory(runID[, options])

Removes specified runid from memory. See details on run persistence

Parameters

Required? Name Type Description
Yes runID String id of run to remove
  options Object Overrides for configuration options.

Example

rs.removeFromMemory('bb589677-d476-4971-a68e-0c58d191e450');

save(attributes[, options])

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

Parameters

Required? Name Type Description
Yes attributes Object The run data and variables to save.
Yes 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 Overrides for configuration options.

Example

// 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' });

do(operation[, params, options])

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.

Parameters

Required? Name Type Description
Yes operation String Name of operation.
  params Array 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 Overrides for configuration options.

Example

// 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' });

serial(operations, params[, options])

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

Parameters

Required? Name Type Description
Yes 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.
Yes params any Parameters to pass to operations.
  options Object Overrides for configuration options.

Returns

Promise - The parameter to the callback is an array. Each array element is an object containing the results of one operation.

Example

// 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: [] }]);

parallel(operations, params[, options])

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

Parameters

Required? Name Type Description
Yes 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.
Yes params any Parameters to pass to operations.
  options Object Overrides for configuration options.

Returns

Promise - The parameter to the callback is an array. Each array element is an object containing the results of one operation.

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] });

introspect(options[, introspectionConfig])

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

Parameters

Required? Name Type Description
Yes 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 Service options for Introspection Service

Example

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

variables([config])

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.

Parameters

Required? Name Type Description
  config Object Overrides for configuration options.

Returns

Object - variablesService Instance

Example

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