Signiant Support

13.4 Media Gateway User's Guide Print


Media Gateway Introduction

Media Gateway automates the creation and movement of packages between systems and users. Media Gateway enables administrators to define Dropbox Monitor jobs to monitor Media Gateway dropbox system folders for new files, folders, and document types such as XML definition files as they are added. Media Gateway converts those objects into packages and delivers the package contents to specified Media Exchange users, groups, or channels.

Media Gateway enables: 

  • Automate package creation and delivery.
  • Channel definition of content and subscribers.
  • Package delivery to destination agents for non-Media Exchange processing.

Media Gateway jobs instruct agents to convert:

  • Individual files in a directory to packages.
  • Folders in a specified directory to packages.
  • Contents defined in XML definition files to packages.

Media Gateway Dropbox Monitors

Once files have been placed in the dropbox, they are examined on a periodic basis as specified by the DropBox Monitor job. The files are evaluated against the package composition criteria. Once a set of files match the criteria the files and folders are moved into a subfolder of the dropbox folder named _Active.

A separate job is then started for the package content. This job will handle creation of the actual package, copying of the files in the package to the Media Exchange repository and the subsequent delivery of the package to its destination recipient(s) and/or channels. The job name will include an alphanumeric portion of the file and/or folder in the package to aid in identification through the Manager GUI.

The DropBox Monitor job will create as many package processing jobs on each run as required to satisfy the files found in the dropbox. When the files in the package have been successfully copied to the Media Exchange package repository, distributed, and delivered, they are deleted from the _Active folder.

When multiple files are being copied into a folder for placement in a package, it would be possible for the dropbox monitor to run and package the files before they have all arrived. To prevent this, a folder named _Stage is created in the dropbox folder. File and folders, placed in this directory, are ignored by the dropbox monitoring job. Once the user has copied the appropriate content, then it will be moved to the top level dropbox folder. Since file moving is an instantaneous operation, there is no chance of any files being missed.

The package name is based on the package composition:

  • Individual files: The package name is based on the file name in the package.
  • Folder: The package name is based on the folder name.
  • XML defined: The package name is as specified in the name of the XML file.

Media Gateway Dropbox Monitor Jobs

To configure Dropbox Monitor jobs do the following:

  1. In the Manager, select Media Gateway>Dropbox Monitors.
  2. Click Add and the Add Job window is displayed.

