<< Documentation

RELATE

What is Relate?

 Relate is the name of a service providing the possibility to relate resources to competence aims in the Norwegian national curricula  bak.udir.no : GREP.

The constituents of the service

Relate is made up of several constituents communicating together:

1. ndla_ontopia_connect module
2. ndla_relate_service module
3. ndla_relate_public_service module
4. Parts of ndla_utils module
5.  The open source Topic Map engine Ontopia

1. The ndla_ontopia_connect module

The ndla_ontopia_connect module contains the internal GREP functionality designed to work within NDLA. Most of the code is inherently designed to work cloesly with the rest of the NDLA code, and will as such have to be rewritten if oen wanted to use the functionality in other Drupal projects.

What the different files in the module do

Folder	File	Notes
css
	ndla_ontopia_connect_style.css	This is the main style sheet for the module, which contains styles for all GUIs
	treeview.css	This style sheet defines styles for thedom tree used to represent GREP structures in GUIs
img
	ajax-loader.gif	Is displayed whenever the GREP-tree waits for connection data
	cross.png	Used as a close button within the GREP tree
	dash.png	Used to build horisontal lines in the "show aim" lightbox
	minus.gif	Used to signify "collapsed" in the GREP tray
	plus.gif	Used to signify "un-collapsed" in the GREP tray
	minus.png	Used to signify "collapsed" in the GREP tree
	plus.png	Used to signify "un-collapsed" in the GREP tree
includes
	ndla_ontopia_connect_admin.inc	Contains admin settings needed to connect to Ontopia and relate as well as forms setting several variables needed for the querying of Ontopia
	ndla_ontopia_connect_grep_tasks.inc	Contains functionality making it possible to port resources connected to obsolete competence aims to competence in updated curricula
	ndla_ontopia_connect_private_functions.inc	Contains "private" functions which are mainly called from ndla_ontopia_connect_public_functions.inc. They are functions that connect, fetch, parse and update data in the Ontopia installation
	ndla_ontopia_connect_public_functions.inc	Contains "public" functions which implement many of the functions implementing menu points, ususally called via ajax using jQuery in functions.js
	ndla_ontopia_relation_form.inc	Contains functions implementing the /competence_aims menu point as well as functions taking care of preparing the  ltm format representing relations to competence aims before saving grep relations]
js
	batch_treeview.js	JavaScript class rendering the GREP tree for the "batch delete competence aims" functionality
	curriculatree.js	JavaScript class rendering the GREP tree for the GREP GUI relating resources to competence aims in /competence_aims
	functions.js	Main JavaScript taking care of all the ajax calls as well as containg diverse javascript functions related to the massaging of data as well as to the view. It is heavily dependent on jQuery
	jquery.json-2.2.min.js	Additional jQuery functionality to provide missing JSON functionality in Drupal
	json2.js	Additional jQuery functionality to provide missing JSON functionality in Drupal
	port_treeview.js	JavaScript class rendering the GREP tree for the "port competence aims" functionality
	treeview.js	JavaScript class rendering the GREP tree for the "Subject => Add Aim filters" functionality in /admin/settings/grep/subjectmapping
ontologi
	relate.xtm	The basic  ontology definitions expressed in the  xtm format
ndla_ontopia_connect
	ndla_ontopia_connect.info	The info file lists a dependency to  lightbox2 (lightbox2) as well as adding the functions.js, jquery.json-2.2.min.js, json2.js and ndla_ontopia_connect_style.css
	ndla_ontopia_connect.module	The .module file itself just includes and loads external files as well as setting javascript Drupal.settings variables in hook_init. It also implements hook_perm, hook_menu, hook_form_alter, hook_nodeapi and hook_block

2. The ndla_relate_service module

The ndla_relate_service module duplicates many of the same functions found in the ndla_ontopia_connect module, but exposed using the  Services Drupal module. The functionality is mainly built to be used by the ndla websites. Some of the functions were built especially to deliver content to the front end caching software taking care of caching content on the ndla production site. It is also provding a backbone to the parallel ndla_relate_public_service module exposing methods to the public.

What the different files in the module do

Folder	File	Notes
img
	dash.png	Used to build horisontal lines in the "show aim" lightbox
includes
	ndla_relate_service_admin.inc	Form containing settings for the configuation of the connection between the relate service and the Ontopia server
	ndla_relate_service_functions.inc	Main file containing all functions duplicated from ndla_ontopia_connect module as well as additional functions fetching and delivering content to the competence aim blocks and lightbox on production site nodes.
	ndla_relate_service_menu_functions.inc	Implementation of menu points fetching competence aim data for the production site cache frontend in order to populate the competence aim block, grep tray and competence aim lightbox.
ndla_relate_service
	ndla_relate_service.info	The info file lists a dependency to  services (services which is needed in order to create the web service end points used by the ndla production servers
	ndla_relate_service.module	The .module file itself includes and loads external files as well as implementing hook_service in addition to hook_perm and hook_menu. The implementation of hook_service defines the different web service end points
	README.txt	Directions describing how to connect to the frontend functions from the frontend.

3. The ndla_relate_public_service module

The ndla_relate_public_service module defines the public end points of the relate service. These end points are meant to be open to the public, making anyone able to connect any resource to any competence aim

What the different files in the module do

Folder	File	Notes
includes
	ndla_relate_public_service_functions.inc	Contains the functions implementing the different web service end points
ndla_relate_public_service
	ndla_relate_public_service.info	The info file lists a dependency to  services (services which is needed in order to create the web service end points
	ndla_relate_public_service.module	The .module file itself includes and loads external files as well as implementing hook_service which defines the different web service end points

4. Parts of ndla_utils module

The ndla_utils module is a utility module containing various functionalities related to several of the modules making up the ndla site.

Files that are relevant to the relate functionality

Folder	File	Notes
js
	top_navigation.js	Contains JavaScript functionality related to the GREP Curriculum tray
ndla_utils
	ndla_utils.blocks.inc	This file contains the ndla_utils_node_listing_block functions which takes care of listing resources connected to a certain competence aim
	ndla_utils.helpers.inc	This file contains an implementation of hook_menu which creates the ndla_utils/menu2010/grep/% menu point calling the ndla_utils_grep_callback function in ndla_utils.pages.inc
	ndla_utils.pages.inc	This file contains the ndla_utils_grep_callback which delivers content to the GREP Curriculum tray

5.  The open source Topic Map engine Ontopia

Ontopia is 100% Java, and runs on any operating system which has Java 1.5. It is fully open source and can be used without any restrictions beyond those in the Apache 2.0 license. It parses, stores and maintains the topic maps, and has an extensive Java API. On top of it are built a number of additional components, as shown in the diagram below.

Using the DB2TM module relational data can be automatically converted into Topic Maps data, either over JDBC or from a CSV file. The conversion uses a simple declarative XML file to describe the mapping from relational data to Topic Maps. It is possible to invoke custom Java code from the XML file in order to perform necessary transformations during the conversion.

Ontopia has a web service interface which provides a number of generic requests such as get-topic, get-tolog (query results), delete-topic, add-fragment (in some Topic Maps syntax), and so on. This interface is exposed both as a plain HTTP interface and using SOAP, so that requests can be sent using both styles.

To make the relate service work, the Ontopia enginge has to be installed on a server reachable by both ndla, red , relate and deling if all ndla modules are in use. It has to run on an RDBMS, ndla.no runs it on a Mysql database which seems to run well at the time of writing (12.2010).

The ontologies

GREP

The GREP structures are first and foremost defined using  ISO/IEC 13250:2003 Topic Maps, an ontologically based, semantically rich indexing standard for the Semantic Web. They can be fetched in two main ways, as full text files, or through RSS feeds containing notifications of changes to the curricula. The feeds kan be fetched catering either to Topic Map or a ER-based xml format. The following ER diagram describes the structure of the curricula

RELATE

The relate server is run by a Topic Map implementing an ontology made up by 3 main groups which together provide a basis for a semantically rich index of relations between resources and GREP competence aims:

Resources

Resources are thought to be digital and to be one of 9 types. The graph below shows the 9 types:

Each resource needs to have a unique identifer; its URI, which makes it possible to assert that two entities identified by their respective unique identificators are related to each other by some or other relation type.

Relation types

Relation types or association types' inTopic Maps are named bidirectional arcs that relate two or more topics together. The name of the arc indicates what the nature of the relation is. A typical association type would be something like e.g. "Father of" < = > "Son of". The graph below shows the three relation types currently used in this ontology:

In addition to relating resources and competence aims with a meaningful relation type, relate also adds some metadata to the relation:

• Subject
  • Tells which subject matter the resource and the relationship to its comeptence aim is relavant for. This makes it possible to use subject matter as a context for picking relevant resources.
• Level
  • Tells what level the relation made is intended for
• Timestamp
  • A way of marking the relation made in temporal space
• user name and User's URL
  • It is increasingly important to be able to know the quality of content and meta data on the internet. Attaching user information to the relation made is a bottum up way of creating a trust layer one can base decisions on when picking resources for learning.

Subjects

Since we are "tagging" the realtions with subjects, the realte topic map needs to keep track of which subjects are available on the ndla production site. The digram below shows how topic Maps represent the subjects, their names as well as language scopes for the names:

Using scopes on is also able to provide the end user the possibility tonot only filter results in her own language, but also making it possible to reach the same subject regardless of which of the 3 language scopes se usses to search for content.

How to configure relate

Configuring relate is not a trivial task if one has more than one environment using more than one installation of relate.  ndla.no,  red.ndla.no,  deling.ndla.no all need to be configured correctly to point to the right relate instances ( relate.ndla.no and  Ontopia)

Since the GREP Curricula definitions change from time to time, and the functionality for automagically updating the topic maps still isn't implemented, some manual labor is needed in addition to setting up a test environment in order to test that the new curricula work as intended this means that one needs at least on extra instance of each of the sites mentioned above which need to be configured.

On some occations the GREP curricula wil undergo major changes resulting in drastic changes in the topic maps such as change in the unique identifiers for competence aims when giviing them new names as well as deletion ov competence aims. This means that one will end up with "orphaned" resources in the relate topicmap. The functionality taking care of both mass deletion and porting of resources from old curricula to new ones is implemented in ndla_ontopia_connect_grep_tasks.inc, which also adds more points of configuration, since addtional ontopia installations are needed to house the old versions of both GREP and relate topic maps.

cm.ndla.no / red.ndla.no

/admin/settings/grep

Relate settings

Attribute	Example Value	Notes
GREP Topic Map	mysql-7106201	This is the mysql id of the GREP topic map as found in  the index of loaded topicmaps in the Ontopia server
GREP Topic Map XTM	Grep_141210_010001.xtm	This is the  XTM source file for the GREP topic map in the RDBMS of the Ontopia server. It serves as an  3.6 Item Identifier for the topics in the topicmap in the way that if we want to locate a single topic in the topic map, its item identifer would be something like file:/opt/ontopia/apache-tomcat/webapps/omnigator/WEB-INF/topicmaps/Grep_141210_010001.xtm#topicid. This value is used to make correct queries to the Ontopia server
Previous version of GREP Topic Map	mysql-305201	This is the mysql id of the previous GREP topic map relative to the current GREP topic map as found in  the index of loaded topicmaps in the Ontopia server. This would be the GREP topic map we use to port "orphaned" resoources from obsolete competence aims to new comeptence aims in the current GREP topic map
Previous GREP Topic Map XTM	Grep_090710_162624.xtm	This is the previous  XTM source file for the GREP topic map in the RDBMS of the Ontopia server instance used to hold the previous version of the GREP topic map. It serves as an  3.6 Item Identifier for the topics in the topicmap in the way that if we want to locate a single topic in the topic map, its item identifer would be something like file:/opt/ontopia/apache-tomcat/webapps/omnigator/WEB-INF/topicmaps/Grep_090710_162624.xtm#topicid. This value is used to make correct queries to the Ontopia server
RELATE Topic Map	mysql-4569201	This is the mysql id of the RELATE topic map which holds the relations between resources and the GREP competence aims as found in  the index of loaded topicmaps in the Ontopia server
Previous RELATE Topic Map	mysql-665001	This is the mysql id of the RELATE topic map which holds the relations between resources and the GREP competence aims as found in  the index of loaded topicmaps in the Ontopia server holding previous topic maps
Relate server	http://relate.ndla.no:8080	This is the URL that leads to the production instance of Ontopia. It is used to send queries to the right server
Previous GREP MAP server	http://relate.ndla.no:8050	This is the URL that leads to the production instance of Ontopia holding the previous GREP topic maps used for the porting of "orphaned" resources. It is used to send queries to the right server
Relate service url	http://relate.ndla.no	This is the URL leading to the production Drupal instance holding the web service functionality for RELATE
Path to Ontopia	/opt	This is the path on the server holding the Ontopia instance. It is used by ndla_ontopia_connect module to build correct queries to the Ontopia server
Path to Ontopia holding previous GREP MAP	/opt	This is the path on the server holding the Ontopia instance holding the previous GREP topic map. It is used by ndla_ontopia_connect module to build correct queries to the Ontopia server
Node base url	http://ndla.no	This is the base URL used by ndla_ontopia_connect module to build the correct URIs used as unique identifiers for the resources beiung related to competence aims in the RELATE topic map
Node test base url	http://test.ndla.no	This is the base URL used by ndla_ontopia_connect module to build the correct URIs when running on a test instance of one of the NDLA servers. This ensures testers being kept within the test servers when clicking GREP related URLs in the site

Grep <=> Nodetype mapping

Attribute	Example Value	Notes
Allow association with GREP to the following content types	Content type checkboxes	This is the løist of content types that should have the ability to connect to GREP competence aims]

External resources settings

Attribute	Example Value	Notes
Activate the "deling" option for the add grep GUI	No	This is a boolean operator flagging whether the competence_aims dialogue should add deling.ndla.no-id' to the relate service or not. Default is No, since the service is intended for ndla.no]
AActivate the "external resources" option for grep	Yes	This is a boolean operator flagging whether the Other resources-block is to be shown or not. The default is yes, which results in deling.ndla.no-resources as well ass NRK-resources connected to the same competence aim as the current node to be listed under "Other resources"]

Frontend settings

Attribute	Example Value	Notes
Use the frontend to render grep-data	No	This is a boolean operator flagging whether GREP datain teh reight collumn should be fetched and rendered by a frontend such as Vanish or not

/admin/settings/grep/assoctypes

Edit association types

Attribute	Example Value	Notes
Resource => Competence Aim - English	Covers partially	This the English name for a given association type viewed from the side of a resource
Resource => Competence Aim - Norsk Bokmål	Dekker delvis	This the Norsk Bokmål name for a given association type viewed from the side of a resource
Resource => Competence Aim - Norsk Nynorsk	Dekkjer delvis	This the Norsk Nynorsk name for a given association type viewed from the side of a resource
Competence Aim => Resource - English	Partially covered by	This the English name for a given association type viewed from the side of a competence aim
Competence Aim => Resource - Norsk Bokmål	Dekkes delvis av	This the Norsk bokmål name for a given association type viewed from the side of a competence aim
Competence Aim => Resource - Nynorsk	Dekkjes delvis av	This the nynorskl name for a given association type viewed from the side of a competence aim

Add association types

Attribute	Example Value	Notes
Computer frendly name	dekker-delvis	This the computer friendly name for a given association type. It should not contain spaces or speichal characters, nor other punctuation characters apart from hyphens and underscores
Resource => Competence Aim - English	Covers partially	This the English name for a given association type viewed from the side of a resource
Resource => Competence Aim - Norsk Bokmål	Dekker delvis	This the Norsk Bokmål name for a given association type viewed from the side of a resource
Resource => Competence Aim - Norsk Nynorsk	Dekkjer delvis	This the Norsk Nynorsk name for a given association type viewed from the side of a resource
Competence Aim => Resource - English	Partially covered by	This the English name for a given association type viewed from the side of a competence aim
Competence Aim => Resource - Norsk Bokmål	Dekkes delvis av	This the Norsk bokmål name for a given association type viewed from the side of a competence aim
Competence Aim => Resource - Nynorsk	Dekkjes delvis av	This the nynorskl name for a given association type viewed from the side of a competence aim

