Oracle Transportation Management

External Programming Interface Guide

Release 6.1
Part No. E16557-01
December 2009

Oracle Transportation Management External Programming Interface Guide, Release 6.1

Part No. E16557-01
Copyright 2009, Oracle and/or its affiliates. All rights reserved.
This software and related documentation are provided under a license agreement containing
restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly
permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate,
broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any
form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless
required by law for interoperability, is prohibited.
The information contained herein is subject to change without notice and is not warranted to be errorfree. If you find any errors, please report them to us in writing.
If this software or related documentation is delivered to the U.S. Government or anyone licensing it on
behalf of the U.S. Government, the following notice is applicable:
U.S. GOVERNMENT RIGHTS
Programs, software, databases, and related documentation and technical data delivered to U.S.
Government customers are "commercial computer software" or "commercial technical data" pursuant
to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As
such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions
and license terms set forth in the applicable Government contract, and, to the extent applicable by the
terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial
Computer Software License (December 2007). Oracle USA, Inc., 500 Oracle Parkway, Redwood City,
CA 94065.
This software is developed for general use in a variety of information management applications. It is
not developed or intended for use in any inherently dangerous applications, including applications
which may create a risk of personal injury. If you use this software in dangerous applications, then
you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to
ensure the safe use of this software. Oracle Corporation and its affiliates disclaim any liability for any
damages caused by use of this software in dangerous applications.
Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be
trademarks of their respective owners.
This software and documentation may provide access to or information on content, products, and
services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly
disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle
Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to
your access to or use of third-party content, products, or services.

ii

Copyright 2009, Oracle and/or its affiliates. All rights reserved.

Contents
CONTENTS................................................................................................ III
SEND US YOUR COMMENTS ......................................................................... V
PREFACE ................................................................................................. 1-1
CHANGE HISTORY .................................................................................................. 1-1

1. EXTERNAL DISTANCE ENGINE ........................................................... 1-1

JAVA INTERFACE FOR EXTERNAL DISTANCE CALCULATION............................................... 1-1
SET UP ............................................................................................................................. 1-1

ORACLE TRANSPORTATION MANAGEMENT API EXPLANATION .......................................... 1-2

INPUTS: ............................................................................................................................ 1-2
OUTPUTS: .......................................................................................................................... 1-2

JAVA INTERFACE FOR EXTERNAL LOCATION VALIDATION ................................................ 1-2

SET UP ............................................................................................................................. 1-3

ORACLE TRANSPORTATION MANAGEMENT API EXPLANATION .......................................... 1-3

INPUTS: ............................................................................................................................ 1-3
OUTPUTS ........................................................................................................................... 1-3

2. EXTERNAL RATING ENGINE ............................................................... 2-1

JAVA INTERFACE FOR EXTERNAL RATE CALCULATION ..................................................... 2-1
SET UP ............................................................................................................................. 2-1

ORACLE TRANSPORTATION MANAGEMENT API EXPLANATION .......................................... 2-3

INPUTS: ............................................................................................................................ 2-3
OUTPUTS: .......................................................................................................................... 2-4

3. DIRECTORY INFORMATION ............................................................... 3-1

Copyright 2009, Oracle and/or its affiliates. All rights reserved.

iii

Send Us Your Comments

Oracle Transportation Management External Programming Interface Guide, Release 6.1
Part No. E16557-01
Oracle welcomes your comments and suggestions on the quality and usefulness of this publication.
Your input is an important part of the information used for revision.

Did you find any errors?

Is the information clearly presented?

Do you need more information? If so, where?

Are the examples correct? Do you need more examples?

What features did you like most about this manual?

If you find any errors or have any other suggestions for improvement, please indicate the title and
part number of the documentation and the chapter, section, and page number (if available). You can
send comments to us in the following ways:

Electronic mail: otm-doc_us@oracle.com

FAX: 610-491-9897 Attn: Manager OTM Curriculum & Documentation

Postal service:
Manager OTM Curriculum & Documentation
Oracle Corporation
1016 W. Ninth Ave.
Suite 300
King of Prussia, PA 19406
USA

If you would like a reply, please give your name, address, telephone number, and electronic mail
address (optional).
If you have problems with the software, contact Support at https://support.oracle.com or find the
Support phone number for your region at http://www.oracle.com/support/contact.html.

Copyright 2009, Oracle and/or its affiliates. All rights reserved.

Preface
The intent of this document is to provide documentation for the Java APIs that have been exposed for
customers or third parties to extend existing Oracle Transportation Management functionality. These
external APIs are stand alone objects with a Java interface provided by Oracle Transportation
Management to minimize the programming effort and maximize runtime performance.

Change History
Date

Document Revision

Summary of Changes

12/15/09

-01

Initial release.
Added Location Validation

Copyright 2009, Oracle and/or its affiliates. All rights reserved.

1-1

1. External Distance Engine

Java Interface for External Distance Calculation
The customer has the ability to interface Oracle Transportation Management to any 3rd party distance
engine by writing their own Java class using the existing Oracle Transportation Management interface.
This will allow a custom tailored distance engine to meet a customers specific needs. They can use the
ExternalDistanceEngineLookupSample.java module as a template to retrieve geo coding from Oracle
Transportation Management and pass the result back to Oracle Transportation Management.

Set Up
The first step is to ensure there is a valid External Distance Engine (EDE) defined in Oracle
Transportation Management that has the path to a custom Java class defined. This is the main link
between Oracle Transportation Management and a custom EDE. If the path is incorrect or points to a
java class that does not implement ExternalDistanceEngineInterface any lookup using the EDE will
fail. Parameters that are required for the specific EDE can be entered in the parameters table on the
EDE itself and are mapped via the parms variable in the interface.
The structure for this External Distance Engine will be:

External Distance Engine Power Data

Field

Value

External Distance Engine

ID

User Defined

Java Class

Ex:
glog.externalapi.distanceengine.MyExternalEngine

This path needs to

point to wherever
the external
interface is located

Cache Control Type

CACHE_OFF = N

Defines whether
the lookup return
value will be
cached and how.
There are more
detailed
descriptions in
Oracle
Transportation
Management help.

CACHE_BY_XLANE_LOOKUP_SAVE = Y
CACHE_BY_XLANE_LOOKUP_NO_SAVE = L
CACHE_BY_XLANE_NO_LOOKUP_SAVE = C
CACHE_BY_ADDRESSES_LOOKUP_SAVE = A
County Override ID

User Defined

Comments

If a county needs
to be translated
before its passed
to the Distance
Engine, it will have
to be mapped in
the County
Override Table.

Copyright 2009, Oracle and/or its affiliates. All rights reserved.

1-1

External Distance Engine Parameters

Parameter

Value

Country Code

Comments

User Defined

User Defined

User Defined

These parameters will

be available to the
external Java class and
can be used for program
control and/or data.
This is in reference to
the fifth input below.

* for all countries

Oracle Transportation Management API Explanation

Inputs:
In the ExternalDistanceEngineLookupSample class, there are several arguments.

SourceAddr is type ExtEngineAddress that contains all the location information for the start
address.

DestAddr is type ExtEngineAddress that contains all the location information for the
destination address.

AuxInput is another class that can contain SCAC and Route Codes off the location. This is
usually only necessary for Rail lookups and is avaliable as read-only.

The ExternalEngineGid displays the name of the EDE defined.

Parms is a mapping to all the input parameters that were entered in Oracle Transportation
Management for the specific EDE.

ExtEngineAddress, ExtEngineAuxInput and ExtEngineInputParam are explained in the included

JavaDocs.

