Overview

Each time a file transfer action occurs on the UDMG server a Universal Event can be generated. This event can be used to trigger a Universal Monitor Task for the processing of the file or for further actions in relation to this transfer.

The event can be published before, after, or in case of an error for a file transfer.

"Before a file transfer", means during the initialization phase of the transfer, before the data transmission of the file content is happening.
"After a file transfer", means after the successful completion of the transfer.
"In case of error", means when a transfer has failed, the error details can be added to the event attributes.

It is recommended to configure events for successful and error conditions.

Creating a Universal Event Template for UDMG File Transfer

Info

Refer to Universal Controller documentation: Creating a Universal Event Template.

The following table shows an example of a Universal Event Template for file transfer.

The attributes are populated by UDMG when the Universal Event is published on the Universal Controller. It is possible to create different templates that can be triggered for different transfer scenarios on UDMG. Each type of event can then be monitored and intercepted differently on the Universal controller.

Field Name

Sample Value and Description

Name

b2bmft

Label

UAC User Event: UDMG transfer

Description

Event for when a file is transferred by UDMG server

Time To Live

60000

Default value for the length of time, in minutes, that the Universal Event data is valid. This value can be unspecified (null).

The Time To Live value can be overridden in the published event.

The value can be tuned depending on business or operational requirements.

Unmapped Attributes Policy

Include Attributes
Any extra attributes will be allowed and passed through as variables.

Attributes

Add the following attributes:

Name	Label	Type
`truefilename`	actual name of the file on the disk	Text
`fullpath`	original path of the file before the transfer	Text
`truefullpath`	actual path of the file on the disk	Text
`date`	date (in format AAAAMMJJ) when the transfer was executed	Text
`size`	filesize	Float
`requestedhost`	identifier of the partner who received the transfer request	Text
`requesterhost`	identifier of the partner who requested the transfer	Text
`localhost`	local partner	Text
`filename`	original name of the file before the transfer	Text
`remotehost`	remote partner	Text
`rule`	rule used by the transfer	Text
`hour`	time (in format HHMMSS) at the time of the execution of the transfer	Text
`transferid`	transfer ID	Text

The template can also be created with the Universal Template Web Services.

Web Service Example

Curl Request

curl -L -X POST 'http://host_name/uc/resources/universaltemplate' \
-H 'Content-Type: application/json' -H 'Accept: application/json' \
--data-raw '{
        "attributesPolicy": "Include Attributes",
        "description": "Event for when a file is transferred by UDMG server",
        "label": "UAC User Event: UDMG transfer",
        "name": "b2bmft",
        "ttl": 60000,
        "attributes": [
            {
                "label": "actual name of the file on the disk",
                "name": "truefilename",
                "type": "Text"
            },
            {
                "label": "original path of the file before the transfer",
                "name": "fullpath",
                "type": "Text"
            },
            {
                "label": "actual path of the file on the disk",
                "name": "truefullpath",
                "type": "Text"
            },
            {
                "label": "date (in format AAAAMMJJ) when the transfer was executed",
                "name": "date",
                "type": "Text"
            },
            {
                "label": "filesize",
                "name": "size",
                "type": "Float"
            },
            {
                "label": "identifier of the partner who received the transfer request",
                "name": "requestedhost",
                "type": "Text"
            },
            {
                "label": "identifier of the partner who requested the transfer",
                "name": "requesterhost",
                "type": "Text"
            },
            {
                "label": "local partner",
                "name": "localhost",
                "type": "Text"
            },
            {
                "label": "original name of the file before the transfer",
                "name": "filename",
                "type": "Text"
            },
            {
                "label": "remote partner",
                "name": "remotehost",
                "type": "Text"
            },
            {
                "label": "rule used by the transfer",
                "name": "rule",
                "type": "Text"
            },
            {
                "label": "time (in format HHMMSS) at the time of the execution of the transfer",
                "name": "hour",
                "type": "Text"
            },
            {
                "label": "transfer ID",
                "name": "transferid",
                "type": "Text"
            }
        ]
    }
'

The Universal Event Template Details is shown below.

Creating a Universal Event Template for UDMG File Transfer Error

Info

Refer to Universal Controller documentation: Creating a Universal Event Template.

The following table shows an example of a Universal Event Template for file transfer error.

The attributes are populated by UDMG when the Universal Event is published on the Universal Controller. It is possible to create different templates that can be triggered for different transfer scenarios on UDMG. Each type of event can then be monitored and intercepted differently on the Universal controller.

Field Name

Sample Value and Description

Name

b2bmft_error

Label

UAC User Event: UDMG transfer error

Description

Event for error with file transfer by UDMG server

Time To Live

6000

Default value for the length of time, in minutes, that the Universal Event data is valid. This value can be unspecified (null).

The Time To Live value can be overridden in the published event.

The value can be tuned depending on business or operational requirements.

Unmapped Attributes Policy

Include Attributes
Any extra attributes will be allowed and passed through as variables.

Attributes

Add the following attributes:

Name	Label	Type
`truefilename`	actual name of the file on the disk	Text
`fullpath`	original path of the file before the transfer	Text
`truefullpath`	actual path of the file on the disk	Text
`date`	date (in format AAAAMMJJ) when the transfer was executed	Text
`size`	filesize	Float
`requestedhost`	identifier of the partner who received the transfer request	Text
`requesterhost`	identifier of the partner who requested the transfer	Text
`localhost`	local partner	Text
`filename`	original name of the file before the transfer	Text
`remotehost`	remote partner	Text
`rule`	rule used by the transfer	Text
`hour`	time (in format HHMMSS) at the time of the execution of the transfer	Text
`transferid`	transfer ID	Text
`errormsg`	error message	Text
`errorcode`	error code	Text

The template can also be created with the Universal Template Web Services.

Web Service Example

Curl Request

curl -L -X POST 'http://host_name/uc/resources/universaltemplate' \
-H 'Content-Type: application/json' -H 'Accept: application/json' \
--data-raw '{
        "attributesPolicy": "Include Attributes",
        "description": "Event for error with file transfer by UDMG server",
        "label": "UAC User Event: UDMG transfer error",
        "name": "b2bmft_error",
        "ttl": 6000,
        "attributes": [
            {
                "label": "actual name of the file on the disk",
                "name": "truefilename",
                "type": "Text"
            },
            {
                "label": "original path of the file before the transfer",
                "name": "fullpath",
                "type": "Text"
            },
            {
                "label": "actual path of the file on the disk",
                "name": "truefullpath",
                "type": "Text"
            },
            {
                "label": "date (in format AAAAMMJJ) when the transfer was executed",
                "name": "date",
                "type": "Text"
            },
            {
                "label": "filesize",
                "name": "size",
                "type": "Float"
            },
            {
                "label": "identifier of the partner who received the transfer request",
                "name": "requestedhost",
                "type": "Text"
            },
            {
                "label": "identifier of the partner who requested the transfer",
                "name": "requesterhost",
                "type": "Text"
            },
            {
                "label": "local partner",
                "name": "localhost",
                "type": "Text"
            },
            {
                "label": "original name of the file before the transfer",
                "name": "filename",
                "type": "Text"
            },
            {
                "label": "remote partner",
                "name": "remotehost",
                "type": "Text"
            },
            {
                "label": "rule used by the transfer",
                "name": "rule",
                "type": "Text"
            },
            {
                "label": "time (in format HHMMSS) at the time of the execution of the transfer",
                "name": "hour",
                "type": "Text"
            },
            {
                "label": "transfer ID",
                "name": "transferid",
                "type": "Text"
            },
            {
                "label": "error message",
                "name": "errormsg",
                "type": "Text"
            },
            {
                "label": "error code",
                "name": "errorcode",
                "type": "Text"
            }
        ]
    }
'

The Universal Event Template Details is shown below.

Configuring UDMG to Send Events to Universal Controller

PUBLISHEVENT Processing Task

The publishing of Universal Event is enabled with the UDMG processing task PUBLISHEVENT, which is an addition to the standard tasks that are provided by the Waarp Gateway.

The task is configured for every transfer rule for which is is required to have an event on Universal Controller.

The interface with the Universal Controller is through the Universal Event Publishing Web Service.

The table below show the list of parameters that are accepted by the PUBLISHEVENT task. Except for the path, they are passed as attributes to the Universal Event.

Parameter	Description
`path`	Path to the Universal Controller API configuration file. Note This parameter is not passed as an event attribute. Warning For Windows path, the '\' character must be escaped as '\\'. For example, instead of `"C:\DATA\UDMG"`, input `"C:\\DATA\\UDMG"`
`rule`	The rule used by the transfer
`date`	The date (in format AAAAMMJJ) when the transfer task was executed
`hour`	The time (in format HHMMSS) at the time of the execution of the transfer task
`filesize`	File size (as string)
`inpath`	The path to the receiving folder for the current transfer. This path depends on the configuration (folder for sending the rule, the server or the Gateway depending on the case)
`outpath`	The path to the receiving folder for the current transfer. This path depends on the configuration (folder for sending the rule, the server or the Gateway depending on the case)
`trueFullPath`	The actual path of the file on the disk
`trueFilename`	The actual name of the file on the disk
`fullPath`	The original path of the file before the transfer
`filename`	The original name of the file before the transfer
`remoteHost`	The identifier of the remote partner
`localHost`	The identifier of the local partner
`transferID`	The transfer ID
`requesterHost`	The identifier of the partner who requested the transfer
`requestedHost`	The identifier of the partner who received the transfer request
`size`	File size (as number)
`errorcode`	Error Code (only for error situation)
`errormsg`	Error Message (only for error situation)

Universal Controller API Configuration Files

The configuration file is set at the task level and specifies the Universal Event Template and the Universal Control URL to use for the publishing of the event.

Being a parameter of the PUBLISHEVENT task, it can be different for each transfer rule and each use of the task. This allows to use different Universal Event Template for successful (for example b2bmft) and failed (for example b2bmft_error) file transfers.

The file format is INI file.
Section name is the 'uac_rest'.
Comments are prefixed by semi-colon ';'.

