1. External Programming Interface Guide
  2. Web Service Calculation

Web Service Calculation

A third-party external rating engine can be defined using ERE Fieldset with the connection type of “WebService (W)” which uses a Java class glog.business.rate.rateengine.external.webservice.client.ExternalRatingWebServiceClient. Oracle Transportation and Global Trade Management Cloud as web service client connects to the custom third-party rating engine web service that adheres to the Rating Engine WSDL provided in WSDLs appendix section.

costShipment Operation

Inputs:

There is one input element called inputDataList which contains a list of inputData as its child element. inputData uses a name attribute to store RBI Name and a list of values for the RBI as it child elements. It will be similar to this:
<n:inputData name="SHIPMENT.LINES.COMMODITY">
    <n:values>
       <n:value>COMMODITY1</n:value>
       <n:value>COMMODITY2</n:value>
    </n:values>
</n:inputData>
<n:inputData name="SHIPMENT.LINES.WEIGHT">
    <n:values>
       <n:value>12.0 LB</n:value>
       <n:value>14.0 LB</n:value>
    </n:values>
</n:inputData>

If the shipment has two lines with two different commodity codes and you want to get the commodity code and weight, you will have to select two RBI. Line Item Commodity Code (SHIPMENT.LINES.COMMODITY), Line Item Weight (SHIPMENT.LINES.WEIGHT). The input element will have both the commodity and weight elements separately but in the same order i.e. COMMODITY1 weight is 12.0 LB and COMMODITY2 weight is 14.0 LB.

Outputs:

rexRateResult has the following child elements

  • err: If this is set, this shows an error in the log but will not throw an exception.
  • serviceDays: If the ERE returns the number of service days, this can be set here. Otherwise, a value of NULL equals no data.
  • utcPickupDateTime: Estimated pickup time, UTC. The type of this variable is long. The value should be in milliseconds i.e. number of milliseconds of this time since January 1, 1970, 00:00:00 GMT. The section “utcPickupDateTime and utcDeliveryDateTime elements” provides more information. If both utcPickupDateTime and utcPickupDateTimeStdFormat, then utcPickupDateTimeStdFormat takes precedence.
  • utcPickupDateTimeStdFormat: Estimated pickup time. The type of variable is xs:dateTime. When xs:dateTime is used to define a date or date time field for a SOAP Web Service, wsimport tool will use java class XMLGregorianCalendar object in the java client and the default formatting for XMLGregorianCalendar object is yyyy-MM-dd'T'HH24:mm:ss.SSSZ. Hence, provide the date time in this format. One more thing to note here is that the ‘Z’ in the format represents time zone offset (E.g. +2:00, +3:00, -4:00, -5:30, +5:30 etc…) and it is optional. If the timezone offset is provided, pickupTimeZone element should not be provided. If both utcPickupDateTime and utcPickupDateTimeStdFormat, then utcPickupDateTimeStdFormat takes precedence.
  • pickupTimezone: Max of 50 characters, java-style time zone identifier (ex. EDT, America/Chicago, etc.). Provide this element only if the time zone offset is not provided in utcPickupDateTimeStdFormat element.
  • utcDeliveryDateTime: Estimated delivery time, UTC. The type of this variable is long. The value should be in milliseconds i.e. number of milliseconds of this time since January 1, 1970, 00:00:00 GMT. The section “utcDeliveryDateTime and utcDeliveryDateTime elements” provides more information. If both utcDeliveryDateTime and utcDeliveryDateTimeStdFormat, then utcDeliveryDateTimeStdFormat takes precedence.
  • utcDeliveryDateTimeStdFormat: Estimated delivery time. The type of variable is xs:dateTime. When xs:dateTime is used to define a date or date time field for a SOAP Web Service, wsimport tool will use java class XMLGregorianCalendar object in the java client and the default formatting for XMLGregorianCalendar object is yyyy-MM-dd'T'HH24:mm:ss.SSSZ. Hence, provide the date time in this format. One more thing to note here is that the ‘Z’ in the format represents time zone offset (E.g. +2:00, +3:00, -4:00, -5:30, +5:30 etc…) and it is optional. If the timezone offset is provided, pickupTimeZone element should not be provided. If both utcDeliveryDateTime and utcDeliveryDateTimeStdFormat, then utcDeliveryDateTimeStdFormat takes precedence.
  • deliveryTimezone: Max of 50 characters. Java-style time zone identifier (ex. EDT, America/Chicago, etc.). Provide this element only if the time zone offset is not provided in utcDeliveryDateTimeStdFormat element.
  • chargeableWeight: Chargeable weight. Copied to the shipment’s 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.)
  • dimWeight: Dimensional weight. Copied to the shipment’s dimensional weight field. Only used when invocation of ERE is specified on the rate offering.
  • dimWeightUom: Unit of measure for the dimensional weight.
  • costDetails: List of costDetail Element where each costDetail is about each individual cost calculated by the external rating engine.
  • shipmentRefnums: List of shipmentRefnum elements where each shipmentRefnum is a pair of shipmentRefnumQualifierGid and ShipmentRefnumValue. The shipmentRefnumQualifierGid needs to be configured to a pre-defined qualifier GID. Whenever a shipment is rated and one of the rates uses this ERE, these reference numbers will be stored on the shipment as reference numbers. For example, the application can return a quote ID and persist it as a reference number on the shipment.

