WebSphere MQ File Transfer Edition Create Transfer Service

The WebSphere® MQ File Transfer Edition Create Transfer service requests file transfers between a source and destination WebSphere MQ File Transfer Edition agent.

Important: Use WebSphere MQ V7.5.x with Sterling B2B Integrator V5.2.3 - 5.2.5 and the WebSphere MQ File Transfer Edition services and adapters. WebSphere MQ V8.0.0.2 is supported with the WebSphere MQ File Transfer Edition services and adapters in Sterling B2B Integrator V5.2.6 or later.
The following table provides an overview of the WebSphere MQ File Transfer Edition Create Transfer service:
System Name WebSphere MQ File Transfer Edition Create Transfer Service
Graphical Process Modeler (GPM) category Communications.
Description This service allows a transfer to be requested between two WebSphere MQ File Transfer Edition agents.
Business usage The WebSphere MQ File Transfer Edition Create Transfer Service is invoked by a business process and used to transfer files between a source FTE agent and a destination FTE agent.
Usage example A payment file must be sent for processing. The WebSphere MQ File Transfer Edition Create Transfer Service requests a transfer to send the file from a mailbox within Sterling B2B Integrator to an agent on a remote machine.
Preconfigured? This service is not preconfigured.
Requires third party files? No
Platform availability All platforms supported by the application
Related services The WebSphere MQ File Transfer Edition Create Transfer Service is tightly integrated with the following adapter:
  • WebSphere MQ File Transfer Edition Agent Adapter
Application requirements No
Initiates business processes? No
Invocation This service must be invoked from a business process.
Business process context considerations The instance parameters in a service configuration map to parameters that can be set in the command.properties file in a standard WebSphere MQ File Transfer Edition installation.
Returned status values Parameter Validation Failed - An error in the parameters was detected before attempting to submit the request. Errors returned when communicating with the command queue manager may also be reported in the Advanced Status column.
Restrictions To use bindings mode, the command queue manager must be running on the same server as Sterling B2B Integrator and the WebSphere MQ java JNI libraries must be available.
Persistence level Not Applicable
Testing considerations Debug information for this service can be found in the WebSphere MQ File Transfer Edition Services log files.

Implementing the WebSphere MQ File Transfer Edition Create Transfer Service

You need to implement this service.
  1. Create an instance of the WebSphere MQ File Transfer Edition Agent Adapter. For information, see Managing Services and Adapters.
  2. Create an instance of the WebSphere MQ File Transfer Edition Create Transfer service. For information, see Managing Services and Adapters.
  3. Use the WebSphere MQ File Transfer Edition Create Transfer service in a business process.

Configuring the WebSphere MQ File Transfer Edition Create Transfer Service

The following table presents the configuration parameters for the File Gateway Route Event Service. For more information on each of the parameters below, please see the IBM WebSphere MQ File Transfer Edition Documentation and search for the equivalent WebSphere MQ File Transfer Edition term that is provided.

Field (BPML Element Value) Description
Name Name that the service will have in Sterling B2B Integrator. String. Required.
Description Description of service. String. Required.
Select a Group Not applicable for this adapter. Leave at default.
Command Queue Manager Name (connectionQMgr) The name of the queue manager used to connect to the WebSphere MQ network. String. Required. Maximum 48 characters. Equivalent WebSphere MQ File Transfer Edition property: connectionQMgr
Connection Mode To Command Queue Manager (ConnectionMode) Indicates if service connects to command queue manager in client mode or bindings mode. Valid values are:
  • Client Mode
  • Bindings Mode
Required.
Command Queue Manager Host (connectionQMgrHost) The host name or IP address of the command queue manager. Optional. Equivalent WebSphere MQ File Transfer Edition property: connectionQMgrHost
Command Queue Manager Port (connectionQMgrPort) The port number used to connect to the command queue manager in client mode. Optional for bindings mode, required for client mode. Equivalent WebSphere MQ File Transfer Edition property: connectionQMgrPort
Command Queue Manager Channel (connectionQMgrChannel) The SVRCONN channel name used to connect to the command queue manager. Default is SYSTEM.DEF.SVRCONN. Optional if using bindings mode, required for client mode. Equivalent WebSphere MQ File Transfer Edition property: connectionQMgrChannel
Multi-Instance Standby Command Queue Manager (connectionQMgrStandby) The IP address or host name and port of the standby queue manager. Format is hostname(port) or ip(port). String. Optional. Equivalent WebSphere MQ File Transfer Edition property: connectionQMgrStandby
SSL On Connection To Command Queue Manager (SSL) Enables SSL on network connection to queue manager. Valid values are:
  • None (default)
  • Must
