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 should be a property of the run (saved/trashed/custom metadata saved with .save). 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,
}, {
 include: ['Price', 'MyOtherVariable']
}, {
 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. Specific operations will vary per model language. For example, a function in python may be called as an operation. Some languages have only a few specific built-in operations (e.g. "step" in SimLang). 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. Specific operations will vary per model language. For example, a function in python may be called as an operation. Some languages have only a few specific built-in operations (e.g. "step" in SimLang). 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

JQuery.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. Specific operations will vary per model language. For example, a function in python may be called as an operation. Some languages have only a few specific built-in operations (e.g. "step" in SimLang). 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

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