Outputs:
Exception Handling:
ExtEngineException.java is explained in the JavaDoc.
Its default constructor is in the format ExtEngineException(Throwable t, String s) and can also
handle a single argument of type String or Throwable.

Standard Output:
Return ExtEngineDistance(25.4 MI);
Or, optional:
Return ExtEngineDistance(MI, 25.4);
Unit of measure is user defined and no conversions will take place

Java Interface for External Location Validation

You have the ability to interface Oracle Transportation Management to any 3rd party engine that
supports location validation by writing your own Java class using the existing Oracle Transportation
Management interface. This will allow a custom-tailored engine to meet your specific needs. You can
use the ExternalDistanceEngineLookupSample.java module as a template to retrieve location data
1-2

Copyright 2009, Oracle and/or its affiliates. All rights reserved.

from Oracle Transportation Management and pass the result back to Oracle Transportation
Management.

Set Up
The first step is to ensure a valid EDE is defined. The setup for the validation is the same as the Java
interface for external distance calculation described above. The only difference is that location
validation does not cache any results so the EDE cache setting will be ignored.

Oracle Transportation Management API Explanation

Inputs:
In the ExternalDistanceEngineLookupSample class, there are several arguments.

SourceAddr is type ExtEngineAddress that contains all the location information for the location
to be validated.

AuxInput is another class that can contain other data and is available as read-only.

The ExternalEngineGid displays the name of the EDE defined.

Parms is a mapping to all the input parameters that were entered in Oracle Transportation
Management for the specific EDE.

ExtEngineAddress, ExtEngineAuxInput and ExtEngineInputParam are explained in the included

JavaDocs.

Outputs
Exception Handling
ExtEngineException.java is explained in the JavaDoc.
Its default constructor is in the format ExtEngineException(Throwable t, String s) and can also
handle a single argument of type String or Throwable.

Standard Output:
Return LocationAddressMatches();
LocationAddressMatches is the return type for the validateAddress method in the interface. Details of
this class are provided in the javadoc. For engines that support multiple suggested locations,
LocationAddressMatches does have a List object that takes type ExtEngineAddress and can contain the
returned locations data.

Copyright 2009, Oracle and/or its affiliates. All rights reserved.

1-3

2. External Rating Engine

Java Interface for External Rate Calculation
You have the ability to interface Oracle Transportation Management to any third party rating engine by
writing your own Java class using the existing Oracle Transportation Management interface. This will
allow a custom tailored rating engine to meet a customers specific needs. They can use the
glog.externalapi.rateengine.samples.REXJavaTest.java module as a template to retrieve input data
from Oracle Transportation Management and pass the result back to Oracle Transportation
Management.

Set Up
The first step is to ensure there is a valid External Rating Engine (ERE) Fieldset defined in Oracle
Transportation Management that has the path to a custom Java class defined. This is the main link
between Oracle Transportation Management and a custom ERE. If the path is incorrect or points to a
java class that does not implement glog.externalapi.rateengine.REXPublicExternalInterface, any
lookup using the ERE will fail.

External Rating Engine Fieldsets

Field

Value

Comments

Fieldset ID

USER_DEFINED

Identifies the fieldset

Valid External Rating

Engine ID

USER_DEFINED

Identifies the external

rating engine that can
utilize this particular
fieldset.

(recommend GENERIC a predefined

external rating engine ID)
Connection Type

Defines the type of

transport mechanism used.
In this case, J = javaclass
which implements
REXPublicExternalInterface.
Other communication
mechanisms will be
supported in future
iterations.

Implementing Java Class

(should be a subset of GC3External

directory)

Specifies the fully qualified

name of the java class
which will implement the
link to the external rating
engine. This class will only
be instantiated one time.

glog.externalapi.rateengine.CLASS_NAME

The External Rating Engine Fieldset also specifies the information that will be passed from Oracle
Transportation Management into the invocation of the external engine by defining a list of one or more
Rate Basis Items (RBIs). Using the lower half of the Fieldset Power Data UI screen, a user can select
a set of RBIs and include them in the fieldset by clicking on one of the right-pointing arrows. These
RBI references (listed below under the GID column) are stored in the
external_rating_engine_fieldset_d table.
Copyright 2009, Oracle and/or its affiliates. All rights reserved.

2-1

RBI

GID

Shipment Number of Line Items

SHIPMENT.NUMLINES

Shipment Source Postal Code

SHIPMENT.SOURCE.POSTAL_CODE

Shipment Destination Postal

Code

SHIPMENT.DEST.POSTAL_CODE

Rate Offering Service Provider

SHIPMENT.RATE.SERVPROV

Rate Offering Rate Service

Calculator

SHIPMENT.RATE.RATE_SERVICE

Shipment Line Item Weight

SHIPMENT.LINES.WEIGHT

There are two ways to invoke an external rating engine using Oracle Transportation Management:

1. Rate Offering method

This method attaches the invocation of an external rating engine to the rate offering. Current,
purpose-build external rating engines are currently invoked using this method. An example would be
our current implementation of our link to SMCs Rateware LTL rating engine. This method requires a
rate offering to specify a Rate Offering Type that includes the EXTERNALRATINGENGINE rate attribute
in its costing sequence. The following fields must be specified on the Attributes page of the Rate
Manager UI:
Field

Value

Comments

External Rating Engine ID

GENERIC

Select the GENERIC external rating

engine.

External Engine Fieldset ID

USER_DEFINED

Choose the fieldset defined for the

external engine that invokes only
the accessorial calculations.

2. Rate Cost method

It is now possible to specify the invocation of an external rating engine as a rate cost during the
processing of standard costs, or during the processing of accessorial costs. The new rate cost UI
contains a Cost Type dropdown list. Choosing the value of External allows the specification of the
same external rating engine fields as found on the Rate Manager UI:

Rate Manager: Rate Costs or Accessorial Cost

Field

2-2

Value

Comments

Copyright 2009, Oracle and/or its affiliates. All rights reserved.

Field

Value

Comments

Cost Type

External

This is a field that explicitly defines

the type of calculation described by
the cost record.

External Rating Engine ID

GENERIC

Select the GENERIC external rating

engine.

External Engine Fieldset ID

USER_DEFINED

Choose the fieldset defined for the

external engine that invokes only
the accessorial calculations.

Optional Service Time

There is also an option to return the service time from the external rating engine. For this type of rate
service, the rate engine will return the specific pickup time and delivery time for a shipment. The rate
service engine uses the pickup and delivery time to test whether it will fit into the orders pickup and
delivery windows. If not, this rate cannot be used.
There are two ways to return service time information from a rating engine

The external rating engine can fill in the estimated pickup and delivery times. The RATE
SERVICE object associated with the rate must have a service type of TIMEDEFINITESERVICE

The external rating engine can fill the serviceDays field. The RATE SERVICE object associated
with the rate must have a service type of EXTERNAL SERVICE DAYS.

If the rate service doesnt have the above service types, then the service time data returned from the
rating engine will be ignored and an exception will be thrown, flagging the rate as infeasible.
For this type of rate service, location calendar, location capacity and carrier capacity are not
considered. Pickup or delivery activity time at a stop is always 0.
The following assumptions also hold true:

Only applies to 2-stop shipments

It does not make sense to have HOLD AS LATE AS POSSIBLE set to TRUE
regardless of the setting of the planning parameter HOLD AS LATE AS POSSIBLE, this type of
rate service is always calculated in HOLD AS LATE AS POSSIBLE = false.

Orders pickup and delivery windows should be a whole day. If the orders have a narrow
pickup and delivery window, the specific pickup time and delivery time will fall out of the
orders windows, so it will fail to use this rate. For example, the orders delivery window is
10:00-11:00am, but rate engine come back with a delivery time of 4:00PM, then rate service
will fail this rate.

