Sessions

A session is the same as a session on the mobile device.

Each session has a number of attributes associated with it that are common for each project, such as the Unit ID of the device that created the session, and a variable number of points according to the definition of the project at the time the session was created.

The JSON representation of the session will be an object with the following keys:

"uuid" : String, The session UUID
"unit_id" :  String, The Unit ID of the device that created (or last edited) this session
"created" :  String, The date and time the session was created
"created_timestamp" : Integer, The unix timestamp for when the session was created
"saved" :  String, The date and time the session was saved
"saved_timestamp" :  Integer, The unix timestamp for when the session was saved
"received" :  String, The date and time the session was received at the server (when the device submitted the session).
"received_timestamp" : Integer, The unix timestamp for when the session was received.
"received_from" : String, The username or device unit ID that created or most recently modified this session. This will be a User's username if the session was created/edited from the web portal or via the API and would be a device unit ID if created/edited via a device.
"is_deleted": Boolean, The status for the session. This will be true when the session has been deleted or false when the session is active.
"data" : object/dictionary, The values for the points in this session, see below for further notes.

The data values for point names are returned in an object as follows:

• The point name is used as the key. This is always represented in lower case, which mirrors the internal implementation of Mobile Data mobile clients, and allows point names to be referred to in a case insentive manner by always converting point names to lower case.
• The corresponding object (dictionary) value is the value of the point. Typically, all values are stored as strings. There may be some points, such as Sketch points that store binary data, or Camera points that store attached image files. These complex values are represented as an object(dictionary) with keys describing the file. This typically includes the name of the attached file, but will not normally contain the actual file data.

Time Zone Support

All values stored in the Mobile Data Anywhere database are UTC timestamps. These can be consistently converted to whatever timezone is required.

However, on the mobile client devices, the times are stored in the local time zone of the device. In order to know what the device’s local time zone is, the mobile devices store their local time zone offset in a hidden point named “timezone”. This value is used, if present to convert the created and saved dates into UTC and back again if sent to a device.

You can easily set this value when creating a session.

The value of the __timezone__ point is the number of seconds from UTC. For example, Brisbane Australia (+10 hours) would be 36000, and New York (-5 hours) would be -18000

Accessing Attachments

For points that contain attachments, the attached file can be accessed via the Attachments API calls. Attachments can be quite large and are stored separately to optimise session data access and filtering operations. This also allows API clients to cache attachments so that they do not need to be downloaded repeatedly, saving bandwidth and time.

Changing project definitions

The points stored in a session reflect the definition of the project at the time the session was created. Subsequently altering a project does not cause session values to be recalculated or populated with default values in the updated project.

Additionally, some points may not store a value at all if the page containing the point has never been accessed. Clients should always test for the presence of a point’s name in the “data” object. A missing key, key with a null value or a key with an empty string value should all be considered as having the same “empty” value.

Filtering results.

The index (get list) and count (get count) methods can apply a filter to the database and return the sessions, or count of sessions matching the filter.

The following filters can be applied in the query string:

• received_since: A unix timestamp where only sessions received by the server after this time will be included.
• skip: Skip a number of results in the get session list method (does not apply to count method).
• limit: Return only this many results in the get session list method (does not apply to count method).
• filter[unit_id]: Only sessions submitted by a specific unit id.
• filter[received_from]: Only sessions that were last modified by the specified username or device unit id.
• filter[Data.{point_name}]. Only sessions where the point named “point_name” will be included. Note that “Data” must have a capital D and the point name must be in lower case.

The “filter” keys also support a number of conditions, such as equals, not equals, contains, not contains, and case insensitive versions of these. There is also conditions to check for the presence or absence of a value for the given point. These filter conditions are used by constructing the query parameter like so:

• filter[Data.{point_name}][{condition}] where {point_name} is the lower case point name, and {condition} is one of:
  • eq - equals
  • not_eq - not equals
  • contains
  • not_contains
  • eq_case - case insensitive equals
  • not_eq_case
  • contains_case
  • not_contains_case
  • present - value is ignored in comparison
  • blank - value is ignored in comparison

Also note that the square brackets need to be correctly URL encoded.

Example:

Filter by presence of a value in a the point “name” and the point “address” containing ‘Coast’ results in the following query string before URL escaping: ?filter[Data.name][present]=1&filter[Data.address][contains]=Coast

GET /api/v1/projects/1234/sessions?filter%5BData.name%5D%5Bpresent%5D%3D1%26filter%5BData.address%5D%5Bcontains%5D%3DCoast