@title@

Why

This version of the @package_name@ is a first stab at a service contract offering a generalized interface to shipping operations such as obtaining quotes for services and tracking shipments.

Background

Shipping goods can be a common occurrence on OpenACS sites. Whether it is to ship goods sold through the ecommerce package or to return items after a problem report logged by the ticket tracker.

There are also many different shipping companies to choose from, e.g. UPS, FedEx, Airborne Express, DHL and many others. Most of these shippers have Internet based APIs for initiating shipments and tracking parcels.

Goal of the @package_name@ is to provide a single shipping interface to OpenACS packages regardless of the actual shipping method. Calling packages do not have to be aware of how shipments are handled; this could be one of the aforementioned shipping companies or an in-house solution.

This version of the @package_name@ is very simple on purpose. The complex nature of the problem combined with the multitude of interfaces by shipping companies and the limited capabilities of the current ACS Service Contract API warrant a careful and deliberate approach. Future versions will grow in capabilities while maitaining back-wards compatibility where possible.

Usage

As is, the @package_name@ provides two operations:

RatesAndServicesSelection

The RatesAndServicesSelection returns a list of services offered by the shipper and their associated charges to ship the given parcel from A to B. Services are identified by the shippers service code.

ServiceDescription

The ServiceDescription operation returns the description of the service level identified by the service code.

The @package_name@ only defines these operations. Concrete functions that implement the operations of the contract have to be written for each shipper. See the ACS Service contract for details on writing implementations for service contracts.

Note: This release has been tested with PostgreSQL only. While the contract supports both databases I was not able to test the Oracle version. Please report any problems you might find in the OpenACS SDM.

API Reference

RatesAndServicesSelection

The RatesAndServicesSelection operation takes 8 input arguments:

1. orig_country_iso:string

   The 2 letter ISO abbreviation of the country where the shipment originates. See the countries table for a complete list of ISO standard abbreviations. The countries table is part of the Reference Data - Country package. E.g. 'US'.

2. orig_zip_code:string

   The zip code of the shipment's origin. E.g. '95062'.

3. dest_country_iso:string

   The 2 letter ISO abbreviation of the destination country of the shipment. See the countries table for a complete list of ISO standard abbreviations. The countries table is part of the Reference Data - Country package. E.g. 'NL'.

4. dest_zip_code:string

   The zip code of the shipment's destination. E.g. '7812 PC'

5. shipment_value:string

   The total value of the shipment. E.g. '49.99'.

6. value_currency_code:string

   The 3 letter abbreviation of the currency used to express the shipment value in. See the currencies

7. shipment_weight:string

   The total weight of the shipment. E.g. '7.8'.

8. weight_unit_of_measure:string

   The unit of measure of the shipment weight. E.g. 'lbs'.

RatesAndServicesSelection returns a list of rates and services in a single parameter: rates_and_services:string. The rates_and_services value is a list of arrays. Each array contains the service_code of service level and the total_charges for the service. The following code example illustrates how the list should be interpreted.

 
      
	set rates_and_services [acs_sc_call "ShippingGateway" "RatesAndServicesSelection" \
				    [list "$orig_country_iso" "$orig_zip_code" "$dest_country_iso" "$dest_zip_code" \
	                                "$shipment_value" "$value_currency_code" "$shipment_weight" "$weight_unit_of_measure"] \
				        "$shipping_gateway"]
        foreach service $rates_and_services {
	    array set rate_and_service $service
	    set total_charges $rate_and_service(total_charges)
	    set service_code $rate_and_service(service_code)
	    set service_description [acs_sc_call "ShippingGateway" "ServiceDescription" \
					"$service_code" \
					 "$shipping_gateway"]

        }
      
    

ServiceDescription

ServiceDescription has only one input argument: service_code:string. The operation also returns a single parameter: service_description:string. See the above code example for an illustration of use of the ServiceDescription operation.

Credits

The @package_name@ was designed and written by Bart Teeuwisse for Berklee College Of Music while working as a subcontractor for furfly.net.

The @package_name@ is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

The @package_name@ is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

A copy of the GNU General Public License is included. If not write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA