preferences_manager

This utility can be used to import and export preference information, manage preference definitions and instances, and change preference instance values. Syntax preferences_manager -u=user-name {-p=password | -pf=password-file} -g=group-name -v=view-contents-in-reports -mode= {append | category | cleanup | cleanup_definitions | clear | export | import | migrate | delete | remove | backup | restore } [-h] Arguments -u Specifies the user ID. This is a user with Teamcenter administration privileges. Note If Security Services single sign-on (SSO) is enabled, the username and password are authenticated by SSO rather than Teamcenter. If you do not supply these arguments, the utility attempts to join an existing SSO session. If no session is found, you are prompted to enter a user ID and password. -p Specifies the user’s password. This argument is mutually exclusive with the -pf argument. -pf Specifies the password file. For more information about managing password files, see Manage password files. This argument is mutually exclusive with the -p argument. -g Specifies the group associated with the user. If used without a value, the user's default group is assumed. -mode append Appends specified values to an existing preference in the database. category Manages preference categories. cleanup Cleans up all the stale preferences that were not removed by other administrative tasks (from the UI for instance). Also removes preference values which are inconsistent with preference type. clear Clears (removes all) the preferences for the specified scope. export Exports scope based preferences in the database to an XML file. import Imports specified preference file to the database. delete Deletes the specified preference definitions from the system. remove Removes the specified preferences for the specified scope from the database. backup Creates a backup of preferences in the database for given locations to an output folder. restore Restores preferences from specified folder to the database for given locations. -h Displays help for this utility. Environment As specified in Setting up a Teamcenter command-line environment. Files As specified in Log files produced by Teamcenter. Restrictions Creation and deletion of preferences is governed by the following rules: If you are a user, you can only create or delete user preferences. If you are a group administrator, you can create or delete group, role, and user preferences. If you are a site administrator, you can create or delete site, group, role, and user preferences. Examples To import the site preferences in an XML file, skipping the processing for all preferences in the XML file that exist in the database, enter the following command on a single line: Copy preferences_manager -u=Tc-admin-user -p=password -g=dba -mode=import -scope=SITE -file=C:\temp\site_pref.xml -action=SKIP To import the site preferences in an XML file, overriding the values of preferences in the database with the values assigned to the same preference in the XML file, enter the following command on a single line: Copy preferences_manager -u=user-id -p=password -g=dba -mode=import -scope=SITE -file=C:\temp\site_pref.xml -action=OVERRIDE To import the site preferences in an XML file, merging the values of preferences in the database with the values assigned to the same preference in the XML file, enter the following command on a single line: Copy preferences_manager -u=Tc-admin-user -p=password -g=dba -mode=import -scope=SITE -file=C:\temp\site_pref.xml -action=MERGE To import preferences, overriding the values of the preferences in the database with the values of the same preference in the file, enter the following command on a single line: Copy preferences_manager -u=Tc-admin-user -p=password -g=dba -mode=import -scope=SITE -file=C:\temp\site_pref -action=OVERRIDE To import a preference (specified on the command line) and override the values in the database with the values specified for the preference on the command line, enter the following command on a single line: Copy preferences_manager -u=Tc-admin-user -p=password -g=dba -mode=import -scope=SITE -file=C:\temp\site_pref -preference=TestPreference -values=Val1,Val2,Val3 -action=OVERRIDE To export all user preferences in the database for the user smith, enter the following command on a single line: Copy preferences_manager -u=smith -p=password -g=design -mode=export -scope=USER -out_file=C:\temp\smith.xml Note In this example, the utility must be run by the user. To export all group preferences in the database for the logged-on group of user smith, enter the following command on a single line: Copy preferences_manager -u=smith -p=password -g=design -mode=export -scope=GROUP -out_file=C:\temp\design.xml To export preferences specified in an input file, enter the following command on a single line: Copy preferences_manager -u=smith -p=password -g=design -mode=export -file=C:\temp\input_file.txt -out_file=c:\temp\exported_preferences.xml To export user preferences for Teamcenter user smith, enter the following command on a single line: Copy preferences_manager -u=Tc-admin-user -p=password -g=dba -mode=export -scope=USER -target=smith -out_file=c:\temp\some-file To remove the pref1 and pref2 preferences for the user smith, enter the following command on a single line: Copy preferences_manager -u=Tc-admin-user -p=password -g=dba -mode=remove -scope=USER -target=smith -preferences=pref1,pref2 To remove the pref1 and pref2 preferences for the Engineering group, enter the following command on a single line: Copy preferences_manager -u=Tc-admin-user -p=password -g=dba -mode=remove -scope=GROUP -target=Engineering -preferences=pref1,pref2 To append the HRN_Cavity value to the existing Connection:HRN_Core,HRN_GeneralWire values on the Connected_ToRules preference, enter the following command on a single line: Copy preferences_manager -u=Tc-admin-user -p=password -g=dba -mode=append -scope=SITE -preference=Connected_ToRules -prefix="Connection:" -values="HRN_Cavity" -delimiter="," -mode=append Appends specified values to an existing preference in the database. -mode=append -scope= {SITE | GROUP | ROLE | USER} -preference=preference-name [-prefix=prefix-to-be-searched-in-value] -values=values-to-be-appended -delimiter=delimiter-to-be-used-for-append -scope Specifies the location to which the specified preferences are appended. It is created in the specified location. Valid values are: SITE Appends the values to preference at the site location. GROUP Appends the values to the preference at the group location. ROLE Appends the values to the preference at the role location. USER Appends the values to the preference at the user location. Note In all these cases, if the preference does not exist at the location, the preference instance is created at the location with the specified value. -preference Specifies the preference to be used for append. If the preference is not found, it is created only if already defined in the database, and only if its protection scope allows for a definition at the given location. -prefix Specifies the prefix to be searched in the values. If the prefix is found, the value is appended to it. If the prefix is not specified, values separated by the delimiter are appended individually to the end of the values list. -values Specifies the values to append to the existing preference values. -delimiter Specifies the delimiter between the values. Back to top -mode=category Manages preference categories. The list of categories is separated by a delimiter using the delimiter option. The default delimiter is a comma. -mode=category -action= CREATE -categories=category-names [-delimiter=delimiter-used-between-categories] -mode=category Manages preference categories. Note This mode requires system administration privileges. -action Specifies the action performed upon the category. The only valid value is CREATE. You can delete categories from the Options dialog box in the rich client. -categories Specifies categories to be created. Categories can be separated by a specified delimiter. -delimiter Specifies the delimiter used between categories. If not specified, the default delimiter is a comma. Back to top -mode=cleanup Removes all instances of all preferences that have no assigned definition. Cleans up user instances of all users with all scopes. -mode=cleanup [-u_target=user-ID list | -u_target=role-ID list | -u_target=group-ID list}] [-dry_run] [-report_file=full-path-to-report-file] -mode=cleanup Takes actions on preferences as per the given action file. If the action_file parameter is specified, it will proceed with the requested actions on the preference instances at the locations specified through the u_target, r_target and g_target parameters. The actions are: preference value removal preference value addition preference value replacement preference renaming In case no targets are specified, the described operations are performed on all the site preference instances and on all the users, roles, and groups present in the database. -u_target Specifies the list of users for which the action will be performed. Entries are the ids of users (separated by a comma) for which the logged-in user has privileges. -r_target Specifies the list of roles for which the action will be performed. Entries are the ids of roles (separated by a comma) for which the logged-in user has privileges. -g_target Specifies the list of groups for which the action will be performed. Entries are the ids of groups (separated by a comma) for which the logged-in user has privileges. -dry_run If specified, no preferences are removed. The system only parses the preferences to be removed and prints the findings in the specified report file. -action_file Full path to the file that contains all the actions to carry out. Example For a documented example action file, look at TC_ROOT\install\actions_on_tcxxx_preferences.xml. -report_file Full path to the file that will contain logging information on the cleanup task. If this argument is not provided, the system will create a default file. Back to top -mode=clear Removes all preference instances in a single scope (user, site, group). If the scope is user, removes only the instances of the target user. This does not remove any preference definitions, not even for custom preferences. -mode=clear {[-scope= {SITE | GROUP | ROLE | USER] [-target=user-ID | role-ID | group-ID] | [-u_target=list-of-user-IDs] [-r_target=list-of-role-IDs] -g_target=list-of-group-IDs]] -mode=clear Removes all preferences of the specified scope. -scope Specifies the location from which the specified preferences are cleared. Valid values are: SITE Clears only site overlay preferences (that is, only the site preferences that have been modified at a site). GROUP Clears all the group preferences of the current logged-on group. ROLE Clears all the role preferences of the current logged-on role. USER Clears all the user preferences of the current logged-on user. -target Specifies the user or role or group ID of the user whose preferences are to be cleared. This option can only be used with the -scope option. -u_target Specifies the list of users for which all preference instances are to be cleared. It cannot be used with the -scope argument but can be used with the -r_target and -g_target arguments. Entries are the IDs of users (separated by a comma) for which the logged-on user has privileges. -r_target Specifies the list of roles for which all preference instances are to be cleared. It cannot be used with the -scope argument but can be used with the -u_target and -g_target arguments. Entries are the IDs of roles (separated by a comma) for which the logged-on user has privileges. -g_target Specifies the list of groups for which all preference instances are to be cleared. It cannot be used with the -scope argument, but can be used with the -r_target and -u_target arguments. Entries are the IDs of groups (separated by a comma) for which the logged-on user has privileges. Back to top -mode=export Exports all definitions and instances in a specified scope. If the scope is user, only the instances of the target user are included. -mode=export [-scope= {SITE | GROUP | ROLE | USER}] [-target= {user-ID | role-ID | group-ID}] [-file=input-file] [-categories=comma-separated-categories] [-delimiter=value-delimiter] [-out_file=output-file-name] [-report_file=full-path-to-report-file] -mode=export Exports scope-based preferences to a specified output file. Note This mode requires system administration privileges. -scope Specifies the location from which the specified preferences are exported. Valid values are: SITE Only the site preferences matching the specified criteria are considered for export. GROUP Only the group preferences (of the current logged-on group) matching the specified criteria are considered for export ROLE Only the role preferences (of the current logged-on role) matching the specified criteria are considered for export USER Only the user preferences (of the current logged-on user) matching the specified criteria are considered for export. -target Specifies the user or role or group ID whose preferences are to be exported. Must be a valid user, role or group ID. If not specified, the export applies to all preferences (including the site location). -file Input file specifying the preferences to be exported. This file contains the preference names (in each line). For example: Item_show_relations Item_DefaultChildProperties -categories Specifies the categories to export. Categories are a comma-separated list, unless a different delimiter is provided with the -delimiter option. This option is ignored if the -file option is provided. -delimiter Specifies the delimiter to be used for the categories. The default delimiter is a comma if the -delimiter option is not specified. -out_file Specifies the file to which preferences are exported. The output is generated in XML format. -report_file Specifies the file that contains logging output. If not specified, a default file is created in the current directory. Back to top -mode=import Imports a specified XML preference file into the database. -mode=import {[-scope= {SITE | GROUP | ROLE | USER] [-target= {user-ID | role-ID | group-ID}] | [-u_target=list-of-user-IDs] [-r_target=list-of-role-IDs] [-g_target=list-of-group-IDs] | [-file=input-file] [-preview] [-categories=categories-to-import] [-delimeter=delimiter] | [-preference=preference-name] [-values=comma-separated-values] [-delimeter=delimiter]} [-protection_scope=default-protection-scope] [-enable_environment=activate] -action= {SKIP | OVERRIDE | MERGE } -report_file=file-name -mode=import Imports a specified preference file into the database. -file=import Specifies an XML preference file. All the preferences within the specified file will imported into the database. -preview=import Performs a dry run and generates the output onto the console. This option is applicable only if -file option is specified. -scope Specifies the location under which the preference instances will be imported. This option can possibly be used with the -target option, but never with any of the -u_target, -r_target or -g_target options. This option can accept one of the following keywords: SITE Preferences in the input file are imported for the site. The logged-in user must be a system administrator. GROUP Preferences in the input file are imported for the group of the logged-in user. The logged-in user must at least be a group administrator. ROLE Preferences in the input file are imported for the role of the logged-in user. The logged-in user must at least be a role administrator. USER Preferences in the input file are imported for the logged-in user. -target Specifies the user or role or group ID whose preferences are to be imported. Must be a valid user, role or group ID. If not specified, the import applies to all preferences (including the site location). -u_target Specifies the list of users whose preference instances are to be imported. This argument can be used with the -r_target and -g_target arguments. Entries are the IDs of users (separated by a comma) for which the logged-on user has privileges. -r_target Specifies the list of roles whose preference instances are to be imported. This argument can be used with the -u_target and -g_target arguments. Entries are the IDs of roles (separated by a comma) for which the logged-on user has privileges. -g_target Specifies the list of groups whose preference instances are to be imported. This argument can be used with the -r_target and -u_target arguments. Entries are the IDs of groups (separated by a comma) for which the logged-on user has privileges. -preference Specifies the preference name that has to be imported to the database. This works only when the -file option is not specified. The preference must have already been defined in the system for this option to work. -protection_scope Specifies the modified (if needed) protection scope to give to the preference specified in the -preference option when the preference is a hierarchical preference already defined in the database, and when the logged-in user is a system administrator. Valid values are: Site, Group, Role, and User. -enable_environment Activates the specified environment. -values Specifies the values for the preference specified in the -preference option. This can be comma-separated values if the -delimiter option is not specified. In order to specify a delimiter other than comma, use the -delimiter option. This option is valid only with the -preference option. If needed, values can be surrounded by double quotation marks. For example, "my value". -delimiter Specifies the delimiter to be used either for the values (when used in conjunction with the -values option) or for the categories (when used with the -categories option. The default delimiter is comma if the -delimiter option is not specified. -categories Specifies the categories to import. Categories are a comma-separated list, unless specified through the -delimiter option. -action Indicates the action to be taken if a preference exists in the database with a different value. Valid values are: SKIP The preference values in the database are untouched. OVERRIDE The preference values in the database are overridden with the new values in the input file MERGE Merges the values in the database with the values in the input file (that is, the union of values in the database and input file). -report_file Specifies the file that to which import results are logged. If not specified, a default file is created. The report file logs the following results: That the import file contains only user scope-protected preferences. That the import file contains role scope-protected preferences. These preferences were not imported for the given users (and a warning was printed in the output report). That the import file contains group scope-protected preferences. These preferences were not imported for the given users/roles (and a warning was printed in the output report). That the import file contains some scope-protected preferences or system preferences. These preferences were not imported for the given users/roles/groups (and a warning was printed in the output report). That the import file contains preferences that are not yet declared at the site level. These preferences were not imported for the given users/roles/groups (and a warning is printed in the output report). Back to top -mode=delete Deletes preference definitions. In this mode, the utility deletes single or multiple definitions and their instances. -mode=delete [-preferences=preference_name–1,preference-name–2, ..., preference-name-n | -file=file-name] [-dry_run] [-report_file= report-file-name] -mode=delete Deletes the specified preference definitions from the system. Note This mode requires system administration privileges. -preferences Comma separated list of preference names which definitions will be removed from the database. Names of foundation preferences are not allowed. This argument cannot be used with the -file option. -file Specifies a list of preferences to be removed. Each preference definition to be removed must be on a separate line in the file. This argument cannot be used with the -preferences option. -dry_run Does not actually complete the operation, though the information is printed in the report file. -report_file Full path to the file that will contain logging information on the upgrade task. If the argument is not provided, the system will create a default file. Back to top -mode=remove Removes instances, not definitions. The exact preference name (or names if removing multiple preferences) must be specified on the command line or in the input file. Only one scope (user, site, group) can be addressed at once. If the scope is user, removes only the specified user preference instances of the target user. -mode=remove {[-scope= {SITE | GROUP | ROLE | USER}] [-target= {user-ID | role-ID | group-ID}] | [-u_target=list-of-user-IDs] [-r_target=list-of-role-IDs] [-g_target=list-of-group-IDs]} [-preferences=preference-name] [-file=file-name] -mode=remove Removes the specified preference instances from the specified location in the database. Note This mode requires system administration privileges. -scope Specifies the location under which the preference instances are deleted. This option may be used with the -target option, but never with any of the -u_target, -r_target or -g_target options. This option can accept one of the following keywords: SITE Removes the specified preferences if they exist in the current logged-on group preferences list. GROUP Removes the specified preferences if they exist in the current logged-on group preferences list. ROLE Removes the specified preferences if they exist in the current logged-on role preferences list. USER Removes the specified preferences if they exist in the current logged-on user preferences list. Note If not specified, this is the default value. -target Specifies the user or role or group ID whose preferences are to be removed. Must be a valid user, role or group ID. If not specified, the removal applies to all preferences (including the site location). -preferences Specifies comma-separated preference names for which the preference instances are to be deleted from the database under the specified locations. -file Contains a list of preferences to be deleted. Each preference should be on a separate line in the file. Note This option cannot be used with the -preferences option. Back to top -mode=backup Creates a backup of preferences in the database for given locations to an output folder. -mode=backup Creates backup of preferences in the system. All the SITE preferences will be backed up by default. To create backup of user/role/group instances use u_list/r_list/g_list options respectively. Note This mode requires system administration privileges. -out_folder Specifies the folder in which preferences backup is created. The output folder structure is shown below: SITE preferences - \PreferenceBackup_\Site\Site_preferences.xml USER preferences - \PreferenceBackup_\User<username>.xml ROLE preferences - \PreferenceBackup_\Role<rolename_UID>.xml GROUP preferences - \PreferenceBackup_\Group<groupname>.xml -u_list Input file specifying the user IDs whose preference instances are to be backed up. Each user ID must be on a separate line in the file. Must be a valid user ID. To backup instances of all users provide u_list option without any file name. Example: Create backup for all users in the system -mode=backup -out_folder= -u_list Create backup for given users only -mode=backup -out_folder= -u_list= Note If u_list option is not provided then backup will not be created for any user. -r_list Input file specifying the role IDs whose preference instances are to be backed up. Each role ID must be on a separate line in the file. Must be a valid role ID. To backup instances of all roles provide r_list option without any file name. Example: Create backup for all roles in the system -mode=backup -out_folder= -r_list Create backup for given roles only -mode=backup -out_folder= -r_list= Note If r_list option is not provided then backup will not be created for any role. -g_list Input file specifying the group IDs whose preference instances are to be backed up. Each group ID must be on a separate line in the file. Must be a valid group ID. To backup instances of all groups provide g_list option without any file name. Example: Create backup for all groups in the system -mode=backup -out_folder= -g_list Create backup for given groups only -mode=backup -out_folder= -g_list= Note If g_list option is not provided then backup will not be created for any group. -report_file Full path to the file that will contain logging information. If the argument is not provided, the system will create a default file. Back to top -mode=restore Restores preferences from specified folder to the database for given locations. -mode=restore Restores preference definition and values from the given backup folder. All the Site preferences will be restored to backup state by default. To restore instances of user/role/group use u_list/r_list/g_list options respectively. For the preferences that are present in the backup, their definition/values will get restored otherwise if they are not present then those preferences/instances will be removed. If you do not wish to remove the added preferences/values then use -preference_list option and provide a file having a list of preferences that you want to restore. Only those preferences will get restored and preferences that are not present in the backup will be preserved. It is recommended to take backup of current system preferences before performing restore operation to recover any data accidentally lost during the restore process. Note This mode requires system administration privileges. -in_folder Specifies the folder from which preferences are to be restored. The input folder is created using -mode=backup. -u_list Input file specifying the user IDs whose preference instances are to be restored. Each user ID must be on a separate line in the file. Must be a valid user ID. To restore all user instances from backup provide u_list option without any file name. Example: Restore all user instances from the backup -mode=restore -in_folder= -u_list Restore instances for given users only -mode=restore -in_folder= -u_list= Note If u_list option is not provided then no user instances will be restored. -r_list Input file specifying the role IDs whose preference instances are to be restored. Each role ID must be on a separate line in the file. Must be a valid role ID. To restore all role instances from backup provide r_list option without any file name. Example: Restore all role instances from the backup -mode=restore -in_folder= -r_list Restore instances for given roles only -mode=restore -in_folder= -r_list= Note If r_list option is not provided then no role instances will be restored. -g_list Input file specifying the group IDs whose preference instances are to be restored. Each group ID must be on a separate line in the file. Must be a valid group ID. To restore all group instances from backup provide g_list option without any file name. Example: Restore all group instances from the backup -mode=restore -in_folder= -g_list Restore instances for given groups only -mode=restore -in_folder= -g_list= Note If g_list option is not provided then no group instances will be restored. -preference_list Input file specifying the list of preferences to be restored from the backup. Each preference name must be on a separate line in the file. Any new preference/instance added in the system that are not present in the backup will be preserved as it is if this option is provided. If this option is not provided then all the preferences from the backup will be restored. -skip_site Skips restore operation for site preference values. None of the Site preference values in the database will be changed. -dry_run Does not actually complete the operation, though the information is printed in the report file. -report_file Full path to the file that will contain logging information. If the argument is not provided, the system will create a default file. Back to top