Index: openacs-4/packages/assessment/www/doc/as_items.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/as_items.html,v
diff -u -r1.3 -r1.4
--- openacs-4/packages/assessment/www/doc/as_items.html 21 Jul 2004 16:02:49 -0000 1.3
+++ openacs-4/packages/assessment/www/doc/as_items.html 28 Jul 2004 10:35:57 -0000 1.4
@@ -13,7 +13,7 @@
assessment
system. These repositories support reuse of Assessment components by
storing of the various as_items (or questions if you like) and groups
-of as_items (ie Sections) that can be used in an assessment. You are
+of as_items (e.g. Sections) that can be used in an assessment. You are
able to
add/edit/delete an as_item of a certain type to a certain scope.
Furthermore it allows you to search and browse for questions for
@@ -119,9 +119,9 @@
perform as_item
adp_chunk - a denormalization to cache the generated
"widget"
-for the as_item (NB: when any change is made to an as_as_item_choice
+for the as_item (NB: when any change is made to an as_item_choice
related
-to an as_as_item, this will have to be updated!)
+to an as_item, this will have to be updated!)
Permissions / Scope: as_items need a clearly defined
scope, in
@@ -212,7 +212,7 @@
response
data_type - Integer vs. real number vs. text
case_sensitive_p - Shall the match be case sensitive
- score - Percentage a correct match gives
+ percent_score - Percentage a correct match gives
compare_by - How is the comparison done (equal, contains,
regexp)
@@ -300,7 +300,8 @@
sort_order - In which order shall this choice appear with
regards to the MC item. Note, this can be overriden by the display type.
- score - Score given to the user if this choice is selected
+ percent_score - Score given to the user if this choice is
+selected
(in percent).
@@ -356,9 +357,9 @@
specified by the author
selected_p - Is this choice selected by default (when the
item is presented to the user)
- correct_answe_p
+ correct_answer_p
- score
+ percent_score
area_type - Type of the
area that uses the coordinates_string
coordinates_string -
@@ -377,7 +378,7 @@
the widget. Each widget has at least one item_display_type associated
with it. In the long run I think this system has the potential to
become a part of OpenACS itself (storing additional display information
-for each acs_object), but we are not there yet :). Obviouslly we are
+for each acs_object), but we are not there yet :). Obviously we are
talking cr_item_types here as well.
Each item_display_type has a couple of attributes in common.
@@ -424,8 +425,6 @@
short_answer (as_item_display_sa) - Multiple textboxes in one
item.
-
- - abs_size - An
abstraction of the real size value in
"small","medium","large". Up to the developer how this translates.
@@ -448,8 +447,6 @@
- abs_size - An abstraction of the real size value in
"small","medium","large". Up to the developer how this translates.
-
- - acs_widget - the
type of "widget" displayed when the
Item is output in html. There are many types we should support beyond
@@ -492,8 +489,7 @@
- choice_label_orientation - how shall the label be positioned
in relation to the choice (top, left, right, buttom).
- - button_type - type of button to use
- - sort_order: Numerical, alphabetic, randomized or
+
- sort_order_type: Numerical, alphabetic, randomized or
by order of entry (sort_order field).
- item_answer_alignment - the orientation between the
@@ -518,7 +514,7 @@
- choice_label_orientation
- allow_multiple_p - Is it allow to select multiple values ?
- - sort_order: Numerical, alphabetic, randomized or
+
- sort_order_type: Numerical, alphabetic, randomized or
by order of entry (sort_order field).
- item_answer_alignment - the orientation between the
@@ -541,7 +537,7 @@
"popup menu" (select box)
- - sort_order: Numerical, alphabetic, randomized or
+
- sort_order_type: Numerical, alphabetic, randomized or
by order of entry (sort_order field).
- allow_multiple_p - Is
it allow to select multiple values ?
@@ -567,8 +563,8 @@
-
-item_answer_alignment - the orientation between the
+ class="reg">item_answer_alignment
+- the orientation between the
"question part" of the Item (the item_text/item_subtext) and the
"answer part" -- the native Item widget (eg the textbox) or the 1..n
choices. Alternatives accommodate L->R and R->L alphabets (or is
@@ -582,24 +578,24 @@
- - multiple-choice-other: Consider, for instance, a combo box
+
- multiple-choice-other (as_item_display_mco): Consider, for
+instance, a combo box
that consists of a radiobutton plus a textbox -- used for instance when
you need a check "other" and then fill in what that "other" datum is.
In effect this is a single Item but it has two different forms: a
radiobutton and a textbox. The answer will NOT be stored in the answer
-choice table. There is no item_type "multiple-choice-other"
+choice table. There is no item_type "multiple-choice-other".
- widget_choice - Type of the widget for the multiple choice
part
- - sort_order: Numerical, alphabetic,
+
- sort_order_type: Numerical, alphabetic,
randomized or
by order of entry (sort_order field).
- - other_size: size of the other text field.
- other_label: label (instead of "other").
-
-item_answer_alignment - the orientation between the
+ class="reg">item_answer_alignment
+- the orientation between the
"question part" of the Item (the item_text/item_subtext) and the
"answer part" -- the native Item widget (eg the textbox) or the 1..n
choices. Alternatives accommodate L->R and R->L alphabets (or is
Index: openacs-4/packages/assessment/www/doc/data_collection.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/data_collection.html,v
diff -u -r1.1 -r1.2
--- openacs-4/packages/assessment/www/doc/data_collection.html 13 Jun 2004 23:20:44 -0000 1.1
+++ openacs-4/packages/assessment/www/doc/data_collection.html 28 Jul 2004 10:35:57 -0000 1.2
@@ -17,11 +17,9 @@
- survey_responses which capture information about which
-survey was completed, by whom, when, etc
-
+survey was completed, by whom, when, etc
- survey_question_responses which capture the actual user
-data in a "long skinny table" mechanism
-
+data in a "long skinny table" mechanism
This suffices for one-shot surveys but doesn't support the fine
@@ -32,17 +30,11 @@
- Assessment Session which captures information about
-which Assessment, which Subject, when, etc
-
- - Assessment Data which holds information about the status
-of the entire Assessment (rolled up from the constituent parts)
-
- - Section Data which holds information about the status of
-each Section
-
+which Assessment, which Subject, when, etc
+ Section Data which holds information about the status of
+each Section
Item Data which holds the actual data extracted from the
-Assessment's html forms; this is the "long skinny table"
-
+Assessment's html forms; this is the "long skinny table"
To support user modification of submitted data (of which
"store&resume" is a special case), we base all these entities in
@@ -53,52 +45,21 @@
Assessment. While this situation may be unusual, the fact that it must
be supported means that the semantics of cr_items don't fit the
Assessment itself. They do fit the semantics of a given user's
-Assessment "session" however.)
-
-Note that all these entities derive from the CR, they are also all
-acs_objects and thus automagically have the standard creation_user,
-creation_date etc attributes. We don't mention them separately here.
-
-Also, while this doesn't impact the datamodel structure per se,
-we add an important innovation to Assessment that wasn't used in
-"complex survey" or questionnaire. When a user initiates an Assessment
-Session, an entire set of Assessment objects are created (literally,
-rows are inserted in all the relevant tables as defined by the
-structure of the Assessment). Then when the user submits a form with
-one or more Items "completed", all database actions from there on
-consist of updates in the CR, not insertions. (In contrast, the systems
-to date all wait to insert into "survey_question_responses", for
-example, until the user submits the html form.) The big advantage of
-this is that determining the status of any given Item, Section or the
-entire Assessment is now trivial. We don't have to see whether an Item
-Data row for this particular Assessment Session is already there and
-then insert it or else update it; we know that it's there and we just
-update it. More importantly, all of our reporting UIs that show
-Assessment admins the current status of users' progress through the
-Assessment are straightforward.
-
+Assessment "session" however.)
We distinguish here between "subjects" which are users whose
information is the primary source of the Assessment's responses, and
"users" which are real OpenACS users who can log into the system.
Subjects may be completing the Assessment themselves or may have
completed some paper form that is being transcribed by staff people who
are users. We thus account for both the "real" and one or more "proxy"
-respondents via this mechanism.
+respondents via this mechanism. To make live not too complicated we
+will assume that all subjects have a user_id in OpenACS.
Note that we assume that there is only one "real"
respondent. Only one student can take a test for a grade. Even if
multiple clinical staff enter data about a patient, all those values
still pertain to that single patient.
-One final note: we denormalize several attributes in these entities
---
-event_id, subject_id and staff_id. The reason for putting these foreign
-keys in each row of the "data" is to produce a "star topology" of fact
-tables and dimension tables. This will facilitate data retrieval and
-analysis. (Are there other dimension keys that we should include
-besides these?)
-
-
Synopsis of Data-Collection Datamodel
Here's the schema for this subsystem:
@@ -107,8 +68,7 @@
-
+ style="width: 1022px; height: 680px;">
@@ -123,238 +83,108 @@
Assessment Sessions (as_sessions) are the top of the
data-collection entity hierarchy. They provide the central definition
of a given subject's performance of an Assessment. Attributes include:
-
- - session_id
+
- session_id
+ - cr::name - Identifier, format "$session_id-$last_mod_datetime"
- - assessment_id (note that this is actually a revision_id)
-
+ - assessment_id (note that this is actually a revision_id)
- subject_id - references a Subjects entity that we don't
-define in this package; presumably a table derived from Persons since
-we need to be able to deploy Assessments to individuals who aren't
-OpenACS users
-
+define in this package. Should reference the users table as there is no
+concept of storing persons in OpenACS in general (yet)
staff_id - references Users if someone is doing the
-Assessment as a proxy for the real subject
-
- event_id
-
- target_datetime - when the subject should do the Assessment
-
+Assessment as a proxy for the real subject
+ target_datetime - when the subject should do the Assessment
creation_datetime - when the subject initiated the
-Assessment
-
+Assessment
first_mod_datetime - when the subject first sent something
-back in
-
- last_mod_datetime - the most recent submission
-
+back in
+ last_mod_datetime - the most recent submission
completed_datetime - when the final submission produced a
-complete Assessment
+complete Assessment
+ session_status - Status of the session (and therefore of the
+assessment with regards to the subject)
+ ip_address - IP Address of the entry
- signature_id - references optionial digital signature in
-as_signatures
+ percent_score - Current percentage of the subject achieved so
+far
- session_status - tracks FSM
-
- ip_address
-
-
-
+
- Assessment Data (as_assessment_data) captures
-information about the Assessment (NB this may overlap with
-as_sessions). Attributes include:
-
-
- - assessment_data_id
-
- - session_id
-
- - subject_id
-
- - staff_id
-
- - event_id
-
- - assessment_id
-
- - signature_id
-
- - assessment_status
-
-
-
-
-
- Assessment Section Data (as_section_data) tracks the
+ Assessment Section Data (as_section_data) tracks the
state of each Section in the Assessment. Attributes include:
-
- - section_data_id
+
- section_data_id
+ - cr::name - Identifier, format "$session_id-$last_mod_datetime"
- - session_id
-
- - event_id
-
- - subject_id
-
- - staff_id
-
- - section_id
-
- - signature_id
-
- - section_status
-
+ - session_id
+ - section_id
+ - section_status
-
-
+
Assessment Item Data (as_item_data) is the heart
of the data collection piece. This is the "long skinny table" where all
the primary data go -- everything other than "scale" data ie calculated
scoring results derived from these primary responses from subjects.
Attributes include:
-
- - item_data_id
-
- - session_id
-
- - event_id
-
- - subject_id
-
- - staff_id
-
- - item_id
-
- - signature_id
-
- - item_status
-
- - is_unknown_p - defaults to "f" - important to clearly
+
- item_data_id
+ - session_id
+ - cr::name - identifier in the format "$item_id-$subject_id"
+ - subject_id
+ - staff_id
+ - item_id
+ - choice_id_answer - references as_item_choices
+ - boolean_answer
+ - clob_answer
+ - numeric_answer
+ - integer_answer
+ - varchar_answer
+ - text_answer
+ - timestamp_answer
+ - content_answer - references cr_revisions
+ - Possible Extension: item_status - Status of the answer. This
+might be
+"unanswered, delayed, answered, final". This can be put together with is_unknown_p - defaults to "f" -
+important to clearly
distinguish an Item value that is unanswered from a value that means
"We've looked for this answer and it doesn't exist" or "I don't know
the answer to this". Put another way, if none of the other "value"
attributes in this table have values, did the subject just decline to
answer it? Or is the "answer" actually this: "there is no answer". This
-attribute toggles that clearly when set to "t".
-
- - choice_id_answer - references as_item_choices
-
- - boolean_answer
-
- - clob_answer
-
- - numeric_answer
-
- - integer_answer
-
- - varchar_answer
-
- - text_answer
-
- - timestamp_answer
-
- - content_answer - references cr_revisions
-
- - attachment_answer - may be redundant with content_answer (?)
-
- - attachment_file_type
-
- - attachment_file_extension
-
+attribute toggles that clearly when set to "t".
-
-
+
- Assessment Scale Data (as_scale_data) captures derived
-data calculated from subjects' raw responses. Attributes include:
-
-
- - scale_data_id
-
- - session_id
-
- - event_id
-
- - subject_id
-
- - staff_id
-
- - scale_id
-
- - assessment_id
-
- - signature_id
-
- - scale_score_status
-
- - is_unknown_p
-
- - numeric_value
-
- - varchar_value - optional nominal or ordinal value
-
-
-
-
+ Assessment Scales will for the time being be handled by
+an external grading / evaluation package. Assessment will only work
+with percentages internally. It might be necessary to add scales into
+assessment as well, but we will think about this once the time arrives.
+
- Assessment Annotations (as_annotations) provides a
+ Assessment Annotations provides a
flexible way to handle a variety of ways that we need to be able to
"mark up" an Assessment. Subjects may modify a response they've already
made and need to provide a reason for making that change. Teachers may
want to attach a reply to a student's answer to a specific Item or make
-a global comment about the entire Assessment. This mechanism provides
-that flexibility, and is designed like the old general_comments system.
-An argument could be made to use a generic OpenACS Comments system but
-such doesn't exist now, and probably our uses here are specific enough
-that it makes sense to have our own. Attributes include:
-
-
- - annotation_id
-
- - on_what_table
-
- - on_what_id
-
- - title
-
- - text
-
- - content_id - references cr_revisions
-
- - signature_id
-
-
-
-
+a global comment about the entire Assessment. This will be achieved by
+using the General Comments System of OpenACS
+
+
+ - Signing of content allows
+to verify that the data submitted is actually from the person it is
+pretended to be from. This assumes an public key environment where the
+public key is stored along with the user information (e.g. with the
+users table) and the data stored in as_item_data is additionally stored
+in a signed version (signed with the secret key of the user). To verify
+if the data in as_item_data is actually verified the system only has to
+check the signed_data with the public key and see if it matches the
+data.
- - Assessment Signatures (as_signatures): abstracts the
-digital signatures mechanism from the data tables themselves.
-Attributes include:
-
-
- - signature_id
-
- - subject_id
-
- - staff_id
-
- - on_what_table
-
- - on_what_id
-
- - reason
-
- - signature - a hash of the primary datum encrypted with the
-user's passcode
-
-
-
+