Quick Guide - FreeLAB 1.0

IntraLAB LIMS

 

Welcome to FreeLAB project Help guide. FreeLAB is a web-based application based on Drupal CMS system. As same as Drupal CMS, FreeLAB project is developed under GNU/GPL license. In this Help guide you can find installation guide for selfpaced installation together with basic configurations of FreeLAB. We are providing step-by-step guide to configure automatic import of injections from Agilent OpenLAB CDS chromatographic and GC/MS MassHunter software. For any further features ask in FreeLAB forum or contact us.

 

Content

Installation

Configuration

Maintenance

Administration

Customization

Modules

 

Installation

FreeLAB software can be downloaded from project websites under Download section. FreeLAB is available in two formats:

1) Web application + database

You have to install own php web server, mysql/mariadb database with appropriate configuration. We recommend this configuration for web server. After installing web server just copy Drupal installation to webroot directory and import database. Change settings of sites/default/settings.php for database location and authentication. This is the way for advanced users or web programmers.

2) Image of Debian Linux OS with installed and configurated FreeLAB app

This is much more easier way. We provide image for VMWare, Virtualbox, Hyper-V. Just download the image, import and run under one of virtual environment. You can find many tutorials how run existing virtual image.

Configuration

Settings of FreeLAB IP address (Virtual Machine only)

Default settings of the FreeLAB image is to get IP address from DHCP server. If needed, IP address of FreeLAB can be changed in the same way as most of debian linux systems. Run virtual machine and open console view or use remote SSH to FreeLAB server if you know IP address from DHCP. You should see a command line in Linux world named "shell"

log in as initial user:

Login: freelab

Password: freelab

now you should log in as root user. Root is the highest administrator of the linux os, type:

su root

Český jazyk

fill the initial root password:

Acetonitrile

now, open the LAN configuration in nano text editor:

sudo nano /etc/network/interfaces

English language

If you can see above, ens33 network card is set as "dhcp". If you want static address, just comment (use #) line "iface ens33 inet dhcp" and uncomment 4 lines below. Set appropriate static IP address. Reboot with command

sudo reboot

 

Note

In case of issues, check your network configuration with command sudo ifconfig -a. This command should show you enabled network cards and id's together with MAC addresses for your DHCP reservation. Change the network card ens33 in example above to specific name of ethernet which is listed in configuration.

               !!!Security: Do not forget to change your default passwords for root and freelab users. Use commands below!!!

sudo passwd root
sudo passwd freelab

 

Settings FreeLAB for automatic import OpenLAB CDS 2.x C/S and OpenLAB 2.x Secure WorkStation

Automatic import of injections from OpenLAB CDS 2.x with Content Management (Data Store in previous revisions) can be configured under Feeds module. Prior to import, we should edit PostgreSQL settings and add new database to Drupal's configuration. See steps below:

 

1) Firstly, we need to edit PostgreSQL on OpenLAB Server/Secure WorkStaion. Log in to Windows where PostgreSQL is installed and run pgAdmin tool. Login to database (ask Agilent representant if you don't know password)

and create new Login Role -> freelab with custom password

 

When new user is created, click on OLSharedServices database and clik to "SQL icon". Fill the script to enable freelab user read-only data from selected database. 

GRANT SELECT ON ALL TABLES IN SCHEMA public TO freelab;

 

 

Finally, edit files pg_hba.conf and postgresql.conf to allow connection from your FreeLAB application. You can find these files under C:\ProgramData\Agilent\PostgreSqlData-9.3\

 

pg_hba.conf

- add two rows below to allow all connections from user freelab

 

host    all             freelab              0.0.0.0/0                       md5
host    all             freelab              ::/0                                 md5

 

postgresql.conf

- edit listen_adresses parameter to * (all)

 

listen_addresses = '*'

 

2) Connect to FreeLAB server via SSH or SFTP and navigate to /var/www/html/freelab/sites/default/ directory. Edit settings.php.

sudo nano settings.php

