Ad Hoc Delivery

Note: The Ad hoc delivery feature is available on MassTransit HP servers only.

Ad hoc delivery allows Web client contacts to send files to users designated by email addresses that may or may not already have accounts in MassTransit. After logging in to the MassTransit Web (MTWeb) site, Web client contacts are allowed to send files to any valid email address. When the web client user clicks on the "Send" button, the files are sent to the MassTransit server. If the entered email address does not belong to an existing contact on the server, an account with that address is automatically created. If you have limited Web client contact licenses, the automatically created contact will be an Ad hoc contact. Otherwise, the created contact will be a Web client contact.

Note: The Ad hoc contacts do NOT detract from your Web client licenses. You can have an unlimited number of Ad hoc contacts on your server.

All automatically created Web client or Ad hoc contacts can be configured to expire or persist.

Note: When licensed for unlimited web clients, MassTransit defaults to creating ad-hoc web client accounts as real web clients instead of ad-hoc.  This can make it difficult to manage large numbers of ad-hoc web clients that need to be expired. A new setting CREATE_WEB_INSTEAD_OF_ADHOC has been added to MassTransitEngine.cfg in MassTransit 7.3. Setting the value to FALSE will cause ad-hoc web clients to be always created as ad-hoc, not regular web clients.  Ad-hoc expiration rules will then apply to the new clients.

After MassTransit creates the account, an email action can be triggered that sends a notification email to the recipient contact’s email address. The email can contain an HTTP or FTP link allowing the contact to click the link and retrieve files from the MassTransit server. These links can either take the contact to the MTWeb or FTP login page with the contact’s user name already populated. Setting passkeys in the links allows the contact to log automatically into the MTWeb or FTP site without having to know their username and password.

Note: Please note that Ad hoc contacts are not allowed to log in to the FTP server. That is why you should not use FTP links and passkeys in e-mails generated for Ad hoc contacts.

Below you can find instructions on how to configure the ad hoc delivery feature as well as information about the security risks of the different types of email links if an email is intercepted by a third party.

Configuring Ad Hoc Delivery

The configuration of the Ad hoc delivery feature consists of five principal stages:

• Enabling the feature;
• Configuring links and passkeys;
• Configuring the settings of the SMTP server which will send the email notifications;
• Creating an e-mail action in MassTransit to notify the file receivers that there are files ready for them to download;
• Configuring the desired individual Web client contacts that will be able to send files to arbitrary email addresses.

Enabling the Ad Hoc Delivery Feature

Follow the steps below to enable the Ad hoc delivery feature:

1. Open the MassTransitEngine.cfg file located in the MassTransit installation directory. By default, this folder is placed on the system drive in:
   1. for MassTransit 7.6 and later:
      • on 64-bit machines:

      C:\Program Files (x86)\Acronis\MassTransit Server

   2. for MassTransit 7.1 to 7.6:
      • on 32-bit machines:

      C:\Program Files\Group Logic\MassTransit Server

      • on 64-bit machines:

      C:\Program Files (x86)\Group Logic\MassTransit Server

   3. for MassTransit 7.0.x:
      • on 32-bit machines:

      C:\Program Files\Group Logic\MassTransit Server 7

      • on 64-bit machines:
      • C:\Program Files (x86)\Group Logic\MassTransit Server 7

      Note: All lines beginning with "%%" in the MassTransitEngine.cfg file are considered commented and therefore ignored. Please ensure that all settings you change are uncommented (if you see "%%" characters at the beginning of any of the settings you modify, delete them).

2. Under the AD-HOC ADDRESSING CONFIGURATION section in the MassTransitEngine.cfg file, find the ADHOC_ADDRESSING_ENABLED setting and set it to TRUE. This enables the feature globally for the MassTransit server. You will also need to enable ad hoc delivery for each Web client contact individually in the MassTransit Administrator. This is described in the Configuring Contacts to Use Ad Hoc Delivery section of this page.
            ADHOC_ADDRESSING_ENABLED=TRUE
3. You can create a profile account whose settings will propagate for every automatically created ad hoc account. To do this, enter an existing Web client contact’s name for the ADHOC_AUTO_ACCOUNT_PROFILE setting. When setting up this Web client contact in the MassTransit Administrator, under the Mailbox tab of the "Contact Information" window, you MUST choose the Default Mailbox option. Only settings found in the Security tab of the "Contact Information" window are propagated to the new Ad hoc contact.
            ADHOC_AUTO_ACCOUNT_PROFILE=WebClientContactName, where WebClientContactName is the name of the existing Web client contact whose profile you want to use as default for Ad hoc contacts.

   Note: For detailed information about contacts, their mailboxes, and privileges, see the Contacts page.

4. If you have forwarding permissions established by MassTransit Master and Distribution lists, and you do not want to override them with the ad hoc delivery feature, set ADHOC_OVERRIDE_MDL_PERMISSIONS_ENABLED to FALSE. The default value for this flag is TRUE.

   Note: For more information about the Master and Distribution lists, see the Active Directory page.

   Note: The configuration of the MassTransitEngine.cfg file is not finished! Please continue with the following section without closing the file.