Option Name	Description
`EventUrl`	Specify the URL for the Target Universal Controller. This specifies where the Event will be published.
`EventName`	Universal Event Template Name
`EventTTL`	Universal Event Template Time To Live in minutes (optional)
`UACEventUsername`	Name of the user to access the Universal Controller REST API Note The user must have the required permissions for calling the Universal Event Web Services.
`UACEventPassword`	Password to access the Universal Controller REST API

Configuration Files Examples

Usage

INI File

Rule Processing Task for Successful Transfer

Configuration File Example for Successful Transfer

rules.ini

[uac_rest]
; URL for REST API call to UAC
UACEventUrl = 'https://host_name/uc/resources/universalevent/publish'
; REST API credentials
UACEventUsername = user
UACEventPassword = password
; UAC Event Name
UACEventName = 'b2bmft'
; Event TimeToLive in minutes (optional)
UACEventTTL = 60000

Rule Processing Task for Transfer in Error

Configuration File Example for Errored Transfer

error.ini

[uac_rest]
; URL for REST API call to UAC
UACEventUrl = 'https://host_name/uc/resources/universalevent/publish'
; REST API credentials
UACEventUsername = user
UACEventPassword = password
; UAC Event Name
UACEventName = 'b2bmft_error'
; Event TimeToLive in minutes (optional)
UACEventTTL = 6000

Configuration of a Post-Task for a UDMG Rule

To send an event after the completion of the file transfer the rule that is associated with the transfer requires to have the PUBLISHEVENT task in the list of Post-Tasks. It is enough to have only this task.

Example of rule post-tasks configuration

Post-Tasks

[
    {
        "type": "PUBLISHEVENT",
        "args": {
            "path": "/data/rules.ini",
            "rule": "#RULE#",
            "date": "#DATE#",
            "hour": "#HOUR#",
            "filename": "#ORIGINALFILENAME#",
            "filesize": "#FILESIZE#",
            "fullPath": "#ORIGINALFULLPATH#",
            "localHost": "#LOCALHOST#",
            "remoteHost": "#REMOTEHOST#",
            "requestedHost": "#REQUESTEDHOST#",
            "requesterHost": "#REQUESTERHOST#",
            "size": "#FILESIZE#",
            "transferID": "#TRANSFERID#",
            "trueFilename": "#TRUEFILENAME#",
            "trueFullPath": "#TRUEFULLPATH#"
        }
    }
]

Configuration of an Error Task for an UDMG Rule

To send an event after an error occured during a the file transfer, the rule that is associated with the transfer requires to have the PUBLISHEVENT task in the list of Rrror Tasks. It is enough to have only this task.

The parameters for error message and error code are added here.

Example of rule error tasks configuration

Error Tasks

[
    {
        "type": "PUBLISHEVENT",
        "args": {
            "path": "/data/rules.ini",
            "rule": "#RULE#",
            "date": "#DATE#",
            "hour": "#HOUR#",
            "filename": "#ORIGINALFILENAME#",
            "filesize": "#FILESIZE#",
            "fullPath": "#ORIGINALFULLPATH#",
            "localHost": "#LOCALHOST#",
            "remoteHost": "#REMOTEHOST#",
            "requestedHost": "#REQUESTEDHOST#",
            "requesterHost": "#REQUESTERHOST#",
            "size": "#FILESIZE#",
            "transferID": "#TRANSFERID#",
            "trueFilename": "#TRUEFILENAME#",
            "trueFullPath": "#TRUEFULLPATH#"
        }
    }
]

Configuring Universal Controller to Receive Events from UDMG

Configuration of Universal Monitor Task for UDMG File Transfer Event

Info

Refer to Creating a Universal Monitor Task

Create a Univerval Monitor task and select the Universal Event Template that was created for UDMG File Transfer.

Additional criteria can be selected to filter the event, by using the event attributes (which contain the file transfer metadata from UDMG). For example the file transfer direction can be infered from the transfer rule name, provided that a consistent naming convention is in place.

Configuration of Universal Monitor Trigger for UDMG File Transfer Event

Info

Refer to Creating a Universal Monitor Trigger

Create a Univerval Monitor Trigger and select the Universal Monitor Task that was created to filter the events to be caught.

Select one or more task to be triggered for each event. The attributes of the event are passed as variables to the tasks which thus can retrieve the details of the file transfer.

The variable name is formed as ops_trigger + universal template name + event attribute name, for example ops_trigger_b2bmft_filesize for the filesize attribute.

Example of the variables for a Task inside a Workflow that was triggered by a Universal Trigger:

Universal Data Mover Gateway 1.1

Universal Event Integration

Overview

Creating a Universal Event Template for UDMG File Transfer

Creating a Universal Event Template for UDMG File Transfer Error

Configuring UDMG to Send Events to Universal Controller

PUBLISHEVENT Processing Task

Universal Controller API Configuration Files

Configuration Files Examples

Configuration of a Post-Task for a UDMG Rule

Configuration of an Error Task for an UDMG Rule

Configuring Universal Controller to Receive Events from UDMG

Configuration of Universal Monitor Task for UDMG File Transfer Event

Configuration of Universal Monitor Trigger for UDMG File Transfer Event