uDownLoad™
Online File Distribution Manager
User's Guide

Version 1.0
Copyright (c) 2004; Microburst Technologies, Inc.
http://www.uburst.com

Table of Contents

1. Introduction

2. Features

3. System Requirements

4. CGI Script Configuration

5. Installing the Script on Your Web Server

6. Troubleshooting

7. Getting Started

8. Control Panel

    8.1 Add Product

      8.1.1 Standard Download Page

      8.1.2 Custom Download Page

    8.2 Edit Product

    8.3 Delete Product

    8.4 Upload Product

    8.5 Assign License

      8.5.1 E-mail Message File Template

    8.6 Lookup License

9. More Information



1. Introduction

Microburst Technologies, Inc. proudly presents:

uDownloadTM Online File Distribution Manager

uDownloadTM is a system that manages electronic file distribution and file downloading via the Internet. With uDownload, you can control the downloading of all types of files such as pictures, artwork, music files, movies, recipes, building plans, software, documents... virtually anything that you want to distribute electronically.

2. Features

The Features of the uDownloadTM include:



3. System Requirements

uDownloadTM consists of one Perl CGI script. System requirements are:



4. CGI Script Configuration

uDownloadTM consists of one Perl script that must be configured and installed on your web server. To configure the script, you will need to open it with any standard text editor - such as NotePad or WordPad - and answer the eleven (11) questions at the top of the script.

If you've never installed or executed any Perl scripts on your web server before, it is strongly recommended that you first try installing our basic test script as described on the following reference page:

http://www.uburst.com/uDownload/testscript.html

By installing this basic Perl script, it should help you to understand how to install and execute scripts on your web server. It also will verify that your web hosting account is configured properly to run Perl scripts and will make installing the uDownloadTM script that much easier.

1. What is the path to perl on your web server?

The uDownloadTM script is written in the Perl programming language, which is a standard on most web servers. In order to run this Perl script, you must specify the location of perl on your web server. If you do not know the path to Perl on your web server, ask your web-hosting provider.

Note: The path to perl should be specified as the very first line at the top of the script and should include the #! characters in front of the path.

On UNIX servers, typical values are:
#!/usr/bin/perl
#!/usr/local/bin/perl
#!/bin/perl

On Windows servers, typical values are:
#!c:/perl/perl.exe
#!c:/perl/bin/perl.exe

Some Windows Servers do not require that this path be specified at all. If that is the case for your web server, just leave the first line of this script as is.

2. What is your uDownload License Number?

For this question, simply enter the license number that you were given when purchasing uDownload. An example value is:

$license_number = "ABC-123-456-789";

3. What is the URL of your website?

For this question, simply enter the full URL of your website. An example value is:

$domain = "http://www.mydomain.com";

4. What is the URL of this script?

The $script_url parameter must be set to the full URL of the script on your web server. For example, if you put the script into your cgi-bin directory, then you should set this value to something like:

$script_url = "http://www.mydomain.com/cgi-bin/udownload.pl";

Note: Some servers require that CGI scripts end with .pl and other servers require that scripts end with .cgi. Remember that if you have to rename the script to use the .cgi file extension instead of the default .pl file extension, then be sure to use udownload.cgi instead of udownload.pl in this parameter.


5. What is the full or relative path to your download data directory?

As part of the installation of this uDownloadTM script on your web server (which is described in the next section), you will need to create a "download data" directory on your web server. This "download data" directory is where uDownloadTM will store all of the downloadable soft goods and download data files. Typically, this "data" directory should be created as a subdirectory of your "cgi-bin" or "cgi-local" directory .

