Importing Preferences
The import utility allows you to import previously exported preference information. You can limit the preference instances it imports from an export file; for example, you could import only the preference instances for a specific user or context. You can also chose to apply the imported preference instances to a specific level, such as to a specific organization or user. In this case, preferences instances are only created for the level specified in the -applyTo parameter. No preference instances are created corresponding to the original level of the imported preference instances.
The syntax for the import command is as follows:
windchill wt.preference.ImportPreferences -importfile="<filepath>"
When the import utility is run, a log file is created in the directory where the tool is run, named PreferenceImport_<YYYYMMDD_HHmm>.txt, where <YYYYMMDD_HHmm> is the date and time that the utility is run. Any mismatches between existing preference information and imported preference information is flagged as a conflict and logged in the PreferenceImportConflicts_<YYYYMMDD_HHmm>.txt log file, also created in the directory where the tool is run.
Parameters are supported by the command that determine what happens with such conflicts. New preference definitions and instances are logged as well. If there is no corresponding preference definition, category, or client as that specified in the preference instance being imported, it is flagged as an error and logged. If a preference definition exists, but is already defined at a higher level than the level at which the import is trying to apply the imported preference instance, an error is logged.
If any errors are encountered, the entire import file is processed, all errors are logged, and the utility exits without importing any preference instances.
If no mismatches or errors are encountered, the import completes successfully.
The following parameters are supported with the import command:
Parameter
Description
-importfile="<filepath>"
The XML file, including full file path, from which to import the preferences. This is typically a file created using the preference export utility. If an invalid file or file path is provided, an error message is displayed.
This parameter is required.
-user="<adminID>"
User ID of the site administrator user. This parameter should be specified together with the -password parameter. If these parameters are not specified, then you will be prompted to authenticate when the utility is run.
-password="<adminpassword>"
Password of the site administrator user. This parameter should be specified together with the -user parameter. If these parameters are not specified, then you will be prompted to authenticate when the utility is run.
-usage
Show of all valid arguments for the command.
-debug="<debugLevel>"
Control the level of informational or debug messages. 1 is the least, 3 is the most.
-importSiteLevel
Import only the site-level preference instances from the import file.
Only one of the following parameters can be specified at a time: -importSiteLevel, -importOrgLevel, -importContainerLevel, or -importUserLevel.
If no preference instances exist in the import file for the specified level, an information message is added to the log, but is not considered an error.
-importOrgLevel="<FullPath>"
Import only the preference instances for the specified organization from the import file. Only one organization can be specified at a time. The fully qualified path for the organization must be specified as the parameter value.
For example, to import preference instances for an organization named Demo Organization, specify the parameter as follows:
-importOrgLevel="/wt.inf.container.OrgContainer=Demo Organization"
Only one of the following parameters can be specified at a time: -importSiteLevel, -importOrgLevel, -importContainerLevel, or -importUserLevel.
If no preference instances exist in the import file for the specified level, an information message is added to the log, but is not considered an error.
-importContainerLevel="<FullPath>"
Import only the preference instances for the specified context (product, library, project, or program) from the import file. Only one context can be specified at a time. The fully qualified path for the context must be specified as the parameter value.
For example, to import all preference instances for a product named Product1 in the Demo Organization, specify the parameter as follows:
-importContainerLevel="/wt.inf.container.OrgContainer=Demo Organization/wt.pdmlink.PDMLinkProduct=Product1"
Only one of the following parameters can be specified at a time: -importSiteLevel, -importOrgLevel, -importContainerLevel, or -importUserLevel.
If no preference instances exist in the import file for the specified level, an information message is added to the log, but is not considered an error.
-importUserLevel=<userId>
Import only the preference instances for the specified user from the import file. Only one user can be specified at a time. For example, to import all preference instances for the wcadmin user, specify the parameter as follows:
-userLevel=wcadmin
Only one of the following parameters can be specified at a time: -importSiteLevel, -importOrgLevel, -importContainerLevel, or -importUserLevel.
If no preference instances exist in the import file for the specified level, an information message is added to the log, but is not considered an error.
-overwriteValueConflicts
All value mismatch conflicts are resolved by overwriting existing values with the value being imported. If this parameter is specified, any multi-value preferences are replaced in the database with the imported preference values.
This preference can be specified in conjunction with the -skipUnresolvedConflicts preference, in which case the import operation should successfully complete with all value conflicts overwritten, and all unresolved conflicts skipped.
-skipUnresolvedConflicts
Any conflicts that are not resolved are skipped. The rest of the file is imported.
This preference can be specified in conjunction with the-overwriteValueConflicts preference, in which case the import operation should successfully complete with all value conflicts overwritten, and all unresolved conflicts skipped.
-applyToSiteLevel
Apply the imported preference instances only to the site level.
-applyToOrgLevel="<FullPath>"
Apply the imported preference instances only to the specified organizations. The parameter value must be the fully qualified path for the organization. Multiple organizations can be specified as a comma-delimited list.
This parameter can only be used in conjunction with one of the following parameters: -importSiteLevel, -importOrgLevel, -importContainerLevel, or -importUserLevel.
If multiple organizations have been specified, the import operation is applied to each organization separately. If the import can successfully complete for some of the specified organizations, but not for others, a message is displayed detailing the organizations for which the import was successful. Any conflicts from the unsuccessful organizations are logged in the log file.
-applyToContainerLevel="<FullPath>"
Apply the imported preference instances only to the specified context (product, library, project, or program) or contexts. The parameter value must be the fully qualified path for the context. Multiple contexts can be specified as a comma-delimited list.
This parameter can only be used in conjunction with one of the following parameters: -importSiteLevel, -importOrgLevel, -importContainerLevel, or -importUserLevel.
If multiple contexts have been specified, the import operation is applied to each context individually. If the import can successfully complete for some of the specified contexts, but not for others, a message is displayed detailing the contexts for which the import was successful. Any conflicts from the unsuccessful contexts are logged in the log file.
-applyToUserLevel="<UserId>"
Apply the imported preference instances only to the specified user or users. Multiple users can be specified as a comma-delimited list.
This parameter can only be used in conjunction with one of the following parameters: -importSiteLevel, -importOrgLevel, -importContainerLevel, or -importUserLevel.
If multiple users have been specified, the import operation is applied to each user individually. If the import can successfully complete for some of the specified users, but not for others, a message is displayed detailing the users for which the import was successful. Any conflicts from the unsuccessful users are logged in the log file.
Was this helpful?