Web integration .NET – nShift

Sections in this article:

Class diagram
ESWebIntegrationWS.asmx.cs
Web.config
Deploying the Web Service
Download .NET project files

Class diagram

The diagram below is a class diagram for the classes that makes up the .NET WS.

The project consists of seven classes. The ESWebIntegrationWS class, which is the main class, contains the web methods we are going to call and it consumes the other 6 classes. The ESWebIntegrationWS class is presented in the file ESWebIntegrationWS.asmx.cs in the project. The other 6 classes are placed in the Classes.cs file.

The sample code in the project is an integration with the open source web shop osCommerce and the database engine is MySQL.
Lets take a look at the Classes.cs and ESWebIntegrationWS.asmx.cs files and explain the use of the classes which is present here.

The LoginCredentials class handles the credentials for user authentication based on the credentials that is used in Consignor. Every web method has LoginCredentials as an input parameter.
You can use the credentials UserName and Password to authenticate the user or just one of them.
In the sample code is UserName used to assign the database prefix, so the user get access only to his tables in the database. string strPrefix = Credentials. UserName. You can also edit and use the function: Authenticate(LoginCredentials Credentials) to manage your user authentification and call it from the web methods as you like.
string strPrefix = Authenticate(Credentials).

public class LoginCredentials
{

public string UserName { get; set; }
public string Password { get; set; }
public string Auxiliary { get; set; } Not in use yet

}

The AddressData class handles the data we want to present on the receiver of the shipment.
This class is used both in order GetOrderData) and customer (GetCustomerData) lookup.
Lines that are marked with * are mandatory and this means you have to assign a value to this AddressData class member in the functions
GetOrderData and GetCustomerData.
Edit the sample code to fit your needs of fields from the AddressData class.

public class AddressData
{

public string Number { get; set; } * Unique key (order number, Customer number)
public string Name1 { get; set; } * Receivers name – Company or private person
public string Name2 { get; set; } C/O or department, not in use in Norway
public string StreetAddress1 { get; set; } Street/Road – must be delivery address
public string StreetAddress2 { get; set; } Department, building, port etc.
public string StreetAddress3 { get; set; } Not in use
public string Postcode { get; set; } * Receivers postal code/Zip code
public string City { get; set; } * Name of delivery city
public string Mobile { get; set; } Used e.g. with SMS service for carrier Posten Norge
public string Phone { get; set; }     Required when sending COD shipments with bedriftspakke(Posten Norge)
public string Email { get; set; } Required if mail back function is used in Consignor
public string Fax { get; set; } Receivers fax number
public string PostOfficeBox { get; set; } Postbox address
public string PostOfficeBoxCity { get; set; } City name of receiver postbox
public string PostOfficeBoxPostcode { get; set; } Postal code for receivers postbox
public string CountryName { get; set; } Necessary for international deliveries. Format isoA2, isoA3, isoN3
public string CustomerOrigin { get; set; } Not in use
public string Attention { get; set; } Contact person name of sender or receiver
public string Contact { get; set; }      Not in use
public string ReceiverRef { get; set; } Reference requested by the receiver. Order/requisitions/invoice number etc.
public string OurRef { get; set; } Not in use
public string MessageToCarrier { get; set; } Carrier may not support this. This will not be printed to the label
public string MessageToDriver { get; set; } Carrier may not support this. This will not be printed to the label
public string MessageToReceiver { get; set; } Carrier may not support this. This will be printed to the label.
public string PurchaseNo { get; set; } Not in use
public string ShipmentTypeNo { get; set; } Drop Point ID / the Id for the chosen drop point on an order
public string DeliveryConditions { get; set; } Not in use
public string DeliveryTime { get; set; } Not in use
public string PaymentTerms { get; set; } Not in use
public string Amount { get; set; }         Not in use
public string Account { get; set; } Not in use
public string Reference { get; set; } Not in use
public AddressType Type { get; set; }* Set type to delivery on GetOrderData and to customers on GetCustomerData functions

}

The LineData class is used in a combination with the AddressData class when you want to get data on an order (GetOrderData) function. LineData provides data members for the shipment.

public class LineData

{

public int PackagesCount { get; set; } Number of colli on the shipment
public string PackagesMarking { get; set; } Marking of the goods, rarely used
public string PackagesContents { get; set; } Parcel or pallet contents
public int PackagesWeight { get; set; } Parcel or pallet weight (gram), used for volume calculation
public int PackagesHeight { get; set; } Parcel or pallet height (mm), used for volume calculation
public int PackagesLength { get; set; } Parcel or pallet length (mm), used for volume calculation
public int PackagesWidth { get; set; } Parcel or pallet width (mm), used for volume calculation
public int PackagesVolume { get; set; } Parcel or pallet volume (mm3)
public string CODAccount { get; set; } Account number for COD payment(rarely used in integration).
public string CODAmount { get; set; } COD amount, comma separated for decimal e.g. for øre.
public string CODKID { get; set; } KID number
public string CODReference { get; set; } Number used for bookkeeping purpose.
public string InsuranceAmount { get; set; } Insurance amount
public string InsuranceCategory { get; set; } Insured package category
public string InsurancePolicyNo { get; set; } Insurances policy number.
public string DeliveryTerms { get; set; } Not in use
public string Department { get; set; } Not in use
public string InvoiceNumber { get; set; } Not in use
public string PaymentTerms { get; set; } A code that determinates if the CODAmount is used on the shipment
public string PaymentType { get; set; } Not in use
public string ProjectName { get; set; } Name of a given project running between a sender and receiver
public string ProjectNumber { get; set; } Number of a given project running between a sender and receiver
public string CarrierCode { get; set; } One single code to select shipping method E.g. code 10 = Servicepakke

}

