Functionality

The functionality provided by the xolp package is explained in the form of simple api usage examples in the following.

API Usage Examples

Minimal example

The following example creates an indicator of 95% for the currently logged in user, where the current URL is taken as activity identifier. (Developers should carefully consider if these defaults make sense in their application context.)

::xolp::Indicator insert -result_numerator 95

Typical example

Suppose there was an Austrian school teacher who conducted a final paper-and-pencil test with three students on 20th December 2016. One student did an excellent job, one showed mediocre performance, one failed. The two positive students practiced before.

Practicing

Firstly, we require an object in the system for the practicing activity:

set practice_test_id [::xolp::Activity require \
  -iri "http://myschool.example.com/2016/class1/course1/practice-test" \
  -title "Practice test" \
  -return id]

Secondly, we require fetch the id for the verb "practiced":

set activity_verb_id [::xolp::ActivityVerb require \
  -iri "http://dotlrn.org/xolp/activity-verbs/practiced" \
  -return id]

Now we can store the students practicing results:

::xolp::Indicator insert \
  -user_id 1 \
  -activity_version_id $practice_test_id \
  -begin_timestamp "2016-12-18 20:58:00" \
  -end_timestamp "2016-12-18 22:10:00" \
  -result_numerator 3 \
  -result_denominator 10

::xolp::Indicator insert \
  -user_id 2 \
  -activity_version_id $practice_test_id \
  -begin_timestamp "2016-12-18 15:54:30" \
  -end_timestamp "2016-12-18 16:59:20" \
  -result_numerator 7 \
  -result_denominator 10

Examination

Analogously, we require an object and verb for the actual test:

set exam_id [::xolp::Activity require \
  -iri "http://myschool.example.com/2016/class1/course1/final-test" \
  -title "Final test" \
  -return id]
set activity_verb_id [::xolp::ActivityVerb require \
  -iri "http://dotlrn.org/xolp/activity-verbs/competed" \
  -return id]

::xolp::Indicator insert \
  -user_id 1 \
  -activity_version_id $exam_id \
  -begin_timestamp "2016-12-20 09:00:30" \
  -end_timestamp "2016-12-20 09:58:00" \
  -result_numerator 100 \
  -result_denominator 100

::xolp::Indicator insert \
  -user_id 2 \
  -activity_version_id $exam_id \
  -begin_timestamp "2016-12-20 09:00:20" \
  -end_timestamp "2016-12-20 09:59:30" \
  -result_numerator 60 \
  -result_denominator 100

::xolp::Indicator insert \
  -user_id 3 \
  -activity_version_id $exam_id \
  -begin_timestamp "2016-12-20 09:01:00" \
  -end_timestamp "2016-12-20 10:02:00" \
  -result_numerator 25 \
  -result_denominator 100

Evaluation

At the end of the day, the teacher decides to evaluate the students' results with his usual grade scale, where one needs 50% to be positive, and 70%, 80% and 90% to get the next higher mark within the Austrian Grading Schema.

set evalschema [::xolp::EvaluationSchema require \
  -iri "https://dotlrn.org/xolp/evaluation-schemas/at-five-to-one"]

set evalscale [::xolp::EvaluationScale require \
  -iri "http://myschool.example.com/gradingschemas/standard" \
  -evalschema_id [$evalschema object_id] \
  -title "MySchool Standard Evaluation Scale" \
  -thresholds {50 70 80 90}]

$evalscale add_to_activity -activity_version_id $activity_version_id

::xolp::User get_activity_evaluation \
    -user_id 1 \
    -iri "http://myschool.example.com/2016/class1/course1/final-test"

Indicator Retrieval

There is a generic procedure ::xolp::Indicator get_values_from_db that allows for (filtered) retrieval of indicators from the fact table.

Date/Time-based Filtering

An example for retrieving indicators filtered by time is implemented in testcase indicator_datetime_queries and exemplified below.

set activity_iri "http://example.com/practice1"
set activity_version_id [::xolp::Activity require -iri $activity_iri -return id]

# Weekend practicing
::xolp::Indicator insert \
  -activity_version_id $activity_version_id \
  -end_timestamp "2016-12-31 23:00:00" \
  -result_numerator 40
::xolp::Indicator insert \
  -activity_version_id $activity_version_id \
  -end_timestamp "2017-01-01 11:30:00" \
  -result_numerator 50

# Weekday practicing
::xolp::Indicator insert \
  -activity_version_id $activity_version_id \
  -end_timestamp "2017-01-02 11:30:00" \
  -result_numerator 60

# All results for this activity
set li [::xolp::Indicator get_values_from_db \
  -user_ids [ad_conn user_id] \
  -activity_iris $activity_iri]

# Dictionary "li"
#  - keys: indicator_ids
#  - values: percentages
# 12345 40.00 12346 50.00 12347 60.00

# Results from weekends
set li [::xolp::Indicator get_values_from_db \
  -user_ids [ad_conn user_id] \
  -activity_iris $activity_iri \
  -end_date_constraint "end_is_weekend = TRUE" ]

# Dictionary "li"
# 12345 40.00 12346 50.00

# Results from weekends in 2016
set li [::xolp::Indicator get_values_from_db \
  -user_ids [ad_conn user_id] \
  -activity_iris $activity_iri \
  -begin_date_constraint "begin_year = '2016'" \
  -end_date_constraint "end_is_weekend = TRUE" ]

# Dictionary "li"
# 12345 40.00

# Average result for this activity
set li [::xolp::Indicator get_values_from_db \
  -aggregate avg \
  -user_ids [ad_conn user_id] \
  -activity_iris $activity_iri]

# Dictionary "li"
#  - keys: aggregated indicator_ids
#  - values: aggregated percentages
# {12345 12346 12347} 50.00

Activity Verb-based Filtering (i.e. Usage Type)

An example for retrieving indicators filtered by usage type (ActivityVerb) is implemented in testcase indicator_verb_queries.

set activity [::xolp::Activity require -iri "http://example.com/activities/test1"]
set practiced_verb [::xolp::ActivityVerb require -iri "http://example.com/verbs/practiced"]
set competed_verb [::xolp::ActivityVerb require -iri "http://example.com/verbs/competed"]

# Practicing
::xolp::Indicator insert \
  -end_timestamp "2014-01-01" \
  -activity_version_id [$activity activity_version_id] \
  -activity_verb_id [$practiced_verb activity_verb_id] \
  -result_numerator 80

# Exam
::xolp::Indicator insert \
  -end_timestamp "2014-01-02" \
  -activity_version_id [$activity activity_version_id] \
  -activity_verb_id [$competed_verb activity_verb_id] \
  -result_numerator 90

# All results for this activity
set results(all) [::xolp::Indicator get_values_from_db \
  -user_ids [ad_conn user_id] \
  -activity_iris [$activity iri]]

# Only exam results
set results(competed) [::xolp::Indicator get_values_from_db \
  -user_ids [ad_conn user_id] \
  -activity_iris [$activity iri] \
  -activity_verb_iris [$competed_verb iri]]

array get results
# competed {124 90.00} all {123 80.00 124 90.00}

Test Cases

The xolp package is shipped with a comprehensive test suite, which can serve as a cookbook for developers with respect to correctly using the api.