forio Toggle navigation

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

** Parameters **

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

** Parameters **

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 [object Object] 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.

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

** Parameters **

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

** Parameters **

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

** Parameters **

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 / [object Object] 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 / [object Object] World to get users from.
  options object Overrides for service options