289163
DHL C-TMS
Web Service Functionality
FUNCTIONAL SPECIFICATION - 10.6
15/08/2011 - 3.1
Reference: FS 289163 PM-8HMA5K
Functional Overview
Client Requirement
Change Request Summary:
Web service functionality to allow information retrieval from C-TMS.
Change Request Details:
Web service functionality to allow information retrieval from C-TMS. This to allow visibility of orders in C-TMS from the order input system which supports call centre activity on the British Gas project.
Benefits identified as a result of the change:
Functionality replacement to enable C-TMS Ethos migration project.
Solution
From the DHL developed British Gas Waste Call Logging application, there is a requirement to query an order and be able to display the current transport status / milestone across order management, planning, execution and debrief.
The query functionality will be developed by the DHL IT team and will be supported by a web service call directly to C-TMS to retrieve the required status tracking data for the order.
The web service will be developed by OBSL and will be exposed to allow external calls from other applications across the DHL network (and internet if required). A description of the operation offered by the service will be written in the Web Services Description Language (WSDL). The service will use Extensible Markup Language (XML) messages that follow the SOAP standard.
Operators will have the ability to initiate the call from within the call logging application on demand. There are 12 operator users in the call centre and it is anticipated that the web service will be utilised up to 100 times per day.
The call to C-TMS will be simple and only needs to contain the specific order reference that C-TMS will use to query the status tracking data.
This reference will be the main Call Logging Application (QJI) reference number which will be unique in C-TMS and stored in the customer reference field for each order (this reference is also known as external reference or SO reference).
Note that to future-proof the call, any one of the 4 main order references in C-TMS can be used in the Web Service call: either OMS reference, customer reference, booking reference or delivery point reference. The reference being used will be qualified in the call by a separate numeric field with allowed values of 1, 2, 3 or 4 to represent each of the available order reference types. N.B. For BG Waste, the BG reference will be stored as the customer reference in C-TMS.
To support audit visibility of the service, the request message will also contain a field for the username requesting the information from the call logging application and a field for the date and time the request was made.
C-TMS will process the request for the order and create a response message containing the following data:
OMS Reference (the C-TMS unique reference for the order)
Customer Reference (the latest reference with regard to rebooking)
Booking Reference
Delivery Point Reference
Order Status
Location Name
Driver Name (if resource allocated)
Crew1 (if resource allocated)
Crew2 (if resource allocated)
Vehicle Registration (if resource allocated)
Completed Arrival Actual Date and Time (if debriefed)
Completed Depart Actual Date and Time (if debriefed)
Delivery Type
DU Type of order line
Product Type of order line
Planned Quantity of order line
Despatched Quantity of order line
Delivered quantity of order line
Debrief Reason Code and Description of order line (if debriefed)
Debrief Notes of order line (if debriefed)
The Order Status will be one of the following values;
NOTFOUND – no order retrieved for the query in C-TMS
UNKNOWN – order is found but status unknown (should never happen but included to cover any unforeseen circumstances)
CANCELLED – order has been cancelled
UNSCHEDULED – Waiting next planning cycle
SCHEDULED – planned on schedule
EN-ROUTE – vehicle is en-route
COMPLETED – debrief completed
CONFIRMED – collection (or delivery) confirmed as done
C-TMS will be developed to keep an audit transaction of each web service call processed as an audit log with date and time and user requesting the information. This logging data will be made available as a screen query in C-TMS which will be used to investigate any issues and confirm who made the request and when from the calling application.
Scope
This change will be applied to system version 10.7.
Set-up
Pre-requisites
- The new database tables, sequence number and trigger have been created.
- The new form is authorised for use.
- The new system parameters have been created.
Menu Structure
The new form may be accessed using the following path:
- ‘Administration’ – ‘Interfaces’ – ‘Web Service Audit’
Data
- The new database tables, sequence number and trigger may be created using the scripts in Appendix A.
- The new form may be made available using the scripts in Appendix A.
- The new system parameters may be created using the script in Appendix A.
Implementation Advice
The new ‘OrderStatusReq’ and ‘OrderStatusResp’ XSD files will be used.
Functional Description
‘WEB_SERVICE_AUDIT’ Table
A new table called ‘WEB_SERVICE_AUDIT’ will be created as follows:
Column | Type | Nullable | Default | Storage | Comments |
AUDIT_ID | NUMBER | N | |||
REF_TYPE | NUMBER | N | |||
REF_VALUE | VARCHAR2(30) | N | |||
ACTIVITY | VARCHAR2(1) | N | |||
USERNAME | VARCHAR2(50) | N | |||
ACTION_DATE | DATE | N | |||
RESPONSE_MESSAGE | CLOB | N |
‘TRG_WEB_SERVICE_AUDIT_BIU’ Trigger
A new sequence number will be created to set a unique audit number for each transaction recorded via a trigger on the database table.
The system time of the audit transaction will be set from the system date and time via the same trigger.
‘SEQ_WEB_SERVICE_AUDIT’ Sequence Number
The audit number will be incremented by 1 for each audit transaction and it will be stored in the ‘AUDIT_ID’ column.
System Parameters
The storage of the response message on the ‘WEB_SERVICE_AUDIT’ table may be controlled by a new system parameter:
- ‘WEB_SERVICE_STORE_RESP’
‘Determines if the message in response to the web server enquiry should be stored in the audit record - Y will store the message as a CLOB value.’
An archive process will be added to the House Keeping Package which will remove requests older than a number of days set within a new system parameter:
- ‘WSA_ARCHIVE_DAYS’
‘Determines the number of days that the web service messages will be retained in C-TMS prior to being archived.’
‘SCH_ORD_NON_CONFORM’ Table
The existing ‘SCH_ORD_NON_CONFORM’ database table will be altered to store the DU type and product type for the non-conformance reason code received from Microlise for the order at the trip stop.
Two columns will be added with the following details:
Column | Type | Nullable | Default | Storage | Comments |
DU_TYPE | VARCHAR2(12) | Y | |||
PRODUCT_TYPE | VARCHAR2(12) | Y |
‘AUTHENTICATION_KEYS’ Table
A new table called ‘AUTHENTICATION_KEYS’ will be created as follows:
Column | Type | Nullable | Default | Storage | Comments |
PROJECT | VARCHAR2(20) | N | |||
TYPE | VARCHAR2(20) | N | |||
KEY | VARCHAR2(25) | N | |||
EXPIRY_DATE | DATE | N |
Microlise XML Flow
The XML flow received from Microlise will be changed to update the DU type and the product type on the ‘SCH_ORD_NON_CONFORM’ table for the non-conformance recorded for the order item at the trip stop.
Procedure ‘PROCESS_MIC_TRIP_XML_IN’ will be changed for this purpose.
Web Service XML Flows
There will be separate XML formats for the inbound request (‘OrderStatusReq’) and the outbound response (‘OrderStatusResp’).
Authentication
The ‘SOAP’ request will need to provide a valid current authentication key for the request to be performed: the key provided will be referenced against the new ‘AUTHENTICATION_KEYS’ table using the following values:
Column | Value |
PROJECT | ‘BGSW’ |
TYPE | ‘WEB_SERVICE’ |
KEY | APP_KEY tag value from ‘OrderStatusReq’ |
OrderStatusReq
The request will provide 5 items:
- APP_KEY
- REF_TYPE
- REF_VALUE
- ACTIVITY
- USERNAME
These items will be under the following tag sections:
- OBS_XML
- ORDER_STATUS_REQUEST
OrderStatusResp
The response will provide 24 items in total at 3 different levels:
- OMS_REF
- EXTERNAL_REF
- BOOKING_REF
- DEL_POINT_REF
- ORDER_STATUS
- LOCATION_NAME
- POSTCODE
- TRIP_NUMBER
- PLAN_DATE_TIME
- DRIVER_NAME
- CREW1
- CREW2
- VEHICLE_REG
- ACT_ARR_DATE_TIME
- ACT_DEP_DATE_TIME
- DELIVERY_TYPE_ID
- DU_TYPE
- PRODUCT_TYPE
- PLANNED_QTY
- DESPATCHED_QTY
- DELIVERED_QTY
- DEBRIEF_RC
- DEBRIEF_ACTIVITY
- DEBRIEF_NOTES
The trip and order level items (1-16) will be under the following tag sections:
- OBS_XML
- ORDER_STATUS_RESPONSE
The order line level items (17-21) will be under the following tag sections with a one-to-many relationship:
- ORDER_LINES_RESPONSES
The order line’s reason code level items (22-24) will be under the following tag sections with a one-to-many relationship:
- REASON_CODES_RESPONSES
‘Web Service Interface’
From the DHL developed British Gas Waste Call Logging application, there is a requirement to query an order and be able to display the current transport status / milestone across order management, planning, execution and debrief.
The query functionality will be developed by the DHL IT team and will be supported by a web service call directly to C-TMS to retrieve the required status tracking data for the order.
The web service will be developed by OBSL and will be exposed to allow external calls from other applications across the DHL network (and internet if required). A description of the operation offered by the service will be written in the Web Services Description Language (WSDL). The service will use Extensible Markup Language (XML) messages that follow the SOAP standard.
Operators will have the ability to initiate the call from within the call logging application on demand. There are 12 operator users in the call centre and it is anticipated that the web service will be utilised up to 100 times per day.
Requests
The call to C-TMS will be simple and only needs to contain the specific order reference type and value that C-TMS will use to query the status tracking data.
This reference will be the main Call Logging Application (QJI) reference number which will be unique in C-TMS and stored in the customer reference field for each order (this reference is also known as external reference or SO reference).
To support audit visibility of the service, the request message will also contain a field for the username requesting the information from the call logging application and a field for the date and time the request was made.
A summary of the requested values may be seen below:
Item | Value | Description |
APP_KEY | Free Text | |
REF_TYPE | 1
2 3 4 |
OMS Reference
Customer Reference Booking Reference Delivery Point Reference |
REF_VALUE | Free Text | |
ACTIVITY | C
D |
Collection from Source Location
Delivery at Destination Location |
USERNAME | Free Text |
The value of the ‘APP_KEY’ will be used to determine if the application key provided is valid and the user may continue with the request.
The value of the ‘REF_TYPE’ will determine to which reference type the requested value refers and thus how the data is selected for the response.
The value of the ‘ACTIVITY’ will determine which leg of the order will be selected, i.e. ‘C’ will select the trip that contains the order being loaded at its source location and ‘D’ will select the trip that contains the order being unloaded at its destination location.
The ‘USERNAME’ will be the name of the user making the request and will be stored for future reference.
Responses
C-TMS will process the request for the order and create a response message containing the following data:
Item | Description | Format |
OMS_REF | OMS reference | VARCHAR2(12) |
EXTERNAL_REF | Customer reference | VARCHAR2(20) |
BOOKING_REF | Booking reference | VARCHAR2(20) |
DEL_POINT_REF | Delivery point reference | VARCHAR2(20) |
ORDER_STATUS | Calculated from the status of the order and/or trip | VARCHAR2(25) |
LOCATION_NAME | Location name of the trip stop | VARCHAR2(50) |
POSTCODE | Location postcode of the trip stop | VARCHAR2(9) |
TRIP_NUMBER | Trip ID | VARCHAR2(12) |
PLAN_DATE_TIME | Planned arrival date and time at the trip stop | YYYY-MM-DDTHH24:MI:SS |
DRIVER_NAME | Driver name of the vehicle assigned to the trip | VARCHAR2(101) |
CREW1 | Name of the first crew member of the vehicle assigned to the trip | VARCHAR2(101) |
CREW2 | Name of the second crew member of the vehicle assigned to the trip | VARCHAR2(101) |
VEHICLE_REG | Vehicle registration number of the tractor assigned to the first stop on the trip | VARCHAR2(12) |
ACT_ARR_DATE_TIME | Actual arrival date and time at the trip stop | YYYY-MM-DDTHH24:MI:SS |
ACT_DEP_DATE_TIME | Actual departure date and time at the trip stop | YYYY-MM-DDTHH24:MI:SS |
DELIVERY_TYPE_ID | The delivery type of the order | VARCHAR2(35) |
DU_TYPE | The delivery unit of the order line | VARCHAR2(12) |
PRODUCT_TYPE | The product type of the order line | VARCHAR2(12) |
PLANNED_QTY | The planned quantity of the order line | NUMBER(24,4) |
DESPATCHED_QTY | The actual despatched quantity of the order line | NUMBER(24,4) |
DELIVERED_QTY | The actual delivered quantity of the order line | NUMBER(24,4) |
DEBRIEF_RC | Debrief reason code and description | VARCHAR2(50) |
DEBRIEF_ACTIVITY | Debrief activity | VARCHAR2(20) |
DEBRIEF_NOTES | Debrief notes | VARCHAR2(256) |
These values will be obtained from the database tables as follows:
Item | Database Table | Database Column |
OMS_REF | SCH_ORD | OMS_REF |
EXTERNAL_REF | SCH_ORD | EXTERNAL_REF |
BOOKING_REF | SCH_ORD | BOOKING_REF |
DEL_POINT_REF | SCH_ORD | DEL_POINT_REF |
ORDER_STATUS | Calculated | |
LOCATION_NAME | GEO_LOCATION | LOCATION_NAME |
POSTCODE | GEO_LOCATION | POSTCODE |
TRIP_NUMBER | SCH_TRIP | TRIP_ID |
PLAN_DATE_TIME | SCH_TRIP_STOP | ARRIVE |
DRIVER_NAME | RES_PERSON | FORENAME + ‘ ‘ + SURNAME |
CREW1 | RES_PERSON | FORENAME + ‘ ‘ + SURNAME |
CREW2 | RES_PERSON | FORENAME + ‘ ‘ + SURNAME |
VEHICLE_REG | SCH_TRIP | TRACTOR_ID |
ACT_ARR_DATE_TIME | SCH_TRIP_STOP | ACTUAL_ARRIVE |
ACT_DEP_DATE_TIME | SCH_TRIP_STOP | ACTUAL_DEPART |
DELIVERY_TYPE_ID | SCH_ORD | DELIVERY_TYPE_ID |
DU_TYPE | SCH_ORDER_LINE | DU_TYPE |
PRODUCT_TYPE | SCH_ORDER_LINE | PRODUCT_TYPE |
PLANNED_QTY | SCH_ORDER_LINE | QUANTITY |
DESPATCHED_QTY | SCH_ORDER_LINE | ACTUAL_DESPATCHED_QUANTITY |
DELIVERED_QTY | SCH_ORDER_LINE | ACTUAL_QUANTITY |
DEBRIEF_RC | SCH_ORD_NON_CONF + SCH_LATE_CODES | REASON_CODE + ‘ ‘ +
DESCRIPTION |
DEBRIEF_ACTIVITY | SCH_ORD_NON_CONF | ACTIVITY |
DEBRIEF_NOTES | SCH_ORD_NON_CONF | COMMENTS |
N.B. If the order is not assigned to a trip then only the order references and the order status may be determined.
N.B. It will be assumed that the order is included once on trip stops at either its source or destination location.
N.B. It will be assumed that only one reason code will be entered as a non-conformance for the ‘Load’ or ‘Unload’ activity of the order at the trip stops.
The ‘Order Status’ will be one of the following values:
Order Status | Description |
NOTFOUND | No order retrieved for the query in C-TMS |
UNKNOWN | Order is found but status is unknown (this should never happen but is included to cover any unforeseen circumstances) |
CANCELLED | Order has been cancelled |
UNSCHEDULED | Order is waiting the next planning cycle |
SCHEDULED | Order is planned on scheduled trip |
EN-ROUTE | Order is on a vehicle and is en-route |
COMPLETED | Order debrief is complete |
CONFIRMED | Order collection (or delivery) is confirmed as done |
The order status is not simply the status of the order in C-TMS as the status of the current trip that contains the order will also be assessed.
An order status of ‘UNKNOWN’ will be applied if the order is found but another status cannot be set.
Once the order is assigned to a trip then the status of the trip will determine the ‘Order Status’ in the response message: if the status of the trip is ‘EN-ROUTE’, ‘CONFIRMED’ or ‘COMPLETED’ then that status will be used, otherwise ‘SCHEDULED’ will be used.
The XML response will be stored as the ‘Response Message’ on the new ‘WEB_SERVICE_AUDIT’ table should the new system parameter ‘WEB_SERVICE_STORE_RESP’ be set to ‘Y’.
The response will be produced in 3 possible levels:
- Trip and Order Header (related to the trip stop activity and the OMS reference)
- Order Lines (related to the order lines of the OMS reference)
- Reason Codes (related to the non-conformance reason codes of the order lines)
An order line may be identified using the combination of DU type and product type.
Rebooking
- If the order has been rebooked (e.g. because it has failed collection) then the C-TMS order will be copied and the customer reference suffixed with ‘_R{SEQUENCE_NUMBER}’.
- If an order has been rebooked then the latest order will be found for the original customer reference, e.g. ‘CUST123_R2’ will be second rebooking for the original customer reference ‘CUST123’.
- The same logic will be applied for the ‘Booking Reference’ and the ‘Delivery Point Reference’ although a suffix will not be generated for these reference types, therefore the latest order will be found for these reference types.
- The same logic will not be applied to the OMS reference because it is always unique and a new OMS reference number will be generated for each rebooking.
‘ORION’ Menu Structure
The new ‘Web Service Audit Enquiry’ screen will be added to the menu structure as follows:
‘Administration’ – ‘Interfaces’ – ‘Web Service Audit’
The ‘ORION’ menu will be updated to include the path shown above.
‘Web Service Audit Enquiry’ Screen
A new form called ‘WEB_SERV_AUDIT’ will be created with the name ‘Web Service Audit Enquiry’ in the main screen.
The screen will be available from the ‘Administration’ - ‘Interface’ menu with the title ‘Web Service Audit’ and will be authorised for use by specific user groups in the ‘Access Control’ screen.
The screen will display the audit trail captured from each web service call processed by the users.
There will be selection criteria available as fields at the top of the screen:
- Ref Type
- Ref Value
- Activity
- User
- Date
The selection criteria will then be used to display the relevant audit transactions recorded in columns with the following headings:
- Audit
- Ref Type
- Ref Value
- Activity
- User
- Date
- Response Message
The ‘Response Message’ will be a ‘CLOB’ value of the XML created and may be viewed in a separate adjacent window to the right of the audit fields.
An example of the proposed layout is below:
There will be 5 optional selection parameters available to filter the data:
- Ref Type
- Ref Value
- Activity
- User
- Date
The ‘Response Message’ will be displayed and will contain the actual message generated in response to the web service request.
Clicking 'Close' will close the screen and return the user to the C-TMS menus.
N.B. None of the information displayed may be changed or deleted, nor may any records be added.
The audit transactions will be obtained from the new ‘WEB_SERVICE_AUDIT’ table:
Column Heading | Database Column |
Audit | AUDIT_ID |
Ref Type | REF_TYPE |
Ref Value | REF_VALUE |
Activity | ACTIVITY |
User | USERNAME |
Date | ACTION_DATE |
Request Message | REQUEST_MESSAGE |
Response Message | RESPONSE_MESSAGE |
The ‘Transaction Date/Time’ will have the format ‘DD/MM/YYYY HH24:MI:SS’.
Table Update Required
A new database table called ‘WEB_SERVICE_AUDIT’ may be created using the following scripts:
create table WEB_SERVICE_AUDIT
(
AUDIT_ID NUMBER not null, REF_TYPE NUMBER not null, REF_VALUE VARCHAR2(30) not null, ACTIVITY VARCHAR2(1) not null, USERNAME VARCHAR2(50) not null, ACTION_DATE DATE not null, RESPONSE_MESSAGE CLOB
) -- Create/Recreate primary, unique and foreign key constraints alter table WEB_SERVICE_AUDIT
add constraint PK_WS_AUDIT_ID primary key (AUDIT_ID);
-- Grant/Revoke object privileges grant select, insert, delete, update, alter on WEB_SERVICE_AUDIT to MTS_USER; grant select on WEB_SERVICE_AUDIT to MTS_USER_READ_ONLY; -- Create public synonym create public synonym WEB_SERVICE_AUDIT for WEB_SERVICE_AUDIT; /
create table AUTHENTICATION_KEYS
(
PROJECT VARCHAR2(20) not null, TYPE VARCHAR2(20) not null, KEY VARCHAR2(25) not null, EXPIRY_DATE NUMBER not null
) -- Grant/Revoke object privileges grant select, insert, delete, update, alter on AUTHENTICATION_KEYS to MTS_USER; grant select on AUTHENTICATION_KEYS to MTS_USER_READ_ONLY; -- Create public synonym create public synonym AUTHENTICATION_KEYS for AUTHENTICATION_KEYS;
The database table ‘SCH_ORD_NON_CONFORM’ will be altered using the following script:
alter table SCH_ORD_NON_CONFORM add (DU_TYPE VARCHAR2(12),PRODUCT_TYPE VARCHAR2(12));
/
A new sequence number for ‘WEB_SERVICE_AUDIT’ may be created using the following script:
-- Create sequence
create sequence SEQ_WEB_SERVICE_AUDIT
minvalue 1
maxvalue 999999999999999999999999
start with 1
increment by 1
cache 20;
-- Grants
grant select, alter on SEQ_WEB_SERVICE_AUDIT to MTS_USER;
grant select on SEQ_WEB_SERVICE_AUDIT to MTS_USER_READ_ONLY;
-- Create public synonym
create public synonym SEQ_WEB_SERVICE_AUDIT FOR SEQ_WEB_SERVICE_AUDIT;
/
A new trigger for ‘WEB_SERVICE_AUDIT’ may be created using the following script:
CREATE OR REPLACE TRIGGER TRG_WEB_SERVICE_AUDIT_BIU
BEFORE INSERT ON WEB_SERVICE_AUDIT REFERENCING NEW AS NEW OLD AS OLD FOR EACH ROW
DECLARE
v_action VARCHAR2(2000);
BEGIN
IF INSERTING THEN NEW.AUDIT_ID := SEQ_WEB_SERVICE_AUDIT.nextval; END IF;
END; /
The new ‘WEB_SERV_AUDIT’ form may be made available for use using the following scripts:
-- Update table
insert into adm_group_menu (menu_string,group_name,menu_label,display_in_menu) values ('INTERFACES.WEB_SERV_AUDIT','ADMIN','Web Service Audit','N');
/
-- Update table
insert into adm_menu_item (menu_name,form_name,menu_type,parent_menu,menu_label) values ('WEB_SERV_AUDIT','WEB_SERV_AUDIT','F','INTERFACES','Web Service Audit');
/
The new ‘WEB_SERVICE_STORE_REQ’ and ‘WEB_SERVICE_STORE_RESP’ system parameters may be created using the following script:
INSERT INTO ADM_SYSTEM_PARAM
(PARAM_NAME,VALUE,DATA_TYPE,MAX_LENGTH,DISPLAYED,USER_MODIFIABLE,DESCRIPTION,CREATED_BY,CREATED_DATE,UPDATED_BY,UPDATED_DATE,CONFIG_BY,CONFIG_BY_VALUE)
VALUES
('WEB_SERVICE_STORE_RESP','N','S',1,'Y','N','Determines if the message in response to the web server enquiry should be stored in the audit record - Y will store the message as a CLOB value.','OBS',SYSDATE,'OBS',SYSDATE,'SYSTEM','NONE');
INSERT INTO ADM_SYSTEM_PARAM
(PARAM_NAME,VALUE,DATA_TYPE,MAX_LENGTH,DISPLAYED,USER_MODIFIABLE,DESCRIPTION,CREATED_BY,CREATED_DATE,UPDATED_BY,UPDATED_DATE,CONFIG_BY,CONFIG_BY_VALUE)
VALUES
('WSA_ARCHIVE_DAYS’,'1','N',1,'Y','N','Determines the number of days that the web service messages will be retained in C-TMS prior to being archived.','OBS',SYSDATE,'OBS',SYSDATE,'SYSTEM','NONE');
/
References
EST-289163 PM-8HMA5K Web Service Functionality v1.0.doc |
Glossary
C-TMS | Calidus TMS |
OBSL | OBS Logistics |
SOAP | Simple Object Access Protocol |
WSDL | Web Services Description Language |
XML | Extensible Markup Language |
XSD | XML Schema Definition |
Document History
Initial version | ||||
Review | ||||
Review | ||||
Added crew members to response | ||||
Reviewed and Issued | ||||
Added section 3.4.2.1 about rebooking | ||||
Reviewed and re-issued | ||||
Added order line and reason code levels to response | ||||
Reviewed and Issued | ||||
Updated to OrderStatusResponse.xsd v1.3 |
AUTHORISED BY
Matt Crisford | Development Manager | |
Peter Greer | TMSCC MTS Product Manager |