264375
264375 - NW-7RGU7M Isotrak ATMS Interface (Two Way)
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
Two way interface from MTS to Isotrak ATMS.
Based on the same MTS to ESI / ESI to MTS format being used for Microlise a similar interface feed is required for MSPF and MSLV. The outbound message should be triggered by the status change of a Trip to ACCEPTED and then actual arrive and departure times will be received from Isotrak ATMS. Departure from the first stop on the Trip should trigger a status change to EN-ROUTE and arrival at the last stop on the Trip should trigger a status change to COMPLETED.
The existing XML format will be used for the interface.
There should be limited development required as part of this RIO but there may well be a requirement for conference calls or a workshop to finalise any mapping questions or issues with ESI / Isotrak.
Solution
The existing Trip schedule message functionality available in MTS will be utilised to enable;
Trip plan messages at ACCEPTED status to be sent to Isotrak via ESI Trip execution updates (at stop level) to be sent back from Isotrak to MTS via ESI
The current version TripOrder v2.3.XSD will be utilised and all message flows will be constructed in XML format.
Consultancy will be provided within the requirements section of the estimate to assist with mapping, analysis and design of the interface implementation and configuration.
Trip Plan
Trip messages will automatically be generated at status ACCEPTED. Resource allocation will be done in Isotrak so the trigger to create trip files will not check resource in MTS (specifically that the resource is Isotrak enabled). Any changes (amendments, additions and deletions) to stop planned times, sequence of stops and orders on stops once at ACCEPTED status will trigger a replacement trip message containing all details.
MTS will generate one XML file per trip. The trip files will be deposited in a folder on the MTS server for ESI to collect.
The file name will be TMS_ISO_MASPRD_TRP_YYYYMMDDHHMMSSII.XML
ESI will transform the trip message to the format required by Isotrak and present to the Isotrak server in the specific filename required.
Execution Updates
Actual date and time updates of arrival and departure at each trip stop will be sent from Isotrak to ESI. ESI will transform these messages to the MTS TripOrder format and the files will be deposited on the MTS server in folder.
The file name is configurable by a system registry but will probably be ISO_TMS_ATMS_YYYYMMDDHHMMSSII.XML
MTS will expect the stop sequence field sent out to Isotrak to be returned in the actuals update preserved. The value in the stop sequence will be used to select the appropriate stop on the trip.
Execution updates are expected to be generated automatically from GPS geofence breaks and so will be presented to MTS stop by stop almost real time.
The actual date and time update from the first stop will update the MTS trip status to EN-ROUTE.
A system parameter will be provided to allow the interface into MTS to be configured to set the trip status to COMPLETED. This update will only be actioned if the result of a file upload means actual date and time are captured in MTS for all stops.
Note that the requirement of this interface is that no order updates will be provided by Isotrak. The content of the interface will be the resource information (driver, tractor, trailer) and stop actual arrival and departure date and times.
Once a stop arrival or departure date and time is set in MTS any subsequent updates for the same stop will be rejected by the interface. The upload will work on a first come first serve basis. It is understood that Isotrak could potentially send multiple updates for the same stop source from GPS and from manual interaction with a hand-held / PDA device.
Scope
These changes will be applied to system version 10.6 on MASTST and once approved MASPRD.
The scope of this functional specification is dependent on the inbound and outbound XML documents being identical in structure to documents currently used within other (DHL) MTS file transmissions. The modification of the MTS system and/or the XML document handling framework and/or the XML files themselves to meet the requirements of the current XML document handling framework is outside the scope of this specification.
SET-UP
Pre-Requisites
The Oracle Package ‘XML’ needs to be compiled on the database(s) specified within the scope of this change. The package is used for the generic conversion of XML tag data (hierarchal format) to a normalized data representation that is able to be used within an oracle database.
The ancillary table: XML_EXTRACT needs to exist on the database(s) specified within the scope of this change.
Data
Scripts will have to be created to insert the data into database table ADM_SYSTEM_PARAM
This RIO for Isotrak ATMS Interface will be based on the current functionality around RIO ‘259080 GN-7M8VK3 Interfaces to enabling systems’ which has been released to Consumer Networks. Therefore, the components for GN-7M8VK3 will also have to be released to M&S database so that they can be re-used. This includes tables, packages, triggers, forms etc.
FUNCTIONAL DESCRIPTION
TMS TRP Message to Isotrak
Triggers on tables SCH_TRIP, SCH_TRIP_STOP and SCH_HAULAGE_ACTIVITY, similar to those used in GN-7M8VK3, will generate an appropriate TMS TRP XML message, with filename format of TMS_ISO_MASPRD_TRP_YYYYMMDDHHMMSSII.XML. This will need to be deposited in folder /webint/db_name/interface/ISO/OUT where ESI can collect it and transform the trip message to the format required by Isotrak and present to the Isotrak server in the specific filename required.
The triggers for Isotrak are :-
Updating a Trip to status ACCEPTED. N.B. Resource allocation will be done in Isotrak so the trigger to create trip files will not check resource in MTS (specifically that the resource is Isotrak enabled)
Any changes (amendments, additions and deletions) to stop planned times, sequence of stops and orders on stops once at ACCEPTED status will trigger a replacement trip message containing all details.
A database job will run at regular intervals and identify any TRP messages that need sending to Isotrak and produce the file in the XML format using the system registries for the folder name.
A safe copy of the file will be kept in the archive folder.
Isotrak Execution Update Messages into MTS
An automated job will be set up to run every five minutes to check if XML Documents have been placed in the inbound location.
OBS staff will modify the DB Package: INT_XML to accept an Isotrak ATMS file stream from ESI. The XML files will be delivered into the inbound directory specified in section 2.3 Data.
Modification details of INT_XML
INT_XML will be changed to accept the passed parameter: ATMS, from the automated job. When this occurs, the following associate actions will be triggered:
Using the parameter: ATMS as a catalyst; necessary parameters will be selected from the database table ADM_SYSTEM_PARAM. These parameters are detailed in section ‘2.3 Data’ and include:
- name of the inbound file,
- list of the files to be processed,
- name of the script that will move the files from inbound, to archive, or failure directories,
- the location of the inbound directory,
- the location of the archive directory where successfully processed files are saved and,
- the location of the failure directory where files that have failed processing are saved.
The file name will be checked to see if it has already been processed, if so, an error message will be given in the table INT_XML_TRIP_STOP.
Once these parameters are passed to DP_FILE_HANDLING, and the files have been listed for processing (passed validation as above), the content of the files can be uploaded into the generic area xml_extract, and validation performed.
File Content Extraction
The file content extraction is performed by a procedure called XML_EXTRACT part of the database package ‘XML’. This is a generic component, part of the OBS XML document handling infrastructure, and does not need to be modified. Note that this component is a pre-requisite component to this specification.
XML.XML_EXTRACT will place the content of the XML document into the XML_EXTRACT table
Insertion of validated file data into the MTS system
Once the inbound file data is fully validated, as part of the PROCESS_ORDER procedure, the data will be applied to the required tables in MTS.
MTS will expect the stop sequence field sent out to Isotrak to be returned in the actuals update preserved. The value in the stop sequence will be used to select the appropriate stop on the trip.
The actual departure date and time update from the first stop will update the MTS trip status to EN-ROUTE.
If actual date and time are captured in MTS for all stops then trip status will be set to COMPLETED.
Note that the requirement of this interface is that no order updates will be provided by Isotrak. The content of the interface will be the resource information (driver, tractor, trailer) and stop actual arrival and departure date and times. These updates will be at SCH_TRIP and SCH_TRIP_STOP level only. Not SCH_ORD level.
Once a stop arrival or departure date and time is set in MTS any subsequent updates for the same stop will be ignored by the interface. The upload will work on a first come first serve basis. It is understood that Isotrak could potentially send multiple updates for the same stop source from GPS and from manual interaction with a hand-held / PDA device.
REFERENCES
| EST-264375 NW-7RGU7M Isotrak ATMS Interface (Two Way) v1.0.doc |
DOCUMENT HISTORY
| Initial version | ||||
| Reviewed and Issued | ||||
| Changes to match development | ||||
| Reviewed and Issued |
AUTHORISED BY
| Matt Crisford | Development Manager | |
| Suk Sandhu | TMSCC MTS Product Manager |