It only applies to single leg shipments: i.e., shipment with rate service type cannot have
upstream and downstream shipment.

Oracle Transportation Management API Explanation

Inputs:
In the REXJavaTest class, costShipment method:

Copyright 2009, Oracle and/or its affiliates. All rights reserved.

2-3

There is one input parameter. A type, Map, that uses a String Argument for the key and a list of
Strings for the values. It will be similar to this:

{SHIPMENT.NUMLINES,3},
{SHIPMENT.SOURCE.POSTAL_CODE,19406},
{SHIPMENT.DEST.POSTAL_CODE,34639},
{SHIPMENT.RATE.SERVPROV,UPS },
{SHIPMENT.RATE.RATE_SERVICE,UPS GROUND},
{SHIPMENT.RATE.SERVPROV_ACCOUNT_NUMBER, 12345634},
{SHIPMENT.LINES.WEIGHT,{10 LB,15 LB,10 LB}}*

Outputs:
glog.externalapi.ratengine.REXRateResult has the following public member variables and is
explained in more detail in the JavaDoc:

REXRateResult:

String err: If this is set, this shows an error in the log but will not throw an exception

Collection<CostDetail> details

Integer serviceDays: If the ERE returns the number of service days, this can be set here.
Otherwise a value of NULL equals no data.

Long utcPickupDateTime: Estimated pickup time, UTC

String pickupTimezone: Max of 50 characters, java-style timezone identifer (ex. EDT,

America/Chicago, etc.)

Long utcDeliveryDateTime: Estimated delivery time, UTC

String deliveryTimezone: Max of 50 characters

Double chargeableWeight: Chargeable weight. Copied to the Shipments chargeable weight

field. Only used when invocation of ERE is specified on the Rate Offering

String chargeableWeightUom: Unit of Measure for the chargeable weight (ex. LB, KG, etc.)

Double dimWeight: Dimensional weight. Copied to the Shipments dimensional weight field.
Only used when invocation of ERE is specified on the Rate Offering

String dimWeightUom: Unit of Measure for the dimensional weight

Collection<CostDetail> details: Details about each individual cost calculated by the external
rating engine

REXRateResult.CostDetail:

2-4

Double cost: Numeric value of the final calculated cost

String currencyCode: Currency code of the cost (USD, GBP, etc.)

CostType costType: One of (Base, Accessorial, Discount, SpecialService)

String accessorialCode: If this cost is an accessorial, the accessorial code is specified here.
This code must exist in Oracle Transportation Management.

String costCode: Secondary accessorial code for classification purposes only. This code must
exist in Oracle Transportation Management.

String specialServiceCode: If this cost is a special service, the special service code is specified
here. This code must exist in Oracle Transportation Management.

Boolean isWeightedCostOnly: Some costs are calculated as weighting factors that do not affect
the actual final cost of a shipment. Set this field to true if this is a weighted cost.

Collection<String> calculationDetails: A list of simple text strings that the ERE implementor
can use to give detailed information on how a cost was calculated.

Copyright 2009, Oracle and/or its affiliates. All rights reserved.

Once the input is defined and an actual lookup is complete, the cost Shipment method needs to return
the REXRateResult object.

Copyright 2009, Oracle and/or its affiliates. All rights reserved.

2-5

3. Directory Information
Jar file with custom java classes should be placed in <otm install dir>/glog/gc3webapp/WEBINF/lib/external/. Oracle Transportation Management includes jar files in this directory on the
classpath.

Javadoc Directory: <otm install dir>/externalAPI/doc/

External Distance Engine Sample source code": <otm install

dir>/externalAPI/distance_engine/

External Rating Engine Sample source code": <otm install

dir>/externalAPI/rating_engine/

Copyright 2009, Oracle and/or its affiliates. All rights reserved.

3-1

3-2

Copyright 2009, Oracle and/or its affiliates. All rights reserved.