+ Author: Rocael Hernández, Viaro Networks. OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.
Date: 17-June-2004
+
The purpouse of this package is to handle any IMS Enterprise v.1.1 XML document, and reflect all the respective data into .LRN.
+ Please read http://imsglobal.org/enterprise/ for more infomation.
+ Note: I found this best practice guide very useful: http://www.imsglobal.org/enterprise/entv1p1/imsent_bestv1p1.html
Basically, what the XML will reflects are 3 things:
+ 1. Users. <person>
+ 2. Departments, Subjects and classes (and its relation between them). <group>
+ 3. Relation between users and classes, and proper roles. <membership>
Right now, what ims-ent does is to mimic what the acs-authentication did for #1, but adding also the functionality of #2 & #3.
+The following parameters: department, subject, class should contain the value that tell us if a <group> tag represents one of them, look at the examples below.
+ (if a <typevalue level=x> is not specified / valid one, the parser will not process those <group>, must match with some of the parameter values above)
+
i.e. level = 1 for departments
+ ++
+<group recstatus = "1">+ +
+ <comments>Add a new department (carrera : INGENIERIA EN ELECTRONICA, INFORMATICA Y CIENCIAS DE LA COMPUTACION)</comments>
+ <sourcedid>
+ <source>Universidad Galileo</source>
+ <id>IE</id>
+ </sourcedid>
+ <grouptype>
+ <scheme>Universiad Galileo</scheme>
+ <typevalue level = "1" />
+ </grouptype>
+ ....
+</group> +
+
level = 2 for subjects,
+ note: relation = 1 indicates which group is the parent and relation = 2 is not used by the parser as a first choice
+
+<group recstatus = "1">+ +
+ <comments>Add a new class CO205 , SEMINARIO TEORIA DE SISTEMAS I</comments>
+ <sourcedid>
+ <source>Galileo University Database</source>
+ <id>IE___CO205</id>
+ </sourcedid>
+ <grouptype>
+ <scheme>Galileo University</scheme>
+ <typevalue level = "2" />
+ </grouptype>
+ <description>
+ <short>SEMINARIO TEORIA DE SISTEMAS I</short>
+ </description>
+ <org>
+ <orgname>Universidad Galileo</orgname>
+ <orgunit>IE</orgunit>
+ <type>class</type>
+ <id>CO205</id>
+ </org>
+ <relationship relation = "1">
+ <sourcedid>
+ <source>Galileo University Database</source>
+ <id>IE</id>
+ </sourcedid>
+ <label>department</label>
+ </relationship>
+ <relationship relation = "2">
+ <sourcedid>
+ <source>UDB Class CO205, seccion A</source>
+ <id>CO205___A</id>
+ </sourcedid>
+ <label>section</label>
+ </relationship>
+ ....
+</group> +
+
level = 3 for classes,
++
+<group recstatus = "1">+ +
+ <comments>Add a new seccion (curso: CO205 , seccion: A)</comments>
+ <sourcedid>
+ <source>Universidad Galileo</source>
+ <id>CO205___A</id>
+ </sourcedid>
+ <grouptype>
+ <scheme>Galileo University</scheme>
+ <typevalue level = "3" />
+ </grouptype>
+ <description>
+ <long>SEMINARIO TEORIA DE SISTEMAS I, Seccion A</long>
+ </description>
+ <timeframe>
+ <begin restrict = "1">2004-01-13</begin>
+ <end restrict = "1">2004-06-04</end>
+ <adminperiod>2004-01-13 - 2004-06-04</adminperiod>
+ </timeframe>
+ <relationship relation = "1">
+ <sourcedid>
+ <source>Galileo University Database</source>
+ <id>IE___CO205</id>
+ </sourcedid>
+ <label>class</label>
+ </relationship>
+</group> +
Note the relation of the class (group) with the its subject (parent group).
+ If a relation is not found, it will try to search in the same document for a group that has this group as a child (relation = 2), if not will give you an error.
+ Using the <relationship relation = "1 or 2"> you can implement the hierarchy like: Dep-->Sub-->Class (the only hierarchy supported by .LRN now)
+
We expect the roletype attribute: <role recstatus="1" roletype="2">
+ This is the actual mapping between standard roles defined in the document (http://imsglobal.org/enterprise/entv1p1/imsent_infov1p1.html#1427710) and the ones defined @ .LRN:
+ 2 { dotlrn_instructor_rel }
+ 7 5 { dotlrn_cadmin_rel }
+ 3 { return dotlrn_ca_rel }
+ 6 8 { dotlrn_ta_rel }
+ 4 1 { dotlrn_student_rel }
This is a normal <membership> tag:
+
+<membership>+ +
+ <sourcedid>
+ <source>Universidad Galileo</source>
+ <id>A3606___A</id>
+ </sourcedid>
+ <member>
+ <sourcedid>
+ <source>Universidad Galileo</source>
+ <id>16001</id>
+ </sourcedid>
+ <role recstatus="1" roletype="2">
+ </role>
+ </member>
+ ......
+</membership> +
(we expect at least this information, which is the only that will be used)
+The parameter UserIdReturnProc is the name of a proc that must return the user_id, based on:
+ 1. the person id that we get from the XML document
+ 2. the -authority_id $authority_id that we will get from the system (the proc must accept this: -authority_id $authority_id, i.e. acs_user::get_by_username -username, the first param to be sent to the proc is the id form the user), i.e. by defualt is set --> acs_user::get_by_username -username, which will be called and sent as username the <id> that comes from the XML (by default that <id> is stored in the username when you import users using ims-ent), but you might call another proc that might be useful to get the user_id based on your own needs, for standard use, the default value is good.
+
(Then for each job, you'll get more information about each transaction processed)
+ http-get: define a valid URL to grab the XML. (i.e. http://mysite.com/ims-ent-snapshot.xml)
+ file system: a local file in your server directories to grab the XML. (i.e. /myfiles/ims-ent/incremental-update.xml)
+ xml-rpc: a valid method in a valid RPC host. (i.e. host: http://mysite.com/RPC2 method: IMSEntSnapshot)
+
+ When creating the terms, will search for the best* term that fits between the dates specified in the <timeframe> tag, and will return it. If none fits, will create one automatically with start/end date defined in the document. If the <timeframe> tag is not provided with start / end date, it will select the term that ends most late.
+ * by "best" we mean the term that fits the start/end date that ends the later. (though that can be easily changed, see: ims_enterprise::ims_dotlrn::groups::guess_term)
+ A lot of rules can be done here, but I wanted to keep it simple so anyone else can easily extend to their needs.
+
For depatment, subject & class, we use:
+<long> <--> pretty_name
+<full> <--> description
+<url> <--> external_url (just for deps)
+
It records all the transactions done for a give document processed, it uses as a base the same that acs-authentication had, but with extra items for the new processes.
+We have tested at Galileo with our own generated IMS xml data, so far works quite stable, but is needed more testing, specially if there are legacy systems that can produce the specific xml. Working on PG, oracle will need a few tweaks to make it work, please contact me if you have an interest for oracle.
++ +