Short Version:

1. Unzip the downloaded file.
2. Upload the folder named 'app' to the root directory of your Magento installation.
3. Flush the Magento cache.

Important Note: Always backup your store's existing files and database before installing any extension in case something goes wrong. (Power failure, anyone?) Also, installing any extension directly to a 'live' production site without first testing on a 'staging' or 'test' site for compatibility with other extensions or modifications is always strongly discouraged.

The Serial Codes extension may be installed (or updated) using whatever method you normally use to install files onto your Magento website server. It may be installed or updated quickly and easily using any FTP client. There are many, many free and paid FTP clients available on the internet. An FTP client allows for remote access to upload, download, or edit the files on your web server from your own computer. If you don't already have an FTP client installed on your computer, Filezilla is an excellent, free, open source FTP client that is updated frequently. Your Website Hosting Service Provider should provide you with the settings (such as username and password) needed to access your website through FTP.

After purchasing the Serial Codes extension from our website, download the .zip file to your computer and extract (unzip) the files (How? Windows, Mac OS). This will extract the necessary files into a new folder on your computer, usually with the same name as the .zip file (e.g., "serialcodes"). Open this new folder with your FTP client (How? Using Filezilla) and upload the folder inside named 'app' to the root directory of your Magento installation on the server. (There will already be a folder named 'app' in the Magento root directory on your web server. The FTP upload will not overwrite any existing files, but will merely place the Serial Codes files where they belong within that same folder.)

You may also wish to take a look at file permissions (which can usually be changed through your FTP client), but frankly, that shouldn't be necessary. Most web servers now days are configured to apply the proper permissions to newly created files and folders by default. If not, you may wish to consider changing your website hosting service in order to save yourself the grief.

Once the files are installed on the server, login to the Admin Panel of your Magento store, navigate to "System > Cache Management" and either refresh the cache or click on 'Flush Magento Cache' depending on your version of Magento. This should complete the installation.

Extension Enabled

New Menu Items

You can check to see if the extension is now installed by navigating to "System > Configuration," scrolling down and clicking on the "Advanced" tab (within the "Advanced" group of tabs), and then opening the "Disable Modules Output" tab to view the list of enabled modules. Near the bottom of the list should be a module named 'Mmsmods_Serialcodes' and it should be enabled. If you ever need to disable the output of the Serial Codes extension for any reason, you can do so here.

There should also be two new menu items visible, "Serial Code Order Items" under the "Sales" menu and "Manage Serial Codes" under the "Catalog" menu. A new table should appear on the Order View page titled "Serial Codes Issued" below the "Items Ordered" table. Finally, if you navigate to "Catalog > Manage Products" and click on a product to edit it, you should find a new attribute group tab on the left entitled 'Serial Codes' which contains a number of new settings (attributes).

A file map of all the included source files is provided below so that you can make sure all files are located in the proper folders if you have any problems.

If this installation process seems like more that you you want to deal with, you can ask your Website Hosting Service Provider to install the Serial Codes files for you. Most reputable hosting service providers will assists customers with installing files and software on their website, either for free or for a small fee.

Short Version:

1. Navigate to "Catalog > Manage Serial Codes" and add the Serial Codes.
2. If you wish to deliver Serial Codes by email to customers at checkout, navigate to "System > Transactional Emails" to create or modify the template to be used for this product or products.
3. Navigate to "Catalog > Manage Products," click on the product to edit it, open the "Serial Codes" tab and configure the attributes shown.

The Serial Codes extension can be set up to issue Serial Codes automatically based on a successful customer purchase (at checkout). A Serial Code will be issued for each item ordered based on quantity. The issued codes are added to the existing Magento database table (sales_flat_order_item) that keeps track of information for each item ordered. This means that issued Serial Codes data will always be available to any Magento module that requires this information. Instructions on how to access this data are provided below in case you wish to modify other aspects of Magento to include these codes.

How To Add Serial Codes

Add Serial Codes

