VB.NET example

See Toolkit - Install and Toolkit - Create for general information that will set the context for using this particular example.

The VB.NET example is based on a solution named: Custom Rate Engine.sln which is used to create a simple web application able to handle Pierbridge Rate Requests and generate rates accordingly. This solution can be modified to match the requirements of each project. The solution consists of following files:

• CustomRateEngine.aspx
• CustomRateParameters.vb
• LogFile.vb
• Web.config

The CustomRateEngine.aspx.vb consists of the main logic of the Custom Rate Engine. This class contains the following methods, which can be called to demonstrate the creation of a Pierbridge Rate Response:

• Example1() - This method will receive a request from the product, access some most commonly used parameters from the request, and create a Pierbridge Rate Response based around the rating logic as an http response to each request.
• Example2() - This method will receive a request from the product, which includes the Pierbridge Rate Request and the Pierbridge Rate or Ship Response present as a child element. Using the request it will access some most commonly used parameters from the response and create a Pierbridge Rate Response based around the rating logic as a http response to each request.

Access request properties

The Pierbridge Rate Request data will be stored in a number of CustomRateParameters which provide an easy access to each individual field through a property. If necessary, access to these parameters can be obtained by:

Dim packageIndex As Integer = 1
Dim parameters As New CustomRateParameters(xml)
parameters.InsuranceType(packageIndex);

It is worth noting that the parameters are pulled out from the request and stored in string format. Therefore, any type checks should be handled accordingly by the custom solution. This is due to the fact that different Custom Rate Engines are likely to deal differently with null and empty values. When expanding the sample code to suit the needs of the project, it may be beneficial to inspect whether the CustomRateParameters class would benefit from appropriate return types for different parameters.

Public ReadOnly Property Carrier()
  Get
    Return Me._request.SelectSingleNode("/*/Carrier").InnerText
  End Get
End Property

The example below shows how a type can be checked before casting and accessing an integer value, which originally has been stored as a string parameter.

If Not String.IsNullOrEmpty(parameters.Carrier()) Then
  Dim carrierId As Integer = Convert.ToInt32(parameters.Carrier())
End If

Access response properties

The Pierbridge Rate or Ship Response is present as a child of the root element. This xml contains the data returned from the carrier, such as rates, zone etc., in the Pierbridge format.

The Pierbridge Ship or Rate Response data is also stored in a number of CustomRateParameters which provide an easy access to each individual field through a property. These properties are can be found in the Response Properties region in this class. If necessary, access to these parameters can be obtained by:

Dim parameters as new CustomRateParameters(xml)
Dim myZone as string = parameters.Zone;

The rates returned by the carrier can be accessed via a list property named CarrierRates:

Public ReadOnly Property CarrierRates() As XmlNodeList
  Get
    Return Me._request.SelectSingleNode(ResponsePath & "/Rates").ChildNodes
  End Get
End Property

Example methods have been written to demonstrate access to specific child elements of a given rate, for example:

Public Function RateWeight(Rate As XmlNode) As Double
  Dim ratedWeight As Double = 0
  If Rate.SelectSingleNode("RateWeight") IsNot Nothing Then
    Double.TryParse(Rate.SelectSingleNode("RateWeight").InnerText, ratedWeight)
  End If
  Return ratedWeight
End Function

These properties and methods can be used as follows:

Dim carrierRates As XmlNodeList = _parameters.CarrierRate
Dim rateWeight As Double = _parameters.RateWeight(carrierRates.Item(0))

Create Pierbridge Rate Response

Any response file manipulation has been done by using a simple string builder to demonstrate the context and in order to keep the example code easy to read. Based on the simple logic present for rating the response is generated:

Dim Builder As New StringBuilder
Dim Response As String = String.Empty

Builder.Append("<?xml version=""1.0"" encoding=""UTF-8""?>")
Builder.Append("<PierbridgeRateResponse xmlns:xsi=""http://www.w3.org/2001/XMLSchema-instance"">")
Builder.Append("<TransactionIdentifier/>")
…
Builder.Append("<Packages><Package>")
Builder.Append("</Package></Packages></PierbridgeRateResponse>")

