fteMigrateAgent: migrate an FTE V7.0 agent to MQ V7.5 or later

If you want to migrate an existing agent and its associated configuration from WebSphere MQ File Transfer Edition Version 7.0 to IBM® WebSphere MQ Version 7.5 or later, use the fteMigrateAgent command to migrate. This command can be used to migrate a standard agent, a Connect:Direct® agent, or a protocol bridge agent. The command can also be used to migrate multiple agents in a single request.

From Version 9.0, Managed File Transfer does not support web agents. If you attempt to use the fteMigrateAgent command to migrate a web agent from an earlier release to Version 9.0, an error message is displayed to explain that the migration of a web agent is not supported.

Note: If you are migrating from WebSphere MQ File Transfer Edition Version 7.0 or later, and want to continue using the FTE_CONFIG environment variable, we can do so without changing the FTE_CONFIG value. We can perform a standard migrate, but BFG_DATA must not be set, and FTE_CONFIG must be set as used in Version 7.0. Important: On IBM MQ for Multiplatforms, only users who are IBM MQ administrators (and members of the mqm group) can run this command. If you try to run this command as a user who is not an IBM MQ administrator, you will receive the error message BFGCL0502E: You are not authorized to perform the requested operation. and the command will not run. On z/OS® systems, the user must satisfy (at least) one of these conditions in order to run the migrate command:

  • Be a member of the mqm group (if the mqm group is defined on the system).
  • Be a member of the group named in the BFG_GROUP_NAME environment variable (if one is named).
  • Have no value set in the BFG_GROUP_NAME environment variable when the command is run.

If your agent is configured to run as a Windows service, use the fteModifyAgent command to reconfigure the agent so that it is no longer a Windows service. After the migration is complete, use the fteModifyAgent command again to configure the new agent to be a Windows service. Alternatively, if you include the -f parameter, the command completes but produces a warning.

Before we can run the fteMigrateAgent command, you must stop the agent you want to migrate using the fteStopAgent command.

If you run the command with the -f parameter, only the information about the agent is refreshed. If a required file is missing, the command fails.

Specifically, the following properties files, XML files, and directory associated with the agent are migrated:
Table 1. Agent files migrated by the fteMigrateAgent command
Name of the file migrated by the fteMigrateAgent command for each agent Information
wmqfte.properties The wmqfte.properties file is renamed to installation.properties in IBM WebSphere MQ Version 7.5 or later.
command.properties  
coordination.properties  
coordination_queue_manager.mqsc  
agent_name_create.mqsc  
agent_name_delete.mqsc  
exits directory The command copies all files in the exits directory.
Applies to standard agents only:  
UserSandboxes.xml  
Applies to Connect:Direct bridge agents only:  
ConnectDirectCredentials.xml  
ConnectDirectNodeProperties.xml  
ConnectDirectProcessDefinitions.xml  
Applies to protocol bridge agents only:  
ProtocolBridgeCredentials.xml  
ProtocolBridgeProperties.xml This file exists on WebSphere MQ File Transfer Edition Version 7.0.4 or later only.
The fteMigrateAgent command migrates the files for the installation, coordination, and command queue managers and copies them to IBM WebSphere MQ Version 7.5 or later if the files do not already exist on Version 7.5 or later. If the files already exist, they are not copied as part of the command.


Syntax

fteMigrateAgent

fteMigrateAgent -agentName agent_name -config configuration_directory -credentialPath credentials_path  -f
  • -pconfiguration_options


  • Parameters

      -agentName agent_name
      Required. The name of the agent to migrate to IBM WebSphere MQ Version 7.5 or later.
      -config configuration_directory
      Required. The path to the configuration directory for the installation that you are migrating the agent from. For example, C:\Documents and Settings\All Users\Application Data\IBM\WMQFTE\config
      -credentialPath credentials_path
      Required. Defines the location to migrate the credential information to. This parameter can either be a directory path where existing credential files are present or a new location to receive a new credential file. For z/OS platforms this can be a pre-existing partitioned data set extended (PDSE), either with existing members to be updated, or without existing members to include a new member for these credentials.Note: If a PDSE is used, it must be variable blocked.
      -f
      Optional. Forces the agent to migrate even if some of the configuration files that are typically migrated conflict with the existing configuration. For example, if there is a mismatch a between the properties files on Managed File Transfer and the properties files on IBM WebSphere MQ Version 7.5, or later, specifying the -f parameter means that this mismatch is ignored.
      -p configuration_options
      Optional. This parameter determines the set of configuration options that is used to locate the configuration to migrate. Use the name of a set of configuration options as the value of the -p parameter. By convention this is the name of a coordination queue manager. If we do not specify this parameter, the default set of configuration options is used. For more information, see MFT configuration options on Multiplatforms.
      -? or -h
      Optional. Displays command syntax.


    Examples

    In this example, AGENT3 and its configuration in /var/ibm/WMQFTE/config is migrated to IBM WebSphere MQ Version 7.5 or later:
    fteMigrateAgent -agentName AGENT3 -config /var/ibm/WMQFTE/config -credentialPath /home/user1/AGENT3
    In this example, all agents and their configurations in C:\Documents and Settings\All Users\Application Data\IBM\WMQFTE\config are migrated to IBM WebSphere MQ Version 7.5 or later. The Windows file path is enclosed in double quotation marks (" "). The -f parameter is specified to force migration and ignore any property file mismatches:
    fteMigrateAgent -agentName "*" -config "C:\Documents and Settings\All Users\Application Data\IBM\WMQFTE\config" 
-credentialPath "C:\Documents and Settings\user1\AGENT3" -p "configurationOption" -f


    Return codes

      0
      Command completed successfully.

      1
      Command ended unsuccessfully.

    For more information about return codes, see Return codes for MFT.