diff --git a/readme.txt b/readme.txt new file mode 100644 index 000000000..a21a43e81 --- /dev/null +++ b/readme.txt @@ -0,0 +1,230 @@ +iTop - version 0.9.1 - 06-Apr-2010 +Readme file + +Content Of This File: + +1. ABOUT THIS RELEASE +2. INSTALLATION +2.1. Requirements +2.2. Install procedure +2.3. Migration from version 0.8.1 +3. LIMITATIONS OF THE CURRENT VERSION +3.1. Changes since 0.8.1 +4. HOW TO +4.1. How to export data out of iTop +4.3. How to import data into iTop + +1. ABOUT THIS RELEASE + ================== +Thank you for downloading the sixth packaged release of iTop. This version is a maintenance +release providing a few bug fixes. +Keep in mind that this version (0.9.1) is still not a final version (see the section "Limitations" below). + +With this release we also provide two user guides. These documents are available +on our web site http://www.combodo.com, under the "Support" topic. + +iTop is released under the GPL (v3) license. (Check license.txt in this directory). +The source code of iTop can be found on SourceForge: http://itop.sourceforge.net + +2. INSTALLATION + ============ + +2.1. Requirements + ------------ +iTop is based on the AMP (Apache / MySQL / PHP) platform and requires PHP 5.2 and +MySQL 5. The installation of iTop does not require any command line access to the +server. The only operations required to install iTop are: copying the files to the +server and browsing some web pages. +Although iTop should work with most modern web browsers the application has been +tested mostly on Firefox 3 and IE7/IE8. + +2.2. Install procedure + ----------------- +1) Make sure that you have a properly configured instance of Apache/PHP running +2) Unpack the files contained in the zipped package in a directory served by your +web server. +3) Point your web browser to the URL corresponding to the directory were the files +have been unpackaged and follow the indications on the screen. + +Note: +iTop uses MySQL with the InnoDB engine. If you are running on Linux and if the setup is +very slow with the hard drive spinning a lot, try to set the following value in the my.cnf +configuration file (usually located at /etc/mysql/my.cnf): + +innodb_flush_method = O_DSYNC + +On some systems you'll see a 5 to 10 times performance improvement for writing data into +the MySQL database ! + +2.3. Migration from a previous version + --------------------------------- +The 0.9.1 data model IS FULLY COMPATIBLE with the former one (0.9). +In order to upgrade from vesion 0.9, just overwrite the files in your iTop directory +with the ones provided in the current version. + +In order to MIGRATE FROM AN OLDER VERSION, you have two options: + - keep your current data model and give up all the benefits from the +new data model (subnets, known errors, etc.). + - export your data into CSV files and import them back after the installation +of the new release. + +Preserving your previous data model +----------------------------------- +In case you want to keep a previous data model (i.e. from 0.8.1) just make sure +that you don't overwrite the content of the "business" directory and its "template" +subdirectory. + +Exporting & re-importing data +----------------------------- +If you choose this option, you have to use the export function for each type of +object, in order to save your data in csv files. +Once done, you can install new release 0.9 using a new database. +Then, you can re-import you object using "csv import" functionality. + +Caution: you need to make sure that attributes for your objects are still valid, +as per the new data model constraints. +In particular, attributes defined as enumerated lists may have to be changed +into the data files, to comply with to the new list of allowed values. +Please refer to the chapter "viewing data model" chapter in the administrator +guide. + +In case you encounter issues, do not hesitate to contact the support team: +support@combodo.com + + + +3. LIMITATIONS OF THE CURRENT VERSION + ================================== + +Release 0.9.1 is not supporting: + + - Creation of new user profile from the iTop user interface. + - "Delete All" action for a list of objects. + - Cloning an existing device. This feature has been disabled for the moment + as it was not working properly. + - "Update All" for n/n relationships. + - A lifecycle is not defined for all types of CIs. Only for incident tickets and change tickets. + - Localized characters (like accentuated letters) are not supported for the moment in eMail notifications + + +3.1. Changes since 0.9 + ------------------- +Only bug fixes haven bee made since version 0.9, hence the increment of the minor revision number. + +Bugs fixed +---------- + +All our bugs are tracked on sourceforge: +http://sourceforge.net/apps/trac/itop/report/1. +This release is closing 3 bugs or enhancement requests. + +#86 major defect Fixed bug on CSV import (was not working fine when exporting/importing fields with multiple lines) +#87 major defect Strings containing only digits were treated as numbers instead of string (i.e leading zeroes were lost) +#93 major defect Fixed issue within the setup data load (related to memory_limit) + +Comprehensive list of all other changes... +------------------------------------------ + +- Fixed bug in DisplayBlock (group by - visible on the page "contacts overview") +- Finalized the demo of impact computation (removed an ugly test message) and added few comments +- Related objects computation: + moved to OQL + added capacity to set a default value based on the related objects (during the creation wizard) +- Fixed issues with the consultant toolkit: upgrade an existing DB (add new class/attribute) +- Developed core services to allow for demonstrating impact computation capability +- Deprecated option operation=direct on page UI.php (not used anyway ?) + +4. HOW TO + ====== + +4.1. How to export data out of iTop + ------------------------------ +A set of objects can be exported by the mean of a web service (could be scripted) +Simply call /pages/export.php?format=xml&expression=OQL +(format=csv is also available) + +Using wget, this would give the following command line: +wget --header="Content-Type:application/x-www-form-urlencoded" --post-file=./login.txt -O "export.txt" http:///webservices/export.php?format=csv&expression=... + +Use the wget option -O to store the result in the specified file, in our example: export.txt + +The format for the file login.txt should be: + +operation=login&auth_user=&auth_pwd=&foo=1 + +The set of objects to be exported is defined by an OQL query. +OQL stands for Object Query Language. The OQL syntax is very close to the SQL. +The main differences between SQL and OQL are: + + * No FROM clause: an OQL query always return a set of objects of a given class + and the user will never specify the expected columns, because the OQL + interpreter retreives this information from the Data Model. + + * JOINS: simply specify "JOIN" and the interpreter will determine for you if an + INNER JOIN or an OUTER JOIN should be performed, based on the definitions of + the Data Model. + +OQL Examples: + +Get all the contacts +SELECT bizContact + +Get all the persons (note that a person is contact also, but it has more +attributes to be exported: first_name and employee_number) + +SELECT bizPerson + +Get the WAN circuits provided by "Foo Telecom" + +SELECT bizCircuit JOIN bizOrganization ON bizCircuit.provider_id = bizOrganization.id +WHERE bizOrganization.name = 'Foo Telecom' + +Get the WAN circuits providers + +SELECT bizOrganization JOIN bizCircuit +ON bizCircuit.provider_id = bizOrganization.id + +(In this example we have just inverted bizCircuit and bizOrganization ; yes the order matters, the first class specified is the expected class) + + +4.2. How to import data + ------------------ +SOAP web service: + +This new SOAP web service enables the creation of incident tickets from an external application. +Look at the iTop WSDL file (http://[&separator=] + +Note that this service emulates the functionality provided by the interactive +bulk load: /pages/import.php + +csvdata must be posted, the first line will contain the codes of the attributes +to load, the first column is always used as the reconciliation key +- should be unique, as it determines if the object needs to be updated or created) +If not specified, the separator defaults to ';' + +The answer is given in a simple html format, explaining what has been done for each row of data. + +Example: +A script that creates a company called "Food and Drug Administration" (code FDA). + +wget --header="Content-Type:application/x-www-form-urlencoded" --post-file=data.txt http:///webservices/import.php?class=bizOrganization + +with: data.txt containing the following text + +auth_user=&auth_pwd=&loginop=login&csvdata=name;code +Food and Drug Administration;FDA +Combodo;CBD