In order to be able to write files to the download data directory you must specify the path to that directory on your web server. This path can be specified as a relative path - relative to the location of the script in your CGI directory - or as the full path to the directory from your root directory. (If you want to use the full path to your directory, you may need to ask your web-hosting provider what the full path to your directory is. This value is NOT your URL and should NOT begin with http://...)

An example of a relative path (from your cgi-bin to your download data directory) would be:

$download_directory = "./downloads/";

An example of a full path (directly to your download data directory) would be:

$download_directory = "/www/youraccount/cgi-bin/downloads/";

...on UNIX servers, or perhaps something like this:

$download_directory = "C:/users/youraccount/cgi-bin/downloads/";

....on Windows Servers.

This is a directory path, not a URL. So it won't start with "http". If you don't know the full path to your cgi-bin directory, then ask your web-hosting provider.


6. What is the e-mail address of the administrator?

This should be the e-mail address of the person who will mainly be in charge of the file distribution system (the uDownloadTM administrator)

An example value for this parameter would be something like:

$admin_email = 'webmaster@mydomain.com';


7. What e-mail method do you want to use? (SENDMAIL, SOCKETS, or CUSTOM)

In order to take advantage of the e-mail notifications or other e-mail utilities, you must configure the e-mail method you would like to use. With the $email_method parameter you can specify "SENDMAIL", "SOCKETS", or "CUSTOM".

For UNIX servers, it is recommended to use sendmail. (Sendmail is an e-mail utility that is standard on most UNIX servers). To use sendmail, set this parameter to:

$email_method = "SENDMAIL";

For Windows Servers, you must use SOCKETS or CUSTOM:

$email_method = "SOCKETS";

or

$email_method = "CUSTOM";


8. If using SENDMAIL in question #7 above, what is the path to sendmail?

In order use sendmail to send e-mail, you must specify the location of sendmail on your UNIX server. Typical locations of sendmail are /usr/lib/sendmail, /usr/bin/sendmail, or /usr/sbin/sendmail. If you do not know the location of sendmail on your web server, you can ask your web-hosting provider for the path to sendmail.

An example setting for this parameter is:

$sendmail_path = "/usr/sbin/sendmail";

If you specified question #7 as "SOCKETS" or "CUSTOM", then you can skip this question.


9. If using SOCKETS in question #7 above, what is the IP address (or name) of you mail server?

In order to send e-mail via SOCKETS, you must specify your mail server either by name (such as postoffice.mydomain.com) or by IP address (such as 123.456.789.0). If you do not know the name or IP address of your mail server, you should be able to ask your web-hosting provider.

An example setting for this parameter is:

$smtp_address = "123.456.789.0";

If you specified question #7 as "SENDMAIL" or "CUSTOM", then you can skip this question.


10. What password would you like to use for the uDownload administrator?

For this question, specify any password that you would like to use when logging in to uDownload’s Control Panel. You can use almost any combination of letters and numbers for the password. An example value is:

$admin_password = "mypassword";


11. What password would you like to use for external interfaces to uDownload?

If you are using optional external interfaces to uDownload use the interface parameter password. An example value is :

$interface_password = "survivor";


Note: Question #11 is not used unless you are going to be utilizing a 3rd party interface to your uDownload script. However, even if not using it, it is recommended that you should still specify a password here, for security purposes.


5. Installing the Script on Your Web Server

After editing/configuring the script, as described in the previous section, you will need to install the file in the CGI directory on your web server. To do this:

  1. Use your favorite FTP program to transfer the "udownload.pl" file to the CGI directory on your web server. IMPORTANT! When transferring this file, be sure to transfer it in ASCII or TEXT transfer mode (as opposed to BINARY or RAW transfer mode).


  2. Once the script has been transferred to the CGI directory on your web server, give the script READ and EXECUTE permissions. If you have a UNIX server, you can give the script READ and EXECUTE permissions (chmod 755) with your FTP program. If you have a Windows Server, then you may have to get your web-hosting provider to give the script EXECUTE permissions for you.


  3. As specified in the previous section(see question 5 above), you will need to create a “download” directory on your web server where the uDownloadTM data files can be stored. To do this, use your FTP program to create a new subdirectory called "data" in the CGI directory on your web server.


  4. Once the "data" directory has been created in the CGI directory on your web server, you will need to give that directory WRITE and EXECUTE permissions. If you have a UNIX server, you can give the directory READ, WRITE and EXECUTE permissions (chmod 777) with your FTP program. If you have a Windows Server, then you may have to get your web-hosting provider to give the directory WRITE permissions for you.

After following the above steps to install uDownloadTM on your web server, you can test that the CGI script is setup correctly by opening your browser and typing the full URL of the script on your web server into the LOCATION box on your browser. This URL should be the same URL that you specified in question #4 of the script setup, such as:

http://www.mydomain.com/cgi-bin/udownload.pl

Upon doing so, you should see uDownload Login Form, similar to when you go to the URL script on Microburst's website:

http://www.uburst.com/cgi-bin/udownload/demo/udownload.pl

If when going to the URL of the script on your web server you get a "Server Error" instead then something is not setup correctly, see the Troubleshooting section below.


6. Troubleshooting

In order to keep the troubleshooting information as up-to-date as possible, we have moved this Troubleshooting section to the uDownloadTM online reference site at:

http://www.uburst.com/uDownload/reference.html


7. Getting Started

In order to get started using uDownloadTM, it is recommended that you follow these steps:

1. Upon receiving the uDownloadTM.zip file, you should unzip the entire .zip file into a new directory on your local computer.

2. Follow the instructions in the Installation section of this User's Guide in order to configure and install the uDownloadTM script on your web server.

3. After installing the script, login to the uDownloadTM main Control Panel by pointing your web browser at the URL of the udownload.pl script on your web server.

4. After logging in, you should see the following message:

Welcome to the
uDownload Electronic File Distribution Manager.
Since this is your first time using uDownload,
you should begin by Adding a product.

5. Try adding a downloadable softgood product/electronic file by selecting the Add Product button (described in Section 8.1). After adding a product the following message is displayed:

    Would you like to upload the product now?

    If you select YES, you will be able to upload the desired softgoods/electronic file at this time. (Reference Section 8.4 for upload function details.) Upon completion a message will be displayed:

      The file filename (prod id) has been uploaded (### bytes).


    If you select NO, you will still be able to upload the desired file at a later time directly by using the Upload Product button described in Section 8.4.

6. After uploading a softgoods file, you are now ready to check out the Assign License feature by selecting the Assign License button (described in Section 8.5). Assign yourself a license for your softgoods product. This license notification can be e-mailed to you as well (optional).

7. Verify successful product download by using the assigned license number and download URL to download the product.


These steps should give you a good idea how uDownloadTM works and whether you have everything configured correctly. You can now go back and add any additional downloadable softgood products to your uDownload Manager as you see fit. Refer to the Control Panel section of this User's Guide for more information about utilizing all of the uDownloadTM features.


8. uDownload Control Panel

The uDownload Control Panel functions as a Web-based control panel by which an administrator can manage product files and licenses, and control the online Softgoods/Electronic file delivery system. To login to the control panel, go to the URL of the uDownload.pl script that you installed in the previous section. This URL should be the same value that you configured in Installation Question #4 of the uDownload.pl script and will be something like:

http://www.mydomain.com/cgi-bin/udownload.pl

Note: It is recommended that you bookmark this URL so that you don't have to type it in each time you want to login to your uDownload program.

Upon entering your password (from Installation Question #10) at the login prompt, uDownload’s Control Panel will be displayed.



Upon logging in, the uDownload Administrator is presented with a control panel by which to manage the products (a.k.a. files) and license numbers. On this control panel, you will see six buttons for the six functions available. Each function is described in the sections that follow (Section 8.1 – Section 8.6):


8.1  Add Product

The uDownload Administrator can add as many new products as desired. For each product, the administrator can specify information relating to each product such as the name of the product, the name of the downloadable file, and a custom pattern/template for license numbers associated with the product.

When Adding a product the Add Product Display Screen is displayed, and the following information is collected:

  Form Field Name Description
1 Product ID A unique product identifier (uDownload will ensure this). Alphanumeric characters.
2 Product Name Identifying name for the product being uploaded.
3 File Name The name of the file being distributed (no path information, just the name & extension). Whatever name you specify here will be the name of the file on the server, regardless of the actual name of the file that you upload via the "UPLOAD PRODUCT" option.
4 Version The merchant-specified version of the product/file. (for example: version 2.4, version 1.0, etc.)
5 License Template The string template used when automatically assigning licenses for the product. You can specify any number of characters in the license template.  Any "%" signs will be automatically replaced by random alphanumeric characters (A - Z) when the license is assigned.  Any "#" signs will be automatically replaced by random numbers (0 - 9) when the license is assigned.  The default license template can be $default_license_template setting near the top of the script.
6, 7 Product Download Page Type This field allows you to specify whether to use uDownload's standard download page (details are below) or a custom download page when downloading this product.
8 Product Logo URL (For Use With "Standard" Download Page Type Only) The full URL to an image that will be displayed on the standard download page.
9 Download Instructions (For Use With "Standard" Download Page Type Only) Specify any download instructions that will be displayed on the standard download page.
10 Licensing Agreement Set this option to "YES" if you want to require customers agree to a license before downloading.
11 Licensing Agreement URL (For Use With "Standard" Download Page Type Only) Specify the full URL of the license agreement.
12 Licensing Agreement Instructions (For Use With "Standard" Download Page Type Only) Specify any instructions about agreeing to the license before downloading.
13 Licensing Link Text (For Use With "Standard" Download Page Type Only) This text should correspond to an exact word or phrase used in the Licensing Agreement Instructions. This exact word or phrase will actually be a hyper-link to the Licensing agreement.


Table 1 : Add Product Screen Form Fields

After adding a product the following message is displayed:

    Would you like to upload the product now?

    If you select YES, you will be able to upload the desired softgoods/electronic file. (Reference Section 8.4 for upload function details.)
    Upon completion a message will be displayed:

    The file filename(file ID) has been uploaded (xxxx bytes).

    If you select NO, you will still be able to upload the desired file at a later time directly by using the Upload Product button described in Section 8.4.

The Product Manager will also be re-displayed.

8.1.1  Standard Download Page

The standard download page is dynamically generated by uDownload when a customer goes to the uDownload download URL.  This download URL is in the format:

    "SCRIPTURL?download=PRODUCTID"
...where SCRIPTURL is the URL of your uDownload.pl file, and PRODUCTID is the unique ID of the product being downloaded.

An example of a download URL:

    http://www.yourdomain.com/cgi-bin/udownload.pl?download=P12345
The standard download page is an HTML form dynamically generated from the download_template.html file located in your download directory.  The download_template.html file can be customized if desired.

Standard "download_template.html" Substitutions:

  Field Name Substitution
1 <ud_product_image> Will be replaced with the URL of the product image.
2 <ud_script_url> Will be replaced with the URL of the uDownload script.
3 <ud_product_id> Will be replaced with the ID of the product being downloaded.
4 <ud_product_name> Will be replaced with the Name of the product being downloaded.
5 <ud_product_version> Will be replaced with the Version of the product being downloaded.
6 <ud_product_file> Will be replaced with the name of the file being downloaded.
7 <ud_license_instructions> Will be replaced with the license acceptance instructions.

Table 2 : "download_template.html" Field Substitutions

8.1.2  Custom Download Page

The custom download page is any HTML page located at the URL specified in the "Custom Download URL" field on the "Add Product" form.   This custom download page will be where customers go to download this product. When creating this custom download page, use the "example_download.html" page included with uDownload.  Be sure to follow the pre-defined form field names outlined in the example download form, detailed in Section 8.1.1.


8.2 Edit Product

The uDownload Administrator can edit or modify any of the product information initially set via the "ADD PRODUCT" form, except for the Product ID. To actually change the Product ID, you would need to "ADD" a new product.

Note that on this form the date at which this product was last uploaded (if any) is displayed.

To upload a newer/different file, you need to use the "UPLOAD PRODUCT" form.

When editing a product, the following message and product drop-down box is displayed:

    Select The Product To Edit (select the product to be edited from the product drop-down box)

Remember: Any of the product information initially set via the "ADD PRODUCT" form, except for the Product ID, can be modified. Should you need to change the Product ID a new product must be added using the ADD Product.


8.3 Delete Product

The uDownload Administrator can delete any product by means of the Delete Product Function. Deletion included removing the product information AND the product's download file from the server.

When Deleting a product the following message and product drop-down box is displayed:

    Select The Product To Delete (select the product to be deleted from the product drop-down box)

A confirmation prompt gives you an extra change to cancel out of the deletion.


8.4 Upload Product

The uDownload Administrator can upload a product by means of the Upload Product Function.

When Uploading a product the following message and product drop-down box is displayed:

    Select The Product To Upload (select the product to be uploaded from the product drop-down box)

The Upload Product Screen will be displayed. The following table describes the Upload Product fields:

  Form Field Name Description
1 Product ID A unique product identifier. Alphanumeric characters.
2 Product Name Identifying name for the product being uploaded.
3 Version The current version of the product being uploaded.
4 Last Upload Date The last upload date (if any) will be displayed.
5 File to Upload Use the "Browse" button to locate/select the file to upload.

Table 3 : Upload Product Screen Form Fields

The file that you upload will be uploaded to the $download_directory on your web server.

The name by which the file is saved on your web server corresponds to the "File Name" that you configured when doing the "ADD PRODUCT".  That is, regardless of the actual file name of the file that you "Browsed" to upload, the file will be saved on your web server as the pre-defined "File Name".


8.5 Assign License

When a customer purchases a product, the uDownload Administrator uses the "Assign License" form to assign a license to the customer. Optionally, an e-mail notification with the license number and download URL is sent to the customer.

When Assigning a License the following message and product drop-down box is displayed:

    Select The Product For Which To Assign License(s) (select the product from the product drop-down box)

The Assign License Screen will be displayed.

The following table describes the Assign License Screen form fields:

  Form Field Name Description
1 Product
2 Customer Name The name of the person to which this license is assigned.
3 Customer e-mail The e-mail of the person to which this license is assigned.
4 License Number(s) This field will be pre-populated with a license generated from the product's "License Template".  You can manually modify this license number if desired. Additionally, you can manually add additional licenses by separating each license with a comma.
5 Notes This field can be used to record any specific notes relating to the customer.
6 Send e-mail This field allows you to specify whether or not to send an e-mail to the customer with the assigned license and download information.
7 E-mail Subject If using the "Send Email" option, this field allows you to specify the Subject that will appear on the e-mail. The E-mail Subject field will be pre-populated with the $default_email_subject setting located near the top of the udownload.pl script.
8 E-mail Message If using the "Send Email" option, this field allows you to specify the e-mail message that will be sent to the customer.  The E-mail Message field will be pre-populated with the message contained in the $default_email_file (specified near the top of the udownload.pl script).

Table 4 : Assign License Screen Form Fields

8.5.1 E-mail Message File Template


uDownload lets you modify the default e-mail template "email_template.html" that is used when sending an e-mail to a customer. If you make changes to this template, use the table below to help you place substituted fields in the e-mail:

  Field Name Substitution
1 <ud_product_id> Will be replaced with the ID of the product.
2 <ud_product_name> Will be replaced with the Name of the product.
3 <ud_download_url> Will be replaced with the download URL.
4 <ud_license> Will be replaced with the License(s) being assigned.
5 <ud_customer_name> Will be replaced with the Customer Name.
6 <ud_customer_email> Will be replaced with the Customer E-mail.

Table 5 : "email_template.html" Substitutions

8.6 Lookup License

The uDownload Administrator uses the "Lookup License" function to obtain customer license information. Additionally, License Information can be edited via the License Details Page.

Various options for looking up licenses are available on the Lookup/Edit License Screen:

  1. Lookup by customer name. Lookup is by product AND customer name.


  2. Lookup by customer e-mail address. Lookup is by product AND customer e-mail.


  3. Lookup by license number. Lookup is by product AND license number.


  4. Lookup by product. (displays all assigned licenses)

After selecting one of the four lookup options, the Lookup License Results Screen is displayed.

Initial license results give a summary of the entries that match the specified query. Summary information includes the 1) License Number, 2) Customer Name, 3) Customer E-mail and whether the license is Enabled/Disabled.

Clicking on the "View/Edit" button allows the user to view the details of the customer/license.

The License Details Screen will be displayed. Detailed information includes:

    1) The Product Name and ID

    2) The Customer Name**

    3) The Customer E-mail Address**

    4) The License Number(s)

    5) The Date/time at which the license was assigned.

    6) An indicator on whether the customer was notified via e-mail.

    7) Whether the license is Enabled or Disabled**

    8) The notes associated with the Customer/License.**

    9) The download history showing each time the license was used to download the product (including the version number of the product at the time of download).

    ** These fields are editable via the details form.

9. More Information

You can find the latest uDownloadTM information including Frequently Asked Questions, Troubleshooting Tips, and More on our uDownloadTM Reference Site at:

http://www.uburst.com/uDownload/reference.html