Panel

Table of Contents

Template Name	Extension Name	Extension Version
UDMG File Transfer	ue-mft-transfer	1.23.0

Refer to Changelog 216894035 for version history information.

...

Software Requirements for Universal Template and Universal Task

Requires Python 3.7.0 or higher. Tested with the Universal Agent bundled Python distribution.

UDMG Server 1.2.1.0 or higher.

Software Requirements for Universal Agent

...

Actions
- GET: trigger a File Transfer on UDMG to download a file from a remote partner.
- PUT: trigger a File Transfer on UDMG to upload a file to a remote partner.
- MGET:trigger a Wildcard File Transfer on UDMG to download several files from a remote partner.
- MPUT: trigger a Wildcard File Transfer on UDMG to upload several files to a remote partner.
- LIST: trigger a Wildcard List File Transfer on UDMG to list the files matching a wildcard pattern on a remote SFTP partner.
File Transfer Control
- Capability to pause a partial transfer.
- Capability to resume a paused transfer.
- Capability to cancel a transfer (from planned, running, paused, or error status).
- Capability to retry a failed transfer.
- Synchronous mode: the task monitors the UDMG transfer and terminates when the transfer is completed (either with success or error).
- Asynchronous mode: the task registers the UDMG transfer and terminates when the transfer request is acknowledged on UDMG.
Input/Output
- Capability for the UAC task author, to retrieve the list of partners from UDMG for a given protocol.
- Capability for the UAC task author, to retrieve the list of transfer rules from UDMG for a given partner.
- Monitor of the transfer with periodic polling from UDMG and display to output-only fields and extension output.
Other
- Support for SFTP, HTTPS, PeSIT, and PeSIT-TLS file transfer protocolprotocols.

Import Universal Template

...

Modifications of this integration, applied by users or customers, before or after import, might affect the supportability of this integration. For more information refer to IntegrationModifications 216894035.

Configure Universal Task

...

Field

Input type

Default value

Type

Description

Action

Required

PUT

Choice

Action performed upon the task execution.
Available actions:

GET
PUT
MGET
MPUT
LIST

Protocol

Required

SFTP

Choice

The transfer protocol.
Available values:

SFTP
HTTP
HTTPS
PeSIT
PeSIT-TLS

Note

title	Note

The protocol serves as a filter for the Partner list. The actual protocol for the file transfer is the one that is configured on UDMG for the selected Partner

MFT Server

Required

-

Text

UDMG Server URL. This is the URL for the REST API endpoint, the port is configured in the UDMG Server configuration file.
For example: http://udmg.stonebranch.com:8080/api

MFT Credentials

Required

-

Credentials

UDMG Server Credentials. The Credentials definition should be as follows.

User Name as "Runtime User".
User Password as "Runtime Password".

The user must have read permissions for rules and partners, read/write permission for transfers

Source File

Required

-

Text

The name of the source file, or the search pattern:

PUT: local file for PUT
GET: remote file for GET
MPUT: wildcard pattern for local files
MGET: wildcard pattern for remote files
LIST: wildcard pattern for remote files

Target File

Introduced in version 1.1.0

Optional

-

Text

The name of file on the target system after the transfer,

PUT: remote file for PUT
GET: local file for GETnot used for MGET and MPUT
MPUT/MGET/LIST: not used, the field is not displayed.

Partner

Required

-

Dynamic Choice

Dynamically fetched list of partner names.
The list is restricted to the partners that support the selected Protocol. The user can select the required partner name from a drop-down list.

Rule

Required

-

Dynamic Choice

Dynamically fetched list of transfer rules.
The list is restricted to the rules that are assigned to the selected Partner. The user can select the required rule from a drop-down list.

Partner Account

Required

-

Text

The name of the account to use for the connection to the selected Partner.
The account credentials are configured on UDMG.

Wait for Transfer Completion

Introduced in version 1.2.0

Required

True

Boolean

By checking this field, the extension monitors the completion of the transfer on UDMG before completing its execution.

Actions PUT/GET: Wait for the single transferred to be completed.
Actions MPUT/MGET/LIST: Wait for the child file transfers to be completed or not. The extension will always wait for the parent process to be completed successfully, regardless of this configuration attribute.

Polling Interval

Optional

5

Integer

The amount of time (in seconds) the task will wait before polling to check the transfer status.
Valid values from 01.

Max Files to Monitor

Introduced in version 1.2.0

Required

100

Integer

The number of files, above which no monitor will be done, apart from the successful trigger of the file transfer.

In practice this means that for the actions MGET & MPUT, if a wildcard transfer results in more child transfers than the number indicated, the extension will not check the transfer status of these files, and proceed to completion with a special return code (see corresponding section in this document).

...

The configuration on UDMG for the partner:

MGET files from a remote SFTP server

Example for downloading multiple files from an SFTP server.

Image Added

LIST files on a remote SFTP server

Example for listing files from an SFTP server.

Image Added

Task Execution

...

Command Name	Allowed Task Instance Status	Description
Pause	RUNNING	Issue the pause command on the UDMG transfer
Resume	RUNNING	Issue the resume command on the UDMG transfer
. For a wildcard transfer (MPUT or MGET), the pause command is issued for all child transfers on UDMG. Only the eligible children, in status PLANNED or RUNNING, are considered. Failure on one transfer does not block the execution for the other transfers.
Resume	RUNNING	Issue the resume command on the UDMG transfer. For a wildcard transfer (MPUT or MGET), the resume command is issued for all child transfers on UDMG. Only the eligible children, in status INTERRUPTED or PAUSED, are considered. Failure on one transfer does not block the execution for the other transfers.

Cancelation

When the task instance is canceled on the Controller, a cancel command is issued on the UDMG transfer to attempt a graceful termination.

Task Output

Output Only Fields

The output fields for this Universal Extension are described below.

...

The current status of the transfer
One of PLANNED, RUNNING, PAUSED, INTERRUPTED, DONE, CANCELLLED or ERROR

