Universal Event Publishing

Each time a file transfer occurs on UDMG Server, a Publish Event Task can publish a Universal Event to Universal Controller.

These events can then trigger a Universal Monitor task for file processing or other automated actions.

Universal Events can be published at specific Event Types (transfer lifecycle events), depending on how Publish Event Tasks are configured in the Pipeline Workflow.

Flow Overview

The following diagram illustrates how UDMG publishes a Universal Event and how it is processed in Universal Controller.

At a high level, the flow is as follows:

1. A file transfer is executed in UDMG through a Pipeline.
2. The Pipeline's Workflow has Publish Event Tasks assigned to different Event Types (transfer lifecycle events).
3. When a trigger condition is met, the corresponding Publish Event Task is executed.
4. The Publish Event Task publishes a Universal Event to Universal Controller.
5. The event is matched against a Universal Event Template, which defines its structure and attributes.
6. A Universal Monitor task listens for events that match the configured template and optional filtering criteria.
7. A Universal Monitor trigger evaluates the monitored events and initiates one or more downstream tasks.
8. The triggered tasks are executed using the event attributes, which contain file transfer metadata from UDMG.

This flow enables UDMG file transfer activity to be integrated into Universal Controller workflows for monitoring, automation, and further processing.

Configuration Steps

Overview

To set up Universal Event Publishing for UDMG file transfers, you need to complete the following steps:

Step	Description
1	Create a Universal Event Template for UDMG file transfers in Universal Controller. This template defines the structure and attributes of the events that UDMG will publish.
2	Configure UDMG Server to send events to Universal Controller. This involves editing the UDMG Server Configuration File to enable the Universal Controller integration and provide the necessary connection details and default event settings.
3	Create a Publish Event Task in UDMG. This Task will be responsible for publishing events to Universal Controller when specific transfer lifecycle events occur.
4	Create a Pipeline in UDMG and assign the Publish Event Task to the Pipeline Workflow. This will ensure that events are published at the appropriate points during the file transfer process.
5	Create a Universal Monitor task in Universal Controller to handle the events. This Universal Monitor task will listen for events that match the Universal Event Template and can be configured to filter events based on their attributes.
6	Configure a Universal Monitor trigger in Universal Controller to trigger downstream tasks based on the events. This allows you to automate actions in response to file transfer events, such as processing transferred files, sending notifications, or updating records.

1. Create a Universal Event Template for UDMG File Transfers

In Universal Controller, create a Universal Event Template named udmg_transfer so that UDMG file transfer events can be monitored by a Universal Monitor task.

As part of the UDMG installation, a Universal Event Template is provided as ops_unv_event_tmplt_udmg_transfer.xml. This file can be imported into Universal Controller to create a Universal Event Template with the required structure and attributes for UDMG file transfer events.

The file is located in the UDMG installation directory, by default:

Linux

/opt/udmg/etc/samp/ops_unv_event_tmplt_udmg_transfer.xml

Windows

C:\Program Files\Stonebranch\UDMG Server\samp\ops_unv_event_tmplt_udmg_transfer.xml

warning

Re-importing the XML file updates the existing template, overwriting the following properties: Description, TTL, Unmapped Attributes Policy, and Metrics. If you have customized any of these properties, note their values before re-importing so you can restore them afterward.

info

For instructions on creating a Universal Event Template, refer to Universal Controller documentation.

2. Set the Configuration File to Send Events to Universal Controller

In the UDMG Server Configuration File, edit the uac block to enable the Universal Controller integration and provide the required connection details, along with default event settings.

For example:

udmg-server.hcl

uac {
  enable                 = true
  urls                   = ["https://uac.example.com:8443/uac/", "https://uac-backup.example.com:8443/uac/"]
  username               = "udmg_user"
  password               = "secret_password"
  event_name             = "udmg_transfer"
  event_ttl              = "60"
  override_publish_event = true
}

info