Delete association types

This lists all existing association types and will delete checked association types

Add subject topicid

Attribute	Example Value	Notes
English Subject title	English	This the English name for a given subject in the site.
Norwegian Subject title	Engelsk	This the Norsk Bokmål name for a given subject in the site.
Subject topicid	english	This is the topicid for the corresponding topic in Ontopia. It should be computer freindly.
Subject PSI	Engelsk (uuid:c330f04b-8179-4604-bbda-fe9c82022ad8)	This dropdown contains the unique Published Subject Ids for each subject contained in the Site.
Node id	636363	This is the drupal node id for the corresponding subject node.

Edit subject topicid

Attribute	Example Value	Notes
English Subject title	English	This the English name for a given subject in the site.
Norwegian Subject title	Engelsk	This the Norsk Bokmål name for a given subject in the site.
Subject topicid	english	This is the topicid for the corresponding topic in Ontopia. It should be computer freindly.
Subject PSI	Engelsk (uuid:c330f04b-8179-4604-bbda-fe9c82022ad8)	This dropdown contains the unique Published Subject Ids for each subject contained in the Site.
Node id	636363	This is the drupal node id for the corresponding subject node.

Delete subject topicid

This lists all existing subject topic ids and will delete checked subject topic ids

Gotchas

Ontopia server

• Since topic maps is an identity based technology, and the ndla_ontopia_connect module uses a feature making it possible to do queries across all loaded topicmaps, having two instances of the same type of topic map e.g. two GREP maps at the same time will result in queries failing.