Manage Serial Codes

When using Serial Codes for a product, the first thing to do is to set up the list of Serial Codes that will be distributed for that particular product. This is accomplished by navigating to "Catalog > Manage Serial Codes" in the Admin Panel where you can add, edit, delete, view, and maintain all of your lists of Serial Codes. You can add additional Serial Codes to your lists at any time by repeating these instructions.

1. Click the "Add Codes" button in the upper right of the screen. This will take you to a form that will allow you to add a list (or pool) of Serial Codes.
2. SKU (or Code Pool) - Enter the 'SKU' of the product that will be issuing these Serial Codes. The unique SKU for each product can be found by navigating to "Catalog > Manage Products" and clicking on the product row. If you prefer not to use product SKUs to assign Serial Codes, or you wish to have more than one product issue from the same list of Serial Codes, see Code Pooling below. This field is required.
3. Serial Code Type - Enter the 'Serial Code Type' (e.g., 'Serial Number' or 'Product Key'). This field is used merely to assist you in organizing and sorting the Serial Codes, so you could actually enter any value you choose here. The customer will never see the contents of this field. The actual Serial Code type that will be issued is set as a product attribute (see below). This field is optional.
4. Codes (one per line) - Now, enter the list of actual 'Codes' to be distributed, one per line. If you have a long list of codes to use, you can cut and paste them into the form. This field is required.
5. Click on the "Save Codes" button.

You will be returned to the "Manage Serial Codes" screen and the grid will now be populated with the list of Serial Codes. This grid has the full range of

Edit Serial Code

Manage Serial Codes

standard Magento features including sorting and filtering by any column, mass 'Delete,' mass updating of 'Code Type,' 'SKU,' or 'Status,' and the ability to edit the values in any single row by clicking on that row.

When Serial Codes are automatically issued, the status for the code that was issued is changed from 'Available' to 'Used,' the order number is placed in the 'Note (Order)' column, and the date/time is 'Updated.'

Email Templates

Delivery Template

Specific email templates can be assigned directly to a product at the store view level and may be customized using the standard Magento tools to include product specific text. If you wish to automatically notify customers of issued Serial Codes by email at the time of the order, you should navigate to "System > Transactional Emails" and set up your email template(s) next. Note that email templates may be assigned to each product at the store view level. This allows for translation of emails into multiple languages.

Two new default email templates have been provided entitled 'Serial Codes Delivery' (filename: 'serialcodes_delivery.html') and 'Serial Codes Low Warning' (filename: 'serialcodes_warning.html'). The 'Serial Codes Delivery' template is meant to be used to deliver issued Serial Codes to the customer and contains the following email variables by default:

• {{var emailtype}} - An email type (e.g., Warranty or Instructions) may be designated for each product (explained below) and is returned by this variable.
• {{var codetype}} - The type of Serial Code (e.g., Serial Number or PIN) is returned by this variable.
• {{var itemshtml}} - This variable returns HTML code that displays the product name along with the Serial Codes issued for that product on this order. The HTML returned may be styled using CSS and is similar to the following:
  <div class="sc_items"> <span class="sc_product">[Product Name]</span><br /> <span class="sc_type">[Serial Code Type]: </span> <span class="sc_code">[Serial Code]</span><br /> ... </div>
• {{var itemstext}} - Returns the plain text version without any HTML tags.
• {{var order}} - Returns the order object which allows additional information from the order to be displayed (e.g., {{var order.getCustomerName()}} will return the customer name). Check this Magento Wiki page for additional information. Look for variables that begin with "var order." Be forewarned, however, that the listed variables don't appear to be organized that well and it seems doubtful that this list is comprehensive.

The 'Serial Codes Low Warning' template can be used to deliver warning messages to site administrators and/or others (such as vendors) when the number of available codes remaining reaches a specified level (see Product Attributes below). It contains the following email variables by default:

• {{var product}} - The name of the product which generated this warning is returned by this variable.
• {{var available}} - the number of remaining Serial Codes is returned by this variable.
• {{var none}} - This variable returns 'true' if no Serial Codes are available to issue.
• {{var codetype}} - The type of Serial Code (e.g., Serial Number or PIN) is returned by this variable.
• {{var pool}} - Returns the SKU or Code Pool that is low on available Serial Codes.
• {{var order}} - Returns the order object which allows additional information from the order to be displayed (e.g., {{var order.getCustomerName()}} will return the customer name). Check this Magento Wiki page for additional information. Look for variables that begin with "var order." Be forewarned, however, that the listed variables don't appear to be organized that well and it seems doubtful that this list is comprehensive.

Product Attributes

Product Attributes

This is where all the magic happens. Navigate to "Catalog > Manage Products," find the product that will be issuing Serial Codes, and click on it to edit its attributes. Now, click on the "Serial Codes" tab on the left. A form containing the following attributes will be shown. Note that these attributes may be set at the store view level. This provides fine control over how Serial Codes are issued and allows for translation into multiple languages.

1. Serial Codes Enabled - Set this field to 'Yes' to automatically issue Serial Codes for this product to the order upon successful customer checkout. This field is required by default.
2. Code Pool (SKU) - If you wish to have more than one product issue from the same list of Serial Codes, or you prefer not to use product SKUs to assign Serial Codes, then copy the value here that was used in the "SKU (or Code Pool)" field when the list of Serial Codes was added. Leave this field blank if you wish to issue Serial Codes based on product SKU. See Code Pooling below for more information. This field is optional.
3. Serial Code Type - Enter the 'Code Type' (e.g., 'Serial Number' or 'Enrollment Key'). Use the singular tense (e.g., 'Serial Number' rather than 'Serial Numbers'). This is the Serial Code type that will be added to the order and displayed to the customer. This field is required for proper operation.
4. Not Available Message - Enter a customized message (containing contact information, for example) to be delivered to the customer if for some reason a Serial Code cannot be issued for the purchased product. The text "Oops! Not available." will be generated if this field is left blank. This field is optional.
5. Show on Customer Order - Decide whether or not to show issued Serial Codes to registered customers on each order when logged into their account. This field is required by default.
6. Send Customer Email - Decide whether or not to deliver Serial Codes notifications by email to customers at checkout. This field is required by default.
7. Delivery Email Template - Select the email template to use for delivering Serial Codes to the customer. If the same template is used for more than one product, then a single email will be sent containing all of those products. You can also choose to send a separate email for each product by using a different template for those products. This field is required by default.
8. Email Type - Allows you to designate an email type (e.g., Warranty or Instructions) that can be used within the email itself and will also appear within the "email sent" notification that appears on the checkout success page. This field is optional.
9. Email Blind Copy To - If you wish to send blind copies of Serial Codes delivery emails to site adminstrators, enter the email address(es) here. Separate each provided email address with a space (do not use commas, semicolons, or other delimiters). This field is optional.
10. Low Warning Level - When the number of available Serial Codes reaches this level (or less), a warning email will be generated and sent to the address(es) listed below. This field is optional.
11. Low Warning Email Template - This is the template to be used for the warning. This field is required by default.
12. Email Low Warning To - If you wish to send a warning message when Serial Codes are running low, enter the email address(es) here. Separate each provided email address with a space (do not use commas, semicolons, or other delimiters). This field is optional.

Code Pooling

Code Pooling

If you find keeping track of Serial Codes based on product SKUs to be confusing or difficult, or if you need to issue Serial Codes to more than one product from the same list of codes, then you can use code pooling. Just make sure the "Code Pool (SKU)" product attribute field contains the same value as the "SKU (or Code Pool)" field under "Manage Serial Codes." This field may contain any alphanumeric value, including the SKU of another product.

For example, your business sells distance education programs (a programming course and a design course) for which you provide online testing. In order to gain access to the online testing application, the student must enter a unique "enrollment key." You can have both courses issue keys from the same pool of keys. Click on the small illustration to the right to view an example of how to set this up.