Required.
SSL Cipher Specification (connectionSslCipherSpec) Cipher specification used for SSL connection to queue manager. Must match the Cipher Specification used on the MQ Channel.
  • DES_SHA_EXPORT
  • DES_SHA_EXPORT1024
  • FIPS_WITH_3DES_EDE_CBC_SHA
  • FIPS_WITH_DES_CBC_SHA
  • NULL_MD5
  • NULL_SHA
  • TLS_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_RSA_WITH_AES_128_CBC_SHA
  • TLS_RSA_WITH_AES_256_CBC_SHA
  • TLS_RSA_WITH_DES_CBC_SHA
  • TRIPLE_DES_SHA_US
Drop-down. Required if SSL On Connection To Command Queue Manager (SSL) set to Must. Equivalent WebSphere MQ File Transfer Edition property: connectionSslCipherSpec
SSL Peer Name (connectionSslPeerName) The distinguished name skeleton that must match the name provided by the command queue manager. The distinguished name is used to check the identifying certificate presented by the queue manager on connection. String. Optional. Equivalent WebSphere MQ File Transfer Edition property: connectionSslPeerName
SSL Trust Store Location (connectionSslTrustStore) The location of the certificates that the service trusts. The values is a file path. If it is a Windows file path the backslash character (\) must be escaped (\\). String. Required if SSL On Connection To Command Queue Manager (SSL) set to Must. Equivalent WebSphere MQ File Transfer Edition property: connectionSslTrustStore
SSL Trust Store Password (connectionSslTrustStorePassword) Specifies the password required to access the truststore. Required if SSL On Connection To Command Queue Manager (SSL) set to Must. Equivalent WebSphere MQ File Transfer Edition property: connectionSslTrustStorePassword
SSL Key Store Location (connectionSslKeyStore) The location of the private key of the service. The value is a file path. If it is a Windows file path the backslash character (\) must be escaped (\\). This property is required if the agent queue manager requires client authentication. String. Optional. Equivalent WebSphere MQ File Transfer Edition property: connectionSslKeyStore
SSL Key Store Password (connectionSslKeyStorePassword) The password required to access the private key of the service. This property is required only if the SSL Key Store property is specified. Optional. Equivalent WebSphere MQ File Transfer Edition property: connectionSslKeyStorePassword

Parameters Passed from Business Process to Service

