Importing projects from e.g. the ELOGbook to Labfolder at the FHI
=================================================================
This is how you generally do it::
1. In labfolder, create a new group project.
2. Get the ELOG logbook "operating" and export it as RAW. Remember where you've put the text file with the raw output and the directory with attachments files.
3. Only once: Get the elog2labfolder repository from github.
4. Adapt elog2labfolder.py to your needs. Specify the name of the project that you created previously.
4. Run elog2labfolder.py
These steps are explained in more detail in the following.
Creating a group project
------------------------
As the group admin (or one of the admins) in labfolder create a group project, for example, "operating" in a group named "FEL". You are now the owner of this project. Make sure you don't have several projects of the same name in one group.
Entries from ELOG
-----------------
The ELOG entries of a certain project need to be exported as *Raw* which looks like this::
$@MID@$: 12
Date: Tue, 03 Dec 2013 12:15:14 +0100
Author: Wieland Schöllkopf
Author Email: mailto:wschoell@fhi-berlin.mpg.de
Category: Shift summary
Subject: 1st solid-state experiment with FHI FEL
Severity: DOCU
Keywords:
Record date: 1386069171
Attachment:
Encoding: HTML
========================================
<p>Today Alex Paarmann and Marc Herzog are measuring in the wavelength range from 10 to 20 micron with a 0.5 mm thick GGG (Gadolinium Gallium Garnet, <a title="Gadolinium" href="http://en.wikipedia.org/wiki/Gadolinium">Gd</a><sub>3</sub><a title="Gallium" href="http://en.wikipedia.org/wiki/Gallium">Ga</a><sub>5</sub><a title="Oxygen" href="http://en.wikipedia.org/wiki/Oxygen">O</a><sub>12</sub>). Electron energy is set to 26 MeV.</p>
The entry shown above looks like this in the ELOG webinterface:
.. image:: _static/elog_entry.png
:width: 100 %
:align: center
What is noticeable is that the ELOG export comes with an "ö" instead of an "ö". Interestingly, if only entries done by Wieland are exported the export file has UTF-8 encoding which can actually print German "Umlaute" (ö, ä, ü). If, however, all entries are exported the encoding changes to an encoding that cannot handle e.g. "ö".
After importing the above ELOG entry into labfolder this entry appears like that:
.. image:: _static/entry_after_import.png
:width: 100 %
:align: center
Using python to import from ELOG to labfolder
---------------------------------------------
There is a GitHub project containing a python program for importing a raw (see the export example above) ELOG project. Get the project files by typing::
$ git clone https://github.molgen.mpg.de/weiher/elog2labfolder.git
The script *elog2labfolder.py* is meant to be executed from remote, that is, not on the machine on which labfolder is running. A prerequisit is the python MySQLDB package because for a few methods the labfolder API cannot be used, instead, direct manipulation of the labfolder MySQL database is needed. The actual labfolder API is applied in the methodes collected in *myPythonAPIv1.py* and *myPythonAPIv2.py*. Mostly, API version 2 is used but adding text at the end of an entry can only be accomplished by using the version 1 API call. *getListOfAuthors.py* gives you a list of all authors that are mentioned in a raw ELOG export file.
To finally import an ELOG logbook to a labfolder project you need to run ``$ python elog2labfolder.py``. Prior to this you need to make some changes to the header of the file, that is, these lines::
### Set the hostname
#hostname = 'lftest'
hostname = 'labfolder'
if hostname == 'lftest':
server = 'http://' + hostname + '.rz-berlin.mpg.de:9091'
elif hostname == 'labfolder':
server = 'https://' + hostname + '.rz-berlin.mpg.de:9091'
### The entries will be created using the following labfolder account which specifies the author of the entry. During the creation process, however, the entry's author ID will be changed to the real author's ID if the real author is already contained in the user table of the labfolder DB.
email = 'weiher@fhi-berlin.mpg.de'
password = getpass.getpass('Enter the labfolder password associated with ' + emailAddress+': ')
### Specify the absolute path to the raw ELOG export file.
elogExportFile = '/home/stefan/Dokumente/labfolder/OperatingLogbook_exportRaw_ORIGINAL.txt'
### Full path to where the attachments of the logbook to be imported are stored:
attachmentsDirectory = '/home/stefan/Dokumente/labfolder/Operating/'
### Project name in labfolder
projectName = 'operating'
Alternatives to manipulating the labfolder DB on MySQL level
------------------------------------------------------------
As mentioned previously: a few methods in the python API use a direct manipulation of the labfolder DB via MySQL queries. These methods are:
* *createUserAccount(email, author, entryContent, verboseOutput, cursor, db)*: If an author of an ELOG logbook entry does not yet have a labolder account this account is created on the fly by setting a default (encrypted) password. This password is irrelevant because labfolder checks the entered password with the one from the LDAP server. Note: when setting a password in the DB labfolder's LDAP authentication needs to be disabled (FEATURE_LDAP_AUTHENTICATION=false) beforehand and enabled again after the setting process is finished.
* *updateAuthor(userID, blockID, cursor, db)*: Update the author of an entry. With the script *elog2labfolder.py* an entry is created with the author that is the person whose labfolder credentials are used to get the login token. Via this method the true author can be set to the passed in *userID*.
* *updateDateAndTime(date, blockID, cursor, db)*: Similar to *updateAuthor()* this method sets the creation and modification date to the creation time and date of the entry to be imported. This is necessary because otherwise creation and modification date in labfolder are the time and date when the import took place.
The labfolder support suggested the following alternative involving using the labfolder API:
* User account: A user account can be created via the API 2 endpoint ``/auth/signup``. The password will be an encrypted dummy password. In order for this to work the LDAP authentication must be turned off when this endpoint is called. After the account creation LDAP authentication should be turned on again. Once the true user of this account logs in labfolder will ignore the dummy password and check the entered password against the password stored in LDAP.
* Author: To create a labfolder entry by using the original entry's author needs a special work-around. **First, make sure to prevent labfolder users from accessing labfolder for the time of the import.** Then, manually change all user passwords in the DB to the same (encrypted) password. Switch off the LDAP authentication and restart labolder. Now, import entry by entry and get a new login token for each new entry. It is only possible to get login tokens for all users because they all have the same known password. If the author of the entry to be imported does not exist yet in the DB you need to create an account via the API 2 endpoint ``/auth/signup``. Now you reopen the access to the labfolder instance and switch on LDAP again restarting labfolder afterwards. The users can login using their FHI credentials no matter the "universal" password in the DB. If LDAP authentication is not turned on the users could do a password recovery on the login screen and re-set their password to their liking.
* Date and time: Since you cannot change creation and modification time stamp of an entry via the API you could instead create custom dates during the import of an entry. The original entry creation timestamp could be "Original entry creation" followed by the creation time and date of the import. All entries can be filtered and searched by the custom dates.