Used for Task instance Extension Status.

...

The date and time the transfer has ended (UDMG Server time)

For a wildcard transfer, this is when the listing of matching files and the registration of the child transfers is completed.

...

Transfer Progress

Modified in version 1.2.0

...

size in KB, MB, or GB for a Single Transfer,
"x out of y files" for a Wildcard Transfer

...

The UDMG transfer error code.

See the table below.

...

Transfer UUID

Introduced in version 1.1.0

...

These fields are also available as task instance variables, with the ops_mft_ prefix:

Image Removed

UDMG Transfer Error Code

...

Indicates that an internal error occurred in the UDMG Server (lost connection to the database, etc.)

...

Exit Codes

The exit codes for this Universal Extension are described below.

...

If the transfer has no children (PUT, GET, LIST action):
- Fetch the UDMG transfer status and update the output-only fields.
- Proceed to cancel the UDMG transfer only when its status is one of PLANNED, RUNNING, INTERRUPTED, PAUSED, or ERROR.
- Update output only fields when the operation is completed.
If the transfer has children (MPUT, MGET action): cancel the execution of all of the eligible child transfers on UDMG ( in status PLANNED, RUNNING, INTERRUPTED, PAUSED, ERROR). Failure on one transfer does not block the execution for the other transfers.

Re-Run

When the task instance is re-run on the Controller, a resume command is issued on the UDMG transfer for the file transfers in status ERROR.

If the transfer has no children (PUT, GET, LIST action):
- Fetch the UDMG transfer status and update the output-only fields.
- Proceed to resume the UDMG transfer only when its status is ERROR, otherwise
- Continute the monitoring until the UDMG transfer is completed.
If the transfer has children (MPUT, MGET action): resume the execution of all of the eligible child transfers on UDMG (in status ERROR). Failure on one transfer does not block the execution for the other transfers.

Task Output

Output Only Fields

The output fields for this Universal Extension are described below.

Field	Type	Description
Transfer ID	Text	The identifier of the transfer on UDMG
Transfer Status	Text	The current status of the transfer One of PLANNED, RUNNING, PAUSED, INTERRUPTED, DONE, CANCELLED or ERROR Used for Task instance Extension Status.
Transfer Start Time	Text	The date and time the transfer has started (UDMG Server time)
Transfer End Time	Text	The date and time the transfer has ended (UDMG Server time) For a wildcard transfer, this is when the listing of matching files and the registration of the child transfers is completed.
Transfer Step	Text	The current processing step of the transfer One of NONE, PRE TASKS, DATA, POST TASKS, ERROR TASKS or FINALIZATION
Transfer Progress Modified in version 1.2.0	Text	The progress of the data transfer in human readable format size in KB, MB, or GB for a Single Transfer, "x out of y files" for a Wildcard Transfer
Error Code	Text	The UDMG transfer error code. See the table below.
Error Message	Text	The error message (if an error occurred)
Transfer Task Number	Text	The number of the task in the processing step. Only for the Transfer Steps 'PRE TASKS', 'POST TASKS', and 'ERROR TASKS'
Local File	Text	Local file path
Remote File	Text	Remote file path
Transfer UUID Introduced in version 1.1.0	Text	The UUID of the transfer on UDMG

These fields are also available as task instance variables, with the ops_mft_ prefix:

Image Added

UDMG Transfer Error Code

Error Code	Description
TeOk	This is the code used by default. It indicates that there is no error
TeUnknown	Indicates an unknown error (the details of the error can give more information).
TeInternal	Indicates that an internal error occurred in the UDMG Server (lost connection to the database, etc.)
TeUnimplemented	Indicates that the partner wanted to use a valid functionality, but which is not implemented by the UDMG Server.
TeConnection	Indicates that the connection to a remote partner cannot be established. This is the most general error code. A more specific code, if available, should be used.
TeConnectionReset	Means "connection reset by peer"
TeUnknownRemote	Indicates that the requested remote partner is not known in the UDMG Server database. For security reasons, the external use of this error code (returning this error to a client) is discouraged for incoming connections in favor of TeBadAuthentication, at the risk of leaking information (here, the account exists, but authentication failed).
TeExceededLimit	Indicates that the transfer cannot be processed because the defined limits have been reached (number of connections, number of transfers, etc.)
TeBadAuthentication	Indicates a connection error caused by incorrect authentication data (user, password, certificate, etc. Details of the error can provide more information).
TeDataTransfer	Indicates that an error occurred during data transfer. This is a general error and a more specific code, if available, should be used.
TeIntegrity	Indicates that the integrity check has failed.
TeFinalization	Indicates that an error occurred during the finalization of the transfer.
TeExternalOperation	Indicates that an error occurred during the execution of pre-transfer, post-transfer, or error processing.
TeStopped	Indicates that the transfer was stopped.
TeCancelled	Indicates that the transfer was cancelled.
TeFileNotFound	Indicates that the requested file was not found.
TeForbidden	Indicates that the remote partner is not allowed to perform an action.
TeBadSize	Indicates an error related to the size of the file (it exceeds a quota, there is not enough space left on the destination disk, etc.)
TeShuttingDown	Indicates that the UDMG Server is shutting down

Exit Codes

The exit codes for this Universal Extension are described below.

