268584
268584 - NW-7V4EKL/ Loc creation from CIM to MTS Ord Msg
Copyright OBS Logistics © 2010
The information contained herein is the property of OBS Logistics and is supplied without liability for errors or omissions. No part may be reproduced or used except as authorised by contract or other written permission. The copyright and foregoing restriction on reproduction and use extend to all media in which the information may be embodied
FUNCTIONAL OVERVIEW
Client Requirement
The CIM order interface is already provided in XML using the OBS TripOrder XSD format. This order interface already provides the full address information including an ID, name, address lines, town, county, country and postcodes.
The XSD needs to be modified to allow the following additional data fields to be passed:
<ORDER_HEADER_ADDRESS><LOCATION_TYPE> - this will allow location types data to be included for example HOSPITAL, HOME, WHOLESALE or BRANCH, SUPPLIER, RDC ORDER_HEADER_ADDRESS><LOCATION_CUST_GROUP> - this will allow Location segregation via Customer Group Usage <ORDER_HEADER_ADDRESS><LOCATION_LOAD_RATE> - this will map to a value passed through from CIM and will be associated with static data in MTS, if the value does not exist it should populate as DEFAULT and an entry be made in the Interface Errors form showing that the value was invalid and set to DEFAULT against the specified Location ID <ORDER_HEADER_ADDRESS><LOCATION_UNLOAD_RATE> - this will map to a value passed through from CIM and will be associated with static data in MTS, if the value does not exist it should populate as DEFAULT and an entry be made in the Interface Errors form showing that the value was invalid and set to DEFAULT against the specified Location ID <ORDER_HEADER_ADDRESS><ADDRESS_CONTACT_FORENAME> - this will allow a contact forename to be included <ORDER_HEADER_ADDRESS><ADDRESS_CONTACT_SURNAME> - this will allow a contact surname to be included. <ORDER_HEADER_ADDRESS><ADDRESS_CONTACT_NUMBER> - this will allow a mobile telephone number to be included. <ORDER_HEADER_ADDRESS><ADDRESS_EMAIL> - this will allow an email address for the contact name to be included.
The MTS order upload is required to create new location records from the order address data where a location is not already maintained in MTS. In this instance the Location ID that has been passed from CIM must be retained and used as the Location ID in MTS.
Solution
The existing TripOrder XSD v2.3 will be changed to accommodate the new data fields below and will become v2.5:
The following 3 data fields will be added to the existing <ORDER_HEADER_ADDRESS> segment:
<ADDRESS_CUST_GROUP>
<ADDRESS_LOAD_RATE>
<ADDRESS_UNLOAD_RATE>
The following 5 data fields will be added to TripOrder XSD v2.5 as part of RIO: NW-7V4GMB (268477):
<ADDRESS_LOC_TYPE>
<ADDRESS_CONTACT_FORENAME>
<ADDRESS_CONTACT_SURNAME>
<ADDRESS_CONTACT_NUMBER>
<ADDRESS_EMAIL>
The CIM interface will be modified to allow two locations to be generated, Departure and delivery based on the <ADDRESS_TYPE> field value.
If the location id passed in does not exist in MTS the location will be inserted into the GEO_LOCATION table. The following data from the inbound file will be used to populate the new location record on GEO_LOCATION:
<ADDRESS_TYPE>
<ADDRESS_ID>
<ADDRESS_AC>
<ADDRESS_NAME>
<ADDRESS_LINE1>
<ADDRESS_LINE2>
<ADDRESS_LINE3>
<ADDRESS_TOWN>
<ADDRESS_COUNTY>
<ADDRESS_COUNTRY_CODE>
<ADDRESS_POSTCODE>
<ADDRESS_LOC_TYPE>
<ADDRESS_CONTACT_FORENAME>
<ADDRESS_CONTACT_SURNAME>
<ADDRESS_CONTACT_NUMBER>
<ADDRESS_EMAIL>
<ADDRESS_CUST_GROUP>
<ADDRESS_LOAD_RATE>
<ADDRESS_UNLOAD_RATE>
The ADDRESS_LOAD_RATE and ADDRESS_UNLOAD_RATE will be validated against the allowed values on MTS. If the values passed on the inbound message are invalid, a warning message will be shown in the interface errors form advising the DEFAULT MTS value has been used. The order will still be loaded into MTS and the new location will be added with a default value against the LOAD or UNLOAD rate.
When creating the new location, longitude/latitude information will be derived from mapping software if available. No trailer type or other data will be added as this will not be passed in the message.
If the location id passed in on the inbound message already exists, no additional action will be taken and the existing data for that location will be used on any orders created.
Proposed 2.5 version of TripOrder XSD:
A revised version 2.5 TripOrder XSD will be generated to allow the following addition data items to be interfaced from CIM to MTS and then MTS to Paragon
<ORDER_HEADER_TMS><KEY_CODE>
<OH_ADDRESS_TRAILERS><OH_ADDRESS_TRAILERS_SET>
The key code is the reference of the physical key that the driver books out and uses to gain entry to the delivery point.
The Trailers set is the string of 1’s and 0’s that denotes vehicle compatibility. Each character position in the string denotes a certain vehicle type and a flag 1 denotes acceptable and 0 unacceptable. It is anticipated that CIM will derive the address Lat and Long coordinates and these values will be passed into MTS and saved on the MTS location record.
See
<ORDER_HEADER_ADDRESS><ADDRESS_LAT>
<ORDER_HEADER_ADDRESS><ADDRESS_:LONG>
Note that the loading and unloading rate will be a code that is passed from CIM to MTS. This means the fixed and variable times will be maintained in MTS (and CIM) static data coded with the code values passed through the interface in the following tags;
<ORDER_HEADER_ADDRESS><ADDRESS_LOAD_RATE>
<ORDER_HEADER_ADDRESS><ADDRESS_UNLOAD_RATE>
Scope
This change will be applied to system version 10.5.
Data
New registry TRIP_ORDER_XSD_VERS will be added under log 268481 but is required for this RIO.This controls the version of the XSD applicable to this integration flow.
This will be set to 2.5 to correspond with the new version XSD
FUNCTIONAL DESCRIPTION
The new functionality will be controlled by the system registry TRIP_ORDER_XSD_VERS. This will determine which version of the XSD is being used. If the version is 2.5 (or greater) then the functionality detailed below will be used.
The order interface will be enhanced to allow new locations to be created and updated in MTS from the order information interfaced from CIM. This is necessary because the Baxter business includes home delivery so new addresses for deliveries will be common. All the main LOCATION information will be automatically created for new addresses including code, address, location type, load and unload rates, contacts and vehicle constraints.
A new version (v2.5) of the existing TRIPORDER XSD will be created as part of this RIO. The new fields below will be added to the <ORDER_HEADER_ADDRESS> segment:
<ADDRESS_CUST_GROUP>
<ADDRESS_LOAD_RATE>
<ADDRESS_UNLOAD_RATE>
<ADDRESS_LAT>
<ADDRESS_LONG>
The following 5 data fields will be added to TripOrder XSD (v2.5) as part of RIO: NW-7V4GMB (268477):
<ADDRESS_LOC_TYPE>
<ADDRESS_CONTACT_FORENAME>
<ADDRESS_CONTACT_SURNAME>
<ADDRESS_CONTACT_NUMBER>
<ADDRESS_EMAIL>
<ADDRESS_CONTACT_JOB>
These fields will be included in the functionality for this RIO (see contact information below.)
A subsection of the <ORDER_HEADER_ADDRESS> segment called <OH_ADDRESS_CONTACTS> will be added. This section will repeat for each contact against the address. It will contain the below fields.
<ADDRESS_CONTACT_FORENAME>
<ADDRESS_CONTACT_SURNAME>
<ADDRESS_CONTACT_NUMBER>
<ADDRESS_EMAIL>
<ADDRESS_CONTACT_JOB>
Note that MTS will load each new contact record under a unique sequence. It is anticipated that CIM will only send the number and e-mail address.
Another subsection of the <ORDER_HEADER_ADDRESS> segment called <OH_ADDRESS_TRAILERS> will be added. This section will repeat for each trailer against the address. It will contain the below fields
<TRAILER_TYPE>
<FILL_FACTOR>
<INCLUDE>
Additionally a field will be used in this section called <OH_ADDRESS_TRAILERS_SET>. This field will allow a character string of flags (1 or 0) which will denote which vehicle types are acceptable at the address location.
A further field <KEY_CODE> will be added to the <ORDER_HEADER_TMS> segment to carry a reference of the physical access key should the driver be allowed access to the delivery location.
Two new tables will be added to store the address contacts, INT_XML_ORD_CONTACTS and the address trailers INT_XML_ORD_TRAILERS. See Appendix A for details. New fields will be added to INT_XML_ORD_HEADER to store the additional information against the address (load rate, unload rate, cust_group, lat, long, location type).
When the orders are processed through the current CIM interface, the location ids for the departure and delivery locations will be checked against the existing locations in MTS. If the location id does not exist then a new record will be inserted into GEO_LOCATION using the following fields from the XML file.
<ADDRESS_TYPE>
<ADDRESS_ID>
<ADDRESS_AC>
<ADDRESS_NAME>
<ADDRESS_LINE1>
<ADDRESS_LINE2>
<ADDRESS_LINE3>
<ADDRESS_TOWN>
<ADDRESS_COUNTY>
<ADDRESS_COUNTRY_CODE>
<ADDRESS_POSTCODE>
<ADDRESS_LOC_TYPE>
<ADDRESS_CONTACT_FORENAME>
<ADDRESS_CONTACT_SURNAME>
<ADDRESS_CONTACT_NUMBER>
<ADDRESS_EMAIL>
<ADDRESS_CUST_GROUP>
<ADDRESS_LOAD_RATE>
<ADDRESS_UNLOAD_RATE>
<ADDRESS_LAT>
<ADDRESS_LONG>
A record will be added to the table GEO_LOCATION_USAGE for the location id and customer group.
A new record will be added to GEO_CONTACT for each <OH_ADDRESS_CONTACT> section against the address.
<ADDRESS_CONTACT_FORENAME>
<ADDRESS_CONTACT_SURNAME>
<ADDRESS_CONTACT_NUMBER>
<ADDRESS_EMAIL>
<ADDRESS_CONTACT_JOB>
A new record will be added to GEO_TRLR_TYPE_USE for each <OH_ADDRESS_TRAILER> section against the address.
<TRAILER_TYPE>
<FILL_FACTOR>
<INCLUDE>
The two sections above can be repeated several times for each address.
The Load rate and Unload rate will be validated against the standing data in RES_LOAD_RATE. If the rate does not exist the default load rate will be taken from the existing system parameters GEO_DEFAULT_LOAD_RATE or GEO_DEFAULT_UNLOAD_RATE. A warning message will be shown in the Interface errors screen to indicate that the default has been used.
The Trailer Type will be validated against the standing data in RES_TRAILER_TYPE. If the trailer type does not exist a warning message will be displayed in the Interface Errors screen to indicate this. The trailer type will not be added to the table, but the order will continue to be loaded.
The lat/long information will be stored against the new address removing the requirement lookup these values in MTS.
As part of this development, the interface errors process will be altered for this flow (note this change will only affect the CIM flow). The validation of some items will result in warnings, and not errors. This means the order will be loaded and stored correctly, but the user will be informed in the interface errors form of data that was incorrect.
Load Rate – Default used when no data found
Unload Rate – Default used when no data found
Trailer Type – Trailer restriction will not be loaded against location
The warnings will displayed in the interface errors screen using the current errors field but as a warning message not an error.
Note that the interface development will include enhancements to automatically update all the LOCATION information described above.
This means that the interface will check to see if a location already exists for the order collection and delivery address. If the location does not exist, then it will be created in MTS using the provided unique index value from CIM as described above. If the location already exists, all the details will be checked and any changes or additions saved to the address lines, lat, long, load and unload rate codes, contacts and vehicle restrictions.
The new fields key code and vehicle restriction code will be saved in MTS and used as pass through values into the Paragon interface
REFERENCES
Not Applicable
DOCUMENT HISTORY
| Initial version | ||||
| Reviewed and Issued | ||||
| Revised, reviewed and re-issued |
AUTHORISED BY
| Matt Crisford | Development Manager | |
| Peter Greer | TMSCC MTS Product Manager |
