Index: openacs-4/packages/ecommerce/www/doc/ecommerce-technical.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/ecommerce/www/doc/ecommerce-technical.adp,v diff -u -r1.5 -r1.5.4.1 --- openacs-4/packages/ecommerce/www/doc/ecommerce-technical.adp 22 May 2003 14:49:34 -0000 1.5 +++ openacs-4/packages/ecommerce/www/doc/ecommerce-technical.adp 9 Feb 2005 11:59:42 -0000 1.5.4.1 @@ -10,14 +10,14 @@

  • Install an implementation of the Payment Service ContractPayment Service Contract such as the Authorize.net Gateway or the VeriSign PayflowPro Gateway .

    + @authorize_gateway_installed@> or the EZIC Gateway .

    (Note: it can take a few weeks for your bank and a payment gateway to get your account ready, so get started on that @@ -26,13 +26,10 @@

    -

    You can start testing @package_name@ with a You can start testing @package_name@ with a 30-day FREE TRIAL VeriSign - test account and the PayflowPro Gateway . With the 30-day FREE - TRIAL, you'll see just how easy it is to begin accepting on-line - payments.

    + test SSL key. +

    @@ -75,35 +72,34 @@
  • -

    Install the @package_name@ - package.

    +

    Install @package_name@ package from OpenACS.

  • ImageMagick (which is free) must be installed (either in /usr/local/bin/ or elsewhere - if you're running your server - chrooted) if you want thumbnails to be automatically - created. For information on the use of ImageMagick in OpenACS, + if you are running your server + chrooted expired info, dated: April 2001) if you want thumbnails to be automatically + created. For information on the original use of ImageMagick in OpenACS, see Chapter 6: + href="http://philip.greenspun.com/panda/images">Chapter 6: Adding Images to Your Site of Philip and Alex's Guide to Web Publishing.

  • -

    Install OpenSSL and the Install OpenSSL and the latest nsopenssl - module for OpenNSD or AOLServer so that @package_name@ + module that is appropriate for the version of AOLserver used, so that @package_name@ can support secure transactions.

    -

    Follow the nsopenssl installation instructions - till the very end. @package_name@ uses ns_httpsopen, ns_httpsget - or ns_httpspost calls and requires https.tcl to be installed.

    +

    Follow the nsopenssl installation instructions. + @package_name@ uses ns_httpsopen, ns_httpsget + or ns_httpspost calls and requires the https.tcl file to be installed.

  • @@ -123,10 +119,11 @@
  • -

    A /web/yourserver/data/ecommerce/product directory is +

    A /var/lib/aolserver/yourserver/ec-data/ecommerce/product directory is needed to hold the products' supporting files (it's outside the - web root so that no uploaded supporting files can be executed). - The directory has to be write-able by nsadmin. (You can change + web server root so that no uploaded supporting files can be executed). + The directory has to be write-able by the username used with AOLserver. + (You can change the directory by editing EcommerceDataDirectory and ProductDataDirectory in your @package_name@ parameters.)

    • @@ -168,7 +165,7 @@

  • Set PaymentGateway to the package key of the Payment Service + href="/doc/payment-gateway/">Payment Service Contract implementation you like to use to handle the financial transactions.

    @@ -186,28 +183,25 @@
  • -

    Qmail must be installed on your system (it may require special - setup if you're running your server - chrooted).

    +

    An MTA with standard sendmail software hooks (such as + qmail or + postfix) must be + installed on your system. It may require a special + setup if you are running + your server chrooted (link info dated: April 2001). +

    • -
  • -

    Optional: @package_name@ includes a customized version of the - registration/login/logout pipeline which handles the transition - to secure logins a bit more gracefully than the ACS Subsites - Package. You may want to patch the ACS Subsites and ACS TCL - packages to match the behavior of @package_name@. See the directions for applying the patch.

  • Optional: If you want to have products be "visible" to the Site Wide Search package then you need to install the Site Wide Search + href="/doc/search/">Site Wide Search Package, including all of its requirements for installation. During the installation of SWS or after run packages/ecommerce/sql/ec-products-sws-setup.sql to add products - to your interMedia index.

    + to your PostgresQL index.

    Note: At this time (Version 4.0a, April 6th, 2001) the interface to SWS has a bug (quite possibly the bug is @@ -230,7 +224,7 @@

    A financial transaction is inserted whenever a credit card authorization to charge or refund is made. These transactions - may or may not be carried through to fulfillment. The + may or may not be "marked" to be carried through to fulfillment. The specifics:

    When an order is placed, an authorization is done for the full @@ -242,24 +236,26 @@ are tied to the order using the order_id. @package_name@ immediately captures the transaction for the items that do not require - shipping. @package_name@ doesn't captures the transaction for the - items that need shipping not until the items ship.

    + shipping. @package_name@ captures the transaction for the + items that need shipping when the items ship.

    -

    When a shipment is made, if it's a full shipment of the order, - the financial transactions inserted when the order is first - placed are ready to be captured. (The field +

    When a shipment is made, if it is a full shipment of the order, + the financial transaction is captured using the existing authorization + from when the order was first placed. (The field to_be_captured_p of the financial transactions - become 't' and @package_name@ attempts to capture it.)

    + become 't', the to_be_captured_date is inserted, + and @package_name@ attempts to capture it.)

    However, if only a partial shipment is made, a new authorization has to be made (therefore a new row is inserted into ec_financial_transactions, - to_be_captured_p is set to 't' and the system + to_be_captured_p is set to 't', the date is inserted into + to_be_captured_date and the system attempts to mark and capture it).

    When a refund is made, a row is also inserted into ec_financial_transactions. A refund is only - inserted if it is definite that it needs to be captured, so + inserted if when it needs to be captured, so there is no need to set to_be_captured_p if transaction_type='refund'.

    @@ -281,9 +277,9 @@

    When the system applies a customer's gift certificate balance to an order, it begins by using the ones that are going to - expire the soonest and continues chronologically until either + expire earlier and continues chronologically until either the order is completely paid for or until the customer's gift - certificates run out. If only part of a gift certificate is + certificates are spent. If only part of a gift certificate is used, the remaining amount can be used later.

    If a customer purchases a gift certificate for someone else, @@ -322,8 +318,7 @@ what the order state will be or it is completely independent of what the order state will be.

    -

    An "X" in a column implies that there is at least one (possibly - many) item in that item state.

    +

    An "X" in a column implies that there is at least one item in that item state --maybe more.

    @@ -600,10 +595,10 @@
    An IN_BASKET order with saved_p='f' and a user_session_id that doesn't correspond to the user_session_id in anyone's cookie (e.g. the user's cookie expired or they turned cookies - off). There's no way of determining whether a shopping cart + off). There is no way of determining whether a shopping cart has been abandoned. These are different from expired orders which are automatically put into the order state EXPIRED if - they're still IN_BASKET after N days, where N is set in the + they are still IN_BASKET after N days, where N is set in the @package_name@ parameters.) @@ -616,16 +611,19 @@ gateway for authorization, some checking is done by the module to make sure that the credit card number is well-formed (using the procedure ec_creditcard_precheck which can be - found in /tcl/ecommerce-credit). The procedure checks the - length of the credit card number, makes sure it starts with the - right digit for the card type, and does a LUHN-10 check (that's - a checksum which can't determine whether the number is a valid - credit card number but which determines whether it's even - possible for it to be a valid credit card number).

    + found in /tcl/ecommerce-credit.tcl). The procedure checks basic + characteristics of a credit card number, such as the + number of digits, verifies that the card number starts with the + right digit for the card type, and if appropriate, does a LUHN-10 + check. LUHN-10 is a checksum that determines if the card number + is a member of the set of valid credit card numbers.

    This procedure only encompasses the three most common credit card types: MasterCard, Visa, and American Express. It can - quite easily be extended to include other credit card types.

    + quite easily be extended to include other credit card types. + Be sure to examine ec_creditcard_precheck + to verify that it does not screen out cards that your + merchant system accepts.

    @@ -639,10 +637,10 @@ site administrator adds a new email template using the admin pages, you will have to create a new procedure that does all the variable substitution, the actual sending out of the email, etc. - This should be easy. Just copy any one of the 7 autoemail - procedures in /tcl/ecommerce-email (except for + This should be straight forward. Copy any one of the 7 autoemail + procedures in /tcl/ecommerce-email.tcl (except for ec_email_gift_certificate_recipient, which is - unusual). Then invoke your new procedure anywhere appropriate + nonstandard). Then invoke your new procedure anywhere appropriate (e.g. the email that says "Thank you for your order" is invoked by calling ec_email_new_order $order_id after the order has been successfully authorized).

    @@ -657,23 +655,25 @@ fulfilled. This is done because a new charge might need to be authorized if a partial shipment is made (we are forced to either capture the amount that a charge was authorized for or to - capture nothing at all - we can't capture any amount in between; - therefore, we are forced to do a new authorization for each + capture nothing at all - we cannot capture any amount inbetween; + Therefore, we are forced to do a new authorization for each amount we are going to charge the user). A new charge also might need to be authorized if a user has asked the site administrator to add an item to their order.

    -

    If you've decided not to allow customers to reuse their credit +

    If you decide to not allow customers to reuse their credit cards, their credit card data is removed periodically (a few times a day) by ec_remove_creditcard_data in - /tcl/ecommerce-scheduled-procs (it removes credit card numbers - for orders that are FULFILLED, RETURNED, VOID, or EXPIRED).

    + /tcl/ecommerce-scheduled-procs.tcl It removes credit card numbers + for orders that are FULFILLED, RETURNED, VOID, or EXPIRED.

    -

    If you've decided to allow customers to reuse their credit +

    If you decide to allow customers to reuse their credit cards, their credit card information is stored indefinitely. This is not recommended unless you have top-notch, full-time, - security-minded system administrators. The credit card numbers - are not encrypted in the database because there isn't much point + security-minded system administrators. Some merchant gateways + may have requirements about how credit card data is stored. + The credit card numbers + are not encrypted in the database because there is not much point in doing so; our software would have to decrypt the numbers anyway in order to pass them off to the payment gateway, so it would be completely trivial for anyone who breaks into the @@ -710,7 +710,7 @@ there will be fewer numbers in your database for the crackers to steal). To clear out the unnecessary credit card data, just run a procedure like ec_remove_creditcard_data (in - /tcl/ecommerce-scheduled-procs) but get rid of the if statement + /tcl/ecommerce-scheduled-procs.tcl). Be sure to bypass the if statement that checks whether SaveCreditCardDataP is 0 or 1.

    @@ -721,35 +721,35 @@

    The site administrator can give the same product different prices for different classes of users. They can also put - products on sale over arbitrary periods of time (sale prices may + products on sale over arbitrary periods of time. Sale prices may be available to all customers or only to ones who have the - appropriate offer_code in their URL).

    + appropriate offer_code in their URL.

    The procedure ec_lowest_price_and_price_name_for_an_item in - /tcl/ecommerce-money-computations determines the lowest price + /tcl/ecommerce-money-computations.tcl determines the lowest price that a given user is entitled to receive based on what user - classes they're in and what offer_codes they came + classes they are in and what offer_codes they came to product with. Their offer_codes are stored, along with their user_session_id, in - ec_user_session_offer_codes (we decided to store - this in the database instead of in cookies because it was a + ec_user_session_offer_codes. We store + this in the database instead of in cookies, because it is a slightly more efficient method, although either implementation would have worked). One minor complication to this is that if a user saves their shopping cart, we want them to get their special offer price, even though they may be coming back with a - different user_session_id; therefore, upon + different user_session_id; Therefore, upon retrieving saved carts, the offer_codes are inserted again into ec_user_session_offer_codes - with the user's current user_session_id (we had to + with the user's current user_session_id. We associate offer_codes with - user_session_id as opposed to user_id - because someone with an offer_code shouldn't be - prevented from seeing the special offer price if they haven't + user_session_id as opposed to user_id, + because someone with an offer_code should not be + prevented from seeing the special offer price if they have not logged in yet).

    -

    The above items are just things that I've found myself explaining +

    The above items are just things that I have found myself explaining to others or things that I think will be useful for people extending this module. Obviously the bulk of the module's code has not been discussed here. If you have any questions, please