forio Toggle navigation

Data API Service

The Data API Service allows you to create, access, and manipulate data related to any of your projects. Data are organized in collections. Each collection contains a document; each element of this top-level document is a JSON object. (See additional information on the underlying Data API.)

Example:

var ds = new F.service.Data({
    account: 'acme-simulations',
    project: 'supply-chain-game',
    root: 'survey-responses',
    scope: F.service.Data.SCOPES.USER,
});
ds.saveAs('user1',
    { 'question1': 2, 'question2': 10,
    'question3': false, 'question4': 'sometimes' } );
ds.saveAs('user2',
    { 'question1': 3, 'question2': 8,
    'question3': true, 'question4': 'always' } );
ds.query('',{ 'question2': { '$gt': 9} });

Scoping:

The scope parameter determines who has read-write access to this data collection. Available scopes are:

Scope Readable By Writable By
GROUP Facilitators & Users in that group Faciliators in that group
USER Faciliator in that group. User who created the collection Faciliator in that group. User who created the collection
FACILITATOR Faciliators in that group Faciliators in that group
PROJECT (default, for legacy reasons) Any user in the project Any user in the project
CUSTOM (to opt out of naming conventions) customize with Epicenter-api-proxy customize with Epicenter-api-proxy

Example:

const DataService = F.service.Data;    
const groupScopeDataService = new DataService({    
    name: 'some-name', 
    scope: DataService.SCOPES.GROUP,   
});    
const userScopeDataService = new DataService({     
    name: 'some-name', 
    scope: DataService.SCOPES.USER,    
});  

Constructor options

Required? Name Type Description
Yes root string The name of the collection. If you have multiple collections within each of your projects, you can also pass the collection name as an option for each call.
  scope string Determines who has read-write access to this data collection. See above for available scopes.
  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

query(key, query[, outputModifier, options])

Search for data within a collection.

Searching using comparison or logical operators (as opposed to exact matches) requires MongoDB syntax. See the underlying Data API for additional details.

Parameters

Required? Name Type Description
Yes key String The name of the document to search. Pass the empty string ('') to search the entire collection.
Yes query Object The query object. For exact matching, this object contains the field name and field value to match. For matching based on comparison, this object contains the field name and the comparison expression. For matching based on logical operators, this object contains an expression using MongoDB syntax. See the underlying Data API for additional examples.
  outputModifier Object Available fields include: startrecord, endrecord, sort, and direction (asc or desc).
  options Object Overrides for configuration options.

Example

// request all data associated with document 'user1'
ds.query('user1');

// exact matching:
// request all documents in collection where 'question2' is 9
ds.query('', { 'question2': 9});

// comparison operators:
// request all documents in collection where 'question2' is greater than 9
ds.query('', { 'question2': { '$gt': 9} });

// logical operators:
// request all documents in collection where 'question2' is less than 10, and 'question3' is false
ds.query('', { '$and': [ { 'question2': { '$lt':10} }, { 'question3': false }] });

// regular expresssions: use any Perl-compatible regular expressions
// request all documents in collection where 'question5' contains the string '.*day'
ds.query('', { 'question5': { '$regex': '.*day' } });

save(key[, value, options])

Save data in an anonymous document within the collection.

The root of the collection must be specified. By default the root is taken from the Data Service configuration options; you can also pass the root to the save call explicitly by overriding the options (third parameter).

(Additional background: Documents are top-level elements within a collection. Collections must be unique within this account (team or personal account) and project and are set with the root field in the option parameter. See the underlying Data API for more information. The save method is making a POST request.)

Parameters

Required? Name Type Description
Yes key String / Object If key is a string, it is the id of the element to save (create) in this document. If key is an object, the object is the data to save (create) in this document. In both cases, the id for the document is generated automatically.
  value Object The data to save. If key is a string, this is the value to save. If key is an object, the value(s) to save are already part of key and this argument is not required.
  options Object Overrides for configuration options. If you want to override the default root of the collection, do so here.

Example

// Create a new document, with one element, at the default root level
ds.save('question1', 'yes');

// Create a new document, with two elements, at the default root level
ds.save({ question1:'yes', question2: 32 });

// Create a new document, with two elements, at `/students/`
ds.save({ name:'John', className: 'CS101' }, { root: 'students' });

pushToArray(key, val[, options])

Append value to an array data structure within a document

Parameters

Required? Name Type Description
Yes key string path to array item
Yes val any value to append to array
  options object Overrides for configuration options

saveAs(key[, value, options])

Save (create or replace) data in a named document or element within the collection.

The root of the collection must be specified. By default the root is taken from the Data Service configuration options; you can also pass the root to the saveAs call explicitly by overriding the options (third parameter).

Optionally, the named document or element can include path information, so that you are saving just part of the document.

(Additional background: Documents are top-level elements within a collection. Collections must be unique within this account (team or personal account) and project and are set with the root field in the option parameter. See the underlying Data API for more information. The saveAs method is making a PUT request.)

Parameters

Required? Name Type Description
Yes key String Id of the document.
  value Object The data to save, in key:value pairs.
  options Object Overrides for configuration options. If you want to override the default root of the collection, do so here.

Example

// Create (or replace) the `user1` document at the default root level.
// Note that this replaces any existing content in the `user1` document.
ds.saveAs('user1',
    { 'question1': 2, 'question2': 10,
     'question3': false, 'question4': 'sometimes' } );

// Create (or replace) the `student1` document at the `students` root,
// that is, the data at `/students/student1/`.
// Note that this replaces any existing content in the `/students/student1/` document.
// However, this will keep existing content in other paths of this collection.
// For example, the data at `/students/student2/` is unchanged by this call.
ds.saveAs('student1',
    { firstName: 'john', lastName: 'smith' },
    { root: 'students' });

// Create (or replace) the `mgmt100/groupB` document at the `myclasses` root,
// that is, the data at `/myclasses/mgmt100/groupB/`.
// Note that this replaces any existing content in the `/myclasses/mgmt100/groupB/` document.
// However, this will keep existing content in other paths of this collection.
// For example, the data at `/myclasses/mgmt100/groupA/` is unchanged by this call.
ds.saveAs('mgmt100/groupB',
    { scenarioYear: '2015' },
    { root: 'myclasses' });

load(key[, outputModifier, options])

Get data for a specific document or field.

Parameters

Required? Name Type Description
Yes key String / Object The id of the data to return. Can be the id of a document, or a path to data within that document.
  outputModifier Object Available fields include: startrecord, endrecord, sort, and direction (asc or desc).
  options Object Overrides for configuration options.

Example

ds.load('user1');
ds.load('user1/question3');

remove(keys[, options])

Removes data from collection. Only documents (top-level elements in each collection) can be deleted.

Parameters

Required? Name Type Description
Yes keys String / Array The id of the document to remove from this collection, or an array of such ids.
  options Object Overrides for configuration options.

Example

ds.remove('user1');

getScopedName(session[, options])

Returns the internal collection name (with scope)

Parameters

Required? Name Type Description
Yes session object Group/User info to add to scope. Gets it from current session otherwise
  options Object Overrides for configuration options.
Yes options.scope string Scope to set to.

Returns

string - Scoped collection name.

getChannel([options])

Gets a channel to listen to notifications on for this collection

Parameters

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

Returns

Channnel - channel instance to subscribe with.