Scroll down to database sections and uncomment database for OpenLAB C/S. Fill the OpenLAB Server IP address and user freelab with appropriate password you set in pgAdmin.

 

 3) Log on FreeLAB application with superadmin credentials:

Default are:

Login: admin_freelab

Pass: freelab

and navigate to path /admin/structure/feeds. Enable feeds import for OpenLAB C/S - Injections, OpenLAB C/S - Instruments and OpenLAB C/S - Projects. If you have complex multiple directory tree for Instruments or Projects, you should edit SQL script in Feeds import or you should add instruments and projects manually in administration part under /administration path. If you add projects and instruments manually, you should enable only OpenLAB C/S - Injections import. Click Edit next to OpenLAB C/S - Injections and click on Settings in SQL Parser part. Choose appropriate database you set in settings.php in step 2. You can also try to see preview import in Import preview section. Default settings of this feed is to run every day and update injections table. 

 

 

Settings FreeLAB for automatic import from GC/MS MassHunter SW

 

MassHunter Import is based on MassHunter log located on workstation PC. Default path to log in is D:\MassHunter\GCMS\1\mslogbook_history. It is neccessary to share this folder in network. Create specific user e.g. freelab for access to this share.

1) Connect MassHunter PC to company network and create new local user freelab

 

Share folder D:\MassHunter\GCMS\1\mslogbook_history  and add freelab user to read-only privilegies

 

 

2) Log on to FreeLAB application with superadmin credentials:

Default are:

Login: admin_freelab

Pass: freelab

and navigate to path /admin/config/workflow/rules. Open rule "Periodic import of MassHunter GCMS" and edit Action "Execute custom PHP code".

You should change IP adress or hostname of computer where MassHunter logs are stored. Optionally, you can change destination directory (in case of more MassHunters) or modificate time filter for copy log files.

When you change this settings, simply save and enable this Rule. Script will run every day using Cron.

 

 

3) Navigate to /admin/structure/feeds. Enable feeds import for MassHunter GCMS - Injections and edit. Click on Settings in FEEDS FETCHER DIRECTORY part and check if the monitored directory is correct. Click on Tamper tab and edit predefined values for Blank source 1,2,3. There should be fixed values for instrument name, project name and username. Unfortunatelly, MassHunter GCMS does not support projects and users so we need to save all injections under fixed values at this time.

After next cron task (default is 1 day), rules and feed should be processed automatically and you will see results in Administration -> Injections

 

 

 

Settings FreeLAB for automatic import from OpenLAB WorkStation

 

OpenLAB WorkStation Import is based on embeeded Firebird database located on each workstation. Default path to database is C:\ProgramData\Agilent\OLSS\.

It is neccessary to share this folder in network. Create specific user e.g. freelab for access to this share.

1) Connect OpenLAB PC to company network and create new local user freelab

 

Share folder C:\ProgramData\Agilent\OLSS  and add freelab user to read-only privilegies.

 

 

2) Log on to FreeLAB application with superadmin credentials:

Default are:

Login: admin_freelab

Pass: freelab

and navigate to path /admin/config/workflow/rules. Open rule "Periodic import of OpenLAB WS database" and edit Action "Execute custom PHP code". You should change IP address or hostname of computer where OpenLAB WS is installed. Optionally, you can change destination directory (in case of more OpenLAB WS PCs). When you change this settings, simply save and enable this Rule. Script will run every day using Cron.

 

 

 

 

Maintenance

 

Regular updates

If you want to have FreeLAB project accessible from Internet we strictly recommend to keep updated your webserver and FreeLAB Drupal installation. Debian Linux operating system can be updated via shell:

sudo apt-get update

sudo apt-get upgrade

Drupal community  releasing new revision of Drupal core and modules when security issue is presented in core. Log in as superadmin to FreeLAB and check table under admin/reports/updates.

If there is any security update, download module and try to update module in your installation. You can use this guide.

Backup procedure

We highly recommend to backup your FreeLAB on regular base.

