Appendix B       Sun ONE Portal Server 3.0 Data Migration Module Author's Guide

---

Note	All instances of the Sun™ ONE Portal Server 3.0 product refer to what were formerly known as the iPlanet™ Portal Server 3.0, Service Pack 3a and iPlanet™ Portal Server 3.0, Service Pack 4 products.

---

The data migration tools are designed to be expandable by using modules. The module can define a menu option, order items within the menu, and specify when it should run relative to other modules. The migration tools themselves are designed as a series of modules which makes them excellent examples of how to write modules.

This appendix contains the following sections:

• What Makes a Module?

• Module Example

What Makes a Module?

---

The syntax for module file names is:

[0-9][0-9][descriptive_text][export,convert, or import]

Migration modules must meet certain criteria. In particular, they must:

• Exist under the installed migration directory /modules.

  The migration tools are located in BaseDir/SUNWps/migration. The core migration tools search for modules in BaseDir/SUNWps/migration/modules in order to build the module list used by the migration executables. Each of the core module's directories (cert, desktop, ldap, rules) contain all the files needed to support the module as well as the module executables. For better organization, you should create your own directory under the modules directory that contains all files needed to run your module, even though files located directly in the modules directory will be added.

• Have the digits 0-9 as the first two characters of the file name.

  The first two digits of the module's file name tell the core tools where in the menu this module belongs as well as the execution order of the module. A higher number will run later in the process. A lower number will run earlier. LDAP is priority 40, Desktop is 50, and certificate is 60. So the menu appears as:

  1) LDAP Database

  2) Desktop

  3) Certificate Databases

  4) All of the above

  5) Exit

  If, for example, you place a new module file 30customexport in BaseDir/SUNWps/migration/modules/custom, the export menu would appear as:

  1) Custom menu text

  2) LDAP Database

  3) Desktop

  4) Certificate Databases

  5) All of the above

  6) Exit

  If the user selected All of the above, the custom module would be run first, LDAP second, Desktop third, and certificate last.

• Have a file name ending with export, convert, or import.

  The last text of the filename must be one of these, otherwise the core tools will not recognize them. There can be other text between the priority number (described in the next bullet) and the suffix to give more meaning to the name. For example, 40ldapexport is the name of the LDAP export module.

• Be written in ksh.

  The core tools, written in ksh, call the module files using the "." function. This requires that the module be written in ksh. Other executables, however, can be run within the module file. The module has access to all variables defined within the core tools, including JAVA_HOME and PERL which allows Java and perl code to be run within the module. There are many examples of this within the LDAP and Desktop modules.

• Be executable.

  The module file must be executable in order to be recognized as a module. Note that module files that return a non-zero exit code will cause the core tool to stop and print an error message. Module files that return zero will assume to have completed successfully.

• Return a single line of text or nothing when invoked with the --menu option.

  The text returned represents the option that will be placed in the menu. If no text is returned, the module is considered "always-run" and will be executed regardless of the option the user selects. The menu option text must be localized by the module file prior to returning the value to the core tool.

Module Example

---

This section provides examples of the Desktop module located in BaseDir/SUNWps/migration/modules/desktop.

Desktop Module Files

Table B-1 shows the files comprising the Desktop module and their definitions. This two-column table shows the module name in the first column and its description in the second column.

Table B-1    Desktop Module File Names and Their Descriptions  

File Name	Description
20dtxpconvert	This is an "always-run" module that extracts the Desktop templates to a temporary directory. The LDAP module uses some of these templates as well, so it runs for every conversion.
50dtconvert	Contains the functionality for converting Desktop templates.
50dtexport	Contains the functionality for exporting Desktop templates from Sun ONE Portal Server 3.0.
50dtimport	Contains the functionality for importing Desktop templates to Sun ONE Portal Server 6.0.
auth.cksum	File used to compare authentication templates.
convertJsp.pl	Converts a single JSP file.
convertTemplate.pl	Converts a single template file.
migrate_files.txt	Contains additional files to be migrated.

Module Code Examples

This section provides code extracts from two Desktop Modules.

• First four lines from the Desktop conversion module:

  if [ "$1" == "--menu" ]; then

  print "`$GETTEXT `Desktop'`"

  exit 0

  fi

  In the second line in the code for the Desktop conversion module, $GETTEXT is used to place the item Desktop in the conversion menu.

• First four lines from the "always-run" Desktop module:

  if [ "$1" == "--menu" ]; then

  print ""

  exit 0

  fi

Note that the Desktop menu option localized the menu option prior to printing it.

Important Variables

Table B-2 shows variables that are considered important for use by modules. This two-column table shows the variable in the first column and its description in the second column.

Table B-2    Important Variables Used by Modules 

Variable	Definition
$exportDir	Location of export data.
$importDir	Location of import data.
$tempDesktop/exportData	Location of extracted templates during conversion.
$isFlatRole	Describes role migration type used only during conversion. If $isFlatRole=0 (default), then the conversion tool performs role to suborganization migration. If $isFlatRole=1, then the conversion tool peforms role to role migration.
$isMerge	Describes the display profile merge type used only during import. If $isMerge=0 (default), then the import tool overwrites all existing display profile documents when they conflict with imported display profile documents. If $isMerge=1, then the import tool merges all existing display profile documents when they conflict with imported display profile documents.
$keepUsers	Describes user LDIF record add and delete type used only during import. If $keepUsers=0 (default), then overwrite all existing users by deleting any existing users that conflict with imported users and add new users. If $keepUsers=1, then keep existing users that conflict with imported users.
$reportFile	FQP to report file. You should only append to this file.
$errorFile	FQP to error file. You should only append to this file.

All variables and functions in each of the core tools are available to the module files.

The following is an example of writing to $reportFile and $errorFile:

if [ ! -d $tempDesktop/exportData ]; then

print "`$GETTEXT `Error - Cannot find exported template data in'` $tempDesktop/exportData" | tee -a $errorFile $reportFile