Integration Manual
Integration between INGRID and other systems
INGRID is an OLM (Open Learner Model) which allows its integration with different e-learning systems working with user models.
In order to use INGRID, a system must provide ir a specific user model and some other configuration options through a web service, which is currently hosted at http://ingrid.iaia.lcc.uma.es/ingridExternal?wsdl. This web service provide us a single operation, connect, returning a URL from which will be temporarily accessible the graphic representation of that model:
String connect(String model, String ontology, String actions, String configuration)
Parameter Description
model
XML-formatted string with the model to be represented. It will link each concept with its distribution and grades, and it will also include the temporal model and the group comparative.
The XML Schema to be fullfilled by that XML string can be found in the next link: XML Schema
Example:
<Model>
<Scores date="10-10-2011" lowBound="0" upperBound="10">
<Concept id="1" score="5">
<Evidence date="09-10-2011" name="Test Siette" score="5">
</Evidence>
<Evidence date "05-10-2011" name="Examen" score="4">
</Evidence>
<Distribution>
<Elem data ="-3" prob="0"></Elem>
<Elem data ="-2" prob="10"></Elem>
<Elem data ="-1" prob="15"></Elem>
<Elem data ="0" prob="15"></Elem>
<Elem data ="1" prob="30"></Elem>
<Elem data ="2" prob="20"></Elem>
<Elem data ="3" prob="10"></Elem>
</Distribution>
<Comparative>
<Elem data ="-3" prob="0"></Elem>
<Elem data ="-2" prob="10"></Elem>
<Elem data ="-1" prob="15"></Elem>
<Elem data ="0" prob="15"></Elem>
<Elem data ="1" prob="20"></Elem>
<Elem data ="2" prob="30"></Elem>
<Elem data ="3" prob="10"></Elem>
</Comparative>
<TempModel>
<Milestone date="20-01-2011" score="3">
<Distribution>
...
</Distribution>
</Milestone>
<Milestone date="20-02-2011" score="5">
<Distribution>
...
</Distribution>
</Milestone>
</TempModel>
</Concept>
<Concept id="2" score="6">
...
</Concept>
</Scores>
</Model>
ontology
URL (linking to owl ontology) or XML-formatted string with the ontology to be represented.
The XML Schema to be fullfilled by that XML string can be found in the next link: XML Schema
Example:
<Ontology>
<Concept id="1" name="Programación C"></Concept>
<Concept id="2" name="Bucles"></Concept>
<Concept id="3" name="Arrays"></Concept>
...
<Relationship idC1="2" type="part_of" idC2="1">
<Relationship idC1="3" type="requires" idC2="2" weight="90">
</Relationship>
</Ontology>
If you prefer to use an url linking to owl ontology you must use an owl ontology such as this:
<rdf:RDF
xmlns="http://example.com/SAMUEL.owl#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
xmlns:xsd="http://www.w3.org/2001/XMLSchema#"
xmlns:owl="http://www.w3.org/2002/07/owl#"
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:dcterms="http://purl.org/dc/terms/"
xmlns:vcard="http://www.w3.org/2001/vcard-rdf/3.0#">
<owl:Class rdf:about="http://example.com/SAMUEL.owl#Concept">
<rdfs:label>Concept</rdfs:label>
</owl:Class>
<Concept rdf:about="#ID1">
<rdfs:label>IHD_01 - Instalaciones y equipos del HOGAR DIGITAL</rdfs:label>
<vcard:SORT-STRING>1</vcard:SORT-STRING>
</Concept>
<Concept rdf:about="#ID2">
<rdfs:label>Conexión a servicios externos de comunicación en el hogar digital</rdfs:label>
<vcard:SORT-STRING>1</vcard:SORT-STRING>
<dcterms:isPartOf rdf:resource="#ID1"/>
<rdf:type rdf:resource="http://example.com/SAMUEL.owl#Concept"/>
</Concept>
<Concept rdf:about="#ID6">
<rdfs:label>Infraestructuras comunes de telecomunicaciones ICT</rdfs:label>
<vcard:SORT-STRING>1</vcard:SORT-STRING>
<dcterms:isPartOf rdf:resource="#ID2"/>
<rdf:type rdf:resource="http://example.com/SAMUEL.owl#Concept"/>
</Concept>
<Concept rdf:about="#ID7">
<rdfs:label>Instalaciones de fibra óptica</rdfs:label>
<vcard:SORT-STRING>2</vcard:SORT-STRING>
<dcterms:isPartOf rdf:resource="#ID2"/>
<rdf:type rdf:resource="http://example.com/SAMUEL.owl#Concept"/>
</Concept>
<Concept rdf:about="#ID3">
<rdfs:label>Red de comunicación en el hogar digital</rdfs:label>
<vcard:SORT-STRING>2</vcard:SORT-STRING>
<dcterms:isPartOf rdf:resource="#ID1"/>
<rdf:type rdf:resource="http://example.com/SAMUEL.owl#Concept"/>
</Concept>
<Concept rdf:about="#ID8">
<rdfs:label>Infraestructuras básicas de red local</rdfs:label>
<vcard:SORT-STRING>1</vcard:SORT-STRING>
<dcterms:isPartOf rdf:resource="#ID3"/>
<rdf:type rdf:resource="http://example.com/SAMUEL.owl#Concept"/>
</Concept>
<Concept rdf:about="#ID9">
<rdfs:label>Instalación y configuración de redes de área local LAN</rdfs:label>
<vcard:SORT-STRING>2</vcard:SORT-STRING>
<dcterms:isPartOf rdf:resource="#ID3"/>
<rdf:type rdf:resource="http://example.com/SAMUEL.owl#Concept"/>
</Concept>
<rdf:Description rdf:about="#ID9">
<dcterms:requires rdf:resource="#ID8"/>
</rdf:Description>
</rdf:RDF>
Where Concept is the class representing a topic, rdf:about is the topic id, rdfs:label is the topic name, dcterms:isPartOf is the topic-subtopic relationship pointing to the parent concept id and vcard:SORT-STRING is the order of the topic (between topics of same level, ie bothers topics). Also, if you want to specify prerequisites relationship you can do it by dcterms:requires element, indicating the id of the required concept.
actions
XML-formatted string with the actions associated to each concept. It allows a null value and an empty string if actions are not needed.
The XML Schema to be fullfilled by that XML string can be found in the next link: XML Schema
Example:
<Actions target="_blank">
<Concept id="1">
<Action name="Test" url="http://www.siette.org..."></Action>
</Concept>
...
</Actions>
configuration
XML-formatted string that defines the appearance that shows the model viewer. Any element can be omitted.
The XML Schema to be fullfilled by that XML string can be found in the next link: XML Schema
Example:
<Configuration>
<user>Ivan</user>
<course>Programming C</course>
<source>Siette</source>
<lang>en</lang>
<palette>
<byName>ylgn9</byName>
<custom>
<colors>
<fromColor>#ff0000</fromColor>
<toColor>#00ff00</toColor>
</colors>
<levels>12</levels>
</custom>
</palette>
<showHeader>true</showHeader>
<showFrame>true</showFrame>
<showTaskPanel>True</showTaskPanel>
<showGraphPanel>True</showGraphPanel>
<defaultView>spacetree</defaultView>
<views><view>spacetree</view><view>sunburst</view><view>table</view></views>
<urlCallback>http://www.example.com</urlCallback>
<actionListTitle>Learning Activities</actionListTitle>
</Configuration>
Where:
- user: the name of the student (shown in the header). It allows a null value.
- course: the name of the course (shown in the header). It allows a null value.
- source: the name of the e-learning system (shown in the header). It allows a null value.
- lang: interface language (“en” or “es”). It allows a null value. Default value: “es”.
- palette: pallete of colors used by Ingrid to represent the knowledge level. There are two different ways to specify the palette:
- By Name: Using "byName" element and some of these palette names:
- rdylgn11 11 colors between red and green,
- rdylgn9 9 colors between red and green,
- ylgn9 9 colors between white and green), and
- greens9 9 colors between white and green.
- By Colors: Using fromColor, toColor and levels elements. Ingrid creates a palette of levels number of colors between fromColor and toColor.
- By Name: Using "byName" element and some of these palette names:
- showHeader: boolean value that indicates whether or not we want to show the header. It allows a null value, which by default is true (to show the header).
- showFrame: boolean value that indicates whether or not we want to show the external frame. It allows a null value, which by default is true (to show the frame).
- showTaskPanel: boolean value that indicates whether or not we want to show the taskPanel.
- showGraphPanel: boolean value that indicates whether or not we want to show the panel with concept without adjacents in graph view (prerequisites view).
- defaultView: default first view.
- views: differents views provided by Ingrid. By default Ingrid shows all available views.
- urlCallback: URL which will process the user proposed grades. If a value is not given (null or empty string), the grade edition will be disabled. For more information go to Grade edition.
- actionListTitle: Action List title. If it is omitted it uses a default value.
All these elements are optional, Ingrid will use default values if any of them are omitted.
Grade Edition
INGRID is designed to represent the user models provided and it does not keep any information record. However, it offers a feature that allows users to add a specific grade for each concept represented.
INGRID acts only as an intermediary between the user and the system responsible for the user model. Therefore, the invocation of INGRID offers a parameter to add a URL where the information selected by the user will be sent. It is the system which manages the user models itselft who must develop the appropiate program hosted at the specified URL. This section provides a basic guide to develop properly this mechanism.
It has been defined a simple communication interface between INGRID and th colling system consisting in a set of input parameters and a particular output format. The application whose URL is provided can be developed in any technology and the only requirement is that it can be invoked through a URL. The parameters added by INGRID to its call to the configured URL are:
- concept: the name of concept for which the grade is proposed.
- mark: numeric value for the concept provided by the user, in the range 1-5.
- callback: string required for the acknowledgement.
For example, an INGRID call previously configured with the URL http://domain/servlet could make a call like: http://domain/servlet?concept=Programming&mark=4&callback=_jqjsp.
Note that you can configure the URL with some other additional parameters so that, if our application requires it, more information can be included in the URL. For example, we could add the user id, because INGRID does not know it, by setting the URL as http://domain/servlet?user=7 so that the result call made by INGRID could be like this: http://domain/servlet?user=7&concept=Programming&mark=4&callback=_jqjsp.
All these additional parameters are optional and do not have any kind of restriction: it can be included as many as necessary and named with any name. The only thing that INGRID guarantee is that a concept and a mark will be received. Other information which may be needed by the user model agent must be added explicitly.
Acknowledgement
As the expected response from the application, it must follow a certain format. To confirm that the inclusion of the grade has been successful, we must use the string from the callback parameter to form a jsonp string. In fact, just add to that string brackets and braces: ({}). For example, the calls showed above in which the callback parameter had the value _jqjsp, the acknowledgement should be: _jqjsp({}).
Error response
If our application finds any problem and wants INGRID to inform the user of that error, just not return anything or return any string different to the acknowledgment. In this way the user will know that his/her action has not been properly registered in the system.
Integration example with JSP
Generate web service artifacts with wsimport
The first step is to import the web service to our Java project. There are several ways to do that, we will do it with the wsimport application. This program can be found in the bin folder of our JDK directory (from version 6) or in the library JAX-WS.
In order to use the application, we open a console and we go to our src folder from our project. Then, write the following command:
This will create the myApp.ingrid package and will genereta the .java files needed to use the INGRID web service. We can remove the -Xnocompile option to generate the .class files too and we can remove the option -p myApp.ingrid if we do not want to specify a package, in which case the default package (lsi.iaia.medea.ingrid.external) will be used. For more information, visit the official documentation.
Once this is done, we can use the connect operation as if it ere a method of a local class.
Example
The example is a call made by the tool soapUI:
Petición:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ext="http://external.ingrid.medea.iaia.lsi/">
<soapenv:Header/>
<soapenv:Body>
<ext:connect>
<!--Required:-->
<model><![CDATA[<Model>
<Scores date="16-03-2011" lowBound="0" upperBound="10">
<Concept id="1" score="6"></Concept>
<Concept id="2" score="8">
<Evidence date="05-10-2010" name="Test" score="5"/>
<Evidence date="10-10-2010" name="Examen" score="Muy Bien"/>
<Distribution>
<Elem data="1" prob="0"/>
<Elem data="2" prob="2"/>
<Elem data="3" prob="8"/>
<Elem data="4" prob="80"/>
<Elem data="5" prob="10"/>
</Distribution>
<Comparative>
<Elem data="1" prob="0"/>
<Elem data="2" prob="2"/>
<Elem data="3" prob="50"/>
<Elem data="4" prob="38"/>
<Elem data="5" prob="10"/>
</Comparative>
<TempModel>
<Milestone date="10-03-2011" score="5">
<Distribution>
<Elem data="1" prob="0"/>
<Elem data="2" prob="2"/>
<Elem data="3" prob="80"/>
<Elem data="4" prob="8"/>
<Elem data="5" prob="10"/>
</Distribution>
</Milestone>
<Milestone date="16-03-2011" score="8">
<Distribution>
<Elem data="1" prob="0"/>
<Elem data="2" prob="2"/>
<Elem data="3" prob="8"/>
<Elem data="4" prob="80"/>
<Elem data="5" prob="10"/>
</Distribution>
</Milestone>
</TempModel>
</Concept>
<Concept id="3" score="5">
<Distribution>
<Elem data="1" prob="2"/>
<Elem data="2" prob="3"/>
<Elem data="3" prob="70"/>
<Elem data="4" prob="20"/>
<Elem data="5" prob="5"/>
</Distribution>
<Comparative>
<Elem data="1" prob="15"/>
<Elem data="2" prob="20"/>
<Elem data="3" prob="30"/>
<Elem data="4" prob="20"/>
<Elem data="5" prob="15"/>
</Comparative>
<TempModel>
<Milestone date="10-03-2011" score="3">
<Distribution>
<Elem data="1" prob="30"/>
<Elem data="2" prob="50"/>
<Elem data="3" prob="15"/>
<Elem data="4" prob="5"/>
<Elem data="5" prob="0"/>
</Distribution>
</Milestone>
<Milestone date="16-03-2011" score="5">
<Distribution>
<Elem data="1" prob="2"/>
<Elem data="2" prob="3"/>
<Elem data="3" prob="70"/>
<Elem data="4" prob="20"/>
<Elem data="5" prob="5"/>
</Distribution>
</Milestone>
</TempModel>
</Concept>
</Scores>
</Model>]]>
</model>
<!--Required:-->
<ontology><![CDATA[<Ontology>
<Concept id="1" name="Geografía"/>
<Concept id="2" name="Europa"/>
<Concept id="3" name="America"/>
<Concept id="4" name="Rios de Europa"/>
<Relationship idC1="2" type="part_of" idC2="1"/>
<Relationship idC1="3" type="part_of" idC2="1"/>
<Relationship idC1="4" type="requires" weight="40" idC2="2"/>
</Ontology>]]>
</ontology>
<!--Optional:-->
<actions><![CDATA[<Actions target="_blank">
<Concept id="2">
<Action name="Wikipedia" url="http://es.wikipedia.org/wiki/Europa"/>
</Concept>
<Concept id="3">
<Action name="Wikipedia" url="http://es.wikipedia.org/wiki/Am%C3%A9rica"/>
</Concept>
</Actions>]]>
</actions>
<!--Optional:-->
<configuration><![CDATA[<Configuration>
<user>John Doe</user>
<course>Course name</course>
<source>Component name</source>
<lang>en</lang>
<palette>
<custom><levels>5</levels></custom>
</palette>
<showHeader>true</showHeader>
<showFrame>true</showFrame>
<defaultView>spacetree</defaultView>
<views>
<view>spacetree</view>
<view>sunburst</view>
<view>table</view>
<view>graph</view>
</views>
<actionListTitle>Learning Activities</actionListTitle>
<showTaskPanel>true</showTaskPanel>
<showGraphPanel>true</showGraphPanel>
<bgFrameColor>#6a6a6a</bgFrameColor>
<bgColor>#ffffff</bgColor>
</Configuration>]]>
</configuration>
</ext:connect>
</soapenv:Body>
</soapenv:Envelope>
Respuesta:
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<ns2:connectResponse xmlns:ns2="http://external.ingrid.medea.iaia.lsi/">
<return>
http://ingrid.iaia.lcc.uma.es/ingrid.html?id=379d6b98106249389509a8e04b47b7f1
</return>
</ns2:connectResponse>
</S:Body>
</S:Envelope>