data-api-service | Documentation

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	Facilitators in that group
USER	Faciliator in that group. User who created the collection	Faciliator in that group. User who created the collection
FACILITATOR	Facilitators in that group	Facilitators 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(documentID, 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	documentID	`String`	The id 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: `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(documentPath, val[, options])

Append value to an array data structure within a document

Parameters

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

saveAs(documentPath[, 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.

Parameters

Required?	Name	Type	Description
Yes	documentPath	`String`	Can be the id of a document, or a path to data within that 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([documentPath, outputModifier, options])

Get data for a specific document or field.

Parameters

Name	Type	Description
documentPath	`String / Object`	The id of the data to return. Can be the id of a document, or a path to data within that document. If blank, returns whole collection
outputModifier	`Object`	Available fields include: `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.

query
save
pushToArray
saveAs
load
remove
getScopedName
getChannel