Order routing

Table of contents
1. Introduction
1.1. The master route
1.2. Route called from a master route
1.3. Route specified in an item
1.4. Route set in the mv_order_route form field
1.5. Route defined for individual cart items
2. Route attributes
2.1. attach
2.2. bcc
2.3. cascade
2.4. cc
2.5. commit
2.6. commit_tables
2.7. counter
2.8. credit_card
2.9. dynamic_routes
2.10. email
2.11. empty
2.12. encrypt
2.13. encrypt_program
2.14. errors_to
2.15. expandable
2.16. extended
2.17. from
2.18. increment
2.19. individual_track
2.20. individual_track_ext
2.21. individual_track_mode
2.22. master
2.23. payment_mode
2.24. pgp_cc_key
2.25. pgp_key
2.26. profile
2.27. receipt
2.28. report
2.29. reply
2.30. rollback
2.31. rollback_tables
2.32. supplant
2.33. track
2.34. track_mode
2.35. transactions
3. Order routing example
3.1. Execution order
3.2. Transactions
3.3. Failure
3.4. Encryption
4. Individual item routing

Introduction

Interchange can send order emails, and perform custom credit card charges and/or logging for each item ordered. The Route directive is used to control this behaviour, along with the mv_order_route item attribute.

If no Route is set up then Interchange will use a default "mail out the order and show a receipt" model.

Here is an example Route definition:

Route mail pgp_key 0x67798115
Route mail email orders@example.com
Route mail reply service@example.com
Route mail encrypt 1
Route mail encrypt_program "/usr/bin/pgpe -fat -q -r %s"
Route mail report etc/report_email

You can also use the Perl-style "here document" syntax, as follows:

Route mail <<EOR
pgp_key 0x67798115
email orders@example.com
reply service@example.com
encrypt 1
encrypt_program "/usr/bin/gpg -e -a -r '%s' --batch
report etc/report_email
EOR

Note

Values that contain whitespace must be quoted.

This route would be used whenever "mail" is called using one of three possible methods, as follows:

The master route

The last route defined becomes the master route. This is named default by convention. Besides setting the global behaviour of the routing mechanism, the master route provides some defaults for the other routes. For example, if encrypt_program is set in the master route, then the same value will be the default for all of the other routes.

Note

Most of the master route settings do not fall through to other routes.

Route called from a master route

Called via the "cascade" parameter from the master route. This is the way that most routes are called in Interchange's Standard ecommerce demo. These routes treat the order as a whole.

Route specified in an item

If an item in the shopping cart has its "mv_order_route" attribute set to "mail" then it will be added to a group of one or more items that will be sent via that route. See the Individual item routing section, below.

Route set in the mv_order_route form field

By setting a value in a "mv_order_route" <form> field, you can specify one or more routes to run. Rows in the cart array may also contain a "mv_order_route" attribute. See the individual item routing section, below.

Deprecation notice

The "mv_order_route" <form> field is the deprecated method of route selection, used in earlier Interchange 4.6.x and Minivend 4 routes. This method will still work fine for the time being but may be withdrawn in the future.

The "mv_order_route" cart item attribute is not deprecated, and remains as valid method of route selection.

Route defined for individual cart items

See the individual item routing section, below.

Route attributes

The attributes that can be set are listed in this section.

attach

This determines whether the order report should be attached to the order report email. This is useful if certain items must be printed separately from others, perhaps for a fax to a fulfilment house.

bcc

The email address(es) where a BCC for the order report will be sent.

cascade

A list of routes which should be pushed on the stack of routes to run, after all currently scheduled routes have finished.

Warning

Cascades can cause endless loops, so only one setting (in the "default" route) is recommended.

cc

The email address(es) where a CC for the order report will be sent.

commit

Perl code that should be executed on a route commit. Also see the rollback attribute.

commit_tables

Tables that are to be pre-opened before running the Perl commit code. Also see the rollback_tables attribute.

counter

The location of a counter file which should be used instead of OrderCounter for this route. This is expected to generate a unique value for mv_order_number for the route. This parameter is normally used to provide unique order references for multi-vendor routing.

credit_card

Determines whether credit card encryption should be performed for this order. Either this or encrypt should always be set.

dynamic_routes

If set in the the master route, this will cause the the RouteDatabase to be checked for a Route. If it exists, it will be read in and the database copy will be used instead of the static copy built when the website was (re)started. If set in a subsidiary route, that route will be ignored when the catalog.cfg is read, and dynamic_routes must be active for it to be seen.

email

The email address(es) where the order should be sent. This is set just like the MailOrderTo directive, which provides the default value for this attribute.

Note

If SendMailProgram is set to "none" then order notification emails will not be sent, and an error will be logged to the website's error log file.

empty

encrypt

Defines whether the entire order should be encrypted with the encrypt_program. If credit_card is set then the credit card details will be encrypted first followed by the whole of the rest of the order.

encrypt_program

The encryption program incantation that should be used. Set identically to the EncryptProgram directive, except that "%s" will be replaced with the pgp_key. There is no default value.

errors_to

Sets the "Errors-To:" email header so that bounced order receipt emails will go to the specified address. The default is the same as MailOrderTo.

expandable

If set in the the master, then route settings will be interpolated for Interchange tags. This has 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 take precedence over any that currently exist, regardless of the order in which they are specified. For example:

Route default extended { email => 'kevin@example.com' }
Route default email walsh@example.com

The ultimate setting of email will be kevin@example.com.

from

The email address used for sending the order report email, if applicable.

increment

Specifies whether the order number should be incremented as a result of this route. The default is to not 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 for download.

individual_track_ext

The suffix that will be appended to the file name for individual_track. Must contain a dot (.), if that is desired. For example:

Route foo individual_track_ext .pgp

individual_track_mode

A number representing the permission mode for the individual_track file. This is best expressed in octal, as follows:

Route foo 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 the receipt and the attach reports. Switching master mid-stream is unlikely to be successful; It should be the first route in a cascade.

payment_mode

If this is set, it enables a payment mode for the route. (Payment modes are also set using the Route directive.)

pgp_cc_key

The PGP/GnuPG key selector that is used to determine which public key is used for encryption of credit card details only.

With PGP 5 and 6, see appropriate values by using "pgpk -l". For GnuPG, use "gpg&nnsp;--list-keys". Defaults to the value of the pgp_key attribute.

pgp_key

The PGP/GnuPG key selector that is used to determine which public key is used for encryption. If pgp_cc_key is set then that key will be used for credit card encryption instead of this value.

With PGP 5 and 6, see appropriate values by using "pgpk -l". For GnuPG, use "gpg&nnsp;--list-keys". Defaults to the value of the pgp_key attribute.

profile

The custom order profile which should be performed to check the order prior to actually running the Route. If it fails then the route will not be used. See OrderProfile and mv_order_profile.

receipt

The customer receipt page that should be used for this route. This only applies if supplant is set for the route, and that normally would only be in the default route.

report

The merchant's report page that should be used for this route. If attach is defined then the contents of the report will be sent as a MIME attachment to the order report.

reply

The "Reply-To:" email header that should be set. Default is the same as the email attribute. If there are only word characters (A-Za-z0-9 and underscore), it describes an Interchange value name where the email address can be found.

rollback

Perl code that should be performed on a route rollback. Also see the commit attribute.

rollback_tables

Tables that are to be pre-opened before running the Perl rollback code. Also see the commit_tables attribute.

supplant

Specify whether the master route should supplant the current route's order report. If set, the AsciiTrack operation will use this route and the normal Interchange order email sequence will not be used. 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 then the normal order tracking mechanism will be used as well.

track_mode

A number representing the permission mode for the track file. This is best expressed in octal, as follows:

Route foo track_mode 0444

transactions

A list of tables to put in transactions mode at the beginning of the route. This is 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, other than routes marked with error_ok, then a rollback will be performed on these tables. A commit will be performed at the end of all order routes if there were no errors.

Order routing example

Route hardware <<EOR
encrypt 1
pgp_key 0x67798115
email hardgoods@example.com
reply service@example.com
report    etc/email_hardware
EOR

Route software <<EOR
empty 1
email ""
profile create_download_link
EOR

Route log <<EOR
empty 1
supplant    0
encrypt 0
increment 0
report    etc/log_transaction
track logs/log
transactions    "transactions orderline inventory"
EOR

Route merchant <<EOR
supplant    1
attach    0
credit_card 1
encrypt 1
email orders@example.com
pgp_key 0x67798115
report    etc/order_email.merchant
receipt etc/receipt.html
track logs/tracking.asc
individual_track orders
EOR

Route copy_user <<EOR
empty 1
error_ok    1
supplant    0
encrypt 0
increment 0
report    etc/order_email.user
track logs/tracking.asc
EOR

Route default <<EOR
master    1
empty 1
supplant    1
cascade log merchant copy_user
email orders@example.com
write_tables    "transactions orderline inventory userdb"
transactions    "transactions orderline inventory"
EOR

The set of routes, above, will have the following behaviour:

Execution order

The master order route is "default" because "default" was the last route defined. The "default route cascades to the "log", "merchant" and "copy_user" routes, which means they will run in that order on completion of the default route. The individual item routes, "hardware" and "software", if applicable, will run before the routes described above.

Transactions

The "log" route specifies the tables that will be put in transaction mode. In this case, the tables are transactions, orderline and inventory.

Failure

All order routes must succeed except "user", which has its "error_ok" attribute set to "1".

Encryption

The "merchant" and the "hardware" order routes will be sent by email, and encrypted against different GnuPG key IDs. They will get their "encrypt_program" setting from the master route.

Individual item routing

Individual item routing causes all items labelled 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] ... [/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.

If items are to be routed individually then the the "mv_order_route" attribute must be set for each item. This could be set when item is placed in the cart, or there could be a database column called "goods_type" (for instance) set to an appropriate value.

The following example uses Perl code to set the "mv_order_route" item attribute, based upon a goods_type column in the products table, for every item in the current cart:

[perl table="products"]
foreach (@{$Items}) {
$_->{mv_order_route} = $Tag->data({
table => 'products',
column => 'goods_type',
key => $_->{code},
});
}
undef;
[/perl]

After the above is run, the individual items will be labelled with a "mv_order_route" value, which causes their inclusion in the appropriate order route.

Upon submission of the order form, any item labelled "hardware" will be accumulated and sent to the "hardgoods@example.com" email address, where the item will be pulled from inventory and shipped.

Any item labelled "software" will be passed to the "create_download_link" profile, 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.

The code in the "create_download_link" profile has not been included in this example.