utcPickupDateTime and utcDeliveryDateTime elements

The utcPickupDateTime and utcDeliveryDateTime is of "long" type. If we send the time as a date string, it will be setting it to '0' in Transportation and Global Trade Management Cloud. To make it work, we have to convert the date string utcPickupDateTime and utcDeliveryDateTime to milliseconds and replace the dates with the milliseconds in the response XML.

Please refer the sample code to convert date of 2019-08-06T16:30 to milliseconds:

import java.util.Calendar;
import java.util.Date;
public class Sample {
	public static void main(String []args) {                      
		convertDateToMillis(2019, Calendar.AUGUST, 06, 16, 30, 00);                      
	}	
	public static long convertDateToMillis(int year, int month, int date, int hour, int minutes, int seconds) {
		Calendar cal = Calendar.getInstance();		
		cal.set(Calendar.YEAR, year);
		cal.set(Calendar.MONTH, month);
		cal.set(Calendar.DATE, date);		

		cal.set(Calendar.HOUR_OF_DAY, hour);
		cal.set(Calendar.MINUTE, minutes);
		cal.set(Calendar.SECOND, seconds);

		Date fullDate = cal.getTime();
		
		System.out.println("The date is : "+fullDate);
		System.out.println("Millisecons : "+fullDate.getTime()); // date to milliseconds
		
		return fullDate.getTime();
	}
}
costDetail:
  • cost: Numeric value of the final calculated cost.
  • currencyCode: Currency code of the cost (USD, GBP, etc.)
  • costType: One of Base, A - Accessorial, O - Other, D - Discount, S - Stop-off, C - Circuity, L – Delta.
  • accessorialCode: If this cost is an accessorial, the accessorial code is specified here. This code must exist in Oracle Transportation and Global Trade Management Cloud.
  • costCode: Secondary accessorial code for classification purposes only. This code must exist in Oracle Transportation and Global Trade Management Cloud.
  • specialServiceCode: If this cost is a special service, the special service code is specified here. This code must exist in Oracle Transportation and Global Trade Management Cloud.
  • 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.
  • calculationDetails: A list of simple text strings that the ERE implementer can use to give detailed information on how a cost was calculated.
shipmentRefnum:
  • shipmentRefnumQualifierGid: A valid shipment reference number qualifier gid defined in OTM.
  • shipmentRefnumValue: A reference number value defined for the qualifier.

Once the input is defined and an actual lookup is complete, the cost shipment method needs to return the rexRateResult.

Note:

All the values for XML elements involved in web service should be valid as per Oracle Transportation and Global Trade Management Cloud WSDL.