Integrated Data Repository Toolkit (IDRT)

Transkript

1 Integrated Data Repository Toolkit (IDRT) TMF-Projekt V091-MI_03 Deliverable 2.1: Bereitstellung integrierte Installation, Administration Sebastian Mate Jan Christoph Prof. Dr. Hans-Ulrich Prokosch Dr. Thomas Ganslandt

2 Autoren Autor 1: Sebastian Mate Friedrich-Alexander-Universität Erlangen-Nürnberg Lehrstuhl für Medizinische Informatik Krankenhausstraße ERLANGEN Telefon / Fax / Webseite: Autor 2: Jan Christoph Friedrich-Alexander-Universität Erlangen-Nürnberg Krankenhausstraße ERLANGEN Telefon / Fax / Webseite: Autor 3: Prof. Dr. Hans-Ulrich Prokosch Friedrich-Alexander-Universität Erlangen-Nürnberg Lehrstuhl für Medizinische Informatik Krankenhausstraße ERLANGEN Telefon / Fax / Webseite: sowie: Medizinisches Zentrum für Informations- und Kommunikationstechnik Krankenhausstraße ERLANGEN Autor 4: Dr. Thomas Ganslandt Medizinisches Zentrum für Informations- und Kommunikationstechnik Krankenhausstraße ERLANGEN Telefon / Fax / Webseite: Abschlussbericht Projektname, Projekt-Nr. XY, Monat Jahr 2 / 11

3 Inhaltsverzeichnis Autoren... 2 Inhaltsverzeichnis... 3 Einleitung... 4 Methode... 5 Ergebnisse... 6 Diskussion und Ausblick... 9 Literatur Anhänge Abschlussbericht Projektname, Projekt-Nr. XY, Monat Jahr 3 / 11

4 Einleitung Im Jahr 2009 wurden im Rahmen des TMF-Projekts V IT-Strategie [1, 2] international frei verfügbare IT-Lösungen hinsichtlich deren Verwendbarkeit für die deutsche Forschungslandschaft evaluiert (siehe: IT_Strategie.aspx). Die neben cabig ebenso evaluierte Software i2b2 (Informatics for Integrating Biology and the Bedside) wurde für verschiedene Anwendungsszenarien als nützlich deklariert. Daraufhin hat sich neben dem Einsatz von i2b2 an diversen deutschen Universitäten eine deutsche i2b2-community gebildet, die sich, vernetzt durch die TMF, bisher zu drei i2b2-workshops zusammengefunden hat. Sowohl im Rahmen des IT-Strategie-Projekts, der Workshops und in der Literatur [3, 4] wurde jedoch immer wieder die komplizierte, zeitaufwändige und schwer reproduzierbare Installation bemängelt. Bereits im Rahmen des IT-Strategie-Projekts wurde damit begonnen, die Installation durch Skripte zu automatisieren. Diese Automatismen zeigten sich jedoch nicht für typische Anwendungen in der Praxis tauglich. Beispielsweise wurde bereits im IT- Strategie-Projekt darauf hingewiesen, dass weitere Lösungen zur Administration von i2b2- Servern (i2b2-projektverwaltung, Ontologie-Verwaltung und Erzeugung) geschaffen werden müssen. Im Rahmen einer studentischen Vorarbeit am Lehrstuhl für Medizinische Informatik der Friedrich-Alexander-Universität wurde das Skript aus dem IT-Strategie-Projekt im Jahre 2010 neu implementiert und stark erweitert. Fortan i2b2-wizard genannt, ermöglichte es neben der reinen i2b2-installation auch die Administration. Da das vorliegende IDRT-Projekt den Aufbau eines integrierten Werkzeugpakets auf Basis bewährter, etablierter Komponenten beabsichtigt, soll dieser i2b2-wizard weiterentwickelt und neben i2b2 selbst als eine zentrale Kernkomponente in das IDRT-Softwarepaket eingebunden werden.