AddressesAndPackages class consists of two data members that presents an instance of AdressData and LineData as a List
object. These two members are used to return a List object of the data members in AdressData and LineData from
the functions GetOrderData and GetCustomerData.

public class AddressesAndPackages
{
public List<AddressData> Addresses = new List<AddressData>();
public List<LineData> Packages = new List<LineData>();
}

The ReturnData class is used to return data on a shipment from Consignor and back to your system, so you are able to update your database based on the return data. The UpdateData function uses the ReturnData class for this purpose.
ColliNumbers and PackageTrackUrl is semicolon( ; ) separated. ShipmentTrackUrl provides carriers track and trace URL with shipment number and PackageTrackUrl provides track and trace URL with colli numbers.

public class ReturnData
{
public string OrderNumber { get; set; } Order number
public int PackagesCount { get; set; } Number of packages
public string ShipmentNumber { get; set; } Track & Trace shipment number, used for tracking shipment on carrier.
public string ShipmentTrackUrl { get; set; } Track & Trace URL with shipment number
public string ColliNumbers { get; set; } Track & Trace colli numbers used for tracking packages on carrier
public string PackageTrackUrl { get; set; } Track & Trace URL with colli numbers
public string Carrier { get; set; } Carriers name e.g. Posten Norge
public string Product { get; set; } Product name e.g. Bedriftspakke dør-dør
public double Price1 { get; set; } Calculated price on the shipment, nett or gross(Configured in Consignor)
public double Price2 { get; set; } Calculated price on the shipment, nett or gross(Configured in Consignor)

}

The AddressType class represents the enumeration of address types.

public enum AddressType
{

Customer, Used in GetCustomerData function as AddressType.Customer
Order,
Order2,
Delivery, Used in GetOrderData function as AddressType.Delivery
Invoice,
Contact

}

ESWebIntegrationWS.asmx.cs

The ESWebIntegrationWS.asmx.cs file contains all the functions (web methods) that is consumed from Consignor and EDI-Soft`s WS.
The function GetOrderData handles order requests. It connects to the database and fetches the order data from SQL query. The function takes two input parameters, OrderNumber as a string and Credentials as LoginCredentials.
As mentioned before, use credentials to authenticate the user in the way that suits your needs.

public AddressesAndPackages GetOrderData(string OrderNumber, LoginCredentials Credentials)

The connection string for connection to the database is fetched from the web.config file, I will write about the web.config file later. You can code the connection string inline if you wish.
string strConn = ConfigurationManager.AppSettings["DBconnectionstring"];

Enter your SQL query in the variable string strSql.

First a new instance of the class is created then a datareader is used to assign the values from the query to data members for the class AddressData and LineData.
The build in function GetOrdinal is used to find the field in the query by name and map it to a class member.

Convert is used so you don't have to check for DBNull. Without this it would generate an execption if a column in the database is NULL.
Use the data members you want from the classes AddressData (remember to include the mandatory members) and LineData.

Do not edit any of the classes in the file Classes.cs and keep the namespace as it is:
[WebService(Namespace = "http://YourDomain.com/ESWebIntegrationWS.asmx")]

I will not get into details on the other functions, I think the comments in these functions will cover it. Remember to use the database provider that suits your database. Edit this in the fuctions UpdateData and IDataReader.

Web.config

In the web.config file you can find three types of connection string. Connection for ODBC, MS SQL Server and MySQL.
Use the one that suits your database.

<appSettings>

<add key="DBconnectionstring" value="Server=localhost;Port=3306;Database=mystore2;userid=root;password=test;Pooling=false;"/>
</appSettings>
<system.web>

One more things to consider is, set debug to false when you are deploying the WS on the web server and going live.

<system.web>

<compilation
debug="false">

Deploying the Web Service

You have to use Visual Studio or Visual Web Developer Express to edit and build the project. It's written in ASP.NET and the language C#.
It is strongly recommended that you compile your project before you deploy it on your server. Then the application don`t have to compile the code from the cs files on request to the WS. This ensures that the WS is running faster and smoother.

If you are using the full version of Visual Studio, this would be done automatically when you build the project. In Visual Web Developer Express you have to do the compiling trough the command prompt or add this as a custom tool as shown on this site: http://www.informit.com/articles/article.aspx?p=1073232&seqNum=2
This approach will work in 2008 express version and not in 2010 express version.

When the project is compiled you have to deploy the bin folder, ESWebIntegrationWS.asmx and the Web.config files on to your web server. The bin folder should contain the compiled file ESWebIntegrationWS.dll. The bin folder also contains the file MySqlData.dll, which is used as a reference to the MySQL data provider for connections to MySQL database. This dll file must remain in the bin folder if you are using MySQL.

Download .NET project files

To get started, download the project files below. It contains a ready made webservice with sample code. Change the code and SQL queries to fit your system and the data you wish to provide with the web service.

Web-Service-Integration.NET_.zip
300 KB Download

Ship Help

Class diagram

ESWebIntegrationWS.asmx.cs

Web.config

Deploying the Web Service

Download .NET project files

Related articles