If uac.override_publish_event is set to true, the uac.event_name, uac.username, and uac.password values can be overridden by the following Publish Event Task fields: Event Name (Overrides Default), and Event Credentials (Overrides Default).

3. Create a Publish Event Task

In UDMG, create a Publish Event Task by following these steps.

4. Create a Pipeline and Assign the Task

In UDMG, create a new Pipeline by following the steps in the corresponding Pipeline page.

Then, assign the Publish Event Task created in step 3 to the Pipeline Workflow by following these steps.

5. Create a Universal Monitor Task to Handle the Event

In Universal Controller, create a Universal Monitor task and select the Universal Event Template created in step 1.

Optionally, you can define additional filtering criteria based on event attributes, which include file transfer metadata from UDMG (see Event Attributes).

For instructions on creating a Universal Monitor task, refer to Universal Controller documentation.

6. Configure a Universal Monitor Trigger for Further Processing

In Universal Controller, create a Universal Monitor trigger and select the Universal Monitor task created in step 5.

Select one or more tasks to trigger for each event. Event attributes are passed to the triggered tasks as variables, allowing those tasks to access file transfer details.

Variable names use the following format: ops_trigger_<universal_event_template_name>_<event_attribute_name>.

For example, ops_trigger_udmg_transfer_filesize for the filesize attribute, or ops_trigger_udmg_transfer_filename for the filename attribute. For a full list of available attributes, see Event Attributes.

For instructions on creating a Universal Monitor trigger, refer to Universal Controller documentation.

Event Attributes

The udmg_transfer Universal Event Template includes the following attributes. Each attribute is populated with file transfer metadata when an event is published.

When used as trigger variables, attribute names follow the format ops_trigger_udmg_transfer_<attribute_name> (for example, ops_trigger_udmg_transfer_filesize).

Attribute Name	Label	Description
account	Account Login	Login of the Account associated with the session.
domainuuid	Domain UUID	UUID of the Domain.
endpointdst	Endpoint Destination	Name of the Destination Endpoint of the Pipeline.
endpointsrc	Endpoint Source	Name of the Source Endpoint of the Pipeline.
filename	Destination File Name	Filename of the transferred file at the destination (basename of filepath).
filepath	Destination Path	Full path of the transferred file at the destination.
filesize	File Size	Size of the transferred file, in bytes.
icapmessage	ICAP Message	ICAP scan response message. Empty if the file passed without issues.
icapstatus	ICAP Status	ICAP scan result (for example, Passed, Infected, or Flagged). Empty if no ICAP scan was performed.
pipeline	Pipeline	Name of the Pipeline that processed the transfer.
sessionid	Session ID	Session ID of the session during which the transfer occurred.
startedat	Start Time (ISO)	Start time of the transfer in ISO 8601 format.
status	Status	Status of the transfer at the time the event was published.
transferid	Transfer ID	Numeric ID of the transfer record.
transferlocation	Location URI of the UDMG Transfer	API path to the transfer record, in the format /api/v1/domains/{domain}/transfers/info/{id}.
virtualpath	Virtual Path	Virtual Path of the transferred file, as visible to the Account.
transferuuid	Transfer UUID	UUID of the transfer record.
sessionuuid	Session UUID	UUID of the session during which the transfer occurred.
pipelineuuid	Pipeline UUID	UUID of the Pipeline.
progressbytes	Progress Bytes	Number of bytes transferred at the time the event was published.
protocol	Protocol	Protocol used for the transfer session (for example, SFTP or FTPS).
failurereason	Failure Reason	Reason the transfer failed. Populated only for On Error events.
sessionremoteaddr	Session Remote Address	Remote IP address and port of the client, in IP:port format.
domainname	Domain Name	Name of the Domain within which the transfer occurred.
virtualfilename	Virtual Filename	Filename portion of the Virtual Path (basename of virtualpath).
tmpfilepath	Temporary File Path	In-flight path of the file being transferred. During upload events, this is the staging or temporary file path; during completion events, it is the final path.
tmpfilename	Temporary File Name	Filename portion of tmpfilepath.