Maiana import and export

From WandoraWiki
Jump to: navigation, search

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.

Maiana is a service to host, explore, and share topic maps. Maiana has been developed in Topic Maps Lab, a working group of the 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 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....

Maiana import 01.gif

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.

Maiana import 02.gif

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.

Maiana import 03.gif

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.

Maiana import 04.gif

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....

Maiana export 01.gif

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.

Maiana export 02.gif

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.

Maiana export 03.gif

After clicking the topic map in Maiana user can browse topic map's topics and associations.

Maiana export 04.gif

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

Maiana export 06.gif

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.

Maiana export 05.gif

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.
Personal tools