Response = Builder.ToString()

It is important to match the rate type node with the rate engine custom rate. Rates are inserted appropriately within the response structure:

‘chargegroups
builder.Append("<ChargeGroups>");
‘chargegroup - accessorials
builder.Append("<ChargeGroup>");
builder.Append("<ChargeGroupType>1</ChargeGroupType>");
builder.Append("<ChargeGroupDescription>Accessorial Charges</ChargeGroupDescription>");
builder.Append("<ChargeGroupValue>" + accessorialCharge.ToString() + "</ChargeGroupValue>");
builder.Append("<ChargeGroupCurrency>USD</ChargeGroupCurrency>");
‘charges - cod
builder.Append("<Charges><Charge>");
builder.Append("<ChargeType>3</ChargeType>");
builder.Append("<ChargeDescription>COD Charge</ChargeDescription>");
builder.Append("<ChargeValue>" + codCharge.ToString() + "</ChargeValue>");
builder.Append("<ChargeGroupCurrency>USD</ChargeGroupCurrency>");
builder.Append("</Charge>");
‘charges - total accessorials
builder.Append("<Charge>");
builder.Append("<ChargeType>15</ChargeType>");
builder.Append("<ChargeDescription>Total Accessorial Charge</ChargeDescription>");
builder.Append("<ChargeValue>" + accessorialCharge.ToString() + "</ChargeValue>");
builder.Append("<ChargeGroupCurrency>USD</ChargeGroupCurrency>");
builder.Append("</Charge></Charges>");
builder.Append("</ChargeGroup>");
builder.Append("</ChargeGroups>");

See Charge Types and Charge Base Types for listings from the Transtream database.

Commitment Date and Time returned in response

Rate Response can return DeliveryDate and DeliveryTime elements, as shown below:

DateTime shipDate = DateTime.Today;
StringBuilder builder = new StringBuilder();
string response = String.Empty;

string deliveryDateString = System.Configuration.ConfigurationManager.AppSettings["DeliveryDate"];
string deliveryTimeString = System.Configuration.ConfigurationManager.AppSettings["DeliveryTime"];

builder.Append("<?xml version=\"1.0\" encoding=\"UTF-8\"?>");
builder.Append("<PierbridgeRateResponse xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\">");
builder.Append("<Rates><Rate>");
//ratetype
builder.Append("<RateType>10</RateType>");
builder.Append("<RateDescription/>");
builder.Append("<ShipDate>" + shipDate.ToString("yyyy-MM-dd") + "</ShipDate>");
builder.Append("<DeliveryDate>" + deliveryDateString + "</DeliveryDate>");
builder.Append("<DeliveryTime>" + deliveryTimeString + "</DeliveryTime>");
builder.Append("<Interline/>");
builder.Append("<Expedited/>");
builder.Append("<DisplayRate/>");
builder.Append("<UpdateRate/>");
//chargegroups
builder.Append("<ChargeGroups>");
//chargegroup - accessorials
builder.Append("<ChargeGroup>");
builder.Append("<ChargeGroupType>1</ChargeGroupType>");
builder.Append("<ChargeGroupDescription>Accessorial Charges</ChargeGroupDescription>");
builder.Append("<ChargeGroupValue>" + accessorialCharge.ToString() + "</ChargeGroupValue>");

Error logging

The rate engine uses a log file for error logging in case any error occurs. If logging is enabled, the error messages are written in a log file. The error log path is configured in the Web.config file and should be modified to match the installation.

<appSettings>
<add key="LogFilePath" value="C:\Temp\Custom Rate Engine" />
<add key="Logging" value="true" />
</appSettings>

Error messages are customizable and can be changed:

LogFile.WriteLogToFile("Custom Error Message”);

In addition, the rate engine outputs the request and response xml to the files; Request (CRE).xml and Response (CRE).xml respectively. These files are placed in the same folder as above.