Field (BPML Element Value) Description
Source Agent Name (SourceAgentName) Name of source agent in requested transfer. Required if Source Agent Adapter is not set. Equivalent WebSphere MQ File Transfer Edition fteCreateTransfer argument: -sa source_agent_name
Source Agent Queue Manager (SourceAgentQMgr) Name of source agent's queue manager. Required if Source Agent Adapter is not set. Equivalent WebSphere MQ File Transfer Edition fteCreateTransfer argument: -sm source_agent_qmgr_name
Source Agent Adapter (SourceAgentAdapter) Name of a WebSphere MQ File Transfer Edition Agent Adapter instance from which the Source Agent Name and Source Agent Queue Manager will be obtained if not otherwise set. Optional.
Destination Agent Name (DestAgentName) Name of destination agent in requested transfer. Required if Destination Agent Adapter is not set. Equivalent WebSphere MQ File Transfer Edition fteCreateTransfer argument: -da destination_agent_name
Destination Agent Queue Manager (DestAgentQMgr) Name of destination agent's queue manager. Required if Destination Agent Adapter is not set. Equivalent WebSphere MQ File Transfer Edition fteCreateTransfer argument: -dm destination_agent_qmgr_name
Destination Agent Adapter (DestAgentAdapter) Name of a WebSphere MQ File Transfer Edition Agent Adapter instance from which the Destination Agent Name and Destination Agent Queue Manager will be obtained if not otherwise set. Optional.
Source File (SourceFile) Path to source file. Required. Equivalent WebSphere MQ File Transfer Edition property: SourceFileSpec
Destination File (DestName) Identifies the destination where source file will be written. How this parameter is interpreted depends on value of DestType parameter. In most cases, this will either be a directory path (DestType = DIRECTORY) or a complete path including file name (DestType = FILE). Required. Equivalent WebSphere MQ File Transfer Edition fteCreateTransfer argument: -df destination_file or -dd destination_directory
Reply Queue Manager (ReplyQMgr) Name of queue manager containing reply queue. Required if ReplyQueue is set.
Reply Queue (ReplyQueueName) Name of queue where reply messages should be published. Required if ReplyQueueManager is set.
Priority (Priority) Priority of transfer. Valid values are:
  • 0 (low)
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9 (high)
Optional. Equivalent WebSphere MQ File Transfer Edition fteCreateTransfer argument: -pr transfer_priority
Transfer Id (TransferId) Transfer Identifier (also known as Request Id). Optional; If not provided, is set by the service. Only the first 24 characters (or 48 characters if HexToByte_TransferId is true) will be used.
Convert Transfer Id from Hex to Bytes (HexToByte_TransferId) Valid values are:
  • TRUE - the Transfer Id parameter must be an even number of hexadecimal characters which will then be converted into a byte array to create the transfer identifier
  • FALSE (default)
Optional.
Checksum Method (Checksum) Type of checksum calculated on file to ensure integrity of transfer. Possible values are:
  • MD5
  • None
Optional. Equivalent WebSphere MQ File Transfer Edition fteCreateTransfer argument: -cs checksum
Destination Type (DestType) Defines how DestName parameter is to be interpreted. Possible values are:
  • FILE
  • DIRECTORY
  • DATASET
  • PDS
  • FILESPACE
Optional. Equivalent WebSphere MQ File Transfer Edition fteCreateTransfer argument: -df -dd -ds -dp
Destination Line Ending (DestLineEnding) Line ending at destination. Valid values are:
  • CRLF
  • LF
Optional. Equivalent WebSphere MQ File Transfer Edition fteCreateTransfer argument: -dle destination_line_ending
Destination Character Encoding (DestCharacterEncoding) Destination character encoding. Optional. Only applies if Transfer Mode is TEXT. Equivalent WebSphere MQ File Transfer Edition fteCreateTransfer argument: -dce destination_character_encoding
Destination File Behavior (DestFileBehavior) Behavior if file already exists at destination. Valid values are:
  • ERROR
  • OVERWRITE
Optional. Equivalent WebSphere MQ File Transfer Edition fteCreateTransfer argument: -de destination_file_behavior
Request Detailed Reply Messages (DetailedReplies) Specifies if the reply messages generated for this transfer should include additional details. Valid values are:
  • TRUE
  • FALSE (default)
Only FTE agents at v7.0.4 or greater are able to produce detailed reply messages. Optional.
Source Line Ending (SourceLineEnding) Line ending at source. Valid values are:
  • CRLF
  • LF
Optional.
Source Character Encoding (SourceCharacterEncoding) Source character encoding. Optional. Only applies if Transfer Mode is TEXT. Equivalent WebSphere MQ File Transfer Edition fteCreateTransfer argument: -sce source_character_encoding
Source File Disposition (SourceFileDisposition) Disposition of source file after successful transfer. Valid values are:
  • LEAVE
  • DELETE
Optional. Equivalent WebSphere MQ File Transfer Edition fteCreateTransfer argument: -sd source_file_disposition
Recursive Source Subdirectories (Recursive) Should source file specification with wildcards recursively match subdirectories and their content. Valid values are:
  • TRUE
  • FALSE
Optional. Equivalent WebSphere MQ File Transfer Edition fteCreateTransfer argument: -r recursive
Transfer Mode (TransferMode) Transfer Mode. Valid values are:
  • TEXT
  • BINARY
