Skip to content

DataItems

Jump to bottom
Steve Greatrex edited this page Feb 26, 2015 · 5 revisions

Working with Data Items

Every piece of information saved by EDGE10 is stored in a Data Item with a reference to a Data Item Definition (sometimes referred to as an Attribute Definition).

Note: these samples use API key authentication as described under Authentication and the edge10-request helper module.

Data Items Definitions

A data item definition contains metadata about the data that it can store:

  • A unique ID
  • A display name
  • A description
  • A data type; one of
    • Numeric
    • Text
    • Bool
    • Duration (e.g. 1.2:03:04.567 for 1 day, 2 hours, 3 minutes, 4 seconds and 567 milliseconds)
    • DateTime (e.g. 2015-01-01T01:02:03)
    • Single Lookup (i.e. 1 item selected from a list of options)
    • Multi Lookup (i.e. 0 or more items selected from a list of options)
    • Table (i.e. a table of data - see below for more details)
    • Exercise (a special-case of tabular data)
  • Optional display template name (used to render the data item on EDGE10 Online)
  • Optional Min- and Max- values (only valid for numeric data items)
  • Decimal places (only valid for numeric data items)
  • Optional column width in characters (for when the data item forms a column in a table)
  • A lookup definition (only valid for lookup data items)
  • One or more categories
  • One or more table columns (only valid for table data items)
  • Exercise type and Units (only valid for exercises)
  • Calculated field properties (see below for more details)

Data Item Types

When accessing data item values through the API, some data types are treated differently to others. A typical (partial) response to a request for a session might be

{
  //...
  "data": [
    {
      "attributeDefinitionId": "2c60193d-983b-4b14-9c07-88344df6313c",
      "value": 123
    },
    {
      "attributeDefinitionId": "9a1c1daf-eb8c-405c-b5f2-ca951089b56c",
      "value": "456"
    },
    {
      "attributeDefinitionId": "d87c75ce-05bd-4329-93bd-5b78e7a19ec4",
      "lookupValues": [
        {
          "id": "1c314ab7-1aa3-4ad7-ae8f-d80223196f38",
          "value": "Premier League",
          "index": 0,
          "score": 0
        }
      ]
    }
  ]
}

Each data item is returned with a reference to associated definition alongside the value.

Simple Types

The majority of data items have a simple data type that is stored in the value field when accessed through the API.

Data Type Example Value Meaning
Numeric 123 The number 123
Text "value" The text 'value'
Bool true True
Duration 1.2:03:04.567 1d 2h 3m 4s 567ms
DateTime 2015-02-01T03:04:05 3:04:05 AM on Feb 1st 2015

Lookups

Lookups - both single- and multi-select - return their values through the lookupValues field when accessed through the API. This field contains an array of all selected values including some metadata about each option:

  • The ID of the selected value
  • The display value
  • The index of that value in the option list
  • The score of that value, if appropriate

Tables

Tables are a means of storing an arbitrary number of rows of data against a set of defined columns. Each column is defined by another data item and are set on the tableColumns field of the data item definition.

Table and exercise data items cannot be table columns; all other combinations are valid.

Exercises

Exercises are a special-case table implementation that contain a fixed set of columns:

  • Target Reps
  • Actual Reps
  • Target Weight
  • Actual Weight
  • Target Duration
  • Actual Duration

Exercise definitions include an exerciseType property that can be set to either WeightBased or DurationBased. In either case, only the applicable columns above are displayed in the table when the data is rendered.

Exercises also allow include a units property. This is a string value that is displayed alongside the exercise but is not currently used in any other way.

Getting Data Items

You can get a list of all data items definitions in the system using the request below:

request({
  url: '/api/attribute'
});

To get a specific data item definition, append either the name or the ID of the data item to the request

request({
  url: '/api/attribute/' + nameOrId
});

Samples

Creating and Updating Data Items

To create a new data item, POST the definition to /api/attribute. Only the name field is required but you will generally want to specify type as well. If left blank, type will default to Numeric.

request({
  method: 'POST',
  url: '/api/attribute',
  body: {
    name: 'New data item',
    type: 'Numeric'
  }
});

To update an existing data item, PUT the updated definition to /api/attribute/[data item ID]. The data item ID must also be included in the body

request({
  method: 'PUT',
  url: '/api/attribute' + dataItemId,
  body: {
    id: dataItemId,
    name: 'Updated name',
    description: 'Updated description'
  }
});

Samples