5 Methode Innerhalb des Arbeitspakets AP2.1 Bereitstellung integrierte Installation, Administration sollte ein integriertes Setup- und Administrationstool für das i2b2-system entwickelt werden. Aufgrund der bereits erfolgten Vorarbeiten in Erlangen sollte in AP2.1 keine neue Software geschaffen werden. Stattdessen sollte der existierende i2b2-wizard entsprechend der Anforderungen des IDRT-Projekts verbessert und erweitert werden. Dies entspricht auch dem übergeordneten Ziel des IDRT-Projekts, in dem basierend auf frei verfügbaren IT- Komponenten [ ] eine nachhaltig nutzbare [ ] Plattform für die Zusammenführung und Abfrage heterogener Datenbestände [ ] geschaffen werden [soll]. [IDRT Projektantrag]. Im Rahmen eines 3. deutschen i2b2-workshops, der zum Kick-Off des IDRT-Projekt am in Berlin durch die TMF organisiert wurde, konnten weitere Anforderungen und Anwenderbedürfnisse an eine solche Plattform ermittelt werden (vgl. Deliverable D1.1). Bezüglich AP2.1 konnten in einem Hands-On-Tutorial gegen Ende des Workshops interessierte Teilnehmer eine i2b2-instanz auf der Basis des i2b2-wizards installieren und Verbesserungspotenziale am i2b2-wizard aufgedeckt und diskutiert werden. Der i2b2-wizard wird als Bash-Shellscript bereitgestellt. Zu Demonstrationszwecken wird er darüber hinaus zusammen mit den anderen IDRT-Komponenten als virtuelle Maschine zur Verfügung gestellt. Deliverable D1.1: Anforderungsanalyse, Integrated Data Repository Toolkit (IDRT), März / 11

