View source for Maiana import and export

'''Maiana has been broken for years and it is unlikely that it will be fixed anytime soon as the Topic Maps Labs is not really working any more. Thus, Wandora's Maiana import and export features have been redesigned and relabeled as [[Waiana import and export]] and work now with Wandora's [[Waiana service module]]. The [[Waiana import and export]] should be compatible with Maiana API too.'''


[http://maiana.topicmapslab.de/ Maiana] is a service to host, explore, and share topic maps. Maiana has been developed in [http://www.topicmapslab.de/ Topic Maps Lab], a working group of the [http://www.asv.informatik.uni-leipzig.de/ Natural Language Processing] chair at the University of Leipzig, Germany. Topic Maps Lab also hosts the service at the moment. Wandora is capable to export topic maps to Maiana, and to import topic maps from Maiana. Both features use an [http://projects.topicmapslab.de/projects/maiana/wiki/API_Controller API] of Maiana and require a personal API key. Maiana user receives an API key while registering the Maiana. Maiana is a free service for users.

== Importing topic map from Maiana ==

A topic map is imported from Maiana to Wandora with a menu option '''File > Import > Import topic maps from Maiana...'''. Choosing the menu option opens an import dialog window. Window has three input fields. Write your personal API key to the API key field. You'll get your API key from your personal page at Maiana. If you know the owner and the identifier of the imported topic map, you can fill in other two fields and press '''Import''' button. Or, if you don't know topic map specific identifiers, you can press the '''Fetch list''' button and Wandora downloads a list of available topic maps from Maiana. Wandora views all available topic maps in selection list below input fields and you can select the topic maps you wish to import from Maiana. You can also select multiple topic maps and Wandora imports each selected topic map to separate layers.

=== Import example ===

In this example Wandora user downloads a topic map from Maiana. First Wandora user starts the import tool by selecting menu option '''File > Import > Import topic maps from Maiana...'''.


[[Image:maiana_import_01.gif|center]]


Wandora opens a dialog window. User writes her API key to the field and presses '''Fetch list''' button. Wandora reads a list of available topic maps from Maiana. The list contains topic maps the user has rights for, including her own topic maps and private topic maps of other users she has been invited to explore. In other words, user can import also topic maps made by other Maiana users. In all cases, in order to import a topic map, it's ''downloadable'' flag must be set true.


[[Image:maiana_import_02.gif|center]]


Wandora user scrolls down the topic map list and selects '''Donald Duck''' topic map made by user '''lmaicher'''. User clicks the '''Import''' button and Wandora starts importing the topic map.


[[Image:maiana_import_03.gif|center]]


After import Wandora views a log and the user can check if the import was successful. If import was successful, Wandora's layer stack at bottom-left corner should contain a topic map layer with a same name as the imported topic map. This new layer contains the imported topic map. If topic map contains no Wandora specific topics you have to use Wandora's search feature to locate new topics.

User searches for '''duck''' with Finder and receives a list of topics. She opens a topic '''Donald Duck''' to Wandora's topic panel.


[[Image:maiana_import_04.gif|center]]

=== Additional notes about import ===

Wandora's topic map model is not fully TMDM compatible and importing topic map from Maiana to Wandora may change the topic map slightly. These changes include

* In Wandora, a topic can carry only one occurrence per type and scope. If topic map contains multiple occurrences with same type and scope, only one of them is imported to Wandora.
* Wandora supports no URL resource occurrences. Wandora converts URL occurrences to topics and creates an association between URL resource topic and the original occurrence carrier.
* Wandora supports only one base name. If topic has more than one base name in Maiana, only one is imported to Wandora.
* In Wandora, a topic can carry only one variant name per scope. If topic map contains many variant names with identical scope, only one imports to Wandora.
* Wandora doesn't use item identifiers. They are converted subject identifiers. If you wish to get rid of these subject identifiers you can delete them with '''Topics > Subject identifiers > Remove SIs with regex...''' feature.
* Wandora merges topics with a same base name. Importing topics with a same name results merged topics in Wandora.
* Import format of topic maps is XTM 2.0.

== Exporting topic map to Maiana ==

To export a topic map from Wandora to Maiana you have several options:

* To export whole layer stack i.e. all topic map layers in Wandora, select menu option '''File > Export > Export topic map to Maiana...'''
* To export single topic map layer select menu option '''Export layer > Export topic map to Maiana...''' in context of the layer you wish to export with right mouse button.
* To export selected topics choose menu option '''Topics > Export > Export selection to Maiana...''' in context of the topic selection with right mouse button.

Choosing any of the export options described above opens a Maiana export dialog window. Window has an input field for your personal API key, for a name and for an identifier name (short name) of the topic map. Fields contain default names and you can edit them if you wish. Also, Wandora fills in the API key field if you have used your API key earlier for Maiana import or export. Wandora doesn't store your API key between use sessions.

=== Export example ===

In this example Wandora user uploads a topic map from Wandora to Maiana. User has Wandora application open and user has somehow created a topic map layer named '''Royal92'''. Layer is selected. User right clicks the layer and a popup menu opens. User selects menu option '''Export layer > Export topic map to Maiana...'''.


[[Image:maiana_export_01.gif|center]]


Wandora opens an export dialog window. User enters her API key. Wandora has filled in both name and short name fields. User doesn't change names nor publicity options. Finally user presses '''Upload''' button.


[[Image:maiana_export_02.gif|center]]


If export was successful user can now login Maiana and uploaded topic map should be visible in her topic map list. Notice, user set the topic map as ''public'' and ''downloadable''. As a consequence, all Maiana users may browse and download the topic map from Maiana.


[[Image:maiana_export_03.gif|center]]


After clicking the topic map in Maiana user can [http://maiana.topicmapslab.de/u/akivela/tm/wandora_export_1286893000013 browse topic map's topics and associations].


[[Image:maiana_export_04.gif|center]]


User clicks the '''Statistics''' link in Overview box and some statistics is shown about the topic map.


[[Image:maiana_export_06.gif|center]]


User goes back to Wandora and checks if numbers provided by Maiana are equal to those provided by Wandora. It looks like the number of association matches but Maiana has one topic more than the topic map Wandora. Looks like Maiana has added one topic to the exported topic map. At the moment is not clear what this additional topic is but I suspect it relates to Maiana's base ontology.

Also notice that the number of locators in Maiana is two times the number of subject identifiers in Wandora plus one. This is due to Maiana's item identifiers. Maiana creates an item identifier for a topic automatically while Wandora doesn't use item identifiers. Thus, round tripping a topic map from Wandora to Maiana and then back to Wandora results a topic map with Maiana's item identifiers transformed to subject identifiers in Wandora.


[[Image:maiana_export_05.gif|center]]

=== Additional notes about export ===

* Wandora accepts almost anything as a subject identifier or as a subject locator. Identifiers don't need to be even valid URIs. On the other hand, Maiana is much more stricter with subject identifiers and locators. If you try to export a topic map with invalid URIs to Maiana, the export fails. You can check whether or not your topic map contains invalid subject identifiers with a feature '''Topics > Subject Identifiers > Check SIs''' in context of topic map layer. Choosing context menu option '''Topics > Subject Identifiers > Fix SIs v2''' fixes all invalid URIs in subject identifiers. Changing subjects may cause unwanted side effects and you should save your topic map before trying to fix subject identifiers.
* At the moment Maiana limits the size of exported topic maps to 20M.
* Export format of topic maps is XTM 2.0.