Calculated Data Items

Calculated data items are very similar to 'normal' data items: they have the same metadata and the same value types.

However, instead of relying on manual entry of a value, calculated data items use a script to generate a value based on other data items on the session whenever the session is saved.

Important Note: data for a calculated field can only come from the same session on which it appears!

In order to support this, calculated fields have 3 additional pieces of metadata:

  • Dependent data items An array of the IDs of other data items on which the calculation relies
  • Calculation script A piece of javascript that defines how the calculation is run
  • Calculation scope What other changes to the session would result in this being recalculated?
    • Data items for the same user/subject? (CurrentOnly)
    • Data items on the general data for the session? (CurrentAndGeneral)
    • Any change to the session? (EntireSession)

These 3 properties define how the calculated field behaves.

Creating or Updating a Calculated Data Item

Saving a calculated data item works in exactly the same way as does any other data item: POST /api/attribute to create; PUT /api/attribute/[id] to update.

request({
  method: 'PUT',
  url: '/api/attribute' + dataItemId,
  body: {
    id: dataItemId,
    name: 'Say Hello',
    type: 'Text',
    isCalculated: true,
    dependentAttributes: ['[id1], '[id2]'],
    script: 'return "hello, world";',
    scriptScope: 'EntireSession'
  }
});

The example above will create a text data item that will always return a value of "hello, world".

Script Context

The calculation script is automatically executed whenever a session is saved that contains the data item. When run, the script has access to the following variables.

session
// --> the full session object.  for advanced use only

currentSubjectId
// --> the ID of the subject for whom the calculation is being run. null when running within general session data

Important Note: the session value in a calculated field is NOT the same format as that retrieved from the API!

In addition to this, several helper functions are available to quickly access session data.

Get a data item value

//gets the value of the specified data item from the general session data
var sessionValue = getValue('[data item id]');

//gets the value of the specified data item from the subject data for the specified
//subject.  Use currentSubjectId to get the value for the current subject
var subjectValue = getValue('[data item id]', '[subject id]');

//gets the value for the data item (for general or subject data) and attempts to convert
//it to a valid number.  Returns 0 as a default
var numericValue = getNumericValue('[data item id]' /*, [optional subject id]*/);

//lookup values are stored as an array of selected items.  to avoid repeating the "check
//value is array, check length, check first item is not null" cycle, getLookupValue will
//return the first selected value for a lookup or null if none is selected
var lookupValue = getLookupValue('[data item id]' /*, [optional subject id]*/);

Iterate through all subjects

foreachSubject(function(subjectId) {
    //this function will be invoked once for each subject on the session with
    //the subject ID being passed in
});

Iterate through all table cells

foreachCell('[table data item id]', '[column data item id]', /*[ optional subject id], */ function(cellValue) {
    //this function will be invoked once for each row in specified table
    //with the value of the specified column being passed in
});

Conversions

Durations in EDGE10 are stored in [days].[hours]:[minutes]:[seconds].[ms] format: great for readability; not great for calculations.

Two functions are provided to convert between this format and the more calculation-friendly "total milliseconds" format.

var value = '1.02:03:04.567';
var asMilliseconds = convertDurationToMilliseconds(value);
var backToDuration = convertMillisecondsToDuration(asMilliseconds);

Return Types

It is important to make sure that the return type of the calculation function matches the type of the data item. The table below shows acceptable return types.

Data Type Return Value Meaning
Numeric 123 The number 123
"123" The number 123
Text "value" The text 'value'
Bool true True
false False
Duration "1.2:03:04.567" 1d 2h 3m 4s 567ms
DateTime "2015-02-01T03:04:05" 3:04:05 AM on Feb 1st 2015
Single Lookup "Red" The first available lookup item with a value matching "Red"

Examples

A few example scripts to get you started...

Multiplication of X and Y

Data item type: Numeric

var x = getNumericValue('[data item id 1]', currentSubjectId);
var y = getNumericValue('[data item id 2]', currentSubjectId);

return x * y;

Average of X from all players

Data item type: Numeric

var total = 0, count = 0;

foreachSubject(function(subjectId) {
    count++;
    total += getNumericValue('[data item id]', subjectId);
});

return total / count;

Traffic light based on X

Data item type: SingleLookup (Traffic Light)

var value = getNumericValue('[data item id]', currentSubjectId);

if (value < 5) {
    return 'Green';
} else if (value < 8) {
    return 'Amber';
}

return 'Red';

Clone this wiki locally