Changes between Initial Version and Version 1 of S3/S3Tracking


Ignore:
Timestamp:
03/22/11 10:15:35 (10 years ago)
Author:
Dominic König
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • S3/S3Tracking

    v1 v1  
     1[[TOC]]
     2= Simple Generic Location Tracking System =
     3
     4S3 provides a simple generic location tracking system.
     5
     6This is implemented in {{{models/03_sit.py}}} and {{{modules/s3/s3track.py}}} and can be applied to virtually all entities.
     7
     8== Background ==
     9
     10Location tracking means that an instance of an entity can have:
     11
     12  - a base location
     13  - a current location X at time Y (a so-called "presence log")
     14
     15The tracking system provides the data model and an API to handle both cases.
     16
     17== Base Location ==
     18
     19The base location can be implemented for an entity by adding a field {{{location_id}}} to which references the {{{gis_location}}} table.
     20
     21As this is a pre-defined re-usable field, simply add it to your model:
     22
     23{{{
     24table = db.define_table(tablename,
     25                        ...
     26                        location_id(), # <= add this to give the entity a base location
     27                        ...)
     28}}}
     29
     30== Presence Log ==
     31
     32To capture the current location of an instance at several timepoints, you need to make your entity "trackable".
     33
     34This can be done by defining {{{sit_trackable}}} as super-entity:
     35
     36{{{
     37table = db.define_table(tablename,
     38                        ...
     39                        super_link(db.sit_trackable), # <= add the super-entity key
     40                        ...)
     41
     42s3xrc.model.configure(table,
     43                      super_entity=db.sit_trackable, # <= configure sit_trackable as super-entity
     44                      ...)
     45}}}
     46
     47There is no problem to have this together with other super-entities (the number of super-entities per table is not limited):
     48
     49{{{
     50table = db.define_table(tablename,
     51                        ...
     52                        super_link(db.org_site),
     53                        super_link(db.sit_trackable),
     54                        ...)
     55
     56s3xrc.model.configure(table,
     57                      super_entity=(db.org_site, db.sit_trackable), # <= multiple allowed!
     58                      ...)
     59}}}
     60
     61== API ==
     62
     63=== S3Trackable ===
     64
     65The API uses a wrapper class for database records - {{{S3Trackable}}}.
     66
     67You can create an S3Trackable by using the s3tracker function with the table and the record ID:
     68
     69{{{
     70trackable = s3tracker(db.my_table, 1)
     71}}}
     72
     73This works fine with record UUIDs too:
     74
     75{{{
     76trackable = s3tracker(db.my_table, uuid="9207324b-5dc6-439b-9410-8920cbaf8a34")
     77}}}
     78
     79Instead of the table, you can also specify the tablename:
     80
     81{{{
     82trackable = s3tracker("my_table", uuid="9207324b-5dc6-439b-9410-8920cbaf8a34")
     83}}}
     84
     85You can also specify a query:
     86
     87{{{
     88trackable = s3tracker(db.my_table.uuid == "9207324b-5dc6-439b-9410-8920cbaf8a34")
     89}}}
     90
     91or a record (must be a Row instance):
     92
     93{{{
     94record = db(db.my_table.uuid=="9207324b-5dc6-439b-9410-8920cbaf8a34").select(limitby=(0, 1)).first()
     95trackable = s3tracker(record)
     96}}}
     97
     98or a set of records (must be a Rows instance):
     99
     100{{{
     101records = db(db.my_table.id.belongs(1,2,3,4)).select()
     102trackable = s3tracker(records)
     103}}}
     104
     105It 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.
     106
     107It 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:
     108
     109{{{
     110trackable = s3tracker(db.pr_pentity, 1) # <= the super-entity is automatically replaced by the respective instance record (e.g. in pr_person)
     111}}}
     112
     113
     114=== Base Location ===
     115
     116To retrieve the base location of an object, use get_base_location():
     117
     118{{{
     119base_location = s3tracker(db.pr_person, 1).get_base_location()
     120}}}
     121
     122This will return the full gis_location record(s) for the respective base location(s).
     123
     124To set the base location of an object, use set_base_location():
     125
     126{{{
     127s3tracker(db.pr_person, 1).set_base_location(25) # <= use the record ID of a gis_location
     128}}}
     129
     130Other ways to specify the location:
     131
     132{{{
     133# Using a location record
     134location = db(db.gis_location.id==25).select(limitby=(0, 1)).first()
     135s3tracker(db.pr_person, 1).set_base_location(location)
     136
     137# Using another object containing a location_id
     138hospital = db(db.hms_hospital.id==3).select(limitby=(0, 1)).first()
     139s3tracker(db.pr_person, 1).set_base_location(hospital)
     140
     141# Using another trackable:
     142trackable = s3tracker(db.hms_hospital, 3)
     143s3tracker(db.pr_person, 1).set_base_location(trackable)
     144}}}
     145
     146=== Current location ===
     147
     148When setting/retrieving the current location of an object, you can additionally specify a time point:
     149
     150{{{
     151from datetime import datetime, timedelta
     152one_hour_ago = datetime.utcnow()-timedelta(hours=1)
     153location = s3tracker(db.pr_person, 1).get_location(timestmp=one_hour_ago)
     154}}}
     155
     156  NOTE: all times in the tracking system are considered to be in UTC!
     157
     158To set a current location, you can use set_location().
     159
     160{{{
     161s3tracker(db.pr_person, 1).set_location(25, timestmp=datetime.utcnow())
     162}}}
     163
     164If you omit the timestmp parameter, then the current server time is used.
     165
     166To specify the location, you have the same options in set_location() as in set_base_location().
     167
     168=== Check-in/out ===
     169
     170It 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.
     171
     172This can be achieved by using the check_in() and check_out() methods.
     173
     174{{{
     175>>> s3tracker(db.vt_vehicle, 1).set_location(40) # <= set a current location for the vehicle
     176>>> s3tracker(db.pr_person, 1).check_in(db.vt_vehicle, 1) # <= check in the person to the vehicle
     177>>> location = s3tracker(db.pr_person, 1).get_location() # <= get the location of the person
     178>>> location.id
     17940
     180>>> s3tracker(db.vt_vehicle, 1).set_location(73) # <= set a new location for the vehicle
     181>>> location = s3tracker(db.pr_person, 1).get_location() # <= get the location of the person
     182>>> location.id
     18373
     184>>> s3tracker(db.pr_person, 1).check_out(db.vt_vehicle, 1) # <= check out the person from the vehicle
     185>>> s3tracker(db.vt_vehicle, 1).set_location(21) # <= set a new location for the vehicle
     186>>> location = s3tracker(db.pr_person, 1).get_location() # <= get the location of the person
     187>>> location.id
     18873
     189}}}
     190
     191When 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.
     192
     193Both 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.
     194
     195If you specify a super-entity instance to check-in to, then the respective instance record will automatically be used:
     196{{{
     197s3tracker(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...
     198}}}
     199
     200----
     201[wiki:S3 S3 Guide]
     202
     203DeveloperGuidelines