Bundled Products

Bundled Products

You may issue Serial Codes for bundled products to the parent product, to any or all of its child products, or to both at the same time. Since you configure Serial Codes for each product individually through product attributes, this gives a great deal of freedom in how bundled products are set up. You may want to pool the Serial Codes for some bundled products, or their child products, and not others, only show some issued Serial Codes on the customer order, send email notifications only for particular products, and/or combine all of the Serial Codes issued for a bundled product and its children into a single email notification. How you implement this functionality is strictly up to you.

Configurable Products

For configurable products, you may issue Serial Codes from either the parent product or from the child products, but obviously not from both at the same time. No matter which way the Serial Codes are issued, they will always be associated with the parent product on the order.

Let's take our example from the Code Pooling topic above where you happen to sell distance education programs (a programming course and a design course) for which you provide online testing. This online testing requires an "enrollment key" to access the test. Instead of setting up each course as a separate product, you decide to create a configurable product where the customer can choose which of the two courses they wish to purchase. If you decide to issue Serial Codes from the parent product, you end up with a configuration similar to the Code Pooling example above where both courses are issued Serial Codes from the same list of codes. However, if you choose to issue Serial Codes from the child products, this allows the Serial Codes issued to differ based on which course was ordered, similar to selling each course separately and not implementing Code Pooling. It's entirely up to you how you wish to use this functionality.

Payment Types

Serial Codes can be automatically issued during checkout once payment has been successfully authorized and the customer is redirected to the checkout success page. This is independent of the actual status (e.g., processing, pending, complete) of the order. This allows the customer immediate access to the relevent Serial Codes once they have actually purchased the product.

Before issuing the codes, the extension checks for deferred payment methods ("Check or Money Order," "Cash On Delivery," or "Bank Transfer") and no Serial Codes are issued in the event one of these payment methods is used (additional deferred payment methods from specific payment modules are also supported). Instead, the message "Issued when payment received." is generated. Serial Codes may then be added to the ordered item automatically or manually by editing the order once payment is received.

Editing Ordered Items

Sales Order Edit

Sales Order View

There are two methods available for viewing, adding, editing, or deleting Serial Codes within existing orders and an additional method for automatically issuing Serial Codes from the Admin Panel with the click of a button. You may navigate to "Sales > Orders" and click on the row of the order you wish to view or edit. If you scroll down, you will notice a new table below the "Items Ordered" table which shows the Serial Codes issued for each item on this Sales Order.

There is a button in the heading of this table which allows you to automatically issue Serial Codes for selected items on this order. First, select the item(s) for which you wish to issue codes in the first column of the table, then click on the "Issue Serial Codes" button. This will automatically issue Serial Codes to these items from the appropriate code pool and update all relevant tables and data. Please note that this will overwrite any codes already issued for the selected items. You may also "Email Serial Codes" to the customer from this same interface.

To the right of each item in this table is an "Edit" link. Clicking this link will generate a popup form where the Serial Code type and/or the actual Serial Code(s) for that particular item may be added, edited, or removed. Generally speaking, you will probably want the number of codes issued to match the quantity (Qty) of the item ordered.

Order Items

Edit Order Items

You may also view Serial Codes within existing orders by navigating to "Sales > Serial Code Order Items." This provides a sortable grid of all items on all existing orders including their issued Serial Codes. You may make changes by clicking on the row of the item you wish to edit. This will take you to a form where you may add, remove, or change the Serial Code type and/or the actual Serial Code(s) for that particular item on that particular order.

You can manually add Serial Codes to an existing order by first navigating to "Catalog > Manage Serial Codes," and selecting the Serial Code(s) you wish to add to the order. Change the staus from "Available" to "Used" (you can also enter a "Note" which could include an order number). Once you have saved your changes, use one of the two methods mentioned above to enter the Serial Code type and the actual Serial Code(s) that you previously designated as "Used." Click on the "Save Codes" button to save your changes.