Optional. Equivalent WebSphere MQ File Transfer Edition fteCreateTransfer argument: -t binary mode or -t text mode
Metadata (MetaData) Name-Value pairs of metadata values as comma separated list (name1=value1,name2=value2). Optional. Equivalent WebSphere MQ File Transfer Edition fteCreateTransfer argument: -md metadata
Job Name (JobName) Job name associated with transfer request. Optional. Equivalent WebSphere MQ File Transfer Edition fteCreateTransfer argument: -jn job name
Originator User Id (OriginatorUserId) User id associated with transfer request. Optional. Equivalent WebSphere MQ File Transfer Edition property: originator
Originator Host Name (OriginatorHostName) Hostname associated with transfer request. Optional. Equivalent WebSphere MQ File Transfer Edition property: hostName
Pre Destination Call Command (PreDestCommand) Name of program, command or script to execute. Optional. Equivalent WebSphere MQ File Transfer Edition fte:command attribute: command
Pre Destination Retry Count (PreDestRetryCount) The number of times to retry calling the program if the program does not return a success return code. Optional. Equivalent WebSphere MQ File Transfer Edition fte:command attribute: retrycount
Pre Destination Wait Between Retries (PreDestRetryWait) The time to wait, in seconds, before trying the program invocation again. Optional. Equivalent WebSphere MQ File Transfer Edition fte:command attribute: retrywait
Pre Destination Success Return Code (PreDestSuccessRC) The value of this attribute determines when the program invocation successfully runs. Optional. Equivalent WebSphere MQ File Transfer Edition fte:command attribute: successrc
Pre Destination Call Type (PreDestCommandType) The value of this attribute specifies what type of program is being called. Possible values are:
  • EXECUTABLE
  • ANTSCRIPT
  • JCL
Optional. Equivalent WebSphere MQ File Transfer Edition fte:command attribute: type
Pre Destination Call Arguments (PreDestArguments) Only valid where the value of the type attribute is EXECUTABLE. Arguments passed to the command. Optional. Equivalent WebSphere MQ File Transfer Edition fte:command attribute: fte:arg
Pre Destination Ant Properties (PreDestProperties) Only valid where the value of the type attribute is ANTSCRIPT. Properties passed to ant script. Optional. Equivalent WebSphere MQ File Transfer Edition fte:command attribute: fte:property
Pre Destination ANT Targets (PreDestTargets) Only valid where the value of the type attribute is ANTSCRIPT. Specifies ant target. Optional. Equivalent WebSphere MQ File Transfer Edition fte:command attribute: fte:target
Post Destination Call Command (PostDestCommand) Name of program, command or script to execute. Optional. Equivalent WebSphere MQ File Transfer Edition fte:command attribute: command
Post Destination Retry Count (PostDestRetryCount) The number of times to retry calling the program if the program does not return a success return code. Optional. Equivalent WebSphere MQ File Transfer Edition fte:command attribute: retrycount
Post Destination Wait Between Retries (PostDestRetryWait) The time to wait, in seconds, before trying the program invocation again. Optional. Equivalent WebSphere MQ File Transfer Edition fte:command attribute: retrywait
Post Destination Success Return Code (PostDestSuccessRC) The value of this attribute determines when the program invocation successfully runs. Optional. Equivalent WebSphere MQ File Transfer Edition fte:command attribute: successrc
Post Destination Call Type (PostDestCommandType) The value of this attribute specifies what type of program is being called. Possible values are:
  • EXECUTABLE
  • ANTSCRIPT
  • JCL
