Universal Event Integration

Owned by Stonebranch (Deactivated)
Last updated: Oct 08, 2024 by Katie Murphy
19 min read


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 file processing or further actions concerning 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 happens.
  • "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.

Recommendation

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:

NameLabelType
truefilenameactual name of the file on the diskText
fullpathoriginal path of the file before the transferText
truefullpathactual path of the file on the diskText
datedate (in format AAAAMMJJ) when the transfer was executedText
sizefilesizeFloat
requestedhostidentifier of the partner who received the transfer requestText
requesterhostidentifier of the partner who requested the transferText
localhostlocal partnerText
filenameoriginal name of the file before the transferText
remotehostremote partnerText
rulerule used by the transferText
hourtime (in format HHMMSS) at the time of the execution of the transferText
transferidtransfer IDText
errormsgerror messageText
errorcodeerror codeText

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

 Web Service Example
Curl Request
curl -L -X POST 'http://host_name/uc/resources/universaleventtemplate' \
-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 are 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 errors. 

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:

NameLabelType
truefilenameactual name of the file on the diskText
fullpathoriginal path of the file before the transferText
truefullpathactual path of the file on the diskText
datedate (in format AAAAMMJJ) when the transfer was executedText
sizefilesizeFloat
requestedhostidentifier of the partner who received the transfer requestText
requesterhostidentifier of the partner who requested the transferText
localhostlocal partnerText
filenameoriginal name of the file before the transferText
remotehostremote partnerText
rulerule used by the transferText
hourtime (in format HHMMSS) at the time of the execution of the transferText
transferidtransfer IDText
errormsgerror messageText
errorcodeerror codeText

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

 Web Service Example
Curl Request
curl -L -X POST 'http://host_name/uc/resources/universaleventtemplate' \
-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 are 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 UDMG-Client.

The task is configured for every transfer rule for which it 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 shows the list of parameters that are accepted by the PUBLISHEVENT task. Except for the path, they are passed as attributes to the Universal Event.

For the other parameter, the related placeholder variable must be used, see the section below.

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"

ruleThe rule used by the transfer.
dateThe date (in format AAAAMMJJ) when the transfer task was executed.
hourThe time (in format HHMMSS) at the time of the execution of the transfer task.
filesizeFile size (as string).
inpathThe path to the receiving folder for the current transfer. This path depends on the configuration (folder for sending the rule, the server, or the udmg-server instance 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 udmg-server instance depending on the case).
trueFullPath

The actual path of the file on the disk.

trueFilenameThe actual name of the file on the disk.
fullPathThe original path of the file before the transfer.
filenameThe original name of the file before the transfer.
remoteHostThe identifier of the remote partner.
localHostThe identifier of the local partner.
transferIDThe transfer ID.
requesterHostThe identifier of the partner who requested the transfer.
requestedHostThe identifier of the partner who received the transfer request.
sizeFile size (as number).
errorcodeError Code (only for error situations).
errormsgError Message (only for error situations).

Placeholders for substitution in UDMG task definition

PlaceholderDescription
#TRUEFULLPATH#The actual path of the file on disk may differ from the original path if the file has been renamed or moved by a UDMG task. 
#TRUEFILENAME#The actual name of the file on disk. It may differ from the original path if the file has been renamed or moved by a UDMG task.
#ORIGINALFULLPATH#The original path of the file before transfer.
#ORIGINALFILENAME#The original name of the file before transfer.
#FILESIZE#File size (value in bytes).
#HOMEPATH#The root folder of the udmg-server . This path is always absolute.
#INPATH#The default receiving folder is defined in the configuration file. This path is always absolute.
#OUTPATH#The default upload folder is defined in the configuration file. This path is always absolute.
#WORKPATH#The default temporary receiving folder is defined in the configuration file. This path is always absolute.
#RULE#The rule used by the transfer.
#DATE#The date (in format YYYYMMDD) when the transfer was executed.
#HOUR#The time (in format HHMMSS) when the transfer was executed.
#REMOTEHOST#The remote partner identifier. The Shared Account login for a server transfer, and the Remote Partner name for a client transfer.
#LOCALHOST#The local partner identifier. The Local Server name for a server transfer, the Remote Account login for a client transfer.
#TRANSFERID#The transfer ID.
#REQUESTERHOST#The partner who requested the transfer. The Shared Account login is for a server transfer, and the Remote Account login for a client transfer.
#REQUESTEDHOST#The partner who received the transfer request. The Local Server name is for a server transfer, and the Remote Partner name for a client transfer.
#FULLTRANSFERID#An "extended" identifier for transfer (in the form TRANSFERID_REQUESTERHOST_REQUESTEDHOST).
#ERRORMSG#Error message (in error handling).
#ERRORCODE#Error code (in error handling).


In addition to these standard placeholders, it is also possible to reference the transfer information key in the definition of a task. To do this, use is the following:

#TI_<key_name># where <key_name>is replaced with the name of the desired key.

At runtime, it will then be substituted by the value associated with the key. For instance #TI_udmg_xfer_log# to get the path of the UDMG transfer log file.

Universal Controller API Configuration Files

The configuration file is set at the task level and specifies that the Universal Event Template and the Universal Control URL are used for publishing 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 the usage of different Universal Event Templates 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

UACEventUrl

This specifies where the Event will be published.

It is the URI of the Publish Universal Event API on the target Universal Controller

UACEventNameUniversal Event Template Name.
UACEventTTLUniversal 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 to call the Universal Event Web Services.

UACEventPasswordPassword to access the Universal Controller REST API.

Configuration Files Examples

UsageINI 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 must have the PUBLISHEVENT task in the list of Post-Tasks. It is enough to have only this task.

Note

The configuration for Pre-Task, Post-Task, and Error-Task is under the Rule tab.



 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#",
            "errorCode": "#ERRORCODE#",
            "errorMsg": "#ERRORMSG#"
        }
    }
]

Configuration of an Error Task for a UDMG Rule

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

Note

The configuration for Pre-Task, Post-Task, and Error-Task is under the Rule tab. 


 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 Universal Monitor task and select the Universal Event Template 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 inferred from the transfer rule name, provided that a consistent naming convention is used.


Configuration of Universal Monitor Trigger for UDMG File Transfer Event


Info

Refer to Creating a Universal Monitor Trigger.

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

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

The variable name is formed using 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: