Properties

Concepts

A property value can hold arbitrary data. Each property has a name, a value and a parent it belongs to. A parent can be a user, a bot or the global object. Saga properties are stored in a timeline, old values are accessible through the stream and value list.

A property can trigger script invocations. They are bound to scripts via a property path:

/PARENT_TYPE/properties/NAME 

PARENT_TYPE is either user, bots or globals. NAME is the name of the property. See scripts for further details.

Special Properties

Property values can hold arbitrary data and have no build in behaviour, except 'geoJSON' and '_defaults'.

geoJSON

Queryable geo data needs special data indexing. Properties with the name 'geoJSON' for any parent needs to conform to the GeoJson.

_defaults

Saga can be used to run simulations. Simulations are likely multiple times. When the users, bots or globals properties are reset, the value keys of the _defaults property value are used to restore the start point of simulation.

Example:

{
  "flickr_settings": {
    "query": {
      "api_key": "ff5fba861475e9e90bdd380c31f39027",
      "radius": 2
    },
    "wait": 500,
    "chance": 0.4
  },
  "carto_db_settings": {
    "access_token": "3109b1009f154bf62949fd23f5220658cca22ecc31",
    "data_base_name": "public.hexagram",
    "public_map_id": "3925d86b-ea46-4457-8a1b-2872414bfbe5",
    "username": "hexagram"
  }
}

After the reset of the properties the user will have the properties flickr_settings and carto_db_settings. No need to manually enter them after the reset.

..._settings

It's recommended to use naming patterns, we recommend that any property that holds important settings such api or authentication keys to be stored in properties with the post fix _settings such carto_db_settings to make them easily identifiable.

Listing Properties

• GET /users/:user_id/properties
• GET /bots/:bot_id/properties
• GET /globals/properties

List of the most current data of the given parent which is either an user, a bot or global.

• type - either bot/user
• parent_id - the id of the parent
• name - the name of the property
• value - the value of the property
• sortable_id - each value has its own sortable id that can be used for streaming and history, see resources below
• source_creator - always contains type to represent what action created that value, can be either _defaults, job, scripts, rest, socket or OOB. In case of job or script it also contains an id attribute that refers to entity that created the value
• source_property - only if the property was created within a script the source_property with the property id is given.
• runnable_call_id - the id of the runnable_call that created that property

RESPONSE

[
    {
        "_id": "5746021d2c720c0300b97a8c",
        "source_creator": {
            "type": "_defaults"
        },
        "type": "user",
        "parent_id": "55eef2a943f0910300969b90",
        "value": {
            "name": "Home Sweet Home -> Mechanics Alley",
            "address": [
                "Mechanics Alley",
                "New York, NY 10002"
            ],
            "location": {
                "latitude": 40.712366,
                "longitude": -73.993799
            }
        },
        "name": "home",
        "runnable_call_id": "5a5e52fedb9ebb774b998415",
        "updatedAt": "2016-05-25T19:50:53.741Z",
        "createdAt": "2016-05-25T19:50:53.741Z",
        "sortable_id": 9717190,
        "__v": 0
    },
    {
        "_id": "577aaf9fdb074e030090a661",
        "sortable_id": 12652429,
        "createdAt": "2016-07-04T18:49:03.658Z",
        "name": "visual_prefences",
        "value": {
            "fashion": 131.99874728799173,
            "pretty": 188.40723030755805,
            "happy": 260.74420072166015,
            "sexy": 70.49070611150216,
            "smile": 195.4470449214787,
            "adult": 365.16412551408087,
            "people": 266.6158979461236,
            "person": 279.5863654583362
        },
        "parent_id": "55eef2a943f0910300969b90",
        "source_property": {
            "id": "577aaf9fdb074e030090a65d"
        },
        "source_creator": {
            "id": "568b1ef0de5a400300712fc7",
            "type": "scripts"
        }
    }
]

Creating Properties

• POST /users/:user_id/properties(/:operator_name)?
• POST /bots/:bot_id/properties(/:operator_name)?
• POST /globals/properties(/:operator_name)?

Create a new property associated with the given parent. A new value will trigger a socket.io WebSocket notification. The source_creator -> type will be always 'rest'.

POST

{
  "name": "test",
  "value": "1"
}

Optional Parameters

• inline when a property is designated for processing by a script, a queue message containing the property_id is queued, when inline is set to true the actual property value is being queued
• inline_parent when a property is designated for processing by a script, a queue message containing the parent_id is queued, when inline_parent is set to true the actual parent value is being queued
• direct when set to true the script property processing is invoked directly in the same process rather than queuing it
• passive when set to true the property is only stored in parent object (either user, bot or global) and no script is triggered.
• test_data declaring the property explicitly as test data
• key refers to the key parameter some operator methods, supply when needed
• operator refers to the methods in the javascript api. Permitted values:
  • inrc
  • mul
  • sadd
  • rem
  • lpush
  • rpush
  • lpop
  • rpop
  • set
  • unset
  • hincr
  • hmul
  • hlpush
  • hrpush
  • hlpop
  • hrpop
  • hrem
  • hsadd

POST

{
  "name": "test",
  "value": "1"
}

RESPONSE

{
    "__v": 0,
    "sortable_id": 12637454,
    "createdAt": "2016-07-04T13:28:48.378Z",
    "updatedAt": "2016-07-04T13:28:48.378Z",
    "name": "test",
    "value": "1",
    "parent_id": "55eef2a943f0910300969b90",
    "source_creator": {
        "type": "http"
    },
    "_id": "577a6490fedf1e030057095c"
}

Reset Properties

• DELETE /users/:user_id/properties
• DELETE /bots/:bot_id/properties
• DELETE /globals/properties

This resets the properties of the given parent. See _defaults above a certain state should be restored.

Streaming Properties

• GET /users/:user_id/properties/stream
• GET /bots/:bot_id/properties/stream
• GET /globals/properties/stream

Gives access to the time-series property value stream of the selected parent. Use the limit URL parameter to limit the amount of values being returned and the before_id or since_id URL parameter to specify the value selection start. Both _id's refer to the sortable_id of a property value (for example sortable_id : 12637454 ). It also allows filtering of certain properties, all the name provided in the not_names URL parameter will not appear in the response. The parameter search can be used for search that match parts of a property name.

Property list response as before

Property Value List

• GET /users/:user_id/properties/:property_name/values
• GET /bots/:bot_ud/properties/:property_name/values
• GET /globals/properties/:property_name/values

Gives access to the time-series values of a specific property. Use the limit URL parameter to limit the amount of values being returned and the before_id or since_id URL parameter to specify the value selection start. Both _id's refer to the sortable_id of a property value (for example sortable_id : 12637454 )

Property list response as before

Getting single properties

• GET /users/:username/properties/id/:property_id
• GET /bots/:botname/properties/id/:property_id
• GET /globals/properties/id/:property_id

Get a single property with the given id.

RESPONSE

{
    "__v": 0,
    "sortable_id": 12637454,
    "createdAt": "2016-07-04T13:28:48.378Z",
    "updatedAt": "2016-07-04T13:28:48.378Z",
    "name": "test",
    "value": "1",
    "parent_id": "55eef2a943f0910300969b90",
    "source_creator": {
        "type": "http"
    },
    "_id": "577a6490fedf1e030057095c"
}

Test Properties

• POST /users/:user_id/properties/test
• POST /bots/:bot_id/properties/test
• POST /globals/properties/test

See Test Data.