Exit Code	Status Classification Code	Status Classification Description	Status Description
0	SUCCESS	Successful Execution	SUCCESS
1	FAIL	Failed Execution	FAIL: < Error Description >
2	AUTHENTICATION_ERROR	Bad credentials	AUTHENTICATION_ERROR: Account cannot be authenticated.
3	AUTHORIZATION_ERROR	Insufficient Permissions	AUTHORIZATION_ERROR: Account is not authorized to perform the requested action.
10	CONNECTION_ERROR	Bad connection data or connection timed out	CONNECTION_ERROR: < Error Description >
11	CONNECTION_ERROR	Extension specific connection error	CONNECTION_ERROR: 404 page not found
20	DATA_VALIDATION_ERROR	Input fields Validation Error	DATA_VALIDATION_ERROR: 400 bad request:
21	TRANSFER_STATUS_ERROR	Transfer Execution Error	TRANSFER_STATUS_ERROR: Transfer failed with error code: TeDataTransferTeUnknown
3022	TRANSFER_STATUS_ERROR	Transfer Execution Error	TRANSFER_STATUS_ERROR: Transfer failed with error code: TeIntegrityTeInternal
3123	TRANSFER_STATUS_ERROR	Transfer Execution Error	TRANSFER_STATUS_ERROR: Transfer failed with error code: TeFinalizationTeUnimplemented
3224	TRANSFER_STATUS_ERROR	Transfer Execution Error	TRANSFER_STATUS_ERROR: Transfer failed with error code: TeExternalOperationTeConnection
3325	TRANSFER_STATUS_ERROR	Transfer Execution Error	TRANSFER_STATUS_ERROR: Transfer failed with error code: TeWarningTeConnectionReset
3426	TRANSFER_STATUS_ERROR	Transfer Execution Error	TRANSFER_STATUS_ERROR: Transfer failed with error code: TeStoppedTeUnknownRemote
3527	TRANSFER_STATUS_ERROR	Transfer Execution Error	TRANSFER_STATUS_ERROR: Transfer failed with error code: TeCanceledTeExceededLimit
3628	TRANSFER_STATUS_ERROR	Transfer Execution Error	TRANSFER_STATUS_ERROR: Transfer failed with error code: TeFileNotFoundTeBadAuthentication
3729	TRANSFER_STATUS_ERROR	Transfer Execution Error	TRANSFER_STATUS_ERROR: Transfer failed with error code: TeForbiddenTeDataTransfer
3830	TRANSFER_STATUS_ERROR	Transfer Execution Error	TRANSFER_STATUS_ERROR: Transfer failed with error code: TeBadSizeTeIntegrity
3931	TRANSFER_STATUS_ERROR	Transfer Execution Error	TRANSFER_STATUS_ERROR: Transfer failed with error code: TeShuttingDownTeFinalization
10032	TRANSFER_STATUS_CANCELERROR	Unexpected Transfer StatusExecution Error	TRANSFER_STATUS_CANCEL: Unexpected CANCELLED status

Extension Output

In the context of a workflow, subsequent tasks can rely on the information provided by this integration as Extension Output.

The Extension output contains attribute result. Attribute result contains the following sub-attributes:

The UUID

Attribute	Type	Description
mft_transfer	object	The details of the main transfer record (the single transfer or the parent transfer in case of Wildcard Transfer).
mft_transfer.transfer_id	string	The identifier of the transfer on UDMG.
mft_transfer.status	string	The current status of the transfer One of PLANNED, RUNNING, PAUSED, INTERRUPTED, DONE, CANCELLLED or ERROR.
mft_transfer.start	string	The date and time the transfer has started (UDMG Server time)
mft_transfer.stop	string	The date and time the transfer has ended (UDMG Server time). For a wildcard transfer, this is when the listing of matching files and the registration of the child transfers is completed.
mft_transfer.step	string	The current processing step of the transfer One of NONE, PRE TASKS, DATA, POST TASKS, ERROR TASKS or FINALIZATION.
mft_transfer.transfer_progress	text	The progress of the data transfer in human readable format size in KB, MB, or GB for a Single Transfer, "x out of y files" for a Wildcard Transfer.
mft_transfer.error_code	string	The error code of the transfer (if an error occurred).
mft_transfer.error_msg	string	The error message (if an error occurred).
mft_transfer.task_number	string	The number of the task in the processing step. Only for the steps 'PRE TASKS', 'POST TASKS', and 'ERROR TASKS'.
mft_transfer.local_file	string	Local file path.
mft_transfer.remote_file	string	Remote file path.
mft_transfer.transfer_uuid Introduced in version 1.1.0	string	ERROR: Transfer failed with error code: TeExternalOperation
33	TRANSFER_STATUS_ERROR	Transfer Execution Error	TRANSFER_STATUS_ERROR: Transfer failed with error code: TeWarning
34	TRANSFER_STATUS_ERROR	Transfer Execution Error	TRANSFER_STATUS_ERROR: Transfer failed with error code: TeStopped
35	TRANSFER_STATUS_ERROR	Transfer Execution Error	TRANSFER_STATUS_ERROR: Transfer failed with error code: TeCancelled
36	TRANSFER_STATUS_ERROR	Transfer Execution Error	TRANSFER_STATUS_ERROR: Transfer failed with error code: TeFileNotFound
37	TRANSFER_STATUS_ERROR	Transfer Execution Error	TRANSFER_STATUS_ERROR: Transfer failed with error code: TeForbidden
38	TRANSFER_STATUS_ERROR	Transfer Execution Error	TRANSFER_STATUS_ERROR: Transfer failed with error code: TeBadSize
39	TRANSFER_STATUS_ERROR	Transfer Execution Error	TRANSFER_STATUS_ERROR: Transfer failed with error code: TeShuttingDown
90	CHILD_TRANSFERS_NOT_MONITORED_WARNING	API Limitations	CHILD_TRANSFERS_NOT_MONITORED_WARNING: Too many child transfers, skipped monitoring their completions status
100	TRANSFER_STATUS_CANCEL	Unexpected Transfer Status	TRANSFER_STATUS_CANCEL: Unexpected CANCELLED status

Extension Output

In the context of a workflow, subsequent tasks can rely on the information provided by this integration as Extension Output.

The Extension output contains attribute result which contains the following sub-attributes:

transfer_info

Introduced in version 1.1.0

Indicator that this is a wildcard transfer.

Only for MPUT and MGETinfo.udmg_xfer_childIDs

Introduced in version 1.2.0