Optional. Equivalent WebSphere MQ File Transfer Edition fte:command attribute: type
Post Destination Call Arguments (PostDestArguments) Only valid where the value of the type attribute is EXECUTABLE. Arguments passed to the command. Optional. Equivalent WebSphere MQ File Transfer Edition fte:command attribute: fte:arg
Post Destination Ant Properties (PostDestProperties) Only valid where the value of the type attribute is ANTSCRIPT. Properties passed to ant script. Optional. Equivalent WebSphere MQ File Transfer Edition fte:command attribute: fte:property
Post Destination ANT Targets (PostDestTargets) Only valid where the value of the type attribute is ANTSCRIPT. Specifies ant target. Optional. Equivalent WebSphere MQ File Transfer Edition fte:command attribute: fte:target
Pre Source Call Command (PreSourceCommand) Name of program, command or script to execute. Optional. Equivalent WebSphere MQ File Transfer Edition fte:command attribute: command
Pre Source Retry Count (PreSourceRetryCount) The number of times to retry calling the program if the program does not return a success return code. Optional. Equivalent WebSphere MQ File Transfer Edition fte:command attribute: retrycount
Pre Source Wait Between Retries (PreSourceRetryWait) The time to wait, in seconds, before trying the program invocation again. Optional. Equivalent WebSphere MQ File Transfer Edition fte:command attribute: retrywait
Pre Source Success Return Code (PreSourceSuccessRC) The value of this attribute is used to determine when the program invocation successfully runs. Optional. Equivalent WebSphere MQ File Transfer Edition fte:command attribute: successrc
Pre Source Call Type (PreSourceCommandType) The value of this attribute specifies what type of program is being called. Possible values are:
  • EXECUTABLE
  • ANTSCRIPT
  • JCL
Optional. Equivalent WebSphere MQ File Transfer Edition fte:command attribute: type
Pre Source Call Arguments (PreSourceArguments) Only valid where the value of the type attribute is EXECUTABLE. Arguments passed to the command. Optional. Equivalent WebSphere MQ File Transfer Edition fte:command attribute: fte:arg
Pre Source Ant Properties (PreSourceProperties) Only valid where the value of the type attribute is ANTSCRIPT. Properties passed to ant script. Optional. Equivalent WebSphere MQ File Transfer Edition fte:command attribute: fte:property
Pre Source ANT Targets (PreSourceTargets) Only valid where the value of the type attribute is ANTSCRIPT. Specifies ant target. Optional. Equivalent WebSphere MQ File Transfer Edition fte:command attribute: fte:target
Post Source Call Command (PostSourceCommand) Name of program, command or script to execute. Optional. Equivalent WebSphere MQ File Transfer Edition fte:command attribute: command
Post Source Retry Count (PostSourceRetryCount) The number of times to retry calling the program if the program does not return a success return code. Optional. Equivalent WebSphere MQ File Transfer Edition fte:command attribute: retrycount
Post Source Wait Between Retries (PostSourceRetryWait) The time to wait, in seconds, before trying the program invocation again. Optional. Equivalent WebSphere MQ File Transfer Edition fte:command attribute: retrywait
Post Source Success Return Code (PostSourceSuccessRC) The value of this attribute is used to determine when the program invocation successfully runs. Optional. Equivalent WebSphere MQ File Transfer Edition fte:command attribute: successrc
Post Source Call Type (PostSourceCommandType) The value of this attribute specifies what type of program is being called. Possible values are:
  • EXECUTABLE
  • ANTSCRIPT
  • JCL
Optional. Equivalent WebSphere MQ File Transfer Edition fte:command attribute: type
Post Source Call Arguments (PostSourceArguments) Only valid where the value of the type attribute is EXECUTABLE. Arguments passed to the command. Optional. Equivalent WebSphere MQ File Transfer Edition fte:command attribute: fte:arg
Post Source Ant Properties (PostSourceProperties) Only valid where the value of the type attribute is ANTSCRIPT. Properties passed to ant script. Optional. Equivalent WebSphere MQ File Transfer Edition fte:command attribute: fte:property
Post Source ANT Targets (PostSourceTargets) Only valid where the value of the type attribute is ANTSCRIPT. Specifies ant target. Optional. Equivalent WebSphere MQ File Transfer Edition fte:command attribute: fte:target
Transfer Item Specification Lists (TransferItemList) List of elements, each representing file to transfer. Optional. An example is shown in the Example Business Processes section.

Parameters Passed from Service to Business Process

The following table presents the parameters passed from this service to a business process.

Field Description
WMQFTE/TransferId The id of the transfer request. If set in input to service, it will be echoed back. If not set in input, the identifier generated by the service is returned
WMQFTE/RequestStatus Indicates if request was successfully placed on agent's command queue. Possible values:
  • SUCCESS
  • FAILURE
  • SUBMISSIONUNKNOWN

Example Business Process to Transfer a Single File

This example shows how the Create Transfer Service can be used in a business process to transfer a single file:

<process name="FTECreateTransfer_SingleFile">
   <sequence>
      <operation name="WebSphereMQ FTE Create Transfer Service">
         <participant name="SFGWMQFTECreateTransfer"/>
            <output message="WebSphereMQFTECreateTransferServiceInputMessage">
              <assign to="." from="*"/>
              <assign to="DestAgentName">DIRK_DAL</assign>
              <assign to="DestAgentQMgr">DAL_AGENTS</assign>
              <assign to="DestName">/localhome/DIRK_DAL</assign>
              <assign to="DestType">DIRECTORY</assign>
              <assign to="ReplyQMgr">DAL_AGENTS</assign>
              <assign to="ReplyQueueName">TEST.REPLY.QUEUE</assign>
              <assign to="SourceAgentName">DIRK23200AGENT</assign>
              <assign to="SourceAgentQMgr">DAL_AGENTS</assign>
              <assign to="SourceFile">/demofileone.txt</assign>
            </output>
            <input message="inmsg">
              <assign to="." from="*"/>
           </input>
        </operation>
  </sequence>
</process>

Example Business Process to Transfer Multiple Files by Building a TransferItemList

The TransferItemList parameter can be used to specify a list of files to be transferred, including unique transfer parameters for each file. The value of the TransferItemList parameter should be an element in process data that contains one or more children, where each child can set values for the following parameters:
  • SourceFile
  • DestName
  • DestType
  • Checksum
  • DestCharacterEncoding
  • DestLineEnding
  • SourceCharacterEncoding
  • SourceLineEnding
  • DestFileBehavior
  • SourceFileDisposition
  • TransferMode
  • Recursive
This two-part example shows a:
  1. TransferItemList element that contains information for two files
  2. Business process that uses the TransferItemList to request multiple files in a single transfer request

This is the example of the TransferItemList element:

<TransferItemList>
	<TransferItem>
		<SourceFile>/SUBDIRA/two.txt</SourceFile>
		<SourceLineEnding>LF</SourceLineEnding>
		<SourceFileDisposition>LEAVE</SourceFileDisposition>
		<Recursive>FALSE</Recursive>
		<DestName>c:\ONE\2.txt</DestName>
		<DestType>FILE</DestType>
		<DestLineEnding>CRLF</DestLineEnding>
		<DestFileBehavior>OVERWRITE</DestFileBehavior>
		<TransferMode>TEXT</TransferMode>
		<Checksum>MD5</Checksum>
	</TransferItem>
	<TransferItem>
		<SourceFile>/SUBDIRA/three.txt</SourceFile>
		<SourceLineEnding>LF</SourceLineEnding>
		<SourceFileDisposition>LEAVE</SourceFileDisposition>
		<Recursive>FALSE</Recursive>
		<DestName>c:\ONE\3.txt</DestName>
		<DestType>FILE</DestType>
		<DestLineEnding>CRLF</DestLineEnding>
		<DestFileBehavior>OVERWRITE</DestFileBehavior>
		<TransferMode>TEXT</TransferMode>
		<Checksum>MD5</Checksum>
	</TransferItem>
</TransferItemList>

This is the example of a BP that populates the TransferItemList parameter via a DocToDOM function call:

<process name="FTECreateTransfer_TransferItemList">
	<sequence>
		<operation name="WebSphereMQ FTE Create Transfer Service">
			<participant name="SFGWMQFTECreateTransfer"/>
			<output message="WebSphereMQFTECreateTransferServiceInputMessage">
				<assign to="." from="*"/>
				<assign to="DestAgentName">DIRK_DAL</assign>
				<assign to="DestAgentQMgr">DAL_AGENTS</assign>
				<assign to="SourceAgentAdapter">DIRK23200AGENT</assign>
				<assign to="TransferItemList" from="DocToDOM(/ProcessData/PrimaryDocument,
                     'false', 'false')/*"/>
				<assign to="JobName">TransferItemList</assign>
			</output>
			<input message="inmsg">
				<assign to="." from="*"/>
			</input>
		</operation>
	</sequence>
</process>