For more information... RTFM!
NAVIGATION
PAGES THAT LINK HERE
ACCOUNT LOGIN

You are not logged in

Powered by Interchange version 5.7.0

Order 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

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

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

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.  Note that either attach, email or empty must be set for a route.

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

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 that either attach, email or empty must be set for a route.

Note

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

Set this if you do not want this route to send an email or attachment.  Note that either attach, email or empty must be set for a route.

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.

Category:  Interchange ecommerce functions
Last modified by: Peter Ajamian
Modification date: Friday 16 January 2009 at 7:47 AM (EST)
Home  |  Legal nonsense  |  Privacy policy  |  Donations  |  Contact us