Changes between Initial Version and Version 1 of S3/S3Tracking

Timestamp:

03/22/11 10:15:35 (14 years ago)

Author:

Dominic König

Comment:

--

S3/S3Tracking

@@ +1 @@
+[[TOC]]
+= Simple Generic Location Tracking System =
+
+S3 provides a simple generic location tracking system.
+
+This is implemented in {{{models/03_sit.py}}} and {{{modules/s3/s3track.py}}} and can be applied to virtually all entities.
+
+== Background ==
+
+Location tracking means that an instance of an entity can have:
+
+  - a base location
+  - a current location X at time Y (a so-called "presence log")
+
+The tracking system provides the data model and an API to handle both cases.
+
+== Base Location ==
+
+The base location can be implemented for an entity by adding a field {{{location_id}}} to which references the {{{gis_location}}} table.
+
+As this is a pre-defined re-usable field, simply add it to your model:
+
+{{{
+table = db.define_table(tablename,
+                        ...
+                        location_id(), # <= add this to give the entity a base location
+                        ...)
+}}}
+
+== Presence Log ==
+
+To capture the current location of an instance at several timepoints, you need to make your entity "trackable".
+
+This can be done by defining {{{sit_trackable}}} as super-entity:
+
+{{{
+table = db.define_table(tablename,
+                        ...
+                        super_link(db.sit_trackable), # <= add the super-entity key
+                        ...)
+
+s3xrc.model.configure(table,
+                      super_entity=db.sit_trackable, # <= configure sit_trackable as super-entity
+                      ...)
+}}}
+
+There is no problem to have this together with other super-entities (the number of super-entities per table is not limited):
+
+{{{
+table = db.define_table(tablename,
+                        ...
+                        super_link(db.org_site),
+                        super_link(db.sit_trackable),
+                        ...)
+
+s3xrc.model.configure(table,
+                      super_entity=(db.org_site, db.sit_trackable), # <= multiple allowed!
+                      ...)
+}}}
+
+== API ==
+
+=== S3Trackable ===
+
+The API uses a wrapper class for database records - {{{S3Trackable}}}.
+
+You can create an S3Trackable by using the s3tracker function with the table and the record ID:
+
+{{{
+trackable = s3tracker(db.my_table, 1)
+}}}
+
+This works fine with record UUIDs too:
+
+{{{
+trackable = s3tracker(db.my_table, uuid="9207324b-5dc6-439b-9410-8920cbaf8a34")
+}}}
+
+Instead of the table, you can also specify the tablename:
+
+{{{
+trackable = s3tracker("my_table", uuid="9207324b-5dc6-439b-9410-8920cbaf8a34")
+}}}
+
+You can also specify a query:
+
+{{{
+trackable = s3tracker(db.my_table.uuid == "9207324b-5dc6-439b-9410-8920cbaf8a34")
+}}}
+
+or a record (must be a Row instance):
+
+{{{
+record = db(db.my_table.uuid=="9207324b-5dc6-439b-9410-8920cbaf8a34").select(limitby=(0, 1)).first()
+trackable = s3tracker(record)
+}}}
+
+or a set of records (must be a Rows instance):
+
+{{{
+records = db(db.my_table.id.belongs(1,2,3,4)).select()
+trackable = s3tracker(records)
+}}}
+
+It is possible to specify multiple records for the same S3Trackable. If multiple records are specified or found, then they will be handled as '''one''' trackable object '''with multiple locations''', i.e. if you retrieve its location, you will get a list of locations back. If you update its location, all of its records will be updated the same way.
+
+It is possible to specify a super-entity for an S3Trackable. In this case, the tracker will automatically find the respective records in the instance table(s) and use them instead:
+
+{{{
+trackable = s3tracker(db.pr_pentity, 1) # <= the super-entity is automatically replaced by the respective instance record (e.g. in pr_person)
+}}}
+
+
+=== Base Location ===
+
+To retrieve the base location of an object, use get_base_location():
+
+{{{
+base_location = s3tracker(db.pr_person, 1).get_base_location()
+}}}
+
+This will return the full gis_location record(s) for the respective base location(s).
+
+To set the base location of an object, use set_base_location():
+
+{{{
+s3tracker(db.pr_person, 1).set_base_location(25) # <= use the record ID of a gis_location
+}}}
+
+Other ways to specify the location:
+
+{{{
+# Using a location record
+location = db(db.gis_location.id==25).select(limitby=(0, 1)).first()
+s3tracker(db.pr_person, 1).set_base_location(location)
+
+# Using another object containing a location_id
+hospital = db(db.hms_hospital.id==3).select(limitby=(0, 1)).first()
+s3tracker(db.pr_person, 1).set_base_location(hospital)
+
+# Using another trackable:
+trackable = s3tracker(db.hms_hospital, 3)
+s3tracker(db.pr_person, 1).set_base_location(trackable)
+}}}
+
+=== Current location ===
+
+When setting/retrieving the current location of an object, you can additionally specify a time point:
+
+{{{
+from datetime import datetime, timedelta
+one_hour_ago = datetime.utcnow()-timedelta(hours=1)
+location = s3tracker(db.pr_person, 1).get_location(timestmp=one_hour_ago)
+}}}
+
+  NOTE: all times in the tracking system are considered to be in UTC!
+
+To set a current location, you can use set_location().
+
+{{{
+s3tracker(db.pr_person, 1).set_location(25, timestmp=datetime.utcnow())
+}}}
+
+If you omit the timestmp parameter, then the current server time is used.
+
+To specify the location, you have the same options in set_location() as in set_base_location().
+
+=== Check-in/out ===
+
+It might be desirable to track one object together with another. For example, if a person is in a vehicle, and the vehicle's location changes, then the location of the person should change as well.
+
+This can be achieved by using the check_in() and check_out() methods.
+
+{{{
+>>> s3tracker(db.vt_vehicle, 1).set_location(40) # <= set a current location for the vehicle
+>>> s3tracker(db.pr_person, 1).check_in(db.vt_vehicle, 1) # <= check in the person to the vehicle
+>>> location = s3tracker(db.pr_person, 1).get_location() # <= get the location of the person
+>>> location.id
+40
+>>> s3tracker(db.vt_vehicle, 1).set_location(73) # <= set a new location for the vehicle
+>>> location = s3tracker(db.pr_person, 1).get_location() # <= get the location of the person
+>>> location.id
+73
+>>> s3tracker(db.pr_person, 1).check_out(db.vt_vehicle, 1) # <= check out the person from the vehicle
+>>> s3tracker(db.vt_vehicle, 1).set_location(21) # <= set a new location for the vehicle
+>>> location = s3tracker(db.pr_person, 1).get_location() # <= get the location of the person
+>>> location.id
+73
+}}}
+
+When you set the location of a checked-in object explicitly using set_location(), then the object will automatically be checked-out from wherever it has been checked-in before.
+
+Both check_in() as well as check_out() accept the timestmp parameter to set the time of the check-in/out explicitly. If omitted, then the current server time is used.
+
+If you specify a super-entity instance to check-in to, then the respective instance record will automatically be used:
+{{{
+s3tracker(db.pr_person, 1).check_in(db.org_site, 4) # <= checks-in the person to the respective org_site instance, i.e. hospital or office...
+}}}
+
+----
+[wiki:S3 S3 Guide]
+
+DeveloperGuidelines