a) If you use FreeLAB installed under custom web server, you can use module Backup and Migrate already enabled in FreeLAB. Log in as superadmin and set module under admin/config/system/backup_migrate/ . This module can be used to backup database or whole website to specified location during cron task. You need backup FreeLAB webroot directory (/var/www/html) together with database.

b) If you use virtual machine you can backup image of the virtual machine to specified network attached disk storage or use Veam Free Backup solution

c) You can also use standard backup tools as rsync. Ask your IT specialist to help you set correct backup.

 

Administration

 

Basic Administration

Administration interface is accessible for users with Manager permissions. Under Basic Administration you can view instruments, injections, projects, inventory and errors in multipurpose table view. It is possible to sort existing nodes in tables on any column. Filter fields in the header allow you to filter nodes by specific string. Under Operations tab you can find very useful feature -  bulk deleting/modyfying/publishing/unpublishing. This is very useful when you need to edit many rows under specific type of content. In next part you can add new rows to injection, instrument, project content type. Last part allows you to view all of nodes under wiki and edit appropriate settings. There is also a way how to edit Wiki's menu.

 

Advanced Administration

Managing users and permissions

You can see all Drupal users in this table. If you want to add new user, click to Add user button. We distinguish two various roles in FreeLAB by default -> manager and operator. You can add new user, fill username, email, display name and give the user associated role. If you use LDAP Authentication, user should login first to create their account automatically or you can create it manually at first. Then you can set the appropriate role to the domain users.

 

LDAP Configuration - allows you to autHENticate with domain username/passwords

FreeLAB distributed as image has already installed php_ldap module and appropriate settings. To enable LDAP (Domain) authentication login as superadmin. Default is:

Login: admin_freelab

Pass: freelab

After log in, be careful for any modification, backup your installation prior to change the configuration. Go to YOURFREELABAIP/admin/config/people/ldap/servers. You can edit existing example and fill correct Domain server address:

Tab Server

Machine name  whatever

Name  whatever

Server Type Active Directory

LDAP Server IP or hostname

LDAP port 389

Binding method Service Account Bind: Use credentials in the Service Account field to bind to LDAP. This option is usually a best practice.

DN for non-anonymous search fill some domain account which you can provide login/password to load users from LDAP (should be some system account without password expiration, users privilegies enough). Use full name (CN name) as account name, not UID for binding

Password fill system user password

Base DNs for LDAP users, groups, and other entries dc=domain,dc=local (or ou)

(if you don't know, go to domain controller and use "dsquery user" command under command line. You will see all users, ou, cn and dn settings. If you do not have an access to domain server, ask your IT specialist to send output of the variables)

AuthName attribut samaccountname

AccountName attribut samaccountname

Email attribut mail

Expression for user DN. Required when "Bind with Users Credentials" method selected uid=%username,%basedn

Groups are not relevant to this Drupal site. This is generally true if LDAP Groups, LDAP Authorization etc are not in use CHECK

Tab Users

FreeLAB - Statistics module for chromatography lab

 

Tab Authentication

- set mixed or LDAP only mode and check your domain server

 

Finally, you can log in with domain username and password. Account will be created automatically. Log in with manager or admin_freelab login to set appropriate permissions to new users from domain.

 

SMTP FOR EMAIL NOTIFICATIONS

Under SMTP email settings you can set SMTP details to enable alert and information emails from FreeLAB. Fill the requested fields under SMTP.

You can use your internal web server or use free smtp from Gmail or similar service. 

 

 

Customization

Change logo

As the FreeLAB is supplied as open source product, you can change logo and colors of application in way you need. It's very simple to achieve your company colors and logo. Log in as default administrator and navigate to /admin/appearance page. Click settings of active theme, uncheck default logo checkbox and upload your desired logo. We recommend to use PNG format. Image should have 200px width and 50px height.

Change color pallete

Navigate to /admin/appearance/colorizer path and change colors of the template parts as you need. Save changes. Make a screenshot for backup settings of default FreeLAB colors.

Inventory table customization

Every content in FreeLAB can be modified. If you want to add new columnor delete existing column from Inventory content type, log on as default administrator and navigate to /admin/structure/types/manage/ Choose manage fileds link on FreeLAB Inventory Table row. Here, you can add new fields type like text, selection field, image, attachments, etc.

English language

  As last thing, you should define in Views how to show your new column. Add new column, sort and set neccessary parameters. For Inventory table, Views configuration path is /admin/structure/views/view/_administration_views/edit/page_5

Český jazyk Český jazyk

          

 

 

Modules

 

Statistics module

Statistics module is the main feature of FreeLAB. This module consist of Instruments and Projects view. You can find detail information, filter, usabilty and injection table under each Instrument or Project card.

 

INSTRUMENTS AND PROJECTS VIEW

From OpenLAB CDS 2.x software, instruments and projects are loading automatically. To use statistics with MassHunter software or any other 3rd party software you have to create instuments and projects manually in Administration -> Add new Instrument/Add new Project.  You can fill fields based on example below. Do not forget to set Status as Active to show in Instruments/Projects list.

 

New Instrument example

FreeLAB - Instruments statistics

 

New Project example

FreeLAB - Inventory module

 

 

INJECTIONS VIEW

Injections view contains header at first position. Header shows Instruments/Project name, description, image and other details (calibration date etc.) Second panel shows Usability of the current instrument in filtered period of time. Third panel is a Filter. You can filter based on any column here. The comparison mark is "Contains" so you can use part of the requested word or number. Last panel is Injection Table. It's listing all of injections based on current filter. Table can be sorted by various column. There is a special feature which SUM time of all injections in table. Table contains 1000 rows per page by default. If more results are filtered, pager allows you to view more results. 

 FreeLAB - internal laboratory Wiki

 

HOW IT WORKS?

Injection table is filling automatically by Feed module. Every software has own Feed. Feed is processing by Cron task periodically -> every day, hour, etc. If you would like to check the Feed details (edit columns, edit instrument name for MassHunter, period time, etc) you should log in with superadmin credentials:

Default are:

Login: admin_freelab

Pass: freelab

and navigate to path /admin/structure/feeds. You can see all feeds in list and edit advanced settings.

 

Wiki module

Wiki allows you to use powerful content management engine to organize your content. Users can create own articles with WYSIWYG editor and add multimedia attachments as images/documents/etc. In case of need, revision history can be used for Wiki. You can use this Wiki for internal documentation, SOP's, manuals, service contacts/contracts and much more. We can help with any modification as paid customization to prepare feature to work as you need.

How it works?

Users with "manager" permission can edit menu under Administration tab. Users with "manager" permission can create a menu tree and then add other users to be an "Wiki editor". Navigate to Wiki with manager's permission and click on left top double arrow mark. Show the menu and choose Member List. You are now allowed to add any other user to Wiki.

FreeLAB - Laboratory calendar    FreeLAB - Placena instalace   

 

Users with appropriate permission will see a create + icon in right bottom corner under specified menu tree.

FreeLAB - Chromatography statistics module

FreeLAB - Instruments statistics

 

Inventory module

Inventory module can show list of instruments, equipments, chemicals, analytical columns and other. Features enable you to alert you via email if Warranty End will be close or alert when column will have more than 300 injections, etc.  Managers can use bulk import tool to import many rows from excel table. Log in with manager role and go to path /import/inventory_bulk_import. Read the instructions, save template and fill the columns with appropriate data. Field PN is unique and will update rows with the same PN if exists. Default administrator can modify feed in any other way.

 FreeLAB - Inventory module

 

For editing location scheme, log in as manager, click to "Customize this page" option on right bottom icon and edit scheme picture under iconFreeLAB - Shared laboratory calendar  .

FreeLAB - internal laboratory Wiki

 

Calendar module

Calendar module allows users to add specific Events to calendar based on Event type. Event type can be instrument/project/customer or any other value. Users of FreeLAB can get information about service/calibration/analysis plan from calendar everywhere and anywhere. As customization option, you can enable feed to allows pair your FreeLAB calendar with Google calendar and add it to your smartphone/computer default calendar client. User with role manager can control Event types and change it as needed.