<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>
Bugzilla::Migrate</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" title="style" type="text/css" href=".././../../../../style.css" media="all" >
</head>
<body id="pod">
<p class="backlinktop"><b><a name="___top" href="../index.html" accesskey="1" title="All Documents"><<</a></b></p>
<h1>Bugzilla::Migrate</h1>
<div class='indexgroup'>
<ul class='indexList indexList1'>
<li class='indexItem indexItem1'><a href='#NAME'>NAME</a>
<li class='indexItem indexItem1'><a href='#DESCRIPTION'>DESCRIPTION</a>
<li class='indexItem indexItem1'><a href='#HOW_MIGRATION_WORKS'>HOW MIGRATION WORKS</a>
<li class='indexItem indexItem1'><a href='#CONSTRUCTOR'>CONSTRUCTOR</a>
<ul class='indexList indexList2'>
<li class='indexItem indexItem2'><a href='#load'>load</a>
</ul>
<li class='indexItem indexItem1'><a href='#METHODS_YOUR_SUBCLASS_CAN_USE'>METHODS YOUR SUBCLASS CAN USE</a>
<ul class='indexList indexList2'>
<li class='indexItem indexItem2'><a href='#config'>config</a>
<li class='indexItem indexItem2'><a href='#debug'>debug</a>
<li class='indexItem indexItem2'><a href='#parse_date'>parse_date</a>
<li class='indexItem indexItem2'><a href='#translate_bug'>translate_bug</a>
<li class='indexItem indexItem2'><a href='#translate_value'>translate_value</a>
<li class='indexItem indexItem2'><a href='#translate_field'>translate_field</a>
</ul>
<li class='indexItem indexItem1'><a href='#METHODS_YOU_MUST_IMPLEMENT'>METHODS YOU MUST IMPLEMENT</a>
<ul class='indexList indexList2'>
<li class='indexItem indexItem2'><a href='#_read_bugs'>_read_bugs</a>
<li class='indexItem indexItem2'><a href='#_read_products'>_read_products</a>
<li class='indexItem indexItem2'><a href='#_read_users'>_read_users</a>
</ul>
<li class='indexItem indexItem1'><a href='#METHODS_YOU_MIGHT_WANT_TO_IMPLEMENT'>METHODS YOU MIGHT WANT TO IMPLEMENT</a>
<ul class='indexList indexList2'>
<li class='indexItem indexItem2'><a href='#REQUIRED_MODULES'>REQUIRED_MODULES</a>
<li class='indexItem indexItem2'><a href='#CUSTOM_FIELDS'>CUSTOM_FIELDS</a>
<li class='indexItem indexItem2'><a href='#CONFIG_VARS'>CONFIG_VARS</a>
<li class='indexItem indexItem2'><a href='#NON_COMMENT_FIELDS'>NON_COMMENT_FIELDS</a>
<li class='indexItem indexItem2'><a href='#before_read'>before_read</a>
<li class='indexItem indexItem2'><a href='#after_read'>after_read</a>
<li class='indexItem indexItem2'><a href='#before_insert'>before_insert</a>
<li class='indexItem indexItem2'><a href='#after_insert'>after_insert</a>
</ul>
<li class='indexItem indexItem1'><a href='#Methods_in_need_of_POD'>Methods in need of POD</a>
</ul>
</div>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="NAME"
>NAME</a></h1>
<p>Bugzilla::Migrate - Functions to migrate from other databases</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="DESCRIPTION"
>DESCRIPTION</a></h1>
<p>This module acts as a base class for the various modules that migrate from other bug-trackers.</p>
<p>The documentation for this module exists mostly to assist people in creating new migrators for other bug-trackers than the ones currently supported.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="HOW_MIGRATION_WORKS"
>HOW MIGRATION WORKS</a></h1>
<p>Before writing anything to the Bugzilla database,
the migrator will read everything from the other bug-tracker's database.
Here's the exact order of what happens:</p>
<ol>
<li>Users are read from the other bug-tracker.</li>
<li>Products are read from the other bug-tracker.</li>
<li>Bugs are read from the other bug-tracker.</li>
<li>The <a href="#after_read" class="podlinkpod"
>"after_read"</a> method is called.</li>
<li>All bugs are translated from the other bug-tracker's fields/values into Bugzilla's fields values using <a href="#translate_bug" class="podlinkpod"
>"translate_bug"</a>.</li>
<li>Users are inserted into Bugzilla.</li>
<li>Products are inserted into Bugzilla.</li>
<li>Some migrators need to create custom fields before migrating,
and so that happens here.</li>
<li>Any legal values that need to be created for any drop-down or multi-select fields are created.
This is done by reading all the values on every bug that was read in and creating any values that don't already exist in Bugzilla for every drop-down or multi-select field on each bug.
This includes creating any product versions and milestones that need to be created.</li>
<li>Bugs are inserted into Bugzilla.</li>
<li>The <a href="#after_insert" class="podlinkpod"
>"after_insert"</a> method is called.</li>
</ol>
<p>Everything happens in one big transaction,
so in general,
if there are any errors during the process,
nothing will be changed.</p>
<p>The migrator never creates anything that already exists.
So users,
products,
components,
etc.
that already exist will just be re-used by this script,
not re-created.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="CONSTRUCTOR"
>CONSTRUCTOR</a></h1>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="load"
>load</a></h2>
<p>Called like <code class="code">Bugzilla::Migrate->load('Module')</code>.
Returns a new <code class="code">Bugzilla::Migrate</code> object that can be used to migrate from the requested bug-tracker.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="METHODS_YOUR_SUBCLASS_CAN_USE"
>METHODS YOUR SUBCLASS CAN USE</a></h1>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="config"
>config</a></h2>
<p>Takes a single parameter,
a string,
and returns the value of the configuration variable with that name (always a scalar).
The first time you call <code class="code">config</code>,
if the configuration file hasn't been read,
it will be read in.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="debug"
>debug</a></h2>
<p>If the user hasn't specified <code class="code">--verbose</code> on the command line,
this does nothing.</p>
<p>Takes two arguments:</p>
<p>The first argument is a string or reference to print to <code class="code">STDERR</code>.
If it's a reference,
<a href="../Data/Dumper.html" class="podlinkpod"
>Data::Dumper</a> will be used to print the data structure.</p>
<p>The second argument is a number--the string will only be printed if the user specified <code class="code">--verbose</code> at least that many times on the command line.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="parse_date"
>parse_date</a></h2>
<p>(Note: Usually you don't need to call this,
because <a href="#translate_bug" class="podlinkpod"
>"translate_bug"</a> handles date translations for you,
for bug data.)</p>
<p>Parses a date string and returns a formatted date string that can be inserted into the database.
If the input date is missing a timezone,
the "timezone" configuration parameter will be used as the timezone of the date.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="translate_bug"
>translate_bug</a></h2>
<p>(Note: Normally you don't have to call this yourself,
as <code class="code">Bugzilla::Migrate</code> does it for you.)</p>
<p>Uses the <code class="code">$translate_fields</code> and <code class="code">$translate_values</code> configuration variables to convert a hashref of "other bug-tracker" fields into Bugzilla fields.
It takes one argument,
the hashref to convert.
Any unrecognized fields will have their value prepended to the <code class="code">comment</code> element in the returned hashref,
unless they are listed in <a href="#NON_COMMENT_FIELDS" class="podlinkpod"
>"NON_COMMENT_FIELDS"</a>.</p>
<p>In scalar context,
returns the translated bug.
In array context,
returns both the translated bug and a second hashref containing the values of any untranslated fields that were listed in <code class="code">NON_COMMENT_FIELDS</code>.</p>
<p><b>Note:</b> To save memory,
the hashref that you pass in will be destroyed (all keys will be deleted).</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="translate_value"
>translate_value</a></h2>
<p>(Note: Generally you only need to use this during <a href="#_read_products" class="podlinkpod"
>"_read_products"</a> and <a href="#_read_users" class="podlinkpod"
>"_read_users"</a> if necessary,
because the data returned from <a href="#_read_bugs" class="podlinkpod"
>"_read_bugs"</a> will be put through <a href="#translate_bug" class="podlinkpod"
>"translate_bug"</a>.)</p>
<p>Uses the <code class="code">$translate_values</code> configuration variable to convert field values from your bug-tracker to Bugzilla.
Takes two arguments,
the first being a field name and the second being a value.
If the value is an arrayref,
<code class="code">translate_value</code> will be called recursively on all the array elements.</p>
<p>Also,
any date field will be converted into ISO 8601 format,
for inserting into the database.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="translate_field"
>translate_field</a></h2>
<p>(Note: Normally you don't need to use this,
because <a href="#translate_bug" class="podlinkpod"
>"translate_bug"</a> handles it for you.)</p>
<p>Translates a field name in your bug-tracker to a field name in Bugzilla,
using the rules described in the description of the <code class="code">$translate_fields</code> configuration variable.</p>
<p>Takes a single argument--the name of a field to translate.</p>
<p>Returns <code class="code">undef</code> if the field could not be translated.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="METHODS_YOU_MUST_IMPLEMENT"
>METHODS YOU MUST IMPLEMENT</a></h1>
<p>These are methods that subclasses must implement:</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="_read_bugs"
>_read_bugs</a></h2>
<p>Should return an arrayref of hashes.
The hashes will be passed to <a href="../Bugzilla/Bug.html#create" class="podlinkpod"
>"create" in Bugzilla::Bug</a> to create bugs in Bugzilla.
In addition to the normal <code class="code">create</code> fields,
the hashes can contain three additional items:</p>
<dl>
<dt><a name="comments"
>comments</a></dt>
<dd>
<p>An arrayref of hashes,
representing comments to be added to the database.
The keys should be the names of columns in the longdescs table that you want to set for each comment.
<code class="code">who</code> must be a username instead of a user id,
though.</p>
<p>You don't need to specify a value for the <code class="code">bug_id</code> column.</p>
<dt><a name="history"
>history</a></dt>
<dd>
<p>An arrayref of hashes,
representing the history of changes made to this bug.
The keys should be the names of columns in the bugs_activity table to set for each change.
<code class="code">who</code> must be a username instead of a user id,
though,
and <code class="code">field</code> (containing the name of some field) is taken instead of <code class="code">fieldid</code>.</p>
<p>You don't need to specify a value for the <code class="code">bug_id</code> column.</p>
<dt><a name="attachments"
>attachments</a></dt>
<dd>
<p>An arrayref of hashes,
representing values to pass to <a href="../Bugzilla/Attachment.html#create" class="podlinkpod"
>"create" in Bugzilla::Attachment</a>.
(Remember that the <code class="code">data</code> argument must be a file handle--we recommend using <a href="../IO/File.html#new_tmpfile" class="podlinkpod"
>"new_tmpfile" in IO::File</a> to create anonymous temporary files for this purpose.) You should specify a <code class="code">submitter</code> argument containing the username of the attachment's submitter.</p>
<p>You don't need to specify a value for the the <code class="code">bug</code> argument.</p>
</dd>
</dl>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="_read_products"
>_read_products</a></h2>
<p>Should return an arrayref of hashes to pass to <a href="../Bugzilla/Product.html#create" class="podlinkpod"
>"create" in Bugzilla::Product</a>.
In addition to the normal <code class="code">create</code> fields,
this also accepts an additional argument,
<code class="code">components</code>,
which is an arrayref of hashes to pass to <a href="../Bugzilla/Component.html#create" class="podlinkpod"
>"create" in Bugzilla::Component</a> (though you do not need to specify the <code class="code">product</code> argument for <a href="../Bugzilla/Component.html#create" class="podlinkpod"
>"create" in Bugzilla::Component</a>).</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="_read_users"
>_read_users</a></h2>
<p>Should return an arrayref of hashes to be passed to <a href="../Bugzilla/User.html#create" class="podlinkpod"
>"create" in Bugzilla::User</a>.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="METHODS_YOU_MIGHT_WANT_TO_IMPLEMENT"
>METHODS YOU MIGHT WANT TO IMPLEMENT</a></h1>
<p>These are methods that you may want to override in your migrator.
All of these methods are called on an instantiated <a href="../Bugzilla/Migrate.html" class="podlinkpod"
>Bugzilla::Migrate</a> object of your subclass by <a href="../Bugzilla/Migrate.html" class="podlinkpod"
>Bugzilla::Migrate</a> itself.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="REQUIRED_MODULES"
>REQUIRED_MODULES</a></h2>
<p>Returns an arrayref of Perl modules that must be installed in order for your migrator to run,
in the same format as <a href="../Bugzilla/Install/Requirements.html#REQUIRED_MODULES" class="podlinkpod"
>"REQUIRED_MODULES" in Bugzilla::Install::Requirements</a>.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="CUSTOM_FIELDS"
>CUSTOM_FIELDS</a></h2>
<p>Returns a hashref,
where the keys are the names of custom fields to create in the database before inserting bugs.
The values of the hashref are the arguments (other than "name") that should be passed to Bugzilla::Field->create() when creating the field.
(<code class="code">custom => 1</code> will be specified automatically for you,
so you don't need to specify it.)</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="CONFIG_VARS"
>CONFIG_VARS</a></h2>
<p>This should return an array (not an arrayref) in the same format as <a href="../Bugzilla/Install/Localconfig.html#LOCALCONFIG_VARS" class="podlinkpod"
>"LOCALCONFIG_VARS" in Bugzilla::Install::Localconfig</a>,
describing configuration variables for migrating from your bug-tracker.
You should always include the default <code class="code">CONFIG_VARS</code> (by calling $self->SUPER::CONFIG_VARS) as part of your return value,
if you override this method.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="NON_COMMENT_FIELDS"
>NON_COMMENT_FIELDS</a></h2>
<p>An array (not an arrayref).
If there are fields that are not translated and yet shouldn't be added to the initial description of the bug when translating bugs,
then they should be listed here.
See <a href="#translate_bug" class="podlinkpod"
>"translate_bug"</a> for more detail.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="before_read"
>before_read</a></h2>
<p>This is called before any data is read from the "other bug-tracker".
The default implementation does nothing.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="after_read"
>after_read</a></h2>
<p>This is run after all data is read from the other bug-tracker,
but before the bug fields/values have been translated,
and before any data is inserted into Bugzilla.
The default implementation does nothing.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="before_insert"
>before_insert</a></h2>
<p>This is called after all bugs are translated from their "other bug-tracker" values to Bugzilla values,
but before any data is inserted into the database or any custom fields are created.
The default implementation does nothing.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="after_insert"
>after_insert</a></h2>
<p>This is run after all data is inserted into Bugzilla.
The default implementation does nothing.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="Methods_in_need_of_POD"
><b>Methods in need of POD</b></a></h1>
<dl>
<dt><a name="do_migration"
>do_migration</a></dt>
<dd>
<dt><a name="verbose"
>verbose</a></dt>
<dd>
<dt><a name="bug_fields"
>bug_fields</a></dt>
<dd>
<dt><a name="insert_users"
>insert_users</a></dt>
<dd>
<dt><a name="users"
>users</a></dt>
<dd>
<dt><a name="check_requirements"
>check_requirements</a></dt>
<dd>
<dt><a name="bugs"
>bugs</a></dt>
<dd>
<dt><a name="map_value"
>map_value</a></dt>
<dd>
<dt><a name="insert_products"
>insert_products</a></dt>
<dd>
<dt><a name="products"
>products</a></dt>
<dd>
<dt><a name="translate_all_bugs"
>translate_all_bugs</a></dt>
<dd>
<dt><a name="config_file_name"
>config_file_name</a></dt>
<dd>
<dt><a name="dry_run"
>dry_run</a></dt>
<dd>
<dt><a name="name"
>name</a></dt>
<dd>
<dt><a name="create_custom_fields"
>create_custom_fields</a></dt>
<dd>
<dt><a name="reset_serial_values"
>reset_serial_values</a></dt>
<dd>
<dt><a name="read_config"
>read_config</a></dt>
<dd>
<dt><a name="write_config"
>write_config</a></dt>
<dd>
<dt><a name="insert_bugs"
>insert_bugs</a></dt>
<dd>
<dt><a name="create_legal_values"
>create_legal_values</a></dt>
</dl>
<p class="backlinkbottom"><b><a name="___bottom" href="../index.html" title="All Documents"><<</a></b></p>
<!-- end doc -->
</body></html>
