Written by Jeff Walters, hiker_jjw@yahoo.com Date Created: 01-23-2000 Date Last Modified: 01-23-2000 Description of ups-lib.pl: up-lib.pl is used to implement the UPS Quick Cost Calculator service, available from www.ups.com, into the Web Store. I recommend that you register your company with UPS so you will receive updates from UPS when they become available. ups-lib.pl contains two subroutines; display_ups_cost_table and get_ups_cost. display_ups_cost_table is used to display a table of UPS services for a user to select from. The table includes the different service names, service costs, and any warning messages. The get_ups_cost subroutine retrieves the UPS Quick Cost information (via a socket connection), based on input variables, and formats the information into several associative arrays. See the ups-lib.pl library for more information. Installation Instructions: Installation of the ups-lib.pl is not an easy task. If you do not feel comfortable making your own "personal" changes to the Web Store then you should probably not attempt this change; in other words, "Stop Here"! On the other hand if you have 'some' CGI/Perl programming experience, then please continue, the result will be worth the effort! The creation of this library was inspired by Gheorghe Chesler's UPS Module and many Perl authors such as Gunther Birznieks, Selena Sol and countless others. http://www.extropia.com/hacks/chesler_shipping.html STEP #1.) First, you will need to add a confirmation page to the Web Store. Do this before you continue. See the following link: http://www.extropia.com/hacks/jackson_ws_confirms.html A confirmation page is needed because we need to get the users "Zipcode" in order to ask the UPS server to calculate the various shipping costs. STEP #2.) Second, we will also need establish the shipping "Weight" of the package. In other words, you will need to create a Weight field in your database and you need it to be your "Measured Field" as well. This is done in your setup file. Add the "weight" field to your database and to the Web Store. Your numbers may and probably will differ!!!!!!!!!! Add "weight" to the $db definition array: $db{"product_id"} = 0; $db{"product"} = 1; $db{"price"} = 2; $db{"name"} = 3; $db{"image_url"} = 4; $db{"description"}= 5; $db{"description2"}= 6; $db{"weight"} = 7; $db{"options"} = 8; Add "weight" to the @sc_db_index_for_defining_item_id array: @sc_db_index_for_defining_item_id = ($db{"product_id"}, $db{"product"}, $db{"price"}, $db{"name"}, $db{"weight"}); Add the "weight" field to the cart definition: $cart{"quantity"} = 0; $cart{"product_id"} = 1; $cart{"product"} = 2; $cart{"price"} = 3; $cart{"name"} = 4; $cart{"weight"} = 5; $cart{"options"} = 6; $cart{"price_after_options"} = 7; $cart{"unique_cart_line_id"} = 8; Define the measured field to be the shipping "weight": $sc_cart_index_of_measured_value = $cart{"weight"}; Add the "weight" to the following two array. The cart display fields and the index for display: @sc_cart_display_fields = ("Description", "Options", "Weight", "After Options"); @sc_cart_index_for_display = ($cart{"name"}, $cart{"options"}, $cart{"weight"}, $cart{"price_after_options"}); Now that you have added the weight to your database and setup all the previous additions to your setup file, you should now see the Weight field in your shopping cart. STEP #3.) We now need to install the ups-lib.pl library and make sure it gets required when needed. This is very important. Copy/FTP the ups-lib.pl to the Web Store ./Library directory. Open up your setup file again, and add the following line to the Global File Location variables section: $sc_ups_lib_path = "./Library/ups-lib.pl"; Next open up your webstore.cgi (main Web Store program) and add the UPS library to the following so ups-lib.pl is properly "required" when needed. Don't forget to FTP the ups-lib.pl file over to your Web server. elsif ($form_data{'confirm_order_button'} ne "") { &require_supporting_libraries (__FILE__, __LINE__, "$sc_ups_lib_path", "$sc_order_lib_path"); &confirm_order; exit; } elsif ($form_data{'submit_order_confirm_button'} ne "") { &require_supporting_libraries (__FILE__, __LINE__, "$sc_ups_lib_path", "$sc_order_lib_path"); &process_order_confirm; exit; } STEP #4.) Setup file additions for the UPS library. Before we go into the UPS setup variables let me mention one more small change. You may need to adjust your shipping display variables so the shipping cost is displayed on the proper pages. This can be found in your setup file. $sc_calculate_shipping_at_display_form = 0; $sc_calculate_shipping_at_process_form = 3; Add the following to your setup file. You will need to define your origin postal zipcode and also the $shipping_field. Your shipping field may be different, see the setup file %sc_order_form_array to find your shipping field "key". # UPS Shipping Cost Variables $sc_origin_postal_code = "99336"; # Washington State, US $shipping_field = '22-shipping'; Next we will add in the UPS services we wish to offer the Web Store users. See the UPS Quick Cost Calculator documentation for more information on the UPS service codes. For shipping in the United States (including Hawaii and Alaska) the following below we do just fine. For Hawaii and Alaska, the program will automatically determine that GNDRES is not available. # An array of possible UPS Service you wish to allow the user to select. # The #'s 1,2,3 are used to sort the UPS services in the order you wish. %sc_ups_services_to_display = ('1-GNDRES', 'Ground Residential', '2-3DS', '3 Day Select', '3-2DA', '2nd Day Air'); Please make note that this routine has only been testing for US shipping. For shipping out of the United States, ups-lib.pl will need to be modified to handle other countries! 5.) Remove the "shipping" selection from your order form html. Your order form might be called, "outlet_order_form_with_shipping.html" or possibly something different. Just make sure to cut out the shipping selection! The user will be making the shipping selection on the following Web Store generated HTML page (subroutine: confirm_order). "web_store_order_lib.pl" changes: Now for the fun part, we need to make the following additions to the "web_store_order_lib.pl". Open up this file and find the beginning of the "confirm_order" subroutine. Add the following code just after the customer information is displayed. The customer information can be found towards the end of this subroutine. ############################################################ if ($required_fields_filled_in eq "yes") { print qq!
UPS Shipping Selection
Our products are shipped using the United Parcel Service, the Internet's leader in E-Commerce solutions. Please, select the type of UPS shipping you would prefer.

!; &get_ups_cost ($sc_origin_postal_code, $form_data{'10-m_zip'}, $form_data{'11-m_country'}, $total_measured_quantity, $subtotal); &display_ups_cost_table("order form"); print qq!
If the information above is correct and you have selected the type of shipping you prefer, just click the "submit secure order" button at the bottom of this page and your order will be completed.
!; } ############################################################ You might decide to move this code above the customers displayed information, it truly doesn't matter. IMHO, the only logic that should be followed is that, $required_fields_filled_in must equal "yes". Feel free to change the wording and formatting HTML. Notice the usage of the two new subroutines &get_ups_cost and &display_ups_cost_table. These are the only two subroutines in the ups-lib.pl library. &get_ups_cost defines all the proper UPS input variables, creates the socket connection to the UPS server and defines the proper output variables which the &display_ups_cost_table uses to display the UPS selections for the user. For more information on how these subroutines work please see the ups-lib.pl library file. Believe it or not there are no needed changes to the process_order_confirm subroutine, but you will have to make the following changes to the calculate_shipping subroutine. STEP #6.) subroutine: calculate_shipping: Remove the old calculate_shipping subroutine and replace it with this new subroutine. ############################################################ # # subroutine: calculate_shipping # Usage: # $shipping = # &calculate_shipping($sub_total, # $total_quantity, # $total_measured_quantity); # # Parameters: # $sub_total = the subtotal to calculate shipping on # $total_quantity = quantity of items to calc shipping on # $total_measured_quantity = quanity of measured item to # calc shipping on # Output: # The value of the shipping # ############################################################ sub calculate_shipping { local($subtotal, $total_quantity, $total_measured_quantity) = @_; local ($form_service_code, $form_service_text, $form_service_cost, $shipping_new); # Call UPS Subroutine to get shipping cost. # Verify cost from FORM values. &get_ups_cost ($sc_origin_postal_code, $form_data{'10-m_zip'}, $form_data{'11-m_country'}, $total_measured_quantity, $subtotal); ($form_service_code, $form_service_text, $form_service_cost) = split(/\|/,$form_data{'22-shipping'}); if ($form_service_cost ne $ups_cost{$form_service_code}) { $$ups_shipping_msg .= "
An inconsistency in the calculated shipping cost has occured!"; } # Re-define the 22-shipping field as the shipping text. $form_data{'22-shipping'} = $form_service_text; # Determine if we should return shipping # cost or error message (failure mode)! if ($ups_shipping_msg ne "" || $ups_socket_msg ne "" || $form_data{'22-shipping'} eq "") { print qq!$ups_socket_msg\n\n

!; print qq!$ups_shipping_msg\n\n

!; $ups_order_msg = qq~ There seems to have been an error while trying to calculate your UPS shipping cost. We will try to contact you via email or phone within 24 hrs. to provide you with a shipping cost for your order! ~; print qq!$ups_order_msg\n\n

!; return (); # OLD CALCULATION REMOVED # general shipping calculation # return(&calculate_general_logic( # $subtotal, # $total_quantity, # $total_measured_quantity, # *sc_shipping_logic, # *sc_order_form_shipping_related_fields)); } else { # Return UPS Calculation return ($form_service_cost); } } # End of calculate_shipping ############################################################ Failure Mode: Please make note that you can easily create a "failure mode" using the above calculate_shipping subroutine. At first, I thought it would be nice to rely on the "old" shipping calculation as a failure mode, but now that I've seen it in action I think it's better off without it. You may feel that you "need" to rely on the old shipping calculation as a "failure mode" for the UPS calculation. If so, just remove the #'s after the # OLD CALCULATION REMOVED line to let the &calculate_general_logic do it's job. Well, that's about it except for general cosmetic changes to the HTML. I "think" I've covered just about everything. If you get this to work properly, please drop me an email so I can see it! If you think I've forgotten something, please email me as well so I can make any necessary changes to these instructions. A working example of this subroutine can be found at www.outdoorstoreusa.com. Jeff Walters hiker_jjw@yahoo.com