World API Adapter

A run is a collection of end user interactions with a project and its model -- including setting variables, making decisions, and calling operations. For building multiplayer simulations you typically want multiple end users to share the same set of interactions, and work within a common state. Epicenter allows you to create "worlds" to handle such cases. Only team projects can be multiplayer.

The World API Adapter allows you to create, access, and manipulate multiplayer worlds within your Epicenter project. You can use this to add and remove end users from the world, and to create, access, and remove their runs. Because of this, typically the World Adapter is used for facilitator pages in your project. (The related World Manager provides an easy way to access runs and worlds for particular end users, so is typically used in pages that end users will interact with.)

As with all the other API Adapters, all methods take in an "options" object as the last parameter. The options can be used to extend/override the World API Service defaults.

To use the World Adapter, instantiate it and then access the methods provided. Instantiating requires the account id (Team ID in the Epicenter user interface), project id (Project ID), and group (Group Name).

  var wa = new F.service.World({
     account: 'acme-simulations',
     project: 'supply-chain-game',
     group: 'team1' });
  wa.create()
     .then(function(world) {
         // call methods, e.g. wa.addUsers()
     });

Constructor options

Required?	Name	Type	Description
	group	string	The group name to use for filters / new runs
	model	string	The model file to use to create runs in this world.
	filter	string	Criteria by which to filter world. Currently only supports world-ids as filters.
	id	string	Convenience alias for filter.
	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])

Creates a new World.

Using this method is rare. It is more common to create worlds automatically while you autoAssign() end users to worlds. (In this case, configuration data for the world, such as the roles, are read from the project-level world configuration information, for example by getProjectSettings().)

Parameters

Required?	Name	Type	Description
Yes	params	object	Parameters to create the world.
	params.group	string	The Group Name to create this world under. Only end users in this group are eligible to join the world. Optional here; required when instantiating the service (new F.service.World()).
	params.roles	object	The list of roles (strings) for this world. Some worlds have specific roles that must be filled by end users. Listing the roles allows you to autoassign users to worlds and ensure that all roles are filled in each world.
	params.optionalRoles	object	The list of optional roles (strings) for this world. Some worlds have specific roles that may be filled by end users. Listing the optional roles as part of the world object allows you to autoassign users to worlds and ensure that all roles are filled in each world.
	params.minUsers	integer	The minimum number of users for the world. Including this number allows you to autoassign end users to worlds and ensure that the correct number of users are in each world.
	options	object	Options object to override global options.

Example

var wa = new F.service.World({
     account: 'acme-simulations',
     project: 'supply-chain-game',
     group: 'team1' });
wa.create({
     roles: ['VP Marketing', 'VP Sales', 'VP Engineering']
 });

update(params[, options])

Updates a World, for example to replace the roles in the world.

Typically, you complete world configuration at the project level, rather than at the world level. For example, each world in your project probably has the same roles for end users. And your project is probably either configured so that all end users share the same world (and run), or smaller sets of end users share worlds — but not both. However, this method is available if you need to update the configuration of a particular world.

Parameters

Required?	Name	Type	Description
Yes	params	object	Parameters to update the world.
Yes	params.name	string	A string identifier for the linked end users, for example, "name": "Our Team".
	params.roles	object	The list of roles (strings) for this world. Some worlds have specific roles that must be filled by end users. Listing the roles allows you to autoassign users to worlds and ensure that all roles are filled in each world.
	params.optionalRoles	object	The list of optional roles (strings) for this world. Some worlds have specific roles that may be filled by end users. Listing the optional roles as part of the world object allows you to autoassign users to worlds and ensure that all roles are filled in each world.
	params.minUsers	integer	The minimum number of users for the world. Including this number allows you to autoassign end users to worlds and ensure that the correct number of users are in each world.
	options	object	Options object to override global options.

Example

var wa = new F.service.World({
     account: 'acme-simulations',
     project: 'supply-chain-game',
     group: 'team1' });
wa.create()
     .then(function(world) {
         wa.update({ roles: ['VP Marketing', 'VP Sales', 'VP Engineering'] });
     });

delete([options])

Deletes an existing world.

This function optionally takes one argument. If the argument is a string, it is the id of the world to delete. If the argument is an object, it is the override for global options.

Parameters

Required?	Name	Type	Description
	options	string / Object	The id of the world to delete, or options object to override global options.

Example

var wa = new F.service.World({
     account: 'acme-simulations',
     project: 'supply-chain-game',
     group: 'team1' });
wa.create()
     .then(function(world) {
         wa.delete();
     });