The following section describes the prompts associated with creating a Media Gateway Dropbox Monitor job.

  • Job Name: Type the name for the new job. This is a mandatory prompt.
  • DropBox Settings
    • DropBox Agent: Select from the drop-down list, the hostname of the agent on which the dropbox is located. This agent does not need to be Media Exchange enabled. This is a mandatory prompt.
    • DropBox Folder: Select the monitored folder into which files and/or folders will be placed. The default user for the DropBox Agent must have access to this folder. Specifically, if a Windows UNC path is used, then a real user, not NT authority\system, must be used. This is a mandatory prompt.
    • Package Composition: These options determine which files will be placed in a given package. One of the following may be selected:
      • Individual Files as Packages: A separate package is created for each file placed in the dropbox folder.
      • Subfolders as Packages: A separate package is created for each subfolder of files in the dropbox folder. If multiple levels of subfolders are used, the folder structure is preserved in the package, which is identified by the top level subfolder.
      • XML Defined Packages: Every file in the dropbox folder, with a .sigpackage.xml extension, is parsed to determine the list of files to be included in a given package. Each XML specification file will result in the creation of a single package. Any .sigpackage.xml file contents that do not meet the XML specification below will result in an error. (see additional information later in this document) When this option is enabled, you can configure both the Expires On and Packages Expires In (Days) prompts in the Default Package Availability Settings section. When both prompts are configured, the Expires On prompt takes precedence.

      Only a single package composition type may be specified for each monitored dropbox folder. E.g. individual files may not be placed in the main dropbox folder in addition to subfolders of files being placed in the main dropbox folder.

      Note: See XML Package Definition section for the format of the XML file.

  • Package Repository
    • Package Repository Agent: From the drop-down list, select the Signiant agent where the files are transferred to for conversion into a package. This agent must be Media Exchange enabled because it becomes the agent responsible for distributing the package to all other recipients. This is a mandatory prompt.
  • Default Package Delivery Settings
    • Recipients: Type or select a list of Media Exchange recipients and guest users to whom the packages will be sent. Guest users should be specified by email address.
    • Personalized Message: A text message to be included in the description of each package. Unicode characters are supported.
  • Default Additional Target Agent Settings (These options are only available with a Package Mover license key.)
    • Target Agents: Select the additional agents to which you want packages transferred.
    • Target Agents Folder: Select the folder on the target agents into which the files and/or folders will be placed.
  • Default Package Availability Settings
    • Not Available Before: Use the calendar to select the date the package is available.
    • Expires On: The date the package expires. If this prompt is configured and you enter a value in Packages Expire In (Days), the value in Expires On is cleared. Note: if you have enabled XML Defined Packages in the Dropbox Settings section, you can configure both prompts but Expires On has precedence over Packages Expires In (Days). (In the case of Media Gateway jobs, you can specify only Expires On or Package Expires In (Days).) When the package reaches this date it is hidden from end users and not visible in the channel listing.
    • Packages Expire In (Days): Specify the number of days in which the package expires. If this prompt is configured and you enter a value in Expires On, the value in Packages Expire In (Days) is cleared. Note: if you have enabled XML Defined Packages in the Dropbox Settings section, you can configure both prompts but Packages Expires In (Days) has precedence over Expires On. (In the case of Media Gateway jobs, you can specify only Expires On or Package Expires In (Days).) When the package reaches this date it is hidden from end users and not visible in the channel listing.
  • Default Package Options
    • Allow Packages To Be Forwarded: From the drop-down list, select Yes or No.
    • Include Package Definition File: From the drop-down list, select Yes or No. Selecting Yes forces the creation of a Signiant package document (XML format) in the delivery folder for each recipient. If needed, this package definition file can be used as an input for downstream Dropbox monitor jobs.
  • Default Interested Party Notifications
    • Notify on Delivery - Copy: Type email addresses to which delivery notices are copied.
    • Notify on Delivery - Blind Copy: Type email addresses to which delivery notices are blind copied.
    • Notify on Download - Copy: Type email addresses to which download notices are copied.
    • Notify on Download - Blind Copy: Type email addresses to which download notices are blind copied.
  • Package Naming Options
    • Package Naming Option: From the drop-down list, select one of the following options:
      • Automatic: This changes the name of the package to line up with "Package Composition" for above. For example, if you choose 'files', each package name is set to the corresponding filename. Similarly, if you select "folders" – each package has the name of the corresponding folder.
      • Prefix Only: Only the Package Naming Prefix is used.
      • Prefix Plus Date/Time: Only the Package Naming Prefix is used.
      • Prefix Plus First File: Only the Package Naming Prefix is used.
    • Package Naming Prefix: Type the prefix that is added to the package name.
  • Job Notification and Logging Options
    • Email Job Failure Reports To: Type the email address of the person who will receive job failure reports. Separate multiple addresses with a comma.
    • Log Detail Level: From the drop-down list, select the amount of information, based on severity, that is logged during the job. Choose Error, Warn (warning), Info (Information) or Debug. Debug provides the greatest level of detail while Error provides the least.
  • Job Creation Options
    • Create Jobs as User: Type the username of the Signiant user who will create the package processing jobs. This user is also used for SOAP communication with the Manager and will be the Media Exchange sender of the package. This is a mandatory prompt. This user must have the following attributes:
      • Schedule permission for the job group into which the package processing jobs are being created.
      • Schedule permission for the Job Template Library Media_ Gateway_Package_Processor.
      • Media Exchange enabled.
      • Media Exchange Allowed to send packages privilege.

      TIP: Create a copy of the "admin" user to simplify this activity.

    • Password: Type the password for the above user. This is a mandatory prompt.
    • Use Job Group: From the drop-down list, select the job group into which the jobs are placed.
    • Job Name Prefix: Type the text that all jobs will start with. This is a mandatory prompt.
    • Use UDP Control Channel: By default this is set to No, ensuring job control information is communicated using TCP instead of UDP. This prompt determines whether the file transfer from the dropbox to the Media Exchange repository uses a TCP or UDP control channel for communication between the Manager and the dropbox agent, as well as between the dropbox and Media Exchange repository agents. In either case, the actual file transfer will utilize WAN acceleration (UDP) if licensed.
    • Encryption Level: The encryption level selected dictates how securely information is transmitted over the network (Note: the file/package is always stored in the original format). Encryption is restricted to the file transfer portion of the job and does not affect how the files are stored on the filesystem. Select one of the following levels from the drop-down list:
      • High
      • Medium
      • Low
      • No Encryption - signed: transfers unencrypted (plain text) data, but includes the SSL protocol's message digest calculation and signing to ensure data stream integrity.
      • No Encryption - unsigned: this default value, allows the transfer of data, after the initial SSL authentication of the endpoints, to proceed with no encryption, no message digest computation and no signing of the message digests (normally included with the SSL protocol). This mode of operation is only for raw performance, since it makes no guarantee of the integrity of the data stream other than the defaults used on a normal network channel. The underlying TCP protocol can guarantee the integrity of messages across each single network hop, but has no facilities for detecting a man-in-the-middle attack.
    • Verify if target directory exists: From the drop-down list, select either Yes or No.
  • Dropbox Monitor Frequency
    • Frequency: Use these options to specify how often the job runs. Select from the following options:
      • None: use for jobs that run only at irregular, user-defined times.
      • Hourly, Daily, Weekly, Monthly, Yearly: run the job once every selected interval.
      • Monthend: run the job once every last day of the month.
      • Once: run the job only once, when first created.

      Note that editing the frequency of a job that is currently in a queued state within a queued job group will have no effect on the job until the next time the job is run.

    • Start Date/Time: Use the calendar to specify the date and time at which you want the job to run. Note that editing the start date/time of a job that is currently in a queued state within a queued job group will have no effect on the job until the next time the job is run.
    • Time Zone: From the drop-down list, select the time zone in which the displayed times are set. For example, if an Eastern Time zone specifies a start time of 9:00 am and a time zone of PST, the job runs at 9:00 am Pacific Standard Time or noon Eastern Standard Time.
    • Priority: From the drop-down list, select the priority for the job. When used in conjunction with a Resource Control, the priority determines the placement of the job within the resource queue. A job with a higher priority is placed before a job with a lower priority. The default value is Medium. Select one of the following:
      • Low
      • Medium
      • High
      • Urgent
      • Immediate
    • Finish Before: Use the calendar to specify the date and time at which you want the job to be completed. When used in conjunction with a Resource Control, this attribute determines the placement of the job within the resource queue. A job with an earlier Finish Before time is placed before a job with a later Finish Before time.