A list of UDMG transfer IDs that are created in the context of this file file transfer. For each file matched the filename input, one file transfer process is created in UDMG.

Only for MPUT and MGET_info.udmg_xfer_files

Introduced in version 1.2.0

The list of files that matched the user input. Each of these files is transferred with a separate file transfer execution, which transfer ids can be found in “udmg_xfer_childIDs“ list.

Only for MPUT and MGET_files_summary

Introduced in version 1.2.0

Summary counters_files_summary.doneNumber of file transfers with success

Attribute	Type	Description
mft_transfer	object	The details of the main transfer record (the single transfer or the parent transfer in case of Wildcard Transfer).
mft_transfer.transfer_id	string	The identifier of the transfer on UDMG.
mft_transfer.	object	The transfer information fields. Set of metadata associated to the transfer on UDMG Server. The fields with udmg_ prefix are set internally by UDMG server. The fields with udmg_ue prefix are set by the UDMG File Transfer task.
mft_transfer.transfer_info.udmg_ue_task_uuid Introduced in version 1.2.0	string	The UUID of the UDMG File Transfer task. It can be used to easily correlate the UC task executions and the corresponding UDMG file transfers.
mft_transfer.transfer_info.udmg_xfer_wildcard Introduced in version 1.2.0	boolean	status	string	The current status of the transfer One of PLANNED, RUNNING, PAUSED, INTERRUPTED, DONE, CANCELLLED or ERROR.
mft_transfer.start	string	The date and time the transfer has started (UDMG Server time)
mft_transfer.stop	string	The date and time the transfer has ended (UDMG Server time). For a wildcard transfer, this is when the listing of matching files and the registration of the child transfers is completed.
mft_transfer.step	string	The current processing step of the transfer One of NONE, PRE TASKS, DATA, POST TASKS, ERROR TASKS or FINALIZATION.
mft_transfer.transfer_	array	progress	text	The progress of the data transfer in human readable format size in KB, MB, or GB for a Single Transfer, "x out of y files" for a Wildcard Transfer.
mft_transfer.error_code	string	The error code of the transfer	array	(if an error occurred).
mft_transfer.error_msg	string	The error message (if an error occurred).
mft_transfer.task_number	string	The number of the task in the processing step. Only for the steps 'PRE TASKS', 'POST TASKS', and 'ERROR TASKS'.
mft_transfer	object	.local_file	string	Local file path.
mft_transfer	number	.remote_file	string	Remote file path.
mft_transfer.transfer_ files_summary.error	number	Number of file transfers in error state uuid Introduced in version 1.1.0	string	The UUID of the transfer on UDMG.
mft_transfer.transfer_ files_summary.cancelled	number	Number of file transfers that are cancelled.	errorsinfo Introduced in version 1.1.0	object	The transfer information fields. Set of metadata associated to the transfer on UDMG Server. The fields with udmg_ prefix are set internally by UDMG server. The fields with udmg_ue prefix are set by the UDMG File Transfer task.
mft_transfer.transfer_info.udmg_ue_task_uuid Introduced in version 1.2.0	arraystring	List of errors for the child transfers.

An example of the Extension Output for an single download from SFTP is presented below.

...

The UUID of the UDMG File Transfer task. It can be used to easily correlate the UC task executions and the corresponding UDMG file transfers.
mft_transfer.transfer_info.udmg_xfer_wildcard Introduced in version 1.2.0	boolean	Indicator that this is a wildcard transfer. Only for MPUT and MGET.
mft_transfer.transfer_info.udmg_xfer_cmd Introduced in version 1.3.0	string	'`list`' is and indicator that this is a wildcard list command. Only for LIST.
mft_transfer.transfer_info.udmg_xfer_childIDs Introduced in version 1.2.0	array	A list of UDMG transfer IDs that are created in the context of this file file transfer. For each file matched the filename input, one file transfer process is created in UDMG. Only for MPUT and MGET.
mft_transfer.transfer_info.udmg_xfer_files Introduced in version 1.2.0	array	The list of files that matched the user input. Each of these files is transferred with a separate file transfer execution, which transfer ids can be found in “udmg_xfer_childIDs“ list. Only for MPUT and MGET.
mft_transfer_files_summary Introduced in version 1.2.0	object	Summary counters
mft_transfer_files_summary.done	number	Number of file transfers with success.
mft_transfer_files_summary.error	number	Number of file transfers in error state.
mft_transfer_files_summary.cancelled	number	Number of file transfers that are cancelled.
errors Introduced in version 1.2.0	array	List of errors for the child transfers.

An example of the Extension Output for an single download from SFTP is presented below.

Expand

Code Block