updateConfig(config)

Updates the configuration for the current instance of the World API Adapter (including all subsequent function calls, until the configuration is updated again).

Parameters

Required?	Name	Type	Description
Yes	config	object	The configuration object to use in updating existing configuration.

Returns

Object - reference to current instance

Example

var wa = new F.service.World({...}).updateConfig({ filter: '123' }).addUser({ userId: '123' });

list([options])

Lists all worlds for a given account, project, and group. All three are required, and if not specified as parameters, are read from the service.

Parameters

Required?	Name	Type	Description
	options	object	Options object to override global options.

Example

var wa = new F.service.World({
     account: 'acme-simulations',
     project: 'supply-chain-game',
     group: 'team1' });
wa.create()
     .then(function(world) {
         // lists all worlds in group "team1"
         wa.list();

         // lists all worlds in group "other-group-name"
         wa.list({ group: 'other-group-name' });
     });

load(worldId[, options])

Load information for a specific world. All further calls to the world service will use the id provided.

Parameters

Required?	Name	Type	Description
Yes	worldId	string	The id of the world to load.
	options	Object	Options object to override global options.

getWorldsForUser(userId[, options])

Gets all worlds that an end user belongs to for a given account (team), project, and group.

Parameters

Required?	Name	Type	Description
Yes	userId	string	The userId of the user whose worlds are being retrieved.
	options	object	Options object to override global options.

Example

var wa = new F.service.World({
     account: 'acme-simulations',
     project: 'supply-chain-game',
     group: 'team1' });
wa.create()
     .then(function(world) {
         wa.getWorldsForUser('b1c19dda-2d2e-4777-ad5d-3929f17e86d3')
     });

addUsers(users, worldId[, options])

Adds an end user or list of end users to a given world. The end user must be a member of the group that is associated with this world.

Parameters

Required?	Name	Type	Description
Yes	users	string / object / array	User id, array of user ids, object, or array of objects of the users to add to this world.
Yes	users.role	string	The role the user should have in the world. It is up to the caller to ensure, if needed, that the role passed in is one of the roles or optionalRoles of this world.
Yes	worldId	string	The world to which the users should be added. If not specified, the filter parameter of the options object is used.
	options	object	Options object to override global options.

Example

var wa = new F.service.World({
     account: 'acme-simulations',
     project: 'supply-chain-game',
     group: 'team1' });
wa.create()
     .then(function(world) {
         // add one user
         wa.addUsers('b1c19dda-2d2e-4777-ad5d-3929f17e86d3');
         wa.addUsers(['b1c19dda-2d2e-4777-ad5d-3929f17e86d3']);
         wa.addUsers({ userId: 'b1c19dda-2d2e-4777-ad5d-3929f17e86d3', role: 'VP Sales' });

         // add several users
         wa.addUsers([
             { userId: 'a6fe0c1e-f4b8-4f01-9f5f-01ccf4c2ed44',
               role: 'VP Marketing' },
             { userId: '8f2604cf-96cd-449f-82fa-e331530734ee',
               role: 'VP Engineering' }
         ]);

         // add one user to a specific world
         wa.addUsers('b1c19dda-2d2e-4777-ad5d-3929f17e86d3', world.id);
         wa.addUsers('b1c19dda-2d2e-4777-ad5d-3929f17e86d3', { filter: world.id });
     });

updateUser(user[, options])

Updates the role of an end user in a given world. (You can only update one end user at a time.)

Parameters

Required?	Name	Type	Description
Yes	user	{"userId":["string"],"role":["string"]}	User object with userId and the new role.
	options	object	Options object to override global options.

Example

var wa = new F.service.World({
     account: 'acme-simulations',
     project: 'supply-chain-game',
     group: 'team1' });

wa.create().then(function(world) {
     wa.addUsers('b1c19dda-2d2e-4777-ad5d-3929f17e86d3');
     wa.updateUser({ userId: 'b1c19dda-2d2e-4777-ad5d-3929f17e86d3', role: 'leader' });
});

removeUser(user[, options])

Removes an end user from a given world.

Parameters

Required?	Name	Type	Description
Yes	user	object / string	The userId of the user to remove from the world, or an object containing the userId field.
	options	object	Options object to override global options.
	options.deleteWorldIfEmpty	boolean	Delete the world if you removed the last user.

Example

var wa = new F.service.World({
     account: 'acme-simulations',
     project: 'supply-chain-game',
     group: 'team1' });