Media Gateway Processing

The following topic describes Media gateway monitoring and package processing.

Monitoring Package Processing

To simplify the monitoring of the jobs created for package processing, three job views are accessible via the menu. Under the Media Gateway menu, a sub menu exists named Delivery Jobs. This sub menu contains menu items corresponding to the following three job views:

  1. All Jobs: View all jobs created for package processing by the Media Gateway Dropbox Monitor.
  2. Running Jobs: View all jobs created for package processing by the Media Gateway Dropbox Monitor that are currently running.
  3. Errored Jobs: View all jobs created for package processing by the Media Gateway Dropbox Monitor that have failed.

Package Processing Job Group

The jobs that process each package are placed in the job group MediaGatewayDeliveryJobs. All packages submitted at the same time will be processed in parallel. If the Manager is licensed for Resource Management, then the queuing feature can be enabled on the job group. In this scenario, the parallel processing of packages will be based on the queuing configuration. See Understanding Resource Controls in Chapter 4 in the Manager User's Guide for further information on this feature.

Note: The automatic processing of packages can generate substantial workload on the agents.  If you expect more than 10 packages will be created during any polling cycle of the package processor, it is recommended that you purchase the Resource Management feature.  Otherwise, you may need to adjust the processes that submit files into the Media Gateway application's dropboxes.