{
    "exit_code": 0,
    "status_description": "Task executed successfully",
    "invocation": {
        "fields": {
         "mft_transfer   "credentials_user": {"admin",
            "transfercredentials_idpassword": "478****",
            "startaction": "2023-05-11 10:04:36.433385+00:00GET",
            "stopprotocol": "2023-05-11 10:04:40.908049+00:00sftp",
            "statusmft_server": "DONEhttp://udmg.stonebranch.com:8080/api",
            "stepfile": "StepNonereadme.txt",
            "transfer_progressoutput": "405  Bytes"null,
            "task_numberpartner": null"rebex",
            "error_coderule": "TeOkrebex_receive_example",
            "error_msguser": null"demo",
            "localwait_for_filecompletion": "/data/in/readme.txt"true,
            "remotetransfer_filedate": "/pub/example/readme.txt"null,
            "transferpolling_uuidinterval": "1656601189657083904"5,
            "transfer_infomax_file_to_monitor": {
 100,
              "udmgue_filetask_computed_extensionuuid": ".txt16835525405027449004GAT04TVODUWH",
        }
    },
  "udmg_file_computed_mimetype  "result": "text/plain; charset=utf-8",{
          "mft_transfer": {
            "udmg_sftp_client_versiontransfer_id": "SSH-2.0-Go478",
            "start":    "udmg_sftp_config_ciphers": ["2023-05-11 10:04:36.433385+00:00",
            "stop": "2023-05-11 10:04:40.908049+00:00",
      "aes128-gcm@openssh.com",      "status": "DONE",
            "step": "chacha20-poly1305@openssh.comStepNone",
            "transfer_progress": "405  Bytes",
     "aes128-ctr",       "task_number": null,
            "aes192-ctrerror_code": "TeOk",
            "error_msg": null,
      "aes256-ctr"      "local_file": "/data/in/readme.txt",
         ],   "remote_file": "/pub/example/readme.txt",
            "udmg_sftp_config_kextransfer_uuid": ["1656601189657083904",
            "transfer_info": {
        "curve25519-sha256@libssh.org        "udmg_file_computed_extension": ".txt",
                "udmg_file_computed_mimetype":    "ecdh-sha2-nistp256"text/plain; charset=utf-8",
                   "udmg_sftp_client_version": "ecdhSSH-sha22.0-nistp384Go",

                   "ecdh-sha2-nistp521","udmg_sftp_config_ciphers": [
                    "diffie-hellman-group-exchange-sha256aes128-gcm@openssh.com",
                    "diffie-hellman-group1-sha1chacha20-poly1305@openssh.com",
                    "aes128-ctr",
                    "diffie-hellman-group14-sha1aes192-ctr",
                    "aes256-ctr"
                ],
                "udmg_sftp_config_mackex": [
                    "hmac-sha2-256-etm@openssh.comcurve25519-sha256@libssh.org",
                    "hmacecdh-sha2-256nistp256",
                    "hmacecdh-sha2-sha1nistp384",
                    "hmacecdh-sha1sha2-96nistp521",
                   ], "diffie-hellman-group-exchange-sha256",
                  "udmg_sftp_failed_auth_methods": [  "diffie-hellman-group1-sha1",
                     "none"diffie-hellman-group14-sha1"
                ],
                "udmg_sftp_hostkeyconfig_algomac": "ssh-rsa", [
                   "udmg_sftp_kex_algo": "curve25519-sha256@libssh.org",hmac-sha2-256-etm@openssh.com",
                   "udmg_sftp_read_algos": { "hmac-sha2-256",
                     "cipher": "aes128-gcm@openssh.com"hmac-sha1",
                    "compressionhmac-sha1-96":
"none",                ],
    "mac": ""            "udmg_sftp_failed_auth_methods": [
                 }   "none"
                ],
                "udmg_sftp_serverhostkey_versionalgo": "SSH-2.0-RebexSSH_5.0.8466.0ssh-rsa",
                "udmg_sftp_sucessfulkex_auth_methodsalgo": "passwordcurve25519-sha256@libssh.org",
                "udmg_sftp_writeread_algos": {
                    "cipher": "aes128-gcm@openssh.com",
                    "compression": "none",
                    "mac": ""
                },
                "udmg_uesftp_taskserver_uuidversion": "16835525405027449004GAT04TVODUWHSSH-2.0-RebexSSH_5.0.8466.0",
                "udmg_sftp_xfersucessful_logauth_methods": "/config/logs/478.log"password",
                } "udmg_sftp_write_algos": {
           },         "mft_transfer_files_summary": {cipher": "aes128-gcm@openssh.com",
                    "donecompression": 1,"none",
                    "errormac": ""
0,              "cancelled": 0 },
       },         "errorsudmg_ue_task_uuid": []"16835525405027449004GAT04TVODUWH",
      } }

An example of the Extension Output for an wildcard download from SFTP with 3 matching files is presented below.

Expand

Code Block

{     "exit_code": 0,
    "statusudmg_xfer_descriptionlog": "Task executed successfully",/config/logs/478.log"
      "invocation": {     }
   "fields": {    },
        "credentials_usermft_transfer_files_summary": "admin",{
            "credentials_passworddone": "****"1,
            "actionerror": "MGET"0,
            "protocolcancelled": "sftp",0
        },
    "mft_server": "http://udmg.stonebranch.com:8080/api",
    "errors": []
      }
}

An example of the Extension Output for an wildcard download from SFTP with 3 matching files is presented below.

Expand

Code Block

{
    "fileexit_code": "m*.png"0,
    "status_description": "Task executed successfully",
    "outputinvocation": null,
 {
          "partnerfields": "rebex",{
            "rulecredentials_user": "rebex_receive_exampleadmin",
            "usercredentials_password": "demo****",
            "wait_for_completionaction": true"MGET",
            "transfer_dateprotocol": null"sftp",
            "pollingmft_intervalserver": 5"http://udmg.stonebranch.com:8080/api",
            "max_file_to_monitor": 100"m*.png",
            "ue_task_uuidoutput": "168355254050277290080KCA7YT971DJ"null,
        }     }"partner": "rebex",
    "result": {        "rule": "mftrebex_receive_transferexample":,
{             "transfer_iduser": "479demo",
            "startwait_for_completion": "2023-05-11 10:44:30.493303+00:00",true,
            "stoptransfer_date": "2023-05-11 10:44:31.144255+00:00"null,
            "statuspolling_interval": "DONE"5,
            "stepmax_file_to_monitor": "StepNone"100,
            "transferue_task_progressuuid": "3 out of 3 files","168355254050277290080KCA7YT971DJ"
        }
    },
    "result": {
        "taskmft_numbertransfer": null,{
            "errortransfer_codeid": "TeOk479",
            "error_msgstart": null "2023-05-11 10:44:30.493303+00:00",
            "local_filestop": "/data/in/m*.png2023-05-11 10:44:31.144255+00:00",
            "remote_filestatus": "/pub/example/m*.pngDONE",
            "transfer_uuidstep": "1656611231072518144StepNone",
            "transfer_infoprogress": {"3 out of 3 files",
            "udmg_sftp_client_versiontask_number": "SSH-2.0-Go"null,
            "error_code": "TeOk",
  "udmg_sftp_config_ciphers": [          "error_msg": null,
             "aes128-gcm@openssh.com"local_file": "/data/in/m*.png",
            "remote_file": "/pub/example/m*.png",
      "chacha20-poly1305@openssh.com",        "transfer_uuid": "1656611231072518144",
            "aes128-ctr",
transfer_info": {
                   "aes192-ctr",
 "udmg_sftp_client_version": "SSH-2.0-Go",
                  "aes256-ctr""udmg_sftp_config_ciphers": [
                    ]"aes128-gcm@openssh.com",
                "udmg_sftp_config_kex": [    "chacha20-poly1305@openssh.com",
                    "curve25519aes128-sha256@libssh.orgctr",
                    "ecdhaes192-sha2-nistp256ctr",
                    "ecdhaes256-sha2-nistp384ctr",
                    "ecdh-sha2-nistp521",
  ],
                 "diffie-hellman-group-exchange-sha256","udmg_sftp_config_kex": [
                    "diffie-hellman-group1-sha1curve25519-sha256@libssh.org",
                    "diffieecdh-hellmansha2-group14-sha1"
            nistp256",
   ],                 "udmg_sftp_config_mac": [ecdh-sha2-nistp384",
                     "hmacecdh-sha2-256-etm@openssh.comnistp521",
                    "hmac-sha2-256diffie-hellman-group-exchange-sha256",
                    "hmacdiffie-hellman-group1-sha1",
                    "hmacdiffie-hellman-group14-sha1-96"
                ],
                "udmg_sftp_failedconfig_auth_methodsmac": [
                    "none"hmac-sha2-256-etm@openssh.com",
                    ]"hmac-sha2-256",
                "udmg_sftp_hostkey_algo": "ssh-rsa",    "hmac-sha1",
                   "udmg_sftp_kex_algo": "curve25519-sha256@libssh.org",hmac-sha1-96"
                "udmg_sftp_read_algos": {],
                     "cipher": "aes128-gcm@openssh.com",
"udmg_sftp_failed_auth_methods": [
                   "compression": "none",
                ],
   "mac": ""                 }"udmg_sftp_hostkey_algo": "ssh-rsa",
                "udmg_sftp_serverkex_versionalgo": "SSHcurve25519-2.0-RebexSSH_5.0.8466.0sha256@libssh.org",
                "udmg_sftp_sucessful_auth_methods": "password",
                "udmg_sftp_write_read_algos": {
                    "cipher": "aes128-gcm@openssh.com",
                    "compression": "none",
                    "mac": ""
                },
                "udmg_uesftp_taskserver_uuidversion": "168355254050277290080KCA7YT971DJSSH-2.0-RebexSSH_5.0.8466.0",
                "udmg_sftp_sucessful_xferauth_childIDsmethods": ["password",
                "udmg_sftp_write_algos": {
  480,                     481"cipher": "aes128-gcm@openssh.com",
                    "compression": "none",
482                 ],   "mac": ""
            "udmg_xfer_files": [   },
                "udmg_ue_task_uuid": "mail-editor.png168355254050277290080KCA7YT971DJ",
                    "mail-send-winforms.png",
"udmg_xfer_childIDs": [
                   "mime-explorer.png"
 480,
               ],     481,
           "udmg_xfer_log": "/config/logs/479.log",        482
        "udmg_xfer_wildcard": true       ],
      }         },
  "udmg_xfer_files": [
      "mft_transfer_files_summary": {             "done": 3,mail-editor.png",
                    "error": 0,mail-send-winforms.png",
                    "cancelled": 0mime-explorer.png"
                }],
        "errors": []        "udmg_xfer_log": "/config/logs/479.log",
      }
}

STDOUT and STDERR

STDERR provides additional information to User about the task instance execution. Verbosity is increased with the Task Log Level, The Debug level can lead to extensive details and is only recommended for troubleshooting.

The populated content can be changed in future versions of this extension without notice. Backward compatibility is not guaranteed.

STDOUT provides a summary report of the child file transfers for a wildcard transfer (only for MPUT and MGET, and only if Wait For Transfer Completion is set). Backward compatibility is not guaranteed.

...

The current status of the transfer
One of PLANNED, RUNNING, PAUSED, INTERRUPTED, DONE, CANCELLLED or ERROR

...

The date and time the transfer has ended (UDMG Server time)

...

step

...

An example of the STDOUT for an wildcard download from SFTP with 3 matching files is presented below.

Expand

Code Block
id status localFilepath start "udmg_xfer_wildcard": true } }, "mft_transfer_files_summary": { "done": 3, "error": 0, "cancelled": 0 }, "errors": [] } }

An example of the Extension Output for an wildcard list from SFTP with 2 matching files is presented below.

Expand

Code Block

{
    "exit_code": 0,
    "status": "SUCCESS",    
    "status_description": "SUCCESS",
    "invocation": {
        "fields": { ... }
    },
    "result": {
        "mft_transfer": {
            "transfer_id": "145",
            "start": "2023-05-26T12:36:36.405685+00:00",
            "stop": "2023-05-26T12:36:37.022167",
            "status": "DONE",
            "step": "StepNone",
            "progress": 2,
            "task_number": null,
            "error_code": "TeOk",
            "error_msg": null,
            "local_file": "/home/udmg/udmg-server/in/wince*.png",
            "remote_file": "/pub/example/wince*.png",
            "transfer_uuid": "1662075259576123392",
            "transfer_info": {
                "udmg_sftp_hostkey_algo": "ssh-rsa",
                "udmg_sftp_kex_algo": "curve25519-sha256@libssh.org",
                "udmg_sftp_read_algos": {
                    "cipher": "aes128-gcm@openssh.com",
                    "compression": "none",
                    "mac": ""
                },
                "udmg_sftp_server_version": "SSH-2.0-RebexSSH_5.0.8466.0",
                "udmg_sftp_sucessful_auth_methods": "password",
                "udmg_sftp_write_algos": {
                    "cipher": "aes128-gcm@openssh.com",
                    "compression": "none",
                    "mac": ""
                },
                "udmg_xfer_files": [
					"winceclient.png",
					"winceclientSmall.png"
                ],                
                "udmg_xfer_log": "/home/mft-user/waarp/log/145.log",
                "udmg_xfer_wildcard": true,
                "udmg_xfer_cmd": "list",
                "udmg_ue_task_uuid": "8a801e6d164c4648a32f94dbcd1bb19a"
            }
        }
    }
}

STDOUT and STDERR

Note

title	Note

STDOUT and STDERR provide additional information for the user. The populated content can be changed in future versions of this extension without notice. Backward compatibility is not guaranteed.

More structured information can be retrieved from the EXTENSION output.

STDERR provides additional information to User about the task instance execution. Verbosity is increased with the Task Log Level, The Debug and Trace levels can lead to extensive details and is only recommended for troubleshooting.

STDOUT provides a summary report for the wildcard transfers, but only if Wait For Transfer Completion is set.

For MPUT and MGET actions, the list of the child file transfers with the following details.

Field	Description
id	The identifier of the transfer on UDMG
status	The current status of the transfer One of PLANNED, RUNNING, PAUSED, INTERRUPTED, DONE, CANCELLLED or ERROR
localFilepath	The path of the file on the local disk
start	The date and time the transfer has started (UDMG Server time)
stop	The date and time the transfer has ended (UDMG Server time)
filesize	The size of file in byte (or -1 when unknown)
progress	The progress of the data transfer in bytes
remoteID	The UUID of the transfer on UDMG
errorCode	The UDMG transfer error code.
errorMessage	The error message (if an error occurred)
step	The current processing step of the transfer One of NONE, PRE TASKS, DATA, POST TASKS, ERROR TASKS or FINALIZATION
taskNumber	The number of the task in the processing step. Only for the Transfer Steps 'PRE TASKS', 'POST TASKS', and 'ERROR TASKS'
remoteFilepath	The path to the file on the remote partner
rule	The name of the transfer rule
isSend	Indicates whether the transfer is a send (true) or a receive (false)
requested	The name of the server/partner that requested the transfer
requester	The name of the account that requested the transfer

An example of the STDOUT for an wildcard download from SFTP with 3 matching files is presented below.

Expand

Code Block

  id  status    localFilepath                    start                             stop                                filesize    progress             remoteID  errorCode    errorMsg    step      taskNumber    remoteFilepath                       rule                   isSend    requested    requester
----  --------  -------------------------------  --------------------------------  --------------------------------  ----------  ----------  -------------------  -----------  ----------  --------  ------------  -----------------------------------  ---------------------  --------  -----------  -----------
 480  DONE      /data/in/mail-editor.png         2023-05-11 10:44:30.493303+00:00  2023-05-11 10:44:40.853704+00:00       16471       16471 stop 1656611233584906240  TeOk                     StepNone        filesize    progress    /pub/example/mail-editor.png         remoteIDrebex_receive_example  errorCodeFalse    errorMsg rebex   step     demo
taskNumber 481  DONE remoteFilepath             /data/in/mail-send-winforms.png  2023-05-11 10:44:30.493303+00:00  2023-05-11 10:44:50.856191+00:00       35414   rule    35414  1656611233622654976  TeOk           isSend    requested    requester ----  --------  -------------------------------  --------------------------------  --------------------------------  ----------  ----------  -------------------  -----------  ----------  --------  ------------  -----------------------------------  ---------------------  --------  -----------  -----------
 480StepNone                /pub/example/mail-send-winforms.png  rebex_receive_example  False     rebex        demo
 482  DONE      /data/in/mailmime-editorexplorer.png         2023-05-11 10:44:30.493303+00:00  2023-05-11 10:4445:4000.853704860761+00:00       1647149011       1647149011  16566112335849062401656611233656209408  TeOk                     StepNone                /pub/example/example/mail-editor.png         rebex_receive_example  False     rebex        demo
 481  DONE      /data/in/mail-send-winforms.png  2023-05-11 10:44:30.493303+00:00  2023-05-11 10:44:50.856191+00:00       35414       35414  1656611233622654976  TeOk                     StepNone                /pub/example/mail-send-winforms.png  rebex_receive_example  False     rebex        demo
 482  DONE      /data/in/mime-explorer.png       2023-05-11 10:44:30.493303+00:00  2023-05-11 10:45:00.860761+00:00       49011       49011  1656611233656209408  TeOk                     StepNone                /pub/example/mime-explorer.png       rebex_receive_example  False     rebex        demo

Integration Modifications

Modifications applied by users or customers, before or after import, might affect the supportability of this integration. The following modifications are discouraged to retain the support level as applied for this integration.

...

General Section

"Name", "Extension", "Variable Prefix", "Icon" should not be changed.

...

Universal Template Details Section

"Template Type", "Agent Type", "Send Extension Variables", "Always Cancel on Force Finish" should not be changed.

...

Result Processing Defaults Section

Success and Failure Exit codes should not be changed.
Success and Failure Output processing should not be changed.

Fields Restriction Section
The setup of the template does not impose any restrictions, However with respect to "Exit Code Processing Fields" section.

Success/Failure exit codes need to be respected.
In principle, as STDERR and STDOUT outputs can change in follow-up releases of this integration, they should not be considered as a reliable source for determining success or failure of a task.

Users and customers are encouraged to report defects, or feature requests at Stonebranch Support Desk.

Document References

This document references the following documents.

...

mime-explorer.png       rebex_receive_example  False     rebex        demo

For a LIST action, the list of matching files is presented:

Field	Description
Filename	The name of a file on the remote path that matched with the wildcard pattern.

An example of the STDOUT for an wildcard list from SFTP with 2 matching files is presented below.

Expand

Code Block
Filename ------------------------------------------------ winceclient.png winceclientSmall.png