wa.create()
     .then(function(world) {
         wa.addUsers(['a6fe0c1e-f4b8-4f01-9f5f-01ccf4c2ed44', '8f2604cf-96cd-449f-82fa-e331530734ee']);
         wa.removeUser('a6fe0c1e-f4b8-4f01-9f5f-01ccf4c2ed44');
         wa.removeUser({ userId: '8f2604cf-96cd-449f-82fa-e331530734ee' });
     });

getCurrentRunId([options])

Gets the run id of current run for the given world. If the world does not have a run, creates a new one and returns the run id.

Remember that a run is a collection of interactions with a project and its model. In the case of multiplayer projects, the run is shared by all end users in the world.

Parameters

Required?	Name	Type	Description
	options	object	Options object to override global options.
Yes	options.model	object	The model file to use to create a run if needed.

Example

var wa = new F.service.World({
     account: 'acme-simulations',
     project: 'supply-chain-game',
     group: 'team1' });
wa.create()
     .then(function(world) {
         wa.getCurrentRunId({ model: 'model.py' });
     });

getCurrentWorldForUser(userId[, groupName])

Gets the current (most recent) world for the given end user in the given group. Brings this most recent world into memory if needed.

Parameters

Required?	Name	Type	Description
Yes	userId	string	The userId of the user whose current (most recent) world is being retrieved.
	groupName	string	The name of the group. If not provided, defaults to the group used to create the service.

Example

var wa = new F.service.World({
     account: 'acme-simulations',
     project: 'supply-chain-game',
     group: 'team1' });
wa.getCurrentWorldForUser('8f2604cf-96cd-449f-82fa-e331530734ee')
     .then(function(world) {
         // use data from world
     });

deleteRun(worldId[, options])

Deletes the current run from the world.

(Note that the world id remains part of the run record, indicating that the run was formerly an active run for the world.)

Parameters

Required?	Name	Type	Description
Yes	worldId	string	The worldId of the world from which the current run is being deleted.
	options	object	Options object to override global options.

Example

var wa = new F.service.World({
     account: 'acme-simulations',
     project: 'supply-chain-game',
     group: 'team1' });

wa.deleteRun('sample-world-id');

newRunForWorld(worldId[, options])

Creates a new run for the world.

Parameters

Required?	Name	Type	Description
Yes	worldId	string	worldId in which we create the new run.
	options	object	Options object to override global options.
Yes	options.model	object	The model file to use to create a run if needed.

Example

var wa = new F.service.World({
     account: 'acme-simulations',
     project: 'supply-chain-game',
     group: 'team1' });

wa.getCurrentWorldForUser('8f2604cf-96cd-449f-82fa-e331530734ee')
     .then(function (world) {
             wa.newRunForWorld(world.id);
     });

autoAssign([options])

Assigns end users to worlds, creating new worlds as appropriate, automatically. Assigns all end users in the group, and creates new worlds as needed based on the project-level world configuration (roles, optional roles, and minimum end users per world).

Parameters

Required?	Name	Type	Description
	options	object	Options object to override global options.
Yes	options.maxUsers	number	Sets the maximum number of users in a world.
Yes	options.userIds	Array.<string>	A list of users to be assigned be assigned instead of all end users in the group.

Example

var wa = new F.service.World({
     account: 'acme-simulations',
     project: 'supply-chain-game',
     group: 'team1' });

wa.autoAssign();

getProjectSettings([options])

Gets the project's world configuration.

Typically, every interaction with your project uses the same configuration of each world. For example, each world in your project probably has the same roles for end users. And your project is probably either configured so that all end users share the same world (and run), or smaller sets of end users share worlds — but not both.

(The Multiplayer Project REST API allows you to set these project-level world configurations. The World Adapter simply retrieves them, for example so they can be used in auto-assignment of end users to worlds.)

Parameters

Required?	Name	Type	Description
	options	object	Options object to override global options.

Example

var wa = new F.service.World({
     account: 'acme-simulations',
     project: 'supply-chain-game',
     group: 'team1' });

wa.getProjectSettings()
     .then(function(settings) {
         console.log(settings.roles);
         console.log(settings.optionalRoles);
     });

consensus(conOpts[, options])

Get an instance of a consensus service for current world

Parameters

Required?	Name	Type	Description
Yes	conOpts	string / {"consensusGroup":["string"],"name":["string"]}	creates a consensus with an optional group name. If not specified, created under the 'default' group
	options	object	Overrides for service options

getPresenceForUsers(world[, options])

Parameters

Required?	Name	Type	Description
Yes	world	string / {"users":["object"]}	World to get users from.
	options	object	Overrides for service options