Welcome!

Providing Effective Solutions to Enhance Your Magento Store

Using Serial Codes (Instructions)

Instructions Archive

What Are Serial Codes?

The Magento Serial Codes extension allows you to easily manage and automatically deliver Serial Numbers, Product Codes, PINs, Activation Keys, Enrollment Keys, Usernames, Passwords, and more to your customers from your Magento store, together with professionally presented Instructions, Warranties, Rules, or whatever other customized text is required.

There are many business models that require the sale of products with unique Serial Numbers, Product Keys, PINs, Activation Codes, Enrollment Keys, Game License Keys, Usernames, Passwords, Contest Codes, ID Numbers, etc.—the list goes on and on. In an effort to assist with discussion and avoid confusion, we have adopted the term 'Serial Code' as shorthand for any piece of information that must be uniquely issued for each individual product sold. This term is used throughout our documentation, and is also used by our extension within the Magento Admin Panel. It contains two parts—the type of Serial Code (e.g., Serial Number) and the actual value of the Serial Code (e.g., 12345A67890).

Installation and Upgrading

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.

Please Also Note — This Is Important: Always remember to navigate to "System > Tools > Compilation" (Magento Community Edition version 1.4.2 or later) in the Admin Panel and make sure that compilation is disabled prior to installing any extension or modification. Once the update is properly installed, do not just re-enable compilation or our module will not be included and errors will result. Instead, run the compilation process again and our module will be included with no issues.

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 Magento 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
Extension Enabled
New Menu Items
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.

Serial Codes Maintenance

How It Works (Overview)

The Serial Codes extension provides a great deal of flexibility in how Serial Codes are issued and delivered to customers. It can be set up to assign and issue Serial Codes automatically to all orders. It can also be set up to only issue and deliver Serial Codes when an item is actually invoiced and paid for, or based upon selected customer groups, or based merely upon a successful customer purchase at checkout. Or, it can be used to automatically or manually issue and deliver Serial Codes to your customers once the order has been reviewed. This flexibility is provided for at the product and store view level, so that different criteria may be used for each product and store.

In order for the extension to automatically issue Serial Codes, a list (or pool) of codes to be issued must be entered and associated with a particular product or products. These pools of Serial Codes are stored in their own database table, which provides the ability for each product to have its own code pool, or for multiple products to issue from the same code pool.

Each Serial Code in a code pool has a status associated with it. There are three possible statuses: "Available" (ready to be assigned or issued), "Used" (already issued to a customer order), and "Pending" (assigned to an order, but not issued to the customer). The "Pending" status allows for codes to be assigned to deferred payment (e.g., Bank Transfers, Check or Money Orders, Purchase Orders, Cash On Delivery) orders, and other orders where payment has not yet been received, without actually delivering them to the customer. This helps in tracking and inventory control. When an order is cancelled, "Pending" codes are removed from the order and returned to "Available" status to be used again since no customer has actually received them.

A Serial Code will be assigned or issued to the customer order for each item based on the quantity ordered. The assigned and 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 assigned or 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 there is a need to modify other aspects of Magento to include these codes.

The Serial Codes extension provides for full editing of available, issued, or assigned Serial Codes and existing orders to authorized administrators. This allows administrators to add, remove, change status, issue, or deliver Serial Codes to any order from the Admin Panel. Authorization may be limited to specific users and roles. This is especially useful when Serial Codes need to be issued or delivered manually, or for special orders or circumstances.

Also included is a product level setting which allows for inventory stock quantities and availability to be kept current automatically based on the number of remaining available Serial Codes. Inventory stock management must be enabled ("[Product] > Inventory > Manage Stock" must be set to "Yes") or this setting will be ignored. This feature allows for the use of the built-in Magento functions of disabling or backordering products that are low on inventory based on the remaining "Available" Serial Codes.

Please use the following instructions to properly set up the Serial Codes extension:

How To Add Serial Codes

Short Version:

  1. Navigate to "Catalog > Manage Serial Codes" and add the Serial Codes.
  2. If you wish to deliver Serial Codes to customers by email, 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.
Manage Serial Codes
Manage Serial Codes
Add Serial Codes
Add Serial Codes

In order to automatically issue Serial Codes when a product is purchased, or to allow for issuing codes automatically once an order has been reviewed by an administrator, a pool of codes must be set up 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 pools at any time by repeating these instructions. This feature is only available to authorized administrators.

  1. Click the "Add Codes" button in the upper right of the page. 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 and issue 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 copy and paste them into the form. This field is required.
  5. Click on the "Save Codes" button.
Manage Serial Codes
Manage Serial Codes
Edit Serial Code
Edit Serial Code

You will be returned to the "Manage Serial Codes" page and the grid will now be populated with the list of Serial Codes. This grid has the full range of standard Magento features including sorting and filtering by any column, mass 'Delete,' mass updating of 'Code Type,' 'SKU (Code Pool),' or 'Status,' and the ability to edit the values in any single row by clicking on it.

When Serial Codes are assigned or issued to an order, the status for those codes is changed from 'Available' to either 'Pending' or 'Used,' the order number is placed in the 'Note (Order)' column, and the date/time is 'Updated.' The sorted and filtered data contained within this grid may be exported to a file on your computer utilizing either CSV or XML formating.

Email Templates

Email Template
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 codevalue}} - Contains the actual Serial Code that was issued. Intended to be used when each Serial Code is being sent in its own separate email. This variable is only populated with a value when the product attribute "Send As Voucher" is set to "Yes," otherwise it is ignored (prints a blank) in the email.
  • {{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
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 (this tab is only visible to authorized administrators). A form containing the following attributes will be shown. Note that most of 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. Issue When Invoiced - Set this field to 'Yes' to automatically issue Serial Codes for this product when the order is invoiced and paid. This occurs when the invoice is created/saved and not when the invoice is sent. The codes will be issued and delivered whether the customer ends up on the order success page or not. If the invoice is still in a pending status (under payment review, for example), or the customer used a deferred payment method so no invoice was created, the codes will still be assigned to the order, but will not be shown or delivered to the customer. When the invoice is marked paid (by capturing it, for example), the codes will be automatically delivered to the customer. Partial invoicing of orders is fully supported. Once again, when an order is cancelled, "Pending" codes are removed from the order and returned to "Available" status to be used again since no customer has actually received them. Supports multiple invoicing of orders by only issuing codes to items that have actually been invoiced and paid on each order. This field is required by default.
  2. Issue On Checkout (Not Recommended) - Set this field to 'Yes' to automatically issue Serial Codes for this product to the order upon successful customer checkout. This is intended to be used only by merchants that are using an older version of Magento or payment methods that don't automatically invoice the order when payment is made. The codes are issued and delivered when the customer reaches the order success page. Because of how this works in older versions, codes are sometimes issued when the order is still in a "Pending" status. If code security is an issue, then this option should not be used. This field is required by default.
  3. Customer Groups
    Customer Groups
    Issue By Customer Group - Set this field to "Yes" to automatically issue Serial Codes for this product based on customer group. This option may be used to always issue or assign Serial Codes to every order. This may also be used in conjunction with the first attribute, "Issue When Invoiced" to allow for issuing and delivering codes to all orders that are invoiced and paid, and also to deferred payment orders (e.g., Bank Transfers, Check or Money Orders, Purchase Orders, Cash On Delivery) for the selected trusted customer groups. This field is required by default.
  4. Select Customer Groups - Use this field to choose the customer groups that will automatically receive issued Serial Codes. Hold down the [Ctrl] key while clicking on the group to select multiple groups. Serial Codes will be issued to the selected groups regardless of order status or payment method. If this option is enabled, groups not selected will have the codes assigned to the order as "Pending." By selecting all of the available customer groups, the extension will always issue Serial Codes for this product and make them available to the customer. By selecting none of the available groups, Serial Codes will always be assigned as "Pending" for this product. This field is only visible if "Issue By Customer Group" is set to "Yes" and is optional.
  5. 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 (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.
  6. 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. Defaults to "Serial Code" if left blank. This field is generally required for proper operation, but is optional.
  7. 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.

  8. Update Inventory Stock - Determines whether to maintain inventory stock quantities based on the number of remaining available Serial Codes. Inventory stock management must be enabled ("[Product] > Inventory > Manage Stock" must be set to "Yes") or this setting will be ignored. This is a global setting since Magento only manages inventory stock at the global level. This field is required by default.
  9. Show on Customer Order - Determines 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.
  10. Delivery Email
    Delivery Email
    Send Customer Email - Enables the automatic delivery of Serial Codes by email to customers at checkout or when an order is invoiced. Supports multiple invoicing of orders by only displaying codes for items that have actually been invoiced and paid. This field is required by default.
  11. Send As Voucher - Setting this to "Yes" will cause each of the issued Serial Codes for each line item to be delivered in it's own individual email rather than grouped together in one email. For example, if you sell three "Super CD Keys" on the same order, three emails will be sent instead of one. The variable that will display the actual Serial Code within the email itself is {{var codevalue}}. This variable is only populated with a value when the product attribute "Send As Voucher" is set to "Yes," otherwise it is ignored (prints a blank) in the email. This field is only visible if "Send Customer Email" is set to "Yes" and is required by default.
  12. 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 only visible if "Send Customer Email" is set to "Yes" and is required by default.
  13. 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 only visible if "Send Customer Email" is set to "Yes" and is optional.
  14. Email Blind Copy To - If you wish to send blind copies of Serial Codes delivery emails to site administrators, 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 only visible if "Send Customer Email" is set to "Yes" and is optional.
  15. Warning Email
    Warning Email
    Send Low Warning Email - Enables sending of emails to administrators and others notifying that the number of remaining Serial Codes for this product is getting low. This field is required by default.
  16. Low Warning Template - This is the template to be used for the warning. This field is only visible if "Send Low Warning Email" is set to "Yes" and is required by default.
  17. 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. If this field is left empty, a warning will only be sent when no available Serial Codes are left for this product. This field is only visible if "Send Low Warning Email" is set to "Yes" and is optional.
  18. Email Low Warning To - If you wish to send a warning message when Serial Codes are running low, you must enter the email address(es) to receive the notification here. Separate each provided email address with a space (do not use commas, semicolons, or other delimiters). This field is only visible if "Send Low Warning Email" is set to "Yes" and is generally required for proper operation, but is optional.

Code Pooling

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
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.

Simple Product Custom Options

Serial Codes may also be assigned or issued based on simple product custom options. Under Manage Serial Codes, just enter the full SKU for the product generated by the selected options into the "SKU (or Code Pool)" field. This SKU can be found on the Order View page within the Items Ordered table right under the product name. It is created using the main product SKU and appending the chosen option SKUs one by one with dashes in between:

[product sku]-[option one]-[option two]...etc.

For example, your business sells t-shirts with two options, size and color. The main SKU is "T-shirt." You have three size options with SKUs of "large," "medium," and "small." You have two colors with SKUs of "yellow" and "blue." If a customer chooses a large, yellow t-shirt, the generated SKU would be:

T-shirt-large-yellow

This is the SKU that needs to be entered in the Manage Serial Codes field. Please remember that Magento does not allow for tracking of inventory stock quantities based on custom options. If inventory tracking is desired, then configurable products should be used instead.

Payment Methods

Magento provides the ability to purchase products using deferred payment methods (e.g., Check or Money Order, Cash On Delivery, Bank Transfer, or Purchase Order) where payment for a purchase will be received at a later time. Some third party payment modules add additional deferred payment methods. Since many merchants only wish to deliver Serial Codes to orders that are actually paid for, a check for the payment method used is executed prior to automatically issuing codes whenever this is relevant. This is based on the method being used to automatically issue the codes. There are three methods available for automatically issuing Serial Codes to the order, "Issue When Invoiced," "Issue On Checkout," and "Issue By Customer Group."

The "Issue When Invoiced" setting will automatically issue Serial Codes for this product when the ordered item is invoiced and the invoice is paid. Unpaid invoices and deferred payment orders will have codes assigned to them as "Pending." These will not be made available to the customer. Instead, the message "Issued when payment received" is displayed. Once the invoice is marked paid (for example, by capturing the item on the order), the status of the assigned codes will be changed to "Used" and they will be made available to the customer. Partial invoicing of orders is fully supported. If an order is cancelled, all "Pending" codes will be removed from that order, and they will be made "Available" again so that they may be issued to a new order. This is a secure method for issuing Serial Codes, since the customer will only receive them once the invoice is marked as paid.

While the "Issue On Checkout" setting is not generally recommended, it is available for those merchants who need to use it. This includes merchants who are still using an older version of Magento or payment methods that don't automatically invoice the order upon successful payment. When using this method, Serial Codes are issued when the customer arrives on the order success ("Thank you") page. Prior to issuing the codes, the extension checks for the order status and the payment method used. If the order status is anything other than "Pending," "Processing," or "Complete," or if the payment method used is a deferred payment method, then codes are not issued to the order but are assigned to the order as "Pending." Again, these will not be made available to the customer. Instead, the message "Issued when payment received" is displayed. Once the item is invoiced and marked paid (for example, by capturing the item on the order), the status of the assigned codes will be changed to "Used" and they will be made available to the customer. If an order is cancelled, all "Pending" codes will be removed from that order, and they will be made "Available" again so that they may be issued to a new order.

Please Note: Since the customer must be returned to the order success page for codes to be issued, and since codes might sometimes be issued to a pending order when using this method, the "Issue On Checkout" method is not as reliable or secure as the other two methods. When using some payment methods (such as PayPal), it is possible for a customer to accidently or intentionally exploit the system to gain access to Serial Codes without actually paying for them. This method should not be used if Serial Code security is a critical issue. (It is possible to vastly improve security when using this method with a simple modification to disable issuing of codes to orders with a "Pending" status. Please let us know if you need this modification.)

The "Issue By Customer Group" setting may be used to automatically assign or issue Serial Codes for this product based on customer group. Serial Codes will be issued to the selected groups regardless of order status or payment method. By selecting all of the available customer groups, the extension will always issue Serial Codes for this product to every order and make them available to the customer.

If this option is enabled, groups not selected will have the codes for this product assigned to the order as "Pending." By selecting none of the available customer groups, Serial Codes will always be assigned as "Pending" for this product. Once again, "Pending" codes will not be made available to the customer. Instead, the message "Issued when payment received" is displayed. If an order is cancelled, all "Pending" codes will be removed from that order, and they will be made "Available" again so that they may be issued to a new order.

This setting may be used in conjunction with the first attribute, "Issue When Invoiced" to allow for issuing and delivering codes to all orders that are invoiced and paid, and also to deferred payment orders (e.g., Bank Transfers, Check or Money Orders, Purchase Orders, Cash On Delivery) for the selected trusted customer groups.

When using this setting, once all codes are assigned to an item as "Pending," those codes may be issued (status changed to "Used") and delivered to the customer by using the "Issue Serial Codes" and "Email Serial Codes" buttons on the Order View page.

Tracking Serial Codes

Order View Page

Sales Order View
Sales Order View

If you navigate to "Sales > Orders" and click on the row of the order you wish to view or edit, then scroll down, you will notice a new table below the "Items Ordered" table which shows the "Serial Codes Issued" or assigned for each item on this sales order. Codes that have been entered manually and are not associated with a code pool will be marked as "Manual." Codes that have been assigned to the ordered item, but are not yet visible to the customer, will be marked as "Pending." A "Warning!" will be displayed for issued Serial Codes that still have a status of "Available," which would allow the same code to be issued again to another 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. 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 which allows the Serial Code type and/or the actual Serial Code(s) for that particular item to be manually added, edited, or removed. This feature may be used to manually issue Serial Codes.

Ordered Items Page

Ordered Items
Ordered Items

The Ordered Items page may be found by navigating to "Sales > Serial Code Order Items." This page contains a grid that lists all of the items ordered by customers and any Serial Codes that have been assigned or issued to those items. It's a great place to monitor all store sales and contains links to the Order, Product, Customer, and Code Pool for each item ordered. These links are limited to admin users and roles that have been granted access to that particular information. Clicking on any item row allows the Serial Code type and/or the actual Serial Code(s) for that particular item to be manually added, edited, or removed. This feature may be used to manually issue Serial Codes to the order.

Serial Codes that have been entered manually and are not associated with a code pool will be marked as "Manual." Codes that have been assigned to the ordered item, but are not yet visible to the customer, will be marked as "Pending." A "Warning!" will be displayed for issued Serial Codes that still have a status of "Available," which would allow the same code to be issued again to another order.

This grid may be sorted and/or filtered on any column. It may be filtered to display only items which have Serial Codes assigned or issued to them by using an asterisk (*) to filter the "Serial Codes" column. The sorted and filtered data contained within this grid may be exported to a file on your computer utilizing either CSV or XML formatting.

Editing Ordered Items

Sales Order Edit
Sales Order Edit
Edit Ordered Items
Edit Ordered Items

Serial Codes can be added, edited, or deleted on existing orders from either the "Order View" or the "Serial Code Order Items" page. This feature is especially useful for special orders or circumstances, or when Serial Codes need to be issued or delivered manually. It is only available to those administrators who have been given permission to edit ordered items (the "Serial Code Order Edit" resource is checked under access control).

From the "Order View" page, scroll down to the "Serial Codes Issued" table. To the right of each item in this table is an "Edit" link. Clicking this link will allow you to edit the Serial Codes for this item. You may make changes from the "Serial Code Order Items" page by clicking on the row of the item you wish to edit.

Either method will display a form where the Serial Codes for that particular item on that particular order may be added, removed, or edited. This form will display (for reference only) the order number, customer name, product name, and quantity ordered for that particular item. It will also allow you to edit the Serial Code type, the actual Serial Codes themselves, and the number of Serial Codes issued.

The "Serial Code Type" shown here is what is actually displayed to the customer. The "Serial Codes (one per line)" field will contain the actual assigned or issued Serial Codes for this item. It may also include any messages (such as "Oops! Not Available.") that you wish to display to the customer. All of the actual codes assigned or issued to this item should be placed before (above) any messages that may appear.

The "Number Serial Codes Issued" field is used to keep track of the numder of Serial Codes actually assigned or issued to this item. It is also used to protect existing codes for this item from being overwritten when Serial Codes are automatically assigned or issued, such as when the order is invoiced or when the "Issue Serial Codes" button is used. It should match the number of actual codes assigned or issued to this item, not including any messages that may be included below them.

If a pool of Serial Codes has been set up, manually entered codes that match a code contained within the pool will be automatically tied to the pool. However, the status of the entered code will not be automatically changed. The status will have to be changed manually from the "Manage Serial Codes" page.

Manually issued Serial Codes may be delivered to the customer through email by using the "Email Serial Codes" button on the "Order View" page.

Other Features

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 to English language translation file containing 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
Role Resources

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

Serial Code Order Items - Disables the ability to view, add, edit or delete Serial Codes on existing orders.

Serial Code Order Edit - Disables the ability to add, edit, or delete Serial Codes on existing orders while still allowing them to be viewed.

Manage Serial Codes - Disables the ability to view, install, or edit lists of Serial Codes.

Serial Code Product Attributes - Disables the ability to view, set, or change the value of product attributes associated with this extension (those listed under the Serial Codes tab).

For Developers

Data Access

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

Sales Order Items

Assigned and issued Serial Codes are stored in the database table '[prefix]sales_flat_order_item' in five new columns:

serial_code_type - Stores the Serial Code type (e.g., 'Serial Number' or 'Activation Key') for this item.
serial_codes - Stores a list of the actual codes issued or assigned to this item.
serial_code_ids - Stores a list of Serial Code Ids (from the Serial Codes table) for the actual codes issued or assigned to this item.
serial_codes_issued - Stores the number of Serial Codes actually issued or assigned to this item.
serial_code_pool - Stores the Code Pool or SKU (from the Serial Codes table) that is associated with this item.

and may be returned using the following methods:

getSerialCodeType()     // Returns a string
getSerialCodes()     // Returns a newline ("\n") delimited string
getSerialCodeIds()     // Returns a comma (",") delimited string
getSerialCodesIssued()     // Returns an integer
getSerialCodePool()     // Returns a string

Assuming the order number is "100000001," you could use the following logic to retrieve and display the issued Serial Codes for that particular order:

/* First load the order */ $order = Mage::getModel('sales/order')->loadByIncrementId(100000001); /* Retrieve all the items on the order */ $items = $order->getAllItems(); /* Loop through each item */ foreach ($items as $item) { /* Check to see if item has serial codes */ if ($item->getSerialCodes()) { /* If so, load the product (used to determine status) */ $product = Mage::getModel('catalog/product') ->setStoreId($order->getStoreId()) ->load($item->getProductId()); /* Retrieve the serial code type from the item */ $codetype = $item->getSerialCodeType(); /* Load the serial codes for this item into an array */ $codes = explode("\n",$item->getSerialCodes()); /* Retrieve a parallel array containing the internal id for each serial code */ $codeids = array_pad(explode(',',$item->getSerialCodeIds()),count($codes),''); /* Loop through each serial code */ for ($i=0; $i<count($codes); $i++) { /* Check to see if the serial code status is pending; if so hide it from customer */ if (Mage::getSingleton('serialcodes/serialcodes') ->hidePendingCodes($order, $item, $product, $codeids[$i], $i)) { $codes[$i] = Mage::helper('serialcodes')->__('Issued when payment received.'); } /* Display serial codes */ echo $codetype.': '.$codes[$i]; } } }

Serial Code Pools

You can access the data contained in the Serial Codes table ('[prefix]serialcodes') by loading the Serial Codes collection:

$codes = Mage::getModel('serialcodes/serialcodes')->getCollection()->load();

and using the following methods:

getSerialcodesId()     // Returns the internal Id (an unsigned integer) of the Serial Code. Used to load individual Serial Codes:

$code = $codes->load($id);  // where $id is the internal Id of the requested Serial Code.

SKU (Code Pool) - getSku()     // Returns a string
Serial Code Type - getType()     // Returns a string
Serial Code - getCode()     // Returns a string
Status - getStatus()     // Returns an integer: 0=Available 1=Used
Note (Order) - getNote()     // Returns a string
Created - getCreatedTime()     // Returns a datetime
Updated - getUpdateTime()     // Returns a datetime

Product Attributes

The values of the Serial Codes product attributes can be returned from the product collection (for a single product) by using the following methods:

Issue When Invoiced - getSerialCodeInvoiced()     // Returns an integer: 0=No 1=Yes
Issue On Checkout - getSerialCodeSerialized()     // Returns an integer: 0=No 1=Yes
Issue By Customer Group - getSerialCodeUseCustomer()     // Returns an integer: 0=No 1=Yes
Select Customer Groups - getSerialCodeCustomerGroups()     // Returns an array: Customer Group Ids
Code Pool (SKU) - getSerialCodePool()     // Returns a string
Serial Code Type - getSerialCodeType()     // Returns a string
Not Available Message - getSerialCodeNotAvailable()     // Returns a string
Update Inventory Stock - getSerialCodeUpdateStock()     // Returns an integer: 0=No 1=Yes
Show on Customer Order - getSerialCodeShowOrder()     // Returns an integer: 0=No 1=Yes
Send Customer Email - getSerialCodeSendEmail()     // Returns an integer: 0=No 1=Yes
Send As Voucher - getSerialCodeUseVoucher()     // Returns an integer: 0=No 1=Yes
Delivery Email Template - getSerialCodeEmailTemplate()     // Returns a string or integer: Template Id
Email Type - getSerialCodeEmailType()     // Returns a string
Email Blind Copy To - getSerialCodeSendCopy()     // Returns a space delimited (" ") string
Send Low Warning Email - getSerialCodeLowWarning()     // Returns an integer: 0=No 1=Yes
Low Warning Template - getSerialCodeWarningTemplate()     // Returns a string or integer: Template Id
Low Warning Level - getSerialCodeWarningLevel()     // Returns an integer
Email Low Warning To - getSerialCodeSendWarning()     // Returns a space delimited (" ") string

Observer Events

Many merchants will have specific needs (for example, generating or retrieving codes from offsite, delivering codes through SMS, assigning codes directly to customer accounts, or recording issued codes offsite), or they may need to issue Serial Codes based on specific criteria (such as location, warehouse, or fraud detection), that are not included by default within the extension. This means that the Serial Codes extension may require modification to support these requirements. The extension is designed to simplify this process while allowing for customization without the need to directly modify the default code base.

The Serial Codes extension currently dispatches two events within the issueSerialCodes() method to assist developers in modifying the behavior of the extension using Magento's event observer functionality rather than actually modifying the code base. This will allow future updates to the extension to be installed (that may contain additional functionality) with very little likelihood of creating any conflict with your own personal modifications. Additional events may be dispatched upon request; please let us know when or where in the process you would like them to be triggered.

The events that are currently being dispatched are:

Mage::dispatchEvent('sc_issue_get_codepool_before', array('item' => $item, 'source' => $source, 'issue_options' => $issueoptions))

This event (sc_issue_get_codepool_before) is dispatched within the issueSerialCodes() method just prior to retrieving the codes to be automatically assigned or issued to this item from the database. It is triggered after the extension has determined that codes should be assigned or issued to this item. It passes three arguments to the observer:

item ($observer->getItem()) - An object that contains the item that will receive the assigned or issued codes. From this object the order, store, product, customer, etc. may be retrieved.

source ($observer->getSource()) - A string that contains the origin ('pending,' 'invoice,' 'checkout,' or 'controller') of the call to issue Serial Codes.

issue_options ($observer->getIssueOptions()) - An object that contains an 'option' parameter which may be used to override the normal behavior of the extension. This allows for the use of your own personal criteria in determining how codes are assigned and issued. Objects are passed by reference, so the parameter needs only to be set; it does not need to be returned. The extension currently recognizes and responds to one of three values for this parameter (halt_issue, status_pending, or status_used). Note the following example:

public function doSomething($observer) { /* Retrieve the issue_options object */ $issueoptions = $observer->getIssueOptions(); /* The option parameter may be set to one of the following three values */ /* halt_issue will cause no codes to be assigned or issued to this item */ $issueoptions->setOption('halt_issue'); /* status_pending will cause the codes to be assigned to this item as "Pending" */ $issueoptions->setOption('status_pending'); /* status_used will cause the codes to be issued to this item as "Used" */ $issueoptions->setOption('status_used'); }

Mage::dispatchEvent('sc_issue_after', array('item' => $item,'source' => $source))

This event (sc_issue_after) is dispatched within the issueSerialCodes() method just after any codes are assigned or issued to the ordered item. It passes two arguments to the observer:

item ($observer->getItem()) - An object that contains the item that will receive the assigned or issued codes. From this object the order, store, product, customer, etc. may be retrieved.

source ($observer->getSource()) - A string that contains the origin ('pending,' 'invoice,' 'checkout,' or 'controller') of the call to issue Serial Codes.

Using this functionality requires creating your own module that contains three short files: the module registration file (XML), the module configuration file (XML), and the observer file (PHP) which contains the actual logic to modify the behavior of the extension. That is all that is needed. You will want to change the Namespace and Modulename (along with the associated folders) to your own namespace and module name within all three files. All text located within brackets ( [ ] ) in the following examples should be replaced with the appropriate text for your implementation. Please note the case used as it is significant.

First, use your favorite text editor (we like Notepad++) to create the file that will register your module:

File path: app\etc\modules\[Namespace]_[Modulename].xml

<?xml version="1.0"?> <config> <modules> <[Namespace]_[Modulename]> <active>true</active> <codePool>local</codePool> <depends> <Mmsmods_Serialcodes /> </depends> </[Namespace]_[Modulename]> </modules> </config>

Next, create the file that configures your module:

File path: app\code\local\[Namespace]\[Modulename]\etc\config.xml

<?xml version="1.0"?> <config> <modules> <[Namespace]_[Modulename]> <version>0.1.0</version> </[Namespace]_[Modulename]> </modules> <global> <models> <[namespace]_[modulename]> <class>[Namespace]_[Modulename]_Model</class> </[namespace]_[modulename]> </models> <events> <[name_of_event]> <observers> <[namespace]_[modulename]> <type>model</type> <class>[namespace]_[modulename]/observer</class> <method>[nameOfMethod]</method> </[namespace]_[modulename]> </observers> </[name_of_event]> </events> </global> </config>

Create the file that contains your custom modification logic:

File path: app\code\local\[Namespace]\[Modulename]\Model\Observer.php

<?php class [Namespace]_[Modulename]_Model_Observer { public function [nameOfMethod]($observer) { /* Retrieving passed values (examples) */ $source = $observer->getSource(); $item = $observer->getItem(); $order = $item->getOrder(); $storeid = $order->getStoreId(); $product = Mage::getModel('catalog/product')->setStoreId($storeid)->load($item->getProductId()); $customer = Mage::getModel('customer/customer')->load($order->getCustomerId()); /*** Place custom modification logic here ***/ /* By Magento convention */ return $this; } }

Now, simply upload these three files to the correct location on your server (note the file path) and refresh the cache. (Remember to navigate to "System > Tools > Compilation" (Magento Community Edition version 1.4.2 or later) in the Admin Panel and make sure that compilation is disabled prior to installing any new modules. Once the module is properly installed, do not just re-enable compilation or your module will not be included and errors will result. Instead, run the compilation process again and your module will be included with no issues.) Your module should now be active.

Further information on using event observers in Magento may be found here: Magento for Developers: Part 1 - Introduction to Magento. A video course excerpt containing a detailed description of Magento events and how to use them may be found here: Fundamentals of Magento Development (Event Observers).

File Map

The following files are included in Serial Codes version 1.4.3 (50 files):

[Magento root]/ |- app/ |- code/ | |- community/ | |- Mmsmods/ | |- Serialcodes/ | |- Block/ | | |- Adminhtml/ | | | | Serialcodes.php | | | |- Serialcodes/ | | | | Edit.php | | | | Grid.php | | | | Items.php | | | |- Edit/ | | | | | Form.php | | | | | Tabs.php | | | | |- Tab/ | | | | Form.php | | | |- Items/ | | | | Edit.php | | | | Grid.php | | | |- Edit/ | | | | | Form.php | | | | | Tabs.php | | | | |- Tab/ | | | | Form.php | | | |- Renderer/ | | | Codepool.php | | | Codes.php | | | Customer.php | | | Order.php | | | Product.php | | |- Bundle/ | | | |- Sales/ | | | |- Order/ | | | |- Items/ | | | Renderer.php | | |- Sales/ | | |- Items/ | | | Abstract.php | | |- Order/ | | Items.php | |- controllers/ | | | IndexController.php | | |- Adminhtml/ | | | SerialcodesController.php | | |- Serialcodes/ | | ItemsController.php | |- etc/ | | config.xml | |- Helper/ | | Data.php | |- Model/ | | | Observer.php | | | Serialcodes.php | | |- Mysql4/ | | | | Serialcodes.php | | | |- Serialcodes/ | | | Collection.php | | |- Product/ | | | |- Customer/ | | | | | Groups.php | | | | |- Groups/ | | | | Backend.php | | | |- Email/ | | | Templates.php | | |- Resource/ | | |- Eav/ | | |- Mysql4/ | | Setup.php | |- sql/ | |- serialcodes_setup/ | mysql4-data-upgrade-1.4.0-1.4.1.php | mysql4-install-1.0.0.php | mysql4-upgrade-1.0.0-1.1.0.php | mysql4-upgrade-1.1.0-1.2.1.php | mysql4-upgrade-1.2.1-1.3.0.php | mysql4-upgrade-1.3.0-1.3.1.php | mysql4-upgrade-1.3.1-1.4.0.php | mysql4-upgrade-1.4.0-1.4.1.php | mysql4-upgrade-1.4.1-1.4.2.php | mysql4-upgrade-1.4.2-1.4.3.php |- design/ | |- adminhtml/ | |- default/ | |- default/ | |- layout/ | | serialcodes.xml | |- template/ | |- serialcodes/ | |- order/ | |- view/ | items.phtml | serialcodes.phtml |- etc/ | |- modules/ | Mmsmods_Serialcodes.xml |- locale/ |- en_US/ | Mmsmods_Serialcodes.csv |- template/ |- email/ serialcodes_delivery.html serialcodes_warning.html

Compatibility

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

Versions 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 1.10, 1.11, 1.12, 1.13

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

Known Issues

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 History (Changelog)

Version 1.4.3 (Current Version)

Added Features

Added the option to automatically issue and deliver Serial Codes based on customer group.

Added the ability to deliver multiple Serial Codes contained within a single line item individually rather than grouped together in one email. For example, an order for three "Super CD Key Vouchers" can be delivered individually using three emails instead of one.

Added the ability to filter the "Serial Code Order Items" grid based on order status.

Added the ability to filter the "Serial Code Order Items" grid to display only items which have Serial Codes assigned or issued by using an asterisk (*) to filter the "Serial Codes" column.

Added CSV and XML export to the "Manage Serial Codes" and "Serial Codes Order Items" grids.

Dispatched two events within the issueSerialCodes() method to assist developers in modifying the behavior of the module using observers rather than actually modifying the code base. Additional events may be triggered upon request; please let us know.

Bug Fixes

Corrected a problem where issued Serial Codes would not be automatically emailed to the customer if they were not returned to the store success page by PayPal upon completion of payment.

Fixed a bug that caused the issuing of credit memos to be improperly handled by the extension.

Fixed several minor problems associated with refactoring the code base.

Version 1.4.1 (Limited Release)

Added Features

Added the ability to keep inventory stock quantities updated based on remaining available Serial Codes.

Added the ability to issue Serial Codes when the order is invoiced and paid. Supports partial invoicing of orders.

Serial Codes may now be issued based on Simple product Custom Options. Magento Simple product Custom Options do not allow for tracking of inventory stock quantities.

Implemented "Pending" status for Serial Codes allowing for better tracking and inventory control. Serial Codes can now be assigned to deferred payment orders but not issued to the customer until payment is received. Pending codes are automatically returned to "Available" status if the order is cancelled.

The "Issue Serial Codes" button on the admin order view page no longer automatically overwrites existing issued Serial Codes.

Added "Serial Code Pool" field to the "Serial Code Order Items" grid.

Added links to the Product and the Code Pool within the "Serial Code Order Items" grid.

Added time to the "Created" and "Updated" timestamp fields in the "Serial Code Order Items" and "Manage Serial Codes" grids.

Added links to online instructions on relevant pages.

Cleaned up the Serial Codes product attribute tab to diminish the "wall of text" effect.

Included many other small tweaks to provide better overall performance and usability.

Bug Fixes

Now properly displays Serial Codes on registered customer orders in the frontend when product name was changed after order placed.

Now properly issues Serial Codes from configurable children with "Issue Serial Codes" button on backend order view page.

Fixed several bugs to now properly sort and filter on all columns in the "Serial Code Order Items" and "Manage Serial Codes" grids.

Notes

This is a major update. A large portion of the code base has been refactored, allowing for easier custom modifications and future updates.

Version 1.3.1

Notes

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