Projects:Carrier Integration/Technical Specification
Contents |
Introduction
In this document are described all the developments needed to properly implement the Carrier Integration and Seur Spain Integration modules.
Module Definition
Integration Base Module
- Name: Carrier Integration
- Java Package: org.openbravo.erputil.carrierintegration
- DB Prefix: OBEUCI
- Commercial: Yes
- Dependencies:
- Freight Management
- Warehouse Packing
Seur Spain Integration Module
- Name: Seur Spain Integration
- Java Package: org.openbravo.erputil.carrierintegration.seurspain
- DB Prefix: OBEUSES
- Commercial: Yes
- Base language: Spanish (Spain)
- Dependencies:
- Carrier Integration
The module integrates with Spanish SEUR carrier and aims the Spanish market so the base language is Spanish (Spain).
Integration Base Module
New window
Carrier Integration
In this window is configured the Carrier Integration. Each module Integrating carriers have to include a record in this window for each of the carriers integrated. Single tab structure. The window is only visible for System Administrator roles.
- Header
- OBEUCI_Carrier table. Integrated carrier definition, including the Java Class implementing the integration methods.
Modified Windows
Goods Shipment
New button Integrate with Carrier that launches the Integration Process when a freight with an available integration is selected.
Packing
New fields
- Integration Status
- Stores the result of the Integration Process. Possible values are: Successfully Integrated (DONE), Error in the integration (ERROR) and Pending to integrate with carrier (PENDING)
- Freight
- Defines the Freight selected to ship the pack to the customer.
New button Integrate with Carrier that launches the Integration Process when a freight with an available integration is selected.
Carrier
New field Carrier Integration to select the Carrier Integration Process to be executed when a freight of this carrier is selected.
New Processes
Send Shipment to Carrier
Executed by a button in the Goods Shipment window. Only available when the Shipment has a related Packing in Complete status and a Freight selected.
The Process allows multiple selection and calls to the OB.OBEUCI.Process.sendship javascript function defined in the ob-sendpack.js file. The process is managed by the SendPackHandler action handler.
Send Pack to Carrier
Executed by a button in the Packing window. Only available when the Pack has an Integration Status different than Done and the pack is Processed.
The Process allows multiple selection and calls to the OB.OBEUCI.Process.sendpack javascript function defined in the ob-sendpack.js file. The process is managed by the SendPackHandler action handler.
SendPackHandler action handler
In case the process is launched from the Goods Shipment window the process gets all the Packings related to them.
For each Pack it gets the corresponding Class that extends the CarrierIntegration Class. If none is found an error is thrown. Once the class is found a new Instance is created and it is processed with the Pack information.
When all the packs are processed a message is shown in the window with the result of each goods shipment / pack integration process. And the integration status of each pack is updated.
CarrierIntegration abstract class
This class must be implemented by the modules that Integrates with a Carrier. Each Carrier must have its own implementing class.
The integration is structured in several steps:
Init
This method initializes the Integration Process global objects using the Pack that is being integrated. It loads the Boxes of the pack ordered by the Box Number. If the Pack does not have any box a error is returned. Available global objects are:
- protected Packing pack;
- protected List<PackingBox> boxes;
- protected String errorMsg;
- protected int result;
Validate
Once the Integration is initialized some validations are done. Common validations included in the abstract class are:
- Mandatory Business Partner in the Pack. This is the customer the Pack is sent to. It contains the Contact information.
- Mandatory Partner address in the Pack. This is the destination address of the Pack.
- Integration status of the Pack different than DONE.
Additional validations might be added by each integration module implementing the doValidate abstract method. When a validation error is found a new OBException needs to be thrown. These exceptions are caught by the SendPackHandler action handler.
Process
When all the validations are successful it is executed the integration process. To do so each integration module must implement the doProcess abstract method.
A proper implementation of the doProcess method must include:
- Updating the Tracking Number of each Box with the number retrieved in the integration.
- Set a message using the setMessage() method with the result of the integration.
- Set the result using the setResult() method. Available values are:
- RESULT_ERROR = 0;
- RESULT_SUCCESS = 1;
- RESULT_WARNING = 2;
Seur Spain Integration Module
New window
Seur Integration Configuration
Single tab window based on OBEUSES_SEUR_CONF table. Contains all the parameters needed to configure the integration with Seur. It is linked with the Carrier Integration window with a default value set to the Seur carrier included in the module.
Modified Windows
Carrier window
New fields on Freight tab.
- Product field
- A list with all the Products available on the Seur platform.
- Service field
- A list with all the Services available on the Seur platform.
SeurIntegration class
Class extending CarrierIntegration abstract class.
It overrides 3 methods:
init()
Initializes global object with the OBEUSES_SEUR_CONF to be used with the configuration parameters.
doValidate()
It implements some extra validations with values needed for a successful integration:
- Existence of a configuration record.
- Existence of a Seur Product defined in the Freight of the Pack
- Existence of a Seur Service defined in the Freight of the Pack
- Existence of a Document Number in the Pack.
doProcess()
It implements the integration process. Seur integration uses SOAP protocol to communicate with its system.
The process has to create a SOAP message. Based on the boxes of the pack and the business partner and address defined in the pack.
When the message is created it is sent to Seur and the response is retrieved in a new SOAP message.
Finally the response is read to retrive the Tracking Number of each of the boxes and the Print Trace that it is stored in the Pack.