5.7.52. Bugzilla::Migrate¶
5.7.52.1. NAME¶
Bugzilla::Migrate - Functions to migrate from other databases
5.7.52.2. DESCRIPTION¶
This module acts as a base class for the various modules that migrate from other bug-trackers.
The documentation for this module exists mostly to assist people in creating new migrators for other bug-trackers than the ones currently supported.
5.7.52.3. HOW MIGRATION WORKS¶
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:
1
Users are read from the other bug-tracker.
2
Products are read from the other bug-tracker.
3
Bugs are read from the other bug-tracker.
4
The after_read method is called.
5
All bugs are translated from the other bug-tracker's fields/values into Bugzilla's fields values using translate_bug.
6
Users are inserted into Bugzilla.
7
Products are inserted into Bugzilla.
8
Some migrators need to create custom fields before migrating, and so that happens here.
9
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.
10
Bugs are inserted into Bugzilla.
11
The after_insert method is called.
Everything happens in one big transaction, so in general, if there are any errors during the process, nothing will be changed.
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.
5.7.52.4. CONSTRUCTOR¶
load¶
Called like Bugzilla::Migrate->load('Module')
. Returns a new
Bugzilla::Migrate
object that can be used to migrate from the
requested bug-tracker.
5.7.52.5. METHODS YOUR SUBCLASS CAN USE¶
config¶
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 config
, if the configuration file hasn't been read, it will
be read in.
debug¶
If the user hasn't specified --verbose
on the command line, this
does nothing.
Takes two arguments:
The first argument is a string or reference to print to STDERR
.
If it's a reference, Data::Dumper will be used to print the
data structure.
The second argument is a number--the string will only be printed if the
user specified --verbose
at least that many times on the command line.
parse_date¶
(Note: Usually you don't need to call this, because translate_bug handles date translations for you, for bug data.)
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.
translate_bug¶
(Note: Normally you don't have to call this yourself, as
Bugzilla::Migrate
does it for you.)
Uses the $translate_fields
and $translate_values
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 comment
element in the returned
hashref, unless they are listed in NON_COMMENT_FIELDS.
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 NON_COMMENT_FIELDS
.
Note: To save memory, the hashref that you pass in will be destroyed (all keys will be deleted).
translate_value¶
(Note: Generally you only need to use this during _read_products and _read_users if necessary, because the data returned from _read_bugs will be put through translate_bug.)
Uses the $translate_values
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, translate_value
will be called recursively on all
the array elements.
Also, any date field will be converted into ISO 8601 format, for inserting into the database.
translate_field¶
(Note: Normally you don't need to use this, because translate_bug handles it for you.)
Translates a field name in your bug-tracker to a field name in Bugzilla,
using the rules described in the description of the $translate_fields
configuration variable.
Takes a single argument--the name of a field to translate.
Returns undef
if the field could not be translated.
5.7.52.6. METHODS YOU MUST IMPLEMENT¶
These are methods that subclasses must implement:
_read_bugs¶
Should return an arrayref of hashes. The hashes will be passed to
Bugzilla::Bug/create to create bugs in Bugzilla. In addition to
the normal create
fields, the hashes can contain three additional
items:
comments
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.
who
must be a username instead of a user id, though.You don't need to specify a value for the
bug_id
column.
history
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.
who
must be a username instead of a user id, though, andfield
(containing the name of some field) is taken instead offieldid
.You don't need to specify a value for the
bug_id
column.
attachments
An arrayref of hashes, representing values to pass to Bugzilla::Attachment/create. (Remember that the
data
argument must be a file handle--we recommend using IO::File/new_tmpfile to create anonymous temporary files for this purpose.) You should specify asubmitter
argument containing the username of the attachment's submitter.You don't need to specify a value for the the
bug
argument.
_read_products¶
Should return an arrayref of hashes to pass to Bugzilla::Product/create.
In addition to the normal create
fields, this also accepts an additional
argument, components
, which is an arrayref of hashes to pass to
Bugzilla::Component/create (though you do not need to specify the
product
argument for Bugzilla::Component/create).
_read_users¶
Should return an arrayref of hashes to be passed to Bugzilla::User/create.
5.7.52.7. METHODS YOU MIGHT WANT TO IMPLEMENT¶
These are methods that you may want to override in your migrator. All of these methods are called on an instantiated Bugzilla::Migrate object of your subclass by Bugzilla::Migrate itself.
REQUIRED_MODULES¶
Returns an arrayref of Perl modules that must be installed in order for your migrator to run, in the same format as Bugzilla::Install::Requirements/REQUIRED_MODULES.
CUSTOM_FIELDS¶
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. (custom => 1
will be specified automatically for you, so you don't need to specify it.)
CONFIG_VARS¶
This should return an array (not an arrayref) in the same format as
Bugzilla::Install::Localconfig/LOCALCONFIG_VARS, describing
configuration variables for migrating from your bug-tracker. You should
always include the default CONFIG_VARS
(by calling
$self->SUPER::CONFIG_VARS) as part of your return value, if you
override this method.
NON_COMMENT_FIELDS¶
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 translate_bug for more detail.
before_read¶
This is called before any data is read from the "other bug-tracker". The default implementation does nothing.
after_read¶
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.
before_insert¶
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.
after_insert¶
This is run after all data is inserted into Bugzilla. The default implementation does nothing.
5.7.52.8. Methods in need of POD¶
do_migration
verbose
bug_fields
insert_users
users
check_requirements
bugs
map_value
insert_products
products
translate_all_bugs
config_file_name
dry_run
name
create_custom_fields
reset_serial_values
read_config
write_config
insert_bugs
create_legal_values
This documentation undoubtedly has bugs; if you find some, please file them here.