9.3. Order Routing
Interchange can send order emails and perform custom credit card charges and/or logging for each item. The Route directive is used to control this behavior, along with the mv_order_route item attribute.
If no Route is in the catalog, Interchange uses a default "mail out the order and show a receipt" model.
Routes are established with the Route directive, which is similar to the Locale directive. Each route is like a locale, so that key-value pairs can be set. Here is an example setting:
Route mail pgp_key 0x67798115 Route mail email orders@akopia.com Route mail reply service@akopia.com Route mail encrypt 1 Route mail encrypt_program "/usr/bin/pgpe -fat -q -r %s" Route mail report etc/report_mail
Note: Values with whitespace in them must be quoted.
You can also set the route in a valid Perl hash reference string:
Route mail <<EOR { pgp_key => '0x67798115', email => 'orders@akopia.com', reply => 'service@akopia.com', encrypt => 1, encrypt_program => q{/usr/bin/gpg -e -a -r '%s' --batch}, report => 'etc/report_mail', } EOR
This route would be used whenever the mail route was called by one of the three possible methods:
route called from master route
-
Called via the cascade parameter from the master route. This is the way that most routes are called in Interchange's the Foundation manpage demo. These routes treat the order as a whole.
route set in item
-
An item in the shopping cart has mail as the value in the attribute mv_order_route. This method is item-specific to this item (or group of items in route mail).
route set in the form variable mv_order_route
-
By setting a value in the mv_order_route form variable, you can specify one or more routes to run. This is the deprecated method used in earlier Interchange 4.6.x and Minivend 4 routes. It will still work fine.
The last route that is defined is the master route, by convention named main. Besides setting the global behavior of the routing, it provides some defaults for other routes. For example, if encrypt_program is set there, then the same value will be the default for all routes. Most settings do not fall through.
The attributes that can be set are:
attach
-
Determines whether the order report should be attached to the main order report e-mail. This is useful if certain items must be printed separately from others, perhaps for FAX to a fulfillment house.
cascade
A list of routes which should be pushed on the stack of routes to run, after all currently scheduled routes are done. NOTE: cascades can cause endless loops, so only one setting is recommended, that being the main route.
commit
-
Perl code which should be performed on a route commit.
commit_tables
-
Tables that are to be pre-opened before running the Perl commit code.
counter
-
The location of a counter file which should be used instead of OrderCounter for this route. It will generate a different value for mv_order_number for the route. This is normally used to obtain unique order references for multi-vendor routing.
credit_card
-
Determines whether credit card encryption should be done for this order. Either this or encrypt should always be set.
dynamic_routes
-
If set in the the master manpage route, will cause the the RouteDatabase manpage to be checked for a route. If it exists, it will be read in and the database copy used instead of the static copy build at catalog configuration time. If set in a subsidiary route, that route will be ignored during catalog.cfg, and dynamic_routes must be active for it to be seen.
-
The email address(es) where the order should be sent. Set just like the MailOrderTo directive, which is also the default.
empty
This should be set if neither attach or email is set.
encrypt
-
Whether the entire order should be encrypted with the encrypt_program. If credit_card is set, the credit card will first be encrypted, then the entire order encrypted.
encrypt_program
-
The encryption program incantation which should be used. Set identically to the EncryptProgram directive, except that %s will be replaced with the pgp_key. Default is empty.
errors_to
-
Sets the Errors-To: e-mail header so that bounced orders will go to the proper address. Default is the same as MailOrderTo.
expandable
-
If set in the the master manpage route, route settings will be expanded for ITL tags. No effect if the route is not the master.
extended
-
Extended route settings that take the form of an Interchange option list; normally a Perl hash reference that will be read. These settings always overwrite any that currently exist, regardless of the order in which they are specified. For example:
Route main extended { email => 'milton@akopia.com' } Route main email papabear@minivend.com
The ultimate setting of email will be milton@akopia.com.
increment
-
Whether the order number should be incremented as a result of this result. Default is not to increment, as the order number should usually be the same for different routes within the same customer order.
individual_track
-
A directory where individual order tracking files will be placed. The file name will correspond to the value of mv_order_number. This can be useful for batching orders via download.
individual_track_ext
-
The extension that will be added to the file name for individual_track. Must contain a period (.), if that is desired.
individual_track_ext .pgp
individual_track_mode
-
A number representing the final permission mode for the individual_track file. Usually expressed in octal:
individual_track_mode 0444
master
-
If set, this route becomes the master route for supplant, dynamic_routes, errors_to, and expandable, and supplies the setting for receipt and the attach report. Switching master in midstream is unlikely to be successful -- it should certainly be the first route in a cascade.
payment_mode
-
If this is set, enables a payment mode for the route. (Payment modes are also set in the Route directive.)
pgp_cc_key
-
The PGP/GPG key selector that is used to determine which public key is used for encryption of credit cards only. With PGP 5 and 6, see appropriate values by using the command pgpk -l. For GPG, use gpg --list-keys. Defaults to the value of the pgp_key manpage.
pgp_key
-
The PGP key selector that is used to determine which public key is used for encryption. If pgp_cc_key is set, that key will be used for credit card encryption instead of pgp_key. With PGP 5 and 6, see appropriate values by using the command pgpk -l. For GPG, use gpg --list-keys. Defaults to the value of the pgp_key manpage.
profile
-
The custom order profile which should be performed to check the order prior to actually running the route. If it fails, the route will not be performed. See OrderProfile and mv_order_profile.
receipt
-
The receipt page that should be used for this routing. This only applies if supplant is set for the route, and that normally would only be in the default route.
report
-
The report page that should be used for this routing. If attach is defined, the contents of the report will be placed in a MIME attachment in the main order report.
reply
-
The Reply-To header that should be set. Default is the same as email.
If there are only word characters (A-Za-z0-9 and underscore), it describes an Interchange variable name where the address can be found.
rollback
-
Perl code which should be performed on a route rollback.
rollback_tables
-
Tables that are to be pre-opened before running the Perl rollback code.
supplant
-
Whether the master route should supplant the main order report. If set, the AsciiTrack operation will use this route and the normal Interchange order e-mail sequence will not be performed. This is normally set in the master route.
track
-
The name of a file which should be used for tracking. If the supplant attribute is set, the normal order tracking will be used as well.
track_mode
-
A number representing the final permission mode for the track file. Usually expressed in octal:
track_mode 0444
transactions
-
A list of tables to put in transactions mode at the beginning of the route. Used to ensure that orders get rolled back if another route fails.
The first route to open a table must have this parameter, otherwise transactions will not work. If any route fails (except ones marked error_ok) then a rollback will be done on these tables. If all routes succeed, a commit will be performed at the end of all order routes.
Individual item routing causes all items labeled with that route to be placed in a special sub-cart that will be used for the order report. This means that the [item-list] LIST [/item-list] will only contain those items, allowing operations to be performed on subsets of the complete order. The [subtotal], [salestax], [shipping], [handling], and [total-cost] tags are also affected.
Here is an example of an order routing:
Route HARD pgp_key 0x67798115 Route HARD email hardgoods@akopia.com Route HARD reply service@akopia.com Route HARD encrypt 1 Route HARD report etc/report_mail Route SOFT email "" Route SOFT profile create_download_link Route SOFT empty 1 Route mail pgp_key 0x67798115 Route mail email orders@akopia.com Route mail reply service@akopia.com Route mail encrypt 1 Route mail report etc/report_all Route user error_ok 1 Route user email email Route user reply service@akopia.com Route user report etc/user_copy Route log empty 1 Route log report etc/log_transaction Route log transactions "transactions orderline inventory" Route log track logs/log Route main supplant 1 Route main receipt etc/receipt.html Route main master log mail user Route main cascade log mail user Route main encrypt_program "/usr/bin/gpg -e -a r '%s' --batch"
This will have the following behavior:
Order
-
The master order route is main, the last one defined. It cascades the routes log, mail, and user, which means they will run in that order at the completion of the main route. The individual item routes HARD and SOFT, if applicable, will run before those.
Transactions
-
The route log specifies the tables that will be put in transaction mode, in this case transactions orderline, and inventory.
Failure
-
All order routes must succeed except user, which has error_ok set to 1.
Encryption The mail order route and the HARD order route will be sent by email, and encrypted against different GPG key IDs. They will get their encrypt_program setting from the main route.
To set the order routing for individual items, some method of determining their status must be made and the mv_order_route attribute must be set. This could be set at the time of the item being placed in the basket, or have a database field called goods_type set to the appropriate value. The following example uses a Perl routine on the final order form:
[perl table=products] my %route; my $item; foreach $item (@{$Items}) { my $code = $item->{code}; my $keycode = $Tag->data('products', 'goods_type', $code); $item->{mv_order_route} = $keycode; } return; [/perl]
Now the individual items are labeled with a mv_order_route value which causes their inclusion in the appropriate order routing.
Upon submission of the order form, any item labeled HARD will be accumulated and sent to the e-mail address hardgoods@akopia.com, where the item will be pulled from inventory and shipped.
Any item labeled SOFT will be passed to the order profile create_download_link, which will place it in a staging area for customer download. (This would be supported by a link on the receipt, possibly by reading a value set in the profile).