Integration Modifications

Modifications applied by users or customers, before or after import, might affect the supportability of this integration. The following modifications are discouraged to retain the support level as applied for this integration.

Python code modifications should not be done.
Template Modifications
- General Section
  - "Name", "Extension", "Variable Prefix", "Icon" should not be changed.
- Universal Template Details Section
  - "Template Type", "Agent Type", "Send Extension Variables", "Always Cancel on Force Finish" should not be changed.
- Result Processing Defaults Section
  - Success and Failure Exit codes should not be changed.
  - Success and Failure Output processing should not be changed.
- Fields Restriction Section
  The setup of the template does not impose any restrictions, However with respect to "Exit Code Processing Fields" section.
  1. Success/Failure exit codes need to be respected.
  2. In principle, as STDERR and STDOUT outputs can change in follow-up releases of this integration, they should not be considered as a reliable source for determining success or failure of a task.

Users and customers are encouraged to report defects, or feature requests at Stonebranch Support Desk.

Document References

This document references the following documents.

Document Link	Description
Universal Templates	User documentation for creating, working with and understanding Universal Templates and Integrations.
Universal Tasks	User documentation for creating Universal Tasks in the Universal Controller user interface.
Credentials	User documentation for creating and working with credentials.
Resolvable Credentials Permitted Property	User documentation for Resolvable Credentials Permitted Property.

Anchor

	Changelog
	Changelog

Changelog

ue-mft-transfer-1.3.0 (2023-09-29)

Deprecations and Breaking Changes

Breaking Change: "Polling Interval" minimum value is set to 1, a value of 0 could cause an infinite loop (#33815).

Enhancements

Added: new LIST action to retrieve the names of the files matching a wildcard pattern on a remote SFTP partner (#33358).
Added: Logging of dynamic command processing in the agent log with TRACE level (#32993).
Added: MGET/MPUT: error is raised when monitoring of child transfers is skipped because the list is greater than "Max Files To Monitor": CHILD_TRANSFERS_NOT_MONITORED_WARNING with exit code 90 (#33065).
Added: Support for throttling the MGET/MPUT monitoring with the environment variable UDMG_CLIENT_MAX_THROTTLE_RATE. It sets the maximum number of calls per second to the UDMG API during the monitoring phase. Default is 60 (#33432).
Changed: "Target File" only visible for GET & PUT actions (#33367).
Changed: After a dynamic command, the extension will terminate immediately if the transfer is already completed (#32989).
Changed: "Polling Interval" field is always visible, as it is still used to check for parent transfer completion (#32994).
Changed: MGET/MPUT: "Transfer Progress" is only updated when a child transfer is completed (DONE, ERROR, CANCELLED) (#33815).
Changed: Sorting of the "Action" list (#33064).

Fixes

Fixed: Exit code to be 11 in case of 404 API errors (#28881).
Fixed: Extension finishes successfully after unexpected transfer CANCELLED status (#29248).
Fixed: Fix Task Cancel to also process child transfers that are in ERROR status (#33804).
Fixed: Proper catching of UDMG API errors during wildcard transfer monitoring (#33310).

ue-mft-transfer-1.2.0 (2023-05-09)

Deprecations and Breaking Changes

Breaking Change: Transfer Progress output only field is changed to text value (#32195)

Enhancements

Add: Support Wildcard Transfer (#32198, #32195, #32201)
1. New actions "MPUT" and "MGET" for wildcard transfers:
  - support for wildcard in source file parameter,
  - creation of wildcard transfer on UDMG,
  - monitoring of child transfers on UDMG,
  - tabular report on STDOUT with final child transfer status,
  - short summary report in EXTENSION output,
  - PAUSE, RESUME, and CANCEL commands are propagated to child transfers
2. "Transfer Progress" output field is redefined to show human readable value
  - size in KB, MB, or GB for single transfer,
  - "x out of y files" for wildcard transfer
3. "Max files to monitor" parameter: limit the number of child transfers that are monitored by the task instances, 100 by default.
4. "Wait for transfer completion" parameter: task instance only returns when the transfer is completed (with DONE or CANCELLED status) on UDMG.
  For wildcard transfers, only returns when all child transfers are completed. Activated by default.
Add: Refresh task instance output with re-run (#32463)
Add: Keep UC task instance ID in UDMG file transfer metadata field udmg_ue_task_uuid (#30931)

ue-mft-transfer-1.1.0 (2023-01-31)

Deprecations and Breaking Changes

Breaking Change: minimum universal agent version set to 7.3

Enhancements

Add: set target filename (rename file) (#31174)
Add: transfer status as UC 7.3 extension status field. (#31041)
Add: retry failed transfer with Task Re-run. (#29599)
Add: show UUID. (#30733)
Add: show transfer info fields. (#30930)
Add: support for PeSIT and PeSIT-TLS protocols (#31051)

Fixes

Fix: optimize number of API calls. (#29247)

...

Page Comparison

Versions Compared

Old Version 1

New Version Current

Key

Software Requirements for Universal Template and Universal Task

Software Requirements for Universal Agent

Import Universal Template

Configure Universal Task

MGET files from a remote SFTP server

LIST files on a remote SFTP server

Task Execution

Cancelation

Task Output

Output Only Fields

UDMG Transfer Error Code

Exit Codes

Re-Run

Task Output

Output Only Fields

UDMG Transfer Error Code

Exit Codes

Extension Output

Extension Output

STDOUT and STDERR

STDOUT and STDERR

Integration Modifications

Document References

Integration Modifications

Document References

Changelog

ue-mft-transfer-1.3.0 (2023-09-29)

Deprecations and Breaking Changes

Enhancements

Fixes

ue-mft-transfer-1.2.0 (2023-05-09)

Deprecations and Breaking Changes

Enhancements

ue-mft-transfer-1.1.0 (2023-01-31)

Deprecations and Breaking Changes

Enhancements

Fixes