289163

From CTMS

Aptean Logo.png







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:


  1. APP_KEY
  2. REF_TYPE
  3. REF_VALUE
  4. ACTIVITY
  5. USERNAME

These items will be under the following tag sections:


  • OBS_XML
  • ORDER_STATUS_REQUEST

289163 1.png

OrderStatusResp

The response will provide 24 items in total at 3 different levels:


  1. OMS_REF
  2. EXTERNAL_REF
  3. BOOKING_REF
  4. DEL_POINT_REF
  5. ORDER_STATUS
  6. LOCATION_NAME
  7. POSTCODE
  8. TRIP_NUMBER
  9. PLAN_DATE_TIME
  10. DRIVER_NAME
  11. CREW1
  12. CREW2
  13. VEHICLE_REG
  14. ACT_ARR_DATE_TIME
  15. ACT_DEP_DATE_TIME
  16. DELIVERY_TYPE_ID
  17. DU_TYPE
  18. PRODUCT_TYPE
  19. PLANNED_QTY
  20. DESPATCHED_QTY
  21. DELIVERED_QTY
  22. DEBRIEF_RC
  23. DEBRIEF_ACTIVITY
  24. DEBRIEF_NOTES

The trip and order level items (1-16) will be under the following tag sections:


  • OBS_XML
  • ORDER_STATUS_RESPONSE

289163 2.png


The order line level items (17-21) will be under the following tag sections with a one-to-many relationship:


  • ORDER_LINES_RESPONSES

289163 3.png


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

289163 4.png


‘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:


  1. Trip and Order Header (related to the trip stop activity and the OMS reference)
  2. Order Lines (related to the order lines of the OMS reference)
  3. 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:


289163 5.png


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


Ref No
Document Title & ID
Version
Date
1
EST-289163 PM-8HMA5K Web Service Functionality v1.0.doc
1.0
06/07/11


Glossary


Term or Acronym
Meaning
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


Version
Date
Status
Reason
Initials
0.1
19/07/11
Draft
Initial version
PDR
0.2
20/07/11
Draft
Review
MJC
0.3
22/07/11
Draft
Review
DJM
0.4
22/07/11
Draft
Added crew members to response
PDR
1.0
22/07/11
Issue
Reviewed and Issued
MJC
1.1
25/07/11
Draft
Added section 3.4.2.1 about rebooking
PDR
2.0
25/07/11
Issue
Reviewed and re-issued
MJC
2.1
02/08/11
Draft
Added order line and reason code levels to response
PDR
3.0
02/08/11
Issue
Reviewed and Issued
MJC
3.1
15/08/11
Draft
Updated to OrderStatusResponse.xsd v1.3
PDR

AUTHORISED BY

Matt Crisford Development Manager
Peter Greer TMSCC MTS Product Manager