Serial Codes may be manually removed from an order and/or placed back into the queue to be reissued by reversing this process. Any Serial Code whose status is set to "Available" will be automatically issued to any new orders.

Language Translations

This extension supports Magento translations including the "Translate Inline" functionality. Setting product attributes at the store view level also allows for language translation of most values the customer will see through the frontend of your store(s). An English language translation file containing all the text strings generated by this extension has been installed at "[Magento Root]/app/locale/en_US/Mmsmods_Serialcodes.csv" to allow for changes to the English text and to assist in translating to other languages.

Access Control

Role Resources

Backend access control for specific users and roles is enabled for the Serial Codes extension. Access control has been separated into four resources which can be enabled or disabled individually:

Getters and Setters

The Serial Codes extension allows access to all stored data using the standard Magento getter and setter magic methods.

File Map

The following files are included in Serial Codes version 1.3.1:

The Serial Codes extension has been designed and tested to be compatible with the following Magento Community Edition versions:

1.3, 1.4, 1.5, 1.6, 1.7

There are currently no known incompatibilities with any other Magento extensions. Please let us know if you have any problems.

While this extension will issue multiple Serial Codes for each product ordered based on quantity, it currently has the ability to issue only one Serial Code type per product and store view (translatable into multiple languages). If more than one Serial Code type is needed for a product, the work-around is to merge the codes and separate them with delimiters (we like using the 'pipe' symbol for this, but any symbol can be used). For example, your store sells online subscriptions that require a Username and a Password for the customer to gain access to the resource. You could use the following:

Serial Code Type: Username | Password
Serial Code: member0003 | 4321!z9876#

This will appear to the customer as:

Username | Password: member0003 | 4321!z9876#

Note that spaces are allowed since they may help with legibility.

Version 1.3.1 (Current Version)

This is a security update. We were made aware of an exploit through Paypal that would allow serial codes to be issued without being paid for. This update closes that vulnerability.

Version 1.3.0

Added Features

Provided immediate access within each row of the Serial Code Order Items grid to the the actual order or customer data by clicking on the order number or customer name for that item.

Added support for additional deferred payment methods for specific payment modules--the Bank Transfer and Direct Debit methods from MultiSafepay (Netherlands), the Direct Debit and Purchase Order methods from SecurePay (Australia), and the eCheck method from PayPal (International).

Bug Fixes

Fixed a bug that caused the Downloads Available text not to appear for downloadable products within the Items Ordered table on the Order View page in the Admin Panel.

Version 1.2.1

Added Features

Added the ability to automatically issue and/or deliver Serial Codes directly from the Sales Order View page in the Admin panel.

Added the ability to email a warning when the number of available Serial Codes is getting low.

Included logic to withhold automatic issuing of Serial Codes for the additional deferred payment types of "Cash On Delivery" and "Bank Transfer."

Improved the display of line items in the "Serial Codes Issued" table on Order View page. This is most noticeable for Bundled products.

Changed Serial Codes product attribute email template dropdowns to include only the relevant templates.

Added instructive text to all Serial Codes product attributes.

Updated English translation CSV file with new string translations.

Bug Fixes

Fixed a potential issue with some Serial Codes product attributes possibly not loading properly if the product was not saved after installation of the extension.

Addressed an issue where some Serial Codes data was not being properly trimmed prior to use by the extension.

Version 1.1.0

Added Features

Incorporated the ability to view, add, edit, or delete issued Serial Codes directly from the Sales Order View page in the Admin panel.

Updated Access Control to also allow editing of Serial Codes on existing orders to be disabled while still allowing the issued Serial Codes to be viewed by the Admin user.

Added English language translation CSV file to allow for changes to the English text and to assist in translating to other languages.

Bug Fixes

Fixed a bug that caused the Serial Code Order Items grid not to populate under a certain specific set of conditions.

Version 1.0.0

Original Version