Media Gateway Implementation

The following describes example Dropbox Monitor implementation scenarios.

Dropbox Per Recipient (Simple)

  • Create a folder on the dropbox agent's filesystem for the user, user group, channel or destination.
  • Setup a dropbox job that monitors that folder and delivers any received content to that user, user group, channel or destination.

For example, to deliver new content that arrives in a dropbox location to a user group called "Sales".  Setup a folder called "Sales" on the dropbox agent and setup the appropriate job details to send to that channel.

Automation From External Systems (Advanced)

  • Create a folder on the dropbox agent's file system where the content is automatically created.
  • Setup a dropbox job that will monitor that file system location.
  • Modify your automation system to output Signiant formatted XML files that indicate the package metadata, file contents and recipient list.

For example, to configure a Media Asset Management (MAM) system that allows you to extract media and format the metadata associated with the media, create a process that extracts the media asset from your MAM and generates Signiant compliant XML files.


Media Gateway Dropbox Subfolders

The  dropbox is composed of the following processing subfolders:

  • _Active: This folder contains all the files currently being processed by active running jobs.
  • _Retry: This folder contains potential problem files which will be retried before they are declared "In Error" and moved to the _Errored folder. For example, a retry may be invoked if a network failure occurs during a file transfer.

    Up to five retries will occur at the next run of the dropbox monitor job, including subsequent attempts at intervals of + 5 minutes, + 1 hour, + 2 hours, and + 1 day after the initial job run.

  • _Errored: If an error occurs in the system before the package can be created or delivered, the files are moved into this folder.
  • _Stage: This folder contains multiple files and folders for placement in a package that are staged before the dropbox monitoring job runs.
  • _Stale: Unprocessed content will be moved to a stale folder after five days and deleted after 30 days. An email notification will be sent to the person identified to receive failure notifications for the dropbox.

Media Gateway XML Package Definition

When a package composition of XML Defined Packages is specified, an XML file placed in the top level of the dropbox folder lists the files to be included in the package. This file is named <package name>.sigpackage.xml. Where <package name> will be the name used for the package itself. Generally, the XML allows you to describe the same characteristics of a package that a user could fill-in via the Media Exchange user interface.

The format specification of the XML file is as follows:

<SigniantPackage>
          <PackageTitle>Package Title</PackageTitle>
          <PackageDescription>Package Description</PackageDescription>
          <Forwardable>true|false OR yes|no</Forwardable>
          <NotAvailableBefore>yyyy-mm-ddThh:mm:ssZ</NotAvailableBefore>
          <NotAvailableAfter>yyyy-mm-ddThh:mm:ssZ</NotAvailableAfter>
          <ArchiveOn>yyyy-mm-ddThh:mm:ssZ</ArchiveOn>
          <PackagePaths>
                   <Path>path2</Path>
                   <Path>pathN</Path>
          </PackagePaths>
          <Recipients>
                   <Recipient>user1</Recipient>
                   <Recipient>user2;user3;userN</Recipient>
          </Recipients>
          <Categories>
                   <Category>Category1</Category>
                   <Category>Category2:SubCategory1</Category>
                   <Category>Category2:SubCategory2</Category>
          </Categories>
          <PersonalizedMessage>Personalized Message</PersonalizedMessage>
          <IncludePackageDefinitionFile>true|false OR yes|no</IncludePackageDefinitionFile>
          <NotifyOnDeliveryCC>
                   <Email>user1@company.com</Email>
                   <Email>user2@company.com;user3@company.com;userN@company.com</Email>
          </NotifyOnDeliveryCC>
          <NotifyOnDeliveryBCC>
                   <Email>user1@company.com</Email>
                   <Email>user2@company.com;user3@company.com;userN@company.com</Email>
          </NotifyOnDeliveryBCC>
          <NotifyOnDownloadCC>
                   <Email>user1@company.com</Email>
                   <Email>user2@company.com;user3@company.com;userN@company.com</Email>
          </NotifyOnDownloadCC>
          <NotifyOnDownloadBCC>
                   <Email>user1@company.com</Email>
                   <Email>user2@company.com;user3@company.com;userN@company.com</Email>
          </NotifyOnDownloadBCC>
</SigniantPackage>
Note: Each <PackagePath> <Path> node will be assumed to be relative to the dropbox folder. Fully qualified paths such as those referencing a shared network folder, having a drive letter prefix, or starting with '/' are not supported and will result in an error. The category tag requires that you space delimit the categories - even if you are only using a single category. An example using a single channel "Sports": <Categories> <Category><Sports ></Category> </Categories> An example using a sub-channel "Hockey" <Categories> <Category><Sports :Hockey ></Category></Categories> there is a space after "Sports" and after "Hockey".

Recipients Tag Recipient information may be specified in the either of the following formats (or a mix of both): 1) A single criterion per <Recipient> tag.

 <Recipients> <Recipient>test@signiant.com</Recipient> <Recipient>john</Recipient> </Recipients>

2) Multiple criteria per <Recipient> tag, semicolon (;) separated. Each criterion in the following example represents a different user. Therefore "test@signiant.com" might match the email of user1, while "John" might match the first name of user2.

<Recipients> <Recipient>test@signiant.com;john </Recipient></Recipients>

If the two criteria were to match against the same user (i.e. a user with the email of "test@signiant.com" AND the first name "John") then the package would be sent only once. Criteria specified in the <Recipient> tag should be specific enough to match a single user in the local or global directories. If multiple matches are found in either the local or global directories, then the package delivery job will fail. Therefore although first and last names are supported, they may not be the best user field to use when specifying recipients. There is a higher likelihood of a single user match if a username (in the local directory) or an email (in either the local or global directories) were specified in the <Recipient> tag.

The following fields will be searched in the local directory (in order):
  1. Username
  2. Email
  3. Group Display name
  4. First name or Last name

The following fields will be searched in the global directory (in no specific order): Email, First name, and Last name.

Note: The element <ArchiveOn> is reserved for future use and currently provides no functionality.

Media Gateway Deployment Use Cases

The following repository use case should be considered when planning a Media Gateway deployment.

Repository Use Case

  • Trusted, externally located media exchange users submitting content.

    Location: The packages are stored within a repository.

    Comments: Generally, this is a relayed configuration.

  • Untrusted, externally located media exchange users submitting content.

    Location: The packages are stored outside a repository.

    Comments: Maintenance will not clean-up files outside the repository. Usually this category is assigned to an agent located in a DMZ.

  • Trusted, internally located users (non-Media Exchange) need filesystem access to content delivered via Media Exchange.

    Location: The packages are stored outside a repository.

    Comments: Maintenance will not clean-up files outside the repository.

  • Automating the delivery of content to external users.

    Location: The packages are stored within a repository.

    Comments: Usually in a DMZ, unless relays are permitted to allow access through the firewall.

  • Automating the delivery of content to processes.

    Location: The packages are stored outside a repository.

    Comments: Maintenance will not clean-up files outside the repository. Normally these categories have the ACL "publish" (and not "read").