Custom Order Routing

### Index Up <<

## Custom Order Routing

MiniVend can send order emails and perform custom credit card charges and/or logging for each individual item. The Route directive is used to control this behavior, along with the `mv_order_route` item attribute and `mv_order_route` form variable.

Routes are established with the Route directive, which is similar to the Locale directive. Each route is like a locale, in that you can set key-value pairs. Here is an example setting:

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

This route would be used whenever the value `VEN` was contained in the form variable `mv_order_route`.

The last route that is defined provides the defaults for all other routes. For example, if encrypt_program is set there then the same value will be the default for all routes.

The attributes that can be set are:

attach
  Determines whether the order report should be attached to the main order report email. This is useful if you must print certain items separately from others, perhaps for FAX to a fulfilment house.

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.

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

cybermode
  If this is set, enables CyberCash for the route. You can also set the variables CYBER_CONFIGFILE, CYBER_SECRET, and all other normal CYBERCASH variables. For example:

          Route VEN cybermode         mauthonly
          Route VEN CYBER_CONFIGFILE  config/vendor1_cfg
          Route VEN CYBER_VERSION     3.2

email
  The email `address(es)` where the order should be sent. Set just like the MailOrderTo directive, which is also the default.

encrypt
  Whether the entire order should be encrypted with the encrypt_program. If credit_card is set, then the credit card will first be encrypted, then the entire order encrypted.

encrypt_program
  The encryption program incantaton which should be used. Set identically to the EncryptProgram directive, except that `%s` will be replaced with the pgp_key. Default is `pgpe -fat -r %s`.

errors_to
  Sets the `Errors-To:` email header so that bounced orders will go to the proper address. Default is the same as MailOrderTo.

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

pgp_cc_key
  The PGP key selector that is used to determine which public key is used for encryption of credit cards only. With PGP 5 and 6, you can see appropriate values by using the command `pgpk -l`.

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, you can see appropriate values by using the command `pgpk -l`.

profile
  The custom order profile which should be performed to check the order. If it fails, then 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 makes sense if supplant is set for the route.

report
  The report page that should be used for this routing. If attach is defined, then 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) then it describes a MiniVend variable name where the address can be found.

supplant
  Whether this route should supplant the main order report. If set, the AsciiTrack operation will use this route and the normal MiniVend order email sequence will not be performed.

track
  The name of a file which should be used for tracking. If the supplant attribute is set, then the normal order tracking will be used as well.

track
  A number representing the mode to change either track or individual_track files to.

An individual item routing causes all items labeld with that route to be placed in a special sub-cart which 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.

Here is an example of an order routing:

        Route  HARD  pgp_key          0x67798115
        Route  HARD  email            hardgoods@minivend.com
        Route  HARD  reply            service@minivend.com
        Route  HARD  encrypt          1
        Route  HARD  encrypt_program  "/usr/bin/pgpe -fat -q -r %s"
        Route  HARD  report           etc/report_mail

        Route  SOFT  email            ""
        Route  SOFT  profile          create_download_link
        Route  SOFT  empty            1

        Route  main  cybermode        mauthonly
        Route  main  CYBER_VERSION    3.2
        Route  main  CYBER_CONFIGFILE etc/cybercash.cfg
        Route  main  pgp_key          0x67798115
        Route  main  email            orders@minivend.com
        Route  main  reply            service@minivend.com
        Route  main  encrypt          1
        Route  main  encrypt_program  "/usr/bin/pgpe -fat -q -r %s"
        Route  main  report           etc/report_all

    To tell MiniVend that order routing is in effect, the variable
    mv_order_route is set on the B<final> order submission form:

        <INPUT TYPE="hidden" NAME="mv_order_route" VALUE="main">

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 you can have a database field called `goods_type` set to the appropriate value. We will use this Perl routine on the final order form:

     [perl arg=carts interpolate=1]
        my $string = <<'EOF';
     [item-list][item-code]  [item-field goods_type]
     [/item-list]
     EOF
        my @items;
        my %route;
        @items = grep /\S/, split /\n+/, $string;
        for(@items) {
            my ($code, $keycode) = split /\t/, $_;
           $route{$code} = $keycode;
        }
        my $cart = $Carts->{'main'};
        my $item;
        foreach $item ( @{ $Carts->{'main'} } ) {
            $item->{mv_order_route} = $route{$item->{'code'}} || undef;
        }
        return '';
     [/perl]

Now the individual items are labeled with a `mv_order_route` value which will cause their inclusion in the appropriate order routing.

Upon submission of the order form, any item labeled `HARD` will be accumulated and sent to the email address `hardgoods@minivend.com`, where presumably 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, perhaps by reading a value set in the profile).

The `main` order routing will use CyberCash to charge the order, and will be completely encrypted for emailing.

### Index Up <<