Configuring Domain, Links, and Passkeys

You now need to configure the domain settings and the link and passkeys that will allow the automatically created contacts to log into the MTWeb or FTP site automatically without having to know their username and password.

Note:Please note that Ad hoc contacts are not allowed to log in to the FTP server. That is why you should not use FTP links and passkeys in e-mails generated for Ad hoc contacts.

Note: Since the password for the automatically created contacts is being created dynamically, if you do not use passkeys in the generated e-mails, the users will be asked for a password, which you will need to set from the MassTransit Administrator. For more information about setting login credentials for MTWeb, see Adding a New Web Client Contact Entry and Available Configurations for Ad Hoc Contacts.

Note: For more information about the passkey links, see Email Notification Tokens page.

1. Under the HTTP and FTP email link configuration section of the MassTransitEngine.cfg file, set the HTTP_DOMAIN settings to the domain name (or the IP address) of your MassTransit server. This will allow the Web client and/or Ad hoc contacts to log into the web site of your server via the HTTP protocol.

   Note: All lines beginning with "%%" in the MassTransitEngine.cfg file are considered commented and therefore ignored. Please ensure that all settings you change are uncommented (if you see "%%" characters at the beginning of any of the settings you modify, delete them).

2. If you want to, you can also set the FTP_DOMAIN settings to the domain name (or the IP address) of your MassTransit server. This will allow the Web client contacts to log into the web site of your server via the FTP protocol. Ad hoc contacts are not allowed to log in via FTP due to security considerations.
3. To determine how long the passkey link will be valid for, enter a value for the PASSKEY_DEFAULT_TTL_HOURS setting. For example, setting it to "168" will make the link valid for a week:
            PASSKEY_DEFAULT_TTL_HOURS=168
4. You can also determine the number of minutes the passkey link will be valid for after the first successful use. In order to do that, change the PASSKEY_DISABLED_AFTER_LOGIN_MINUTES setting. For example, setting it to "30" will make the link valid for half an hour after its first use:
            PASSKEY_DISABLED_AFTER_LOGIN_MINUTES=30
5. After setting up the desired configuration settings, save and close the MassTransitEngine.cfg file.
6. Restart the MassTransit services from the Services console.

   Note: Any time you make a change to the MassTransitEngine.cfg file, you must restart the MassTransit services for the changes to take effect.

Configuring SMTP Server Settings

In order to be able to send emails, you need to have an SMTP server set up for MassTransit to use. Follow the steps below to configure the settings for the SMTP server.

1. Open the MassTransit.cfg file located in the MassTransit installation directory. By default, this folder is placed on the system drive in:
   1. for MassTransit 7.6 and later:
      • on 64-bit machines:

      C:\Program Files (x86)\Acronis\MassTransit Server

   2. for MassTransit 7.1 to 7.6:
      • on 32-bit machines:

      C:\Program Files\Group Logic\MassTransit Server

      • on 64-bit machines:

      C:\Program Files (x86)\Group Logic\MassTransit Server

   3. for MassTransit 7.0.x:
      • on 32-bit machines:

      C:\Program Files\Group Logic\MassTransit Server 7

      • on 64-bit machines:
      • C:\Program Files (x86)\Group Logic\MassTransit Server 7

      Note: All lines beginning with "%%" in the MassTransit.cfg file are considered commented and therefore ignored. Please ensure that all settings you change are uncommented (if you see "%%" characters at the beginning of any of the settings you modify, delete them).

2. Under the SMTP SERVER CONFIGURATION section in the MassTransit.cfg file, find the notification_smtp_server_address= setting and set it to the address of your SMTP server.
3. Under the same section, find the notification_smtp_server_port= setting and set the port number which will be used for the communication between the MassTransit server and the SMTP server.
4. If you have configured encryption of the entire web traffic on your web server, you should set the notification_smtp_server_secure= setting to true, as shown below. Otherwise, leave the setting to false.
             notification_smtp_server_secure=true
5. You can configure a name and an email address that will be displayed as a sender's name and address in all emails sent by MassTransit. To do that:
   1. Enter an email address as a value of the notification_smtp_from_address= setting.
   2. Enter the name that will be displayed as a sender name in the emails to the users as a value of the notification_smtp_from_display_name= setting.
6. Enter the user name and the password for logging into the SMTP server in order to authenticate and allow MassTransit sending emails. If you leave this settings blank, the default login credentials will be used.
   1. Enter the username for authenticating on the SMTP server as a value of the notification_smtp_auth_user= setting.
   2. Enter the password for the used in point a username as a value of the notification_smtp_auth_password= setting.
7. After setting up the desired configuration settings, save and close the MassTransitEngine.cfg file.
8. Restart the MassTransit services from the Services console.

Note: Any time you make a change to the MassTransit.cfg file, you must restart the MassTransit services for the changes to take effect.

Creating an Email Action

The next step to setting up the ad hoc delivery feature is to add an email action in MassTransit that will notify the Web client and/or Ad hoc contacts that there are files ready for them to download.

1. Open the MassTransit Administrator application and click on the Setup button from the Navigation Bar.
2. In the Actions tab of the Setup window, click on the Add… button.
3. Enter a name for the action in the Name field (e.g., "Files ready for download email").
4. Select the After Files Are Added option from the When drop-down menu.
5. Click on the Configure Email Action button from the Tasks area (the first button on the left side of the window).
6. Make the following changes in the Configure Email Action window:
   1. Leave the To field empty.
   2. Check the Include Contact Email Address When Available check box.
   3. Enter a subject for the notification e-mails in the Subject field.
   4. Enter text for the e-mail notification in the Message field. You can set e-mail links which can either take the contact to the MassTransit Web (MTWeb) or FTP login page with the contact's user name already populated. If the link also contains a passkey, the contact is automatically logged in the MTWeb or FTP site without having to know his username and password.

   There are 4 tokens that can be used to send e-mail to a contact that will contain an FTP or HTTP link, allowing the contact to click the link and retrieve files from the MassTransit server. The specific token names are:

• for Web client contacts:

  $${{HTTPLink}} $${{HTTPLink_passkey}} $${{FTPLink}} $${{FTPLink_passkey}}

• for Ad hoc contacts:

  $${{HTTPLink}} $${{HTTPLink_passkey}}

  There also are other tokens which can include the following information in the e-mail notification – the contact name, contact e-mail address, date, time; file transfer information such as number of files, length of transfer, and size of transfer; license and link expiration.

  Note: The complete list with the available passkeys and detailed information about them can be found on the Email Notification Tokens page.

  Here is example text for the e-mail action Message area:

  $${{ContactName}}, You have $${{XferNumFiles}} file(s) that were sent to you from $${{OriginatingContactName}}, ($${{OriginatingEmailAddress}}).

  If you already have a MassTransit login, click here to pick up your files. $${{HTTPLink}} If not, click the link below to log in and download your files. $${{HTTPLink_passkey}} This automatic login link is good for $${{PasskeyTTLHours}} hours. $${{XferFileList}}

  Note: Instead of the $${{XferFileList}} token, you can check the Include File List check box below the message area to show the file list in the email.

  The used tokens in the example text of the e-mail notification do the following:

  • $${{ContactName}} - displays the name of the person receiving the email
  • $${{OriginatingContactName}} - displays the contact name of the originating user who sent the files
  • $${{OriginatingEmailAddress}} - displays the email address of the originating user
  • $${{XferNumFiles}} - displays the count of the file(s) for download
  • $${{XferFileList}} - lists each file by name and size
  • $${{PasskeyTTLHours}} - displays the validity time of the passkey link set in the MassTransitEngine.cfg file

1. If you check the Include Error Messages [When Available] checkbox, the e-mail notification will display error messages when such occur.
2. When you are ready with the configuration of the e-mail action, click on the OK button in the Configure Email Action window to save the changes.
3. The newly configured task for sending an e-mail should appear in the list under the Tasks area of the Add Actions window. Click OK to save the changes.
4. If you chose to save the action, it should appear in the list of the Actions tab in the Setup window. Click OK in the Setup window to save the action. Otherwise, click Cancel.

Configuring Contacts to Use Ad Hoc Delivery

The last step for configuring the ad hoc delivery feature is to set the desired individual users who will be able to send files to arbitrary e-mail addresses. This configuration is per user only and you need to do it for each Web client contact that you want to use the feature. To do this, edit an existing Web client contact or add a new one from the Contacts window of the MassTransit Administrator.

1. To edit an existing Web client contact, highlight it in the Contacts window of the MassTransit Administrator and click on the Edit... button.
2. In the Contact Information window that appears, open the Security tab.
3. Check the Allow Sending Files To Arbitrary Email Addresses check box in the Web Privileges section.

   Note: For more information about contact privileges, see Contact Privileges on the Contacts page.

4. Click OK in the Contact Information window to save the changes.

Now, the ad hoc delivery feature is fully configured and the chosen Web client contacts should be able to send files to arbitrary email addresses. In addition, Ad hoc contacts, if given permission to send files, can send files back to the originating contact or other contacts using MassTransit.

Security Considerations

There are four types of e-mail links: FTPLink, HTTPLink, FTPLink_passkey, and HTTPLink_passkey. The FTPLink and HTTPLink have different security considerations than FTPLink_passkey and HTTPLink_passkey.

When the FTPLink or HTTPLink types are used, the users of the web client (for FTPLink and HTTPLink – Web client contacts; for HTTPLink – Ad hoc contacts) receive e-mails that contain a web browser link. This link directs the user to the MTWeb login page with their login name field filled in. If the e-mail is intercepted, a third party will know the web client user’s login name but NOT their password.

When the FTPLink_passkey or HTTPLink_passkey types are used, e-mails sent to web client users contain a link with a temporary passkey code. When this link is clicked, the user is automatically logged into MTWeb under his account and is able to transfer files. If the e-mail is intercepted, a third party can log into MTWeb under the user’s account until the passkey expires. The only way to fully prevent a third party from gaining access is by ensuring that e-mails with passkey codes are not intercepted. Another preventative measure to take is to reduce the amount of time a passkey lives by modifying the passkey lifetime parameters in the MassTransitEngine.cfg file.