6 Ergebnisse Im Rahmen dieser Arbeit wurde mit dem i2b2-wizard ein Bash-Programm (siehe: weiterentwickelt, das den kompletten Lebenszyklus einer i2b2-instanz abdeckt. Dies betrifft sowohl die Vorbereitung der Linux-Installation, das Herunterladen von benötigter Software, die Installation, Pflege und Administration des i2b2- Systems sowie eine automatische Fehlererkennung und im beschränkten Rahmen automatischen Fehlerkorrektur: Durch die ausgiebige Nutzung des Tools dialog (siehe: arbeitet die Software vollständig Menü-gesteuert. Diese Benutzeroberfläche ist jedoch vollständig textbasiert, wodurch sie sich insbesondere auch über SSH-Verbindungen einsetzen lässt. Die Software unterstützt die vollständige Installation eines i2b2-servers: o Es wird erkannt, ob erforderliche Softwarepakete von Dritt-Herstellern fehlen (d. h. Software, die nicht im Repository der Linux-Distribution enthalten ist, z.b. Oracle XE). Falls erforderlich, werden diese automatisch von dem Skript heruntergeladen und entpackt. o Das Skript unterstützt darüber hinaus die automatische Überprüfung und, falls erforderlich, die Installation von benötigten Softwarepakten aus den Repositories der jeweiligen Linux-Distribution. Grundsätzlich wurde das Skript für Ubuntu entwickelt; es ist jedoch leicht möglich, weitere Debian- Distributionen zu unterstützen, insofern die Paket-Namen im Skript ergänzt werden. Durch die Kapselung der Repository-Softwareinstallation in eigenständige Funktionen kann das Skript auch für weitere Distributionen ergänzt werden. Exemplarisch wurde eine partielle Unterstützung für CentOS umgesetzt. o Das Skript hält in einem Verzeichnis eine vollständige i2b2-serverkonfiguration (jedoch ohne die Oracle-Datenbankinhalte) vor, die bei der Verwendung des i2b2-wizards ständig aktualisiert wird. Beim Deployen des i2b2-quellcodes wird diese Konfiguration dazu verwendet, den i2b2-quellcode vorab auf die aktuelle Serverkonfiguration zu aktualisieren. Dies ermöglicht es, die Konfiguration des Applikationsserver im Notfall binnen Sekunden wieder herzustellen. Wird auch der Inhalt der Oracle-Datenbank berücksichtigt, kann der i2b2- Server auch recht einfach auf eine neue Hardware migriert werden, was jedoch etwas manuelle Arbeit erfordert. o Das Skript übernimmt auch sämtliche administrativen Arbeiten, die in Bezug mit der Oracle-Datenbank stehen. Hierzu gehört beispielweise das bedarfsweise Prüfen, Anlegen und Löschen von Datenbankschemata, die Erzeugung von Tabellen und deren Einträgen, usw. Die Software übernimmt auch administrative Aufgaben, die im Betrieb des i2b2- Servers ständig anfallen: o Das Anlegen und Löschen von neuen i2b2-projekten und i2b2-benutzerkonten sowie die Registrierung von i2b2-benutzern für i2b2-projekte o Illustration, wie Daten ins i2b2 importiert werden können ( i2b2-wizard ETL, diese Funktion ist jedoch nicht Gegenstand des ETL-Prozesses, der im IDRT- Projekt entwickelt werden soll) o o Das Laden oder Entfernen der offiziellen Demodaten der i2b2-entwickler Diverse andere administrative Aufgaben wie zum Beispiel Unterstützung bei der Netzwerkkonfiguration (menübasierte Auswahl des erforderlichen Netzwerk-Interfaces), die Festlegung von Datenbankpasswörtern, der Hive-ID, usw. Deliverable D1.1: Anforderungsanalyse, Integrated Data Repository Toolkit (IDRT), März / 11

7 Bei der Auswahl einer Aufgabe über das Menü werden sämtliche erforderliche andere Aufgaben (Dependencies) durch das Skript automatisch rekursiv aufgelöst. Beispiel: wird das Skript zum allerersten Mal gestartet und sofort versucht, einen neuen Benutzer anzulegen, erkennt das Skript automatisch, dass es erst noch Software herunterladen und installieren muss. Nachdem der Anwender die Benutzerangaben eingegeben hat, erfolgen diese Arbeitsschritte durch das Skript automatisch im Hintergrund ohne weitere Benutzerinteraktion. Das Skript ist seit längerer Zeit für die Installation (jedoch noch nicht für die Administration) von SHRINE vorbereitet. In der hier vorliegenden Version wird SHRINE jedoch nicht unterstützt, da die aktuelle SHRINE-Version nicht mit i2b2 1.6 zusammenarbeitet. Sobald SHRINE von seinen Entwicklern aktualisiert wird, kann die SHRINE- Unterstützung im i2b2-wizard wieder aktiviert werden. Änderungen am i2b2-wizard im Rahmen des IDRT-Projekts Im Rahmen dieser Arbeit konnten einige der Anforderungen der deutschen i2b2- Community, welche im dritten deutschen i2b2-workshop genannt wurden, umgesetzt wurden. Beispielsweise wurde mit dem Ziel der besseren Benutzerführung die Menü- Struktur (Benutzer- und Projekte-Menü) und die Anzeige des JBoss/SHRINE-Status verbessert. Es hat sich gezeigt, dass die Auswahl einer offiziellen Unterstützung von Ubuntu-Linux durch den i2b2-wizard zwar von vielen Anwendern begrüßt wird, jedoch nicht immer im Einklang mit den IT-Richtlinien in den einzelnen Instituten steht. Beispielsweise sollen Server (wie der für i2b2) häufig virtualisiert werden und die Rechenzentren der Institute stellen hierfür ausgesuchte Linux-Distributionen (z. B. CentOS, SuSE-Linux) bereit, die dann auch automatisch durch das Rechenzentrum administriert werden. Im Rahmen des Wechsels von Version 1 auf 2 wurde der Quellcode des i2b2-wizards fast vollständig refokturiert und das Programm modularisiert. Einzelne Module (Shell-Skripte) werden nun abhängig von der Systemkonfiguration beim Programmstart in das Hauptskript eingebunden. Dadurch wird eine Unterstützung für weitere Betriebssysteme und Linux-Distributionen möglich; ebenso können verschiedene i2b2-versionen von ein und demselben i2b2-wizard installiert und administriert werden. Da die Skripte grundsätzlich vor- und rückwärtskompatibel sind, kann beispielsweise nur der i2b2-wizard aktualisiert werden, ohne jedoch die i2b2-version zu ändern. So kann ein möglicherweise gut funktionierendes i2b2 beibehalten und trotzdem von den Verbesserungen der neuen i2b2-wizard-version profitiert werden. Des Weiteren wurden die Datenbankroutinen modularisiert und in diesem Zuge (experimentelle) Unterstützung für Microsoft SQL-Server integriert. Eine weitere Änderung ist die Möglichkeit, gewisse administrative i2b2- Datenbankschemata (üblicherweise mit I2B2PM und I2B2HIVE bezeichnet) nach eigenen Wünschen zu bezeichnen. Weiterhin wurden Funktionen zur automatischen Fehlererkennung stark verbessert. So wird nun auch der JBoss-Start überwacht und im Falle eines Fehlers eine Fehlermeldung und dann das JBoss-Log angezeigt. Darüber hinaus wurde eine Erkennung der Verwendung falscher Passwörter eingebaut. So prüft der i2b2-wizard nun zunächst, ob er eine Datenbankverbindung aufbauen kann, bevor er eine Datenbankoperation durchführt. Einen großen Anteil der Änderungen am i2b2-wizard im Rahmen des IRDT-Projekts stellen jedoch viele kleine Fehlerkorrekturen und allgemeine Verbesserungen dar (z. B. hinsichtlich der zukünftigen Maintainance des Tools). Die folgende Abbildung visualisiert die Än- Deliverable D1.1: Anforderungsanalyse, Integrated Data Repository Toolkit (IDRT), März / 11

8 derungen zwischen Version (letzte Version ohne IDRT-Features) und Version (erste Version mit IDRT-Features). Man beachte die geänderten Zeilen, die auf dem Balken rechts durch rot dargestellt ersichtlich sind. Deliverable D1.1: Anforderungsanalyse, Integrated Data Repository Toolkit (IDRT), März / 11

9 Diskussion und Ausblick Durch die Verwendung des i2b2-wizards wird den Anwendern erheblich vereinfacht, eine i2b2-instanz zu installieren und zu administrieren, da das Tool einen Großteil der dafür erforderlichen Konfigurationsschritte reproduzierbar in Programmcode abbildet und vor dem Anwender versteckt. Nachdem damit die neben der Datenaufbereitung größte Hürde am i2b2-system überwunden wird, ist zu erhoffen, dass das i2b2-system weiterhin an Popularität gewinnt, insbesondere im deutschsprachigen Anwenderraum. Für Anwender außerhalb Deutschlands ist sicherlich die Tatsache interessant, dass der i2b2- Wizard zwar grundsätzlich in das IDRT-Softwarepaket integriert wurde, jedoch nicht an dieses gekoppelt ist. Es ist weiterhin möglich, den i2b2-wizard auch ohne die sonstigen IDRT- Komponenten zu benutzen. Für eine breitere Unterstützung anderer Linux-Distributionen neben dem offiziell unterstützten Ubuntu-Linux ist jedoch auch die internationale i2b2-community gefragt. Insbesondere Interesse für eine Unterstützung für SuSE-Linux und CentOS wurde bereits des Öfteren in der i2b2-community bekundet. Es bleibt zu hoffen, dass das Tool auch in Zukunft weitergepflegt und entwickelt werden kann sei es durch Feedback aus der Community oder das Aufgreifen des Projekts durch die Community selbst. Durch die GPL2-Lizenz ist dies ohne weiteres möglich. Deliverable D1.1: Anforderungsanalyse, Integrated Data Repository Toolkit (IDRT), März / 11

10 Literatur 1. Prokosch HU (2009) Abschlussbericht TMF-Projekt V IT-Strategie 2. Mate S (2009) Evaluation von i2b2 am Universitätsklinikum Erlangen. Studienarbeit, Friedrich-Alexander-Universität Erlangen-Nürnberg 3. Deshmukh VG, Meystre SM, Mitchell JA (2009) Evaluating the Informatics for Integrating Biology and the Bedside System for Clinical Research. BMC Medical Research Methodology 9:70 4. Ganslandt T, Mate S, Helbing K, Sax U, Prokosch H (2011) Unlocking Data for Clinical Research - The German i2b2 Experience. Applied Clinical Informatics 2(1): Deliverable D1.1: Anforderungsanalyse, Integrated Data Repository Toolkit (IDRT), März / 11

11 Anhänge i2b2-wizard Anleitung Präsentation mit Installations Walk-Through Deliverable D1.1: Anforderungsanalyse, Integrated Data Repository Toolkit (IDRT), März / 11

12 i2b2 Wizard Chair of Medical Informatics, University of Erlangen-Nuremberg, Germany and the IDRT team Contact: May 16, 2012 Contents 1 Introduction 2 2 Copyright and Licensing 3 3 How to start 3 4 VirtualBox VM Setup 4 5 Linux Installation Ubuntu Linux x Desktop Edition Ubuntu Linux x Server Edition Some Hints i2b2 Wizard Installation 7 7 How i2b2 Wizard works important things you need to know 9 8 i2b2 Wizard Quick-Start 10 9 All i2b2 Wizard Functions Setting The Default Parameters Automatic Software Download Automatic Software Installation Updating the server IP address Loading or Dropping I2B2HIVE and I2B2PM Creating a new i2b2 Project Removing an i2b2 Project Creating an i2b2 User Removing an i2b2 User Assigning an User to a Project Loading and Removing the Boston Demodata

13 9.12 Building the i2b2 Source Code Controlling the JBoss Process Creating a Separate JBoss Linux User Running ETL-Scripts Using the i2b2 Wizard ETL Approach 21 1 Introduction The Wizard for Simplied i2b2 Administration or i2b2 Wizard is a bash-based program to manage your i2b2 instance. Instead of working with the i2b2 source code, you can use a semi-graphical menu system to install i2b2, create i2b2 projects, create users and much more. Special Features: Semi-graphical program to install and congure i2b2 Full i2b2 installation support Automatic download and extraction of required software packages Automatic installation of Linux software packages Automatic conguration and compilation of the i2b2 source code Automatic handling of all database stu (schema creation, etc.) Full support for i2b2 administration Create and remove i2b2 projects and users Load and remove the Boston Demodata Change Hive ID and network interface and database conguration Change various passwords (e. g. from I2B2HIVE and I2B2PM) Recursive resolving of dependencies for setup targets / administration tasks 2

14 Preparation of special template ETL SQL scripts which can be used to load data into the i2b2 Hive, the ETL process can also be triggered directly in i2b2 Wizard (please note that is is not part of the IDRT functionality). SHRINE Installation (does not cover SHRINE conguration) 2 Copyright and Licensing Copyright (C) Chair of Medical Informatics, Friedrich-Alexander-University of Erlangen-Nuremberg, Germany Portions by 'Integrated Data Repository Toolkit' project (IDRT) Copyright (C) 2012 Technologie- und Methodenplattform fuer die vernetzte medizinische Forschung e.v. (TMF) This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FIT- NESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA , USA. 3 How to start Don't worry: This document appears longish because it describes many things and con- guration steps in detail. The use of i2b2 Wizard, however, is easy and straigtforward. If you're alredy experienced in using Linux and if you keep some important properties of i2b2 Wizard in mind, you will be able to install future i2b2 hives in about 60 minutes including the Linux system! Section 4 describes how you can create the VirtualBox virtual machine with Ubunu Linux. It is important to use 1 GB of RAM, a hard disk with at least 16 GB of space and 3

15 an additional Host-only Adapter network interface if you are using VirtualBox. That's it! Section 5 describes in detail how you can set up the Linux. Currently, only Ubuntu Linux x (32 bit desktop or server edition) is ocially supported. Also make sure that you provide more than 1 GB swap space and use English as your system's language. That's all! Section 6 describes how you can use SFTP to copy the i2b2 Wizard installation les and i2b2 source packages onto your virtual machine and how you launch wizard.sh. Very easy! Section 7 explains how i2b2 Wizard works from very top-level view and outlines some very important aspects, for example the one-way communication with the database. Section 8 contains a walk-though and explains the most important functions of i2b2 Wizard. Section 9 explains all functions of i2b2 Wizard in detail. You should read this if you plan to load more than just the provided Demodata... 4 VirtualBox VM Setup In order to use the i2b2 Wizard, you need either a physical computer or a virtual machine, both running Ubuntu Linux In this guide, we use Sun VirtualBox because it is free and works on a variety of operating systems. In addition, a virtual machine has many advantages compared to a physical computer, such as storing the current machine state and reverting to it. 1. Get yourself a copy of VirtualBox from and install it. In this guide version is used (on a Macintosh). 2. Get a copy of Ubuntu Linux x from To be more specic: you need the le ubuntu desktop-i386.iso. The server edition works too, but is more dicult to install below are some hints regarding this version. The i2b2 Wizard will probably not work with other Linux editions! 3. Launch VirtualBox and choose New. In the new window press Next. Choose a name for your i2b2 instance, for example i2b2 Server. Below, choose Linux and Ubuntu. Press Next. 4

16 4. On the next screen, choose 1024 MB of memory. Press Next. 5. Choose Create new hard disk, Next. In the new window press Next, choose Dynamically expanding storage, Next. Choose 16 GB (8 GB is not enough), Next, Finish and Finish. The new virtual machine will be listed in the VirtualBox main window. 6. On the right side of the window in the Details tab you will nd the entry Network (printed in blue color) with one entry: Adapter 1: PCnet-FAST III (NAT). Click on this blue Network entry. In the new window select the tab Adapter 2, check Enable Network Adapter and select Attached to: Host-only Adapter. Press OK. The main window should now list Adapter 1 and Adapter 2 below Network. 7. Now add the Ubuntu ISO-le. Select the blue Storage entry in the VirtualBox main window. On the left side of the new window in the Storage Tree select the CD-icon labeled Empty. On the right side, click on the yellow/green folder icon. A new window will pop up. Click on Add and choose the ubuntu desktop-i386.iso which you have previously downloaded. The entry IDE Secondary Master (CD/DVD): ubuntu desktopi386.iso ( MB) should now be listed in the VirtualBox main window under Storage. 5 Linux Installation 5.1 Ubuntu Linux x Desktop Edition 1. Start your new (virtual) machine and wait until the graphical installation manager comes up. Select English on the left side (other languages will probably fail, because this choice aects how the Oracle database is initialized (date format, etc.) and how various Linux tools print messages). Then select Install Ubuntu x LTS. 5

17 Figure 1: Hard disk partitioning with > 1 GB swap space. 2. Choose your keyboard layout. It is OK to choose one dierent to English. Press Forward. 3. The next step is to partition the hard disk manually to get more than 1 GB swap space. Select Specify partitions manually (advanced) and press Forward. Select New Partition Table... and Continue. Select the free space entry in the table above and click on the Add... button. In the new window enter in New partition size in megabytes: the value 1101 and select Use as: swap area. Click OK. A new swap partition with 1101 MB should show up. Again, select the free space entry in the table and click on the Add... button. In the new window enter in Mount point: the value /. Click OK. A new ext4 partition with 15 GB should show up. If the whole partitioning looks like in Figure 1 on page 6, press Forward. 4. In the Who are you? screen ll in your desired information. Click Next. This will install Ubuntu Linux on your (virtual) machine. After the installation press Restart Now. After the shut-down, hit enter to eject the disc. 6

18 5. It is a good idea to install the VirtualBox Guest Additions and to assign a static IP address to the VirtualBox Host-Only-Adapter if you have more than one virtual machine in VirtualBox. The Host-Only-Adapter is the interface with the ***-IP. Also install all system updates if the the update-manager pops up. 5.2 Ubuntu Linux x Server Edition Some Hints Partitioning: create two primary partitions: create a 1.1 GB swap partition, and use the rest as Ext4 partition with mount point /. Set the second one to bootable. Network setup: Modify /etc/network/interfaces. You should have two network interfaces (eth0 and eth1 where one is the NAT interface and the other one the vboxnet0 interface), but only one has been congured by the Ubuntu installer. Assuming eth1 is the vboxnet0 interface, the le should contain these contents:... auto eth0 auto eth1 iface eth0 inet dhcp iface eth1 inet static address netmask Replace with your desired (static) IP address. After the modication, run ifup eth1 to get the interface working. Adding a repository for Sun Java: Add the following line to /etc/apt/- sources.list: deb lucid partner After this run apt-get update. 6 i2b2 Wizard Installation All you need to do is to copy the required les to the Ubuntu machine and launch the script wizard.sh. 7

19 1. Download the required i2b2 les from The i2b2 Wizard automatically downloads all required les, however, those from cannot be downloaded automatically. You need the following les: i2b2core-src-xxx.zip (i2b2 Hive source code) i2b2createdb-xxx.zip (Boston Demodata) i2b2webclient-xxx.zip (i2b2 webclient source code) Here, XXX is a placeholder for the current version. Please note that each version of i2b2 Wizard is designed for a specic i2b2 version. To nd out which i2b2 version you need, open wizard.sh in a text editor and look at the rst few lines. Put these les into the packages folder from the i2b2 Wizard installation directory. If you haven't downloaded the les (because you are unable to do so), i2b2 Wizard will ask you to provide a server path in a later step. If this URL contains the valid i2b2 source code repository, i2b2 Wizard can download all les automatically. If you experience diculties in downloading the i2b2 source code les from the i2b2 website, please contact the developer of i2b2 Wizard. 2. Start your new Ubuntu Linux and log in. You need to an additional package source which is required for Sun Java. Select System => Administration => Software Sources, click on the Other Software. Check... lucid partner and click on Close, then Reload. 3. Open a Terminal (Applications => Accessories => Terminal) and type in the following commands: sudo -s (and provide your password) passwd root (assign a password for user 'root') apt-get update apt-get upgrade apt-get install openssh-server This installs the OpenSSH server which allows you to copy the i2b2 Wizard installation les to the Ubuntu machine. 4. Copy all les with SFTP to the Ubuntu machine. On Windows, you can use Win- SCP ( on a Mac the program Cyberduck ( or the excellent MacFusion ( a x for OS X exists here: 8

20 To connect to your virtual machine, use the Host-Only-Adapter. The Host-Only- Adapter is the interface with the ***-IP. You can use the command ifcong to nd out the IP. 5. It is highly recommended to create a snapshot of your VirtualBox virtual machine before running the i2b2 Wizard. 7 How i2b2 Wizard works important things you need to know /i2b2wizard-1.x.x/ /i2b2src/ config/ Project*and*user*configura5on* Configured*i2b2*source*code* i2b2%wizard$ wizard.sh i2b2$ Warning:' one:way!' Create'users' and'i2b2'projects' /opt/jboss ga/ JBoss*applica5on*server*with*i2b2* webservices* Oracle'DB' Project*and*user*config* i2b2*project*data* Manage'users'and' projects' /var/www/admin official*i2*admin*interface*(h@p:// localhost/admin)* Figure 2: i2b2 Wizard's interaction with the i2b2 and Linux system. Figure 2 on page 9 illustrates how i2b2 Wizard interacts with i2b2 and the overall Linux system. The large white rectangle in the upper left part shows the i2b2 Wizard directory, which contains wizard.sh (the i2b2 Wizard bash program) and, besides others, a cong directory. This cong directory stores the current conguration of your i2b2 hive, i.e. information about all created i2b2 projects, users, passwords,... everything that can be congured through i2b2 Wizard's menu system. 9

21 This conguration is used to congure the i2b2 hive source code during deployment (the source code is automatically extracted to /i2b2scr/, then cogured and deployed to /opt/jboss ga/ by i2b2 Wizard during setup, see gure 2, right part). It is OK to delete /i2b2scr/ and /opt/jboss ga/ if something gets messed up, because i2b2 Wizard will automatically rebuild these directories whenever necessary. i2b2 Wizard also writes conguration information to the Oracle database (see bottom left part of gure 2). However, it is important to keep in mind is that this a one-way communication only. This means that i2b2 Wizard only writes to the database but never reads it (future versions of i2b2 Wizard might be able to do this). Because these writes happen as soon as they are necessary (e.g. if a new i2b2 project is being set up and therefore a new Oracle database schema has to be created) but are not stored anywhere, it is not possible to rebuild the database from the cong directory afterwards. Therefore it is possible to migrate an i2b2 server to a new physical machine easily just by copying the i2b2 Wizard directory along with the whole Oracle database. Another important implication from the one-way database communication is that it is not possible to convert an existing i2b2 server into an i2b2 Wizard i2b2 server you'll always have to start from scratch (or rebuild the i2b2 Wizard cong directory to match your existing conguration, which is dicult and out of the scope of this manual). 8 i2b2 Wizard Quick-Start Launch the i2b2 Wizard by executing sh wizard.sh as root. If everything is OK, you will be greeted by the i2b2 Wizard after a few seconds (it will probably install the required tool dialog rst), see Figure 3 on page 11: 1. To download and to install the required server software, select System Setup => Install Software. This will take a considerable amount of time depending on your internet connection speed. Please note that this installs Oracle XE. The license is accepted automatically by i2b2 Wizard. 2. Go to the Menu Hive Tasks and select Load I2B2PM and I2B2HIVE. A window will pop up and ask you which network interface is used to communicate with the i2b2 Workbenches, see Figure 5 on page 15. Select the interface with the ***-IP by pressing the space bar. This is the Host-Only-Adapter if you are using VirtualBox. 3. To create an i2b2 project, go to Projects & Users and select Create i2b2 Project. Enter your desired parameters as shown in gure 7 on page