Project Import

The imported archive contains a list of users. Those users are not necessarily present on the target Tuleap instance. Therefore we need to know what action must be taken for unknown users; in some cases we will need to map to another existing users (jdoe on source instance may be john.doe on target instance), or we may have to create a new user.

This is done thanks to a mapping file in csv format. Hopefully a script is here to generate this mapping file based on the archive and current users on target instance:

$> su - codendiadm
$> cd /usr/share/tuleap/
$> src/utils/php-launcher.sh src/utils/generate_user_mapping_for_project_import.php \
   -u SITE_ADMIN_USERNAME \
   -i PATH_TO_ARCHIVE \
   -o PATH_TO_MAPPING_FILE

The generated file will look like:

name,action,comments
jdoe,noop,"Status of existing user jdoe is [S]"
nterray,create:S,"Nicolas Terray (nterray) <nterray@example.com> must be created"
yrossetto,map:,"There is an existing user yrossetto but its email <yannis@example.com> does not match <yrossetto@example.com>. Use action "map:yrossetto" to confirm the mapping"
...

In this example:

  1. jdoe is a suspended user on the target instance. You may decide to do nothing (noop), or you can decide to map jdoe to another user (see below).

  2. nterray does not exist, it should be created. It will be created with suspended status create:S, with active status create:A or with restricted status create:R. Default status is suspended.

  3. yrossetto seems to already exist on the target platform but the email is not the same than the source one. In order to not impersonate someone, you must confirm that both accounts relate to the same person. Maybe it is someone else, therefore you can map: to another account.

Comments column should give you all needed information about current status.

Note

Please note that this column is only informative and will not be used during the import.

Note

The following diagram explains how the décision is made while parsing the users.xml:

User mapping during project import

After having reviewed/edited the mapping file, you should pass it through a script in order to know if your choices are valid in regards to current status of the target instance:

$> src/utils/php-launcher.sh src/utils/check_user_mapping_for_project_import.php \
   -u SITE_ADMIN_USERNAME \
   -i PATH_TO_ARCHIVE \
   -m PATH_TO_MAPPING_FILE

This will generate some feedback about the wellness of the mapping file. You must fix any remaining errors before doing the real import:

$> su - codendiadm
$> cd /usr/share/tuleap/
$> tuleap import-project-xml
   -p PROJECT_ID_IMPORT \
   -u SITE_ADMIN_USERNAME \
   -i PATH_TO_ARCHIVE \
   -m PATH_TO_MAPPING_FILE

If the project to be imported does not yet exist, you must use the root user instead of codendiadm and not use the -p parameter.

$> su - root
$> cd /usr/share/tuleap/
$> tuleap import-project-xml
   -u SITE_ADMIN_USERNAME \
   -i PATH_TO_ARCHIVE \
   -m PATH_TO_MAPPING_FILE

Note

If you encounter XML parse errors without details, we suggest to install the package java-1.8.0-openjdk and try to import again. It should add explicit error messages.