FS 370536 FleetCheck Interface: Difference between revisions

From Calidus HUB
VisualWikitext
(v0.1 - Initial draft version - incomplete)
 
(v0.4 - Changes after review, additional scope and corrections to trigger naming.)
 
(2 intermediate revisions by the same user not shown)
Line 5: Line 5:
{{#vardefine:SystemCode|CTMS}}
{{#vardefine:SystemCode|CTMS}}
{{#vardefine:Doc_Title|FleetCheck Interface}}
{{#vardefine:Doc_Title|FleetCheck Interface}}
{{#vardefine:Version|0.1}}
{{#vardefine:Version|0.4}}
{{#vardefine:Date|6th May 2020}}
{{#vardefine:Date|19th May 2020}}
{{#vardefine:Reference|370536}}
{{#vardefine:Reference|370536}}
{{#vardefine:Year|2020}}
{{#vardefine:Year|2020}}
Line 76: Line 76:
It is expected that the following are the responsibilities of the systems:
It is expected that the following are the responsibilities of the systems:
* CTMS:
* CTMS:
**  Maintain vehicle types (type) and carriers (categories) - inform FleetCheck of the data.
**  Maintain trailer types (external type) and carriers (categories) - inform FleetCheck of the data.
**  Tractor/Trailer/Driver carrier assignment (TBC)
**  Tractor/Trailer/Driver carrier assignment (TBC)
* FleetCheck:
* FleetCheck:
Line 88: Line 88:
* Carriers and Category may be maintained separately without an interface, but this may result in messages failing to be processed.
* Carriers and Category may be maintained separately without an interface, but this may result in messages failing to be processed.
* Vehicle and trailer types should be created and maintained within CTMS. As this is a CTMS convention rather than a FleetCheck one, this should be the responsibility of CTMS.
* Vehicle and trailer types should be created and maintained within CTMS. As this is a CTMS convention rather than a FleetCheck one, this should be the responsibility of CTMS.
{{Note}} This interface is at system level, and therefore any carriers with named resources will be managed through FleetCheck, when this system is enabled. In the future, the system may be modified to enable/disable the interface on a per-carrier basis.
{{Note}} It may be that, when adding a record into CTMS and therefore triggering the add of the record in FleetCheck, that this may already exist. In this case, the process will log the failure, if a failure code is returned - it will not then attempt to call the web service method again to update the existing record. It is expected that, if this were required, then the FleetCheck web services should support that automatically, as the CALIDUS web services will.




Line 103: Line 108:


== Menu Structure  ==
== Menu Structure  ==
 
The EDI Log is accessible from Administration/EDI/Interface Errors, the EDI audit is available on tab EDI Audit.




== Data  ==
== Data  ==
 
N/A




== Implementation Advice ==
== Implementation Advice ==
 
N/A




Line 179: Line 184:
* Accessible options.
* Accessible options.
* Configuration.
* Configuration.


Actions taken when updating data will be audited in the system through this user account.
Actions taken when updating data will be audited in the system through this user account.
Line 220: Line 226:
* Authorisation parameters
* Authorisation parameters
* ''id'' - unique ID. Used when updating an existing tractor. Use the registration.
* ''id'' - unique ID. Used when updating an existing tractor. Use the registration.
* ''type'' - must be a valid vehicle type in the system. Required when creating a tractor.
* ''type'' - must be a valid trailer type in the system. Required when creating a tractor.
* ''desc'' - Required when creating a tractor. Maximum length 50.
* ''desc'' - Required when creating a tractor. Maximum length 50.
* ''inactive'' - Optional. Will be assumed to be "N" when creating a new tractor if not provided. Values "Y" or "N".
* ''inactive'' - Optional. Will be assumed to be "N" when creating a new tractor if not provided. Values "Y" or "N".
Line 332: Line 338:
* Authentication parameters.
* Authentication parameters.
* ''CategoryName''
* ''CategoryName''
* ''CategoryId'' - {{Warning}} Required?
* ''CategoryId''




Line 346: Line 352:
* Authentication parameters.
* Authentication parameters.
* ''DriverId''
* ''DriverId''
* ''AssetId''
* ''CategoryName''




Line 406: Line 412:
<!-- NEW PAGE -->  
<!-- NEW PAGE -->  
= TECHNICAL NOTES =
= TECHNICAL NOTES =


== CTMS Web Service, for FC->CTMS ==
== CTMS Web Service, for FC->CTMS ==
Line 434: Line 430:


These are RESTful web services and generally support only the POST and PUT actions.
These are RESTful web services and generally support only the POST and PUT actions.
=== General Notes ===
All code to process the received data from FleetCheck should be in package DP_FLEETCHECK.


=== Responses ===
=== Responses ===
Responses will be handled by the .NET code.


Responses will be sent as per HTTP standards:
Responses will be sent as per HTTP standards:
Line 453: Line 455:
     }
     }
</pre>
</pre>
=== Parameters ===
Parameters will be extracted and validated in the .NET code.




Line 464: Line 470:
     &surname=SMITH&forename=JOHN&job=DRIVER&inactive=N&carrier=FLEET
     &surname=SMITH&forename=JOHN&job=DRIVER&inactive=N&carrier=FLEET
</pre>
</pre>
All parameters passed in to all web service methods will be checked to ensure that there is no SQL insertion, as well as standard checks for requirement, length and basic type.
Parameters will be extracted from the call to the web service. They will be passed to the appropriate procedure within CTMS package DP_FLEETCHECK.


=== Authorisation ===


Authorisation parameters consist of:
Authorisation parameters consist of:
Line 475: Line 487:
* Configuration.
* Configuration.


A default FLEETCHECK user will be created. This FleetCheck user will be used solely by the .NET web service system for connection purposes.
A new user parameter will be created called FLEETCHECK_AUTHCODE. This will be set against the default FLEETCHECK user - many may be created, but only one expected, and is an optional parameter.
The authorisation procedure in .NET will call package DP_FLEETCHECK.AUTHORISE_USER, accepting the authcode parameter above, returning an error code, and with in/out parameters for username, password and errors (if any).
The procedure will find the user set up with FLEETCHECK_AUTHCODE set to the passed-in Auth Code.
Any issues should be returned with a false return code (negative integer), and the description of the issue, for example:
* -1 - Authcode not valid.
Actions taken when updating data will be audited in the system through this default FleetCheck user account.
Any issues should also be logged by the .NET code to a local logging file. These files should be created new every hour.
=== General Processing ===
Procedure code should exist in package DP_FLEETCHECK dedicated to the particular web service, for example, DRIVER.
The .NET code should call the correct procedure associated to the web service, passing in the specific parameters in the process, as well as the following:
* p_message - error descriptions, if any.
* p_action - the action derived from the HTTP action above:
**  A - Add
**  U - Update
The procedure should also return a basic error code (0 or negative number to identify the specific error) or 1 if all worked as expected.
The procedure should update or create records on appropriate tables, as detailed in the specific descriptions.
The .NET code written should be separated into DAL and BAL objects. BAL objects should define the actions being taken for each web service method, for example AddDriver, UpdateDriver or AddUpdateDriver. These will call define DAL object methods. DAL objects should contain the call the the CTMS Oracle package code - Oracle should not be referenced in any other places in the code, as this web services project may be converted to work with SQL Server for CTL TMS or for C-ePOD.
If adding a record that already exists, the process should look to update it. If updating a record that doesn't already exist, if the process has enough key information to create the user, then the process should create it instead.
=== Audit Logging ===
Actions taken when updating data will be audited in the system through this user account.
Actions taken when updating data will be audited in the system through this user account.
All package code will audit to ADM_EDI_AUDIT, for success and failure.
{| class="wikitable" border="1"
|-bgcolor="silver"
!Field !! Comment
|-
|STMT || Generated
|-
|PROG_NAME || Package and procedure, dot delimited e.g. DP_FLEETCHECK.DRIVER
|-
|ORI_USER || As normal
|-
|USER_SESSION || As normal
|-
|ERR_TYPE || 'ERROR' if an error, 'INFO' otherwise. 'AUDIT' may be used for debugging statements, but should be limited.
|-
|DATE_CREATED || System date and time
|-
|ERR_MESSAGE || The generated error message for an error plus an indication of the data e.g. "Error updating Driver XXX: YYYY", otherwise a success message indicating the action taken, identifying the data e.g. "Driver XXX updated".
|-
|SCHED_NAME || N/A
|-
|CUSTOMER_ID || N/A
|-
|LOCATION_ID || N/A
|}




Line 490: Line 566:
Parameters:  
Parameters:  
* Authorisation parameters
* Authorisation parameters
* ''id'' - unique numeric ID. Used when updating an existing driver.
* ''p_id'' - unique numeric ID. Used as the key when adding or updating a driver.
* ''surname'' - must be provided when creating a new driver. Maximum 50 characters. If id is not provided, surname and forename will be used to identify the driver.
* ''p_surname'' - must be provided when creating a new driver. Maximum 50 characters. If id is not provided, surname and forename will be used to identify the driver.
* ''forename'' - must be provided when creating a new driver. Maximum 50 characters. If id is not provided, surname and forename will be used to identify the driver.
* ''p_forename'' - must be provided when creating a new driver. Maximum 50 characters. If id is not provided, surname and forename will be used to identify the driver.
* ''job'' - must be provided when creating a new driver. Maximum 50 characters.
* ''p_job'' - must be provided when creating a new driver. Maximum 50 characters.
* ''inactive'' - Optional. Will be assumed to be "N" when creating a new driver is not provided. Values "Y" or "N"
* ''p_inactive'' - Optional. Will be assumed to be "N" when creating a new driver is not provided. Values "Y" or "N"
* ''agency'' - Is this an agency driver. "Y" or "N". Optional. Assumed to be "N" when creating a new driver if not provided.
* ''p_agency'' - Is this an agency driver. "Y" or "N". Optional. Assumed to be "N" when creating a new driver if not provided.
* ''agencyname'' - provide the agency name. Maximum 100 characters. Required if agency = "Y".
* ''p_agencyname'' - provide the agency name. Maximum 100 characters. Required if agency = "Y".
* ''carrier'' - must be a valid carrier id. Maximum 12 characters. Optional. Assumes driver is not assigned to a carrier if omitted when creating a new driver.
* ''p_carrier'' - must be a valid carrier id. Maximum 12 characters. Optional. Assumes driver is not assigned to a carrier if omitted when creating a new driver.
* ''carriername'' - must be a valid carrier name. Maximum 50 characters. Optional. Assumes driver is not assigned to a carrier if omitted when creating a new driver.
* ''p_carriername'' - must be a valid carrier name. Maximum 50 characters. Optional. Assumes driver is not assigned to a carrier if omitted when creating a new driver.


 
Procedure: DP_FLEETCHECK.DRIVER.
==== System Processing ====


Table RES_PERSON:
Table RES_PERSON:
Line 509: Line 584:
! Field !! Type !! Notes
! Field !! Type !! Notes
|-
|-
| ID || NUMBER ||
| ID || NUMBER || ''p_id''
|-
|-
| SURNAME || VARCHAR2(50) ||
| SURNAME || VARCHAR2(50) || ''p_surname''
|-
|-
| FORENAME || VARCHAR2(50) ||
| FORENAME || VARCHAR2(50) || ''p_forename''
|-
|-
| JOB_TITLE || VARCHAR2(50) ||
| JOB_TITLE || VARCHAR2(50) || ''p_job''
|-
|-
| LOCATION_ID || VARCHAR2(12) ||
| LOCATION_ID || VARCHAR2(12) || &nbsp;
|-
|-
| CREATED_BY || VARCHAR2(40) ||
| CREATED_BY || VARCHAR2(40) || When adding, CTMS Username
|-
|-
| CREATED_DATE || DATE ||
| CREATED_DATE || DATE || When adding, SYSDATE
|-
|-
| UPDATED_BY || VARCHAR2(40) ||
| UPDATED_BY || VARCHAR2(40) || When updating, CTMS Username
|-
|-
| UPDATED_DATE || DATE ||
| UPDATED_DATE || DATE || When updating, SYSDATE
|-
|-
| CONTACT_NO || VARCHAR2(50) ||
| CONTACT_NO || VARCHAR2(50) || N/A
|-
|-
| INACTIVE || VARCHAR2(1) | Use this for unavailability
| INACTIVE || VARCHAR2(1) || ''p_inactive''
|-
|-
| AGENCY || VARCHAR2(1) ||
| AGENCY || VARCHAR2(1) || ''p_agency''
|-
|-
| SMARTPHONE_ENABLED || VARCHAR2(100) ||
| SMARTPHONE_ENABLED || VARCHAR2(100) || N/A
|-
|-
| EPOD_USERNAME || VARCHAR2(10) ||
| EPOD_USERNAME || VARCHAR2(10) || N/A
|-
|-
| TOMTOM_ENABLED || VARCHAR2(1) ||
| TOMTOM_ENABLED || VARCHAR2(1) || N/A
|-
|-
| HUB_LOCATION || VARCHAR2(12) ||
| HUB_LOCATION || VARCHAR2(12) || N/A
|-
|-
| START_AT_HUB || VARCHAR2(1) ||
| START_AT_HUB || VARCHAR2(1) || N/A
|-
|-
| RETURN_TO_HUB || VARCHAR2(1) ||
| RETURN_TO_HUB || VARCHAR2(1) || N/A
|-
|-
| AGENCY_NAME || VARCHAR2(100) ||
| AGENCY_NAME || VARCHAR2(100) || ''p_agencyname''
|}
|}


If a carrier or carrier name is provided, the carrier should be updated.


To update driver carrier assignment.
To update driver carrier assignment.


{{Note}}
* This is how a driver would be made unavailable to CTMS, by ensuring that they are not assigned to any carrier.
* As FleetCheck supports only one category assigned to each resource, then changing the category should make the prior carrier unavailable and this carrier available.


Note: this is a method available to either system. Therefore, if updating carrier assignment from this method, this method should not then send an update out through the other system web service method.  
First, the process should find the carrier. This may be through the ID provided or the carrier name. If the carrier is not found, do not perform the update of the carrier assignment. Return an error.


If the carrier is found, check whether the driver has a carrier entry. If it does not, one should be created. If found, it should be updated.


Table RES_PERSON_CARRIER
Table RES_PERSON_CARRIER
Line 564: Line 639:
! Field !! Type !! Notes
! Field !! Type !! Notes
|-
|-
| INACTIVE || VARCHAR2(1) || {{Warning}} Use for availability
| INACTIVE || VARCHAR2(1) || ''p_inactive''
|-
|-
| PC_ID || NUMBER(10) ||  
| PC_ID || NUMBER(10) || ''p_id''
|-
|-
| ID || NUMBER || {{Warning}} Irrelevant?
| ID || NUMBER || N/A
|-
|-
| CARRIER_ID || VARCHAR2(12) ||  
| CARRIER_ID || VARCHAR2(12) || The carrier ID found
|-
|-
| RAG || VARCHAR2(1) || {{Warning}} ???
| RAG || VARCHAR2(1) || N/A
|}
|}


{{Note}}As FleetCheck supports only one category assigned to each resource, then changing the category should make the prior carrier unavailable and this carrier available. The process should find all other carrier records and mark them inactive, if the user is being marked as active to this carrier. This is handled in the CTMS-FleetCheck interface, defined below.
{{Note}} This is a method available to either system. Therefore, if updating carrier assignment from this method, this method should not then send an update out through the other system web service method.




Line 591: Line 669:
Parameters:  
Parameters:  
* Authorisation parameters
* Authorisation parameters
* ''id'' - unique ID. Used when updating an existing tractor. Use the registration.
* ''p_id'' - unique ID. Used when updating an existing tractor. Use the registration.
* ''type'' - must be a valid vehicle type in the system. Required when creating a tractor.
* ''p_type'' - must be a valid trailer type in the system. Required when creating a tractor.
* ''desc'' - Required when creating a tractor. Maximum length 50.
* ''p_desc'' - Required when creating a tractor. Maximum length 50.
* ''inactive'' - Optional. Will be assumed to be "N" when creating a new tractor if not provided. Values "Y" or "N".
* ''p_inactive'' - Optional. Will be assumed to be "N" when creating a new tractor if not provided. Values "Y" or "N".
* ''mpg'' - Optional. Decimal number, 3 decimal places.
* ''p_mpg'' - Optional. Decimal number, 3 decimal places.
* ''vin'' - optional. Maximum length 17.
* ''p_vin'' - optional. Maximum length 17.
* ''carrier'' - must be a valid carrier id. Maximum 12 characters. Optional. Assumes tractor is not assigned to a carrier if omitted when creating a new tractor.
* ''p_carrier'' - must be a valid carrier id. Maximum 12 characters. Optional. Assumes tractor is not assigned to a carrier if omitted when creating a new tractor.
* ''carriername'' - must be a valid carrier name. Maximum 50 characters. Optional. Assumes tractor is not assigned to a carrier if omitted when creating a new tractor.
* ''p_carriername'' - must be a valid carrier name. Maximum 50 characters. Optional. Assumes tractor is not assigned to a carrier if omitted when creating a new tractor.




==== System Processing ====
Procedure: DP_FLEETCHECK.TRACTOR.


Table RES_TRACTOR
Table RES_TRACTOR:


{| class="wikitable" border="1"
{| class="wikitable" border="1"
Line 609: Line 687:
! Field !! Type !! Notes
! Field !! Type !! Notes
|-
|-
| TRACTOR_ID || VARCHAR2(12) ||
| TRACTOR_ID || VARCHAR2(12) || ''p_id''
|-
|-
| TRACTOR_TYPE || VARCHAR2(12) ||  
| TRACTOR_TYPE || VARCHAR2(12) || ''p_type''
|-
|-
| DESCRIPTION || VARCHAR2(50) ||  
| DESCRIPTION || VARCHAR2(50) || ''p_desc'', if provided
|-
|-
| INACTIVE || VARCHAR2(1) || Use this for availability
| INACTIVE || VARCHAR2(1) || ''p_inactive'', if provided
|-
|-
| LOCATION_ID || VARCHAR2(12) ||  
| LOCATION_ID || VARCHAR2(12) || N/A
|-
|-
| TRACKING_ENABLED || VARCHAR2(50) ||  
| TRACKING_ENABLED || VARCHAR2(50) || N/A
|-
|-
| CONTACT_NO || VARCHAR2(50) ||  
| CONTACT_NO || VARCHAR2(50) || N/A
|-
|-
| MPG || NUMBER(6,3) ||  
| MPG || NUMBER(6,3) || ''p_mpg'', if provided.
|-
|-
| TRACK_REF || VARCHAR2(30) ||  
| TRACK_REF || VARCHAR2(30) || N/A
|-
|-
| VIN_NO || VARCHAR2(17) ||  
| VIN_NO || VARCHAR2(17) || ''p_vin'' if provided.
|-
|-
| FLEET_ID || VARCHAR2(100) ||  
| FLEET_ID || VARCHAR2(100) || N/A
|-
|-
| BLUE_LIGHT || VARCHAR2(1) ||  
| BLUE_LIGHT || VARCHAR2(1) || N/A
|-
|-
| TAIL_LIFT || VARCHAR2(1) ||  
| TAIL_LIFT || VARCHAR2(1) || N/A
|-
|-
| TOMTOM_ENABLED || VARCHAR2(1) ||  
| TOMTOM_ENABLED || VARCHAR2(1) || N/A
|-
|-
| EPOD_ENABLED || VARCHAR2(1) ||  
| EPOD_ENABLED || VARCHAR2(1) || N/A
|-
|-
| RAG || VARCHAR2(1) ||  
| RAG || VARCHAR2(1) || N/A
|}
|}
If a carrier or carrier name is provided, the carrier should be updated.


To update vehicle carrier assignment.
To update vehicle carrier assignment.


Note: this is a method available to either system. Therefore, if updating carrier assignment from this method, this method should not then send an update out through the other system web service method.  
 
First, the process should find the carrier. This may be through the ID provided or the carrier name. If the carrier is not found, do not perform the update of the carrier assignment. Return an error.
 
If the carrier is found, check whether the vehicle has a carrier entry. If it does not, one should be created. If found, it should be updated.




Line 653: Line 737:
! Field !! Type !! Notes
! Field !! Type !! Notes
|-
|-
| ID || NUMBER(10) ||  
| ID || NUMBER(10) || N/A
|-
|-
| TRACTOR_ID || VARCHAR2(12) ||  
| TRACTOR_ID || VARCHAR2(12) || ''p_id''
|-
|-
| CARRIER_ID || VARCHAR2(12) ||  
| CARRIER_ID || VARCHAR2(12) || The carrier ID found
|-
|-
| INACTIVE || VARCHAR2(1) || Use this for availability? |
| INACTIVE || VARCHAR2(1) || ''p_inactive''
|}
|}
{{Note}}As FleetCheck supports only one category assigned to each resource, then changing the category should make the prior carrier unavailable and this carrier available. The process should find all other carrier records and mark them inactive, if the user is being marked as active to this carrier.
{{Note}} This is a method available to either system. Therefore, if updating carrier assignment from this method, this method should not then send an update out through the other system web service method. This is handled in the CTMS-FleetCheck interface, defined below.




Line 677: Line 765:
Parameters:  
Parameters:  
* Authorisation parameters
* Authorisation parameters
* ''id'' - unique ID. Used when updating an existing trailer.
* ''p_id'' - unique ID. Used when updating an existing trailer.
* ''type'' - must be a valid trailer type in the system. Required when creating a trailer.
* ''p_type'' - must be a valid trailer type in the system. Required when creating a trailer.
* ''inactive'' - Optional. Will be assumed to be "N" when creating a new trailer if not provided. Values "Y" or "N".
* ''p_inactive'' - Optional. Will be assumed to be "N" when creating a new trailer if not provided. Values "Y" or "N".
* ''carrier'' - must be a valid carrier id. Maximum 12 characters. Optional. Assumes trailer is not assigned to a carrier if omitted when creating a new trailer.
* ''p_carrier'' - must be a valid carrier id. Maximum 12 characters. Optional. Assumes trailer is not assigned to a carrier if omitted when creating a new trailer.
* ''carriername'' - must be a valid carrier name. Maximum 50 characters. Optional. Assumes trailer is not assigned to a carrier if omitted when creating a new trailer.
* ''p_carriername'' - must be a valid carrier name. Maximum 50 characters. Optional. Assumes trailer is not assigned to a carrier if omitted when creating a new trailer.


Procedure: DP_FLEETCHECK.TRAILER


==== System Processing ====
The process should first check the authorised user parameters. If the user does not have a default cost centre, return an error and do no more processing.


Table RES_TRAILER
Table RES_TRAILER
Line 692: Line 781:
! Field !! Type !! Notes
! Field !! Type !! Notes
|-
|-
| TRAILER_ID || VARCHAR2(12) ||  
| TRAILER_ID || VARCHAR2(12) || ''p_id''
|-
|-
| TRAILER_TYPE || VARCHAR2(12) ||  
| TRAILER_TYPE || VARCHAR2(12) || ''p_type''
|-
|-
| INACTIVE || VARCHAR2(1) || Use this for availability
| INACTIVE || VARCHAR2(1) || ''p_inactive''
|-
|-
| TRACKING_ENABLED || VARCHAR2(50) ||  
| TRACKING_ENABLED || VARCHAR2(50) || N/A
|-
|-
| COST_CENTRE_NAME || VARCHAR2(12) || Defaulted through authorisation user  
| COST_CENTRE_NAME || VARCHAR2(12) || from the user cost centre parameter
|}
|}


Line 706: Line 795:
To update trailer carrier assignment.
To update trailer carrier assignment.


Note: Assigning a trailer to a carrier will check the carrier group of that carrier and assign the trailer to that carrier group. As trailers can only be assigned to one category in FleetCheck, if this trailer is assigned to another carrier group, this should be made unavailable to that prior carrier group.
First, the process should find the carrier. This may be through the ID provided or the carrier name. If the carrier is not found, do not perform the update of the carrier assignment. Return an error.


Note: this is a method available to either system. Therefore, if updating carrier assignment from this method, this method should not then send an update out through the other system web service method.  
If the carrier is found, check whether the vehicle has a carrier group entry for the carrier group of that carrier. If it does not, one should be created. If found, it should be updated.


Table RES_TRAILER_CARRIER_GROUP
Table RES_TRAILER_CARRIER_GROUP
Line 716: Line 805:
! Field !! Type !! Notes
! Field !! Type !! Notes
|-
|-
| ID || NUMBER(10) || {{Warning}} Irrelevant?
| ID || NUMBER(10) || N/A
|-
|-
| TRAILER_ID || VARCHAR2(12) ||
| TRAILER_ID || VARCHAR2(12) || ''p_id''
|-
|-
| INACTIVE || VARCHAR2(1) || Use this for availability?
| INACTIVE || VARCHAR2(1) || ''p_inactive''
|-
|-
| NAME || VARCHAR2(35) || Carrier Group, taken from RES_CARRIER.CARRIER_NAME
| NAME || VARCHAR2(35) || Carrier Group, taken from RES_CARRIER.GROUP_NAME
|}
|}
{{Note}} This is a method available to either system. Therefore, if updating carrier assignment from this method, this method should not then send an update out through the other system web service method. This is handled in the CTMS-FleetCheck interface, defined below.
{{Note}} Assigning a trailer to a carrier will check the carrier group of that carrier and assign the trailer to that carrier group. As trailers can only be assigned to one category in FleetCheck, if this trailer is assigned to another carrier group, this should be made unavailable to that prior carrier group.




Line 739: Line 832:
Parameters:  
Parameters:  
* Authorisation parameters
* Authorisation parameters
* ''id'' - unique ID. Used when updating an existing tractor.
* ''p_id'' - unique ID. Used when updating an existing tractor.
* ''desc'' - Required when creating equipment. Maximum length 255. If id not provided, this will be used to identify the equipment.
* ''p_desc'' - Required when creating equipment. Maximum length 255. If id not provided, this will be used to identify the equipment.
* ''qty'' - Optional. If not provided when creating new equipment, defaults to 1.
* ''p_qty'' - Optional. If not provided when creating new equipment, defaults to 1.
 
 
==== System Processing ====


{{Note}}
* Should we allow deletion?
* Should/Do we have availability flags for equipment?


Procedure: DP_FLEETCHECK.EQUIPMENT


RES_EQUIPMENT
Table RES_EQUIPMENT


{| class="wikitable" border="1"
{| class="wikitable" border="1"
Line 757: Line 845:
! Field !! Type !! Notes
! Field !! Type !! Notes
|-
|-
| EQUIPMENT_TYPE || VARCHAR2(12) || Make this a unique identifier instead of a type.
| EQUIPMENT_TYPE || VARCHAR2(12) || ''p_id''. {{Note}} This will be used as a unique identifier rather than a type.
|-
|-
| EQUIPMENT_DESCRIPTION || VARCHAR2(255) ||
| EQUIPMENT_DESCRIPTION || VARCHAR2(255) || ''p_desc''
|-
|-
| RPE | NUMBER ||  
| RPE || NUMBER || 0
|-
|-
| WEIGHT | NUMBER ||  
| WEIGHT || NUMBER || 0
|-
|-
| TRIP_FREQUENCY | VARCHAR2(20) ||  
| TRIP_FREQUENCY || VARCHAR2(20) || N/A
|-
|-
| QUANTITY | NUMBER ||  
| QUANTITY || NUMBER || ''p_qty'' if provided, else 1.
|-
|-
| LOADING_TIME | NUMBER ||  
| LOADING_TIME || NUMBER || 0
|}
|}


Line 813: Line 901:


=== System Parameters ===
=== System Parameters ===
{{Warning}} System parameters to control access to FleetCheck interface
System parameters are required to control access to the FleetCheck interface.


* FC_URL - the base URL for the FleetCheck system.
* FC_URL - the base URL for the FleetCheck system.
Line 819: Line 907:
* FC_FLEET_KEY - the FleetCheck fleet being updated by C-TMS.
* FC_FLEET_KEY - the FleetCheck fleet being updated by C-TMS.
* FC_TIMEOUT - the amount of time to wait when trying to update FleetCheck.
* FC_TIMEOUT - the amount of time to wait when trying to update FleetCheck.
{{Warning}} Should we do this?
* FC_BLOCKED_DT - the database date/time up to which the FleetCheck interface is blocked i.e. C-TMS will not send messages to FleetCheck.
* FC_FAILED_COUNT - the database date/time up to which the FleetCheck interface is blocked i.e. C-TMS will not send messages to FleetCheck.




Line 829: Line 914:
Any triggers that must update FleetCheck should call the appropriate procedure within DP_FLEETCHECK.
Any triggers that must update FleetCheck should call the appropriate procedure within DP_FLEETCHECK.


All triggers should be named appropriately to the table following system conventions, and suffixed with "_FLEETCHECK".
All triggers should be named appropriately to the table following system conventions.


For example:
For example:


  TRG_RES_TRAILER_TYPE_FLEETCHECK
  TRG_RES_TRAILER_TYPE_BUI


 
All FleetCheck code should be clearly marked in these triggers (as they may already exist and the code will be added to them).
{{Warning}} All auditing ?




Line 843: Line 927:


The procedures will receive several parameters, predominantly driven by the data to send to FleetCheck. One is common:
The procedures will receive several parameters, predominantly driven by the data to send to FleetCheck. One is common:
* p_strAction - (A)dd, (U)pdate or (D)elete.
* p_action - (A)dd, (U)pdate or (D)elete.
This will be determined by whether we are adding, updating or deleting data.
This will be determined by whether we are adding, updating or deleting data.


Line 858: Line 942:
* ''FleetKey'' - from FC_ACCESS_FLEET.
* ''FleetKey'' - from FC_ACCESS_FLEET.


The action for the web service call will be determined by the parameter p_strAction:
The action for the web service call will be determined by the parameter p_action:
* A - POST
* A - POST
* U - PUT
* U - PUT
Line 870: Line 954:
If this is in the success range (200), this should be audited so that it is visible in the existing EDI Log screen as a successful send.
If this is in the success range (200), this should be audited so that it is visible in the existing EDI Log screen as a successful send.


If this is in the error range (400), this should be audited so that it is visible in the existing EDI Log screen as an error. {{Warning}} Any data included in the error returned should be kept as part of the audit.
If this is in the error range (400), this should be audited so that it is visible in the existing EDI Log screen as an error. Any data included in the error returned should be kept as part of the audit.
 
 
{{Note}} It may be that, when adding a record into CTMS and therefore triggering the add of the record in FleetCheck, that this may already exist. In this case, the process will log the failure, if a failure code is returned - it will not then attempt to call the web service method again to update the existing record. It is expected that, if this were required, then the FleetCheck web services should support that automatically, as the CALIDUS web services will.
 
 
=== Audit Logging ===
Actions taken when updating data will be audited in the system through this user account.
 
All package code will audit to ADM_EDI_AUDIT, for success and failure.
 
{| class="wikitable" border="1"
|-bgcolor="silver"
!Field !! Comment
|-
|STMT || Generated
|-
|PROG_NAME || Package and procedure, dot delimited e.g. DP_FLEETCHECK.UPDATE_EXTERNAL_TYPE
|-
|ORI_USER || As normal
|-
|USER_SESSION || As normal
|-
|ERR_TYPE || 'ERROR' if an error, 'INFO' otherwise. 'AUDIT' may be used for debugging statements, but should be limited.
|-
|DATE_CREATED || System date and time
|-
|ERR_MESSAGE || The generated error message for an error plus an indication of the data e.g. "Error updating trailer type XXX: YYYY", otherwise a success message indicating the action taken, identifying the data e.g. "Trailer type XXX updated".
|-
|SCHED_NAME || N/A
|-
|CUSTOMER_ID || N/A
|-
|LOCATION_ID || N/A
|}




=== External Type ===
=== External Type ===
To add, update or delete FleetCheck External Types (trailer types).


Whenever vehicles and trailer types are added to C-TMS, edited or deleted (i.e. in a database trigger), the system will call DP_FLEETCHECK.UPDATE_EXTERNAL_TYPE, passing in parameters of:
Whenever trailer types are added to C-TMS, edited or deleted (i.e. in a database trigger), the system will call DP_FLEETCHECK.UPDATE_EXTERNAL_TYPE, passing in parameters of:
* p_strAction - (A)dd, (U)pdate or (D)elete.
* p_action - (A)dd, (U)pdate or (D)elete.
* p_strId - {{Warning}} the vehicle type or trailer type ID.
* p_id - the trailer type (RES_TRAILER_TYPE.TRAILER_TYPE).
* P_strDesc - the vehicle type of trailer type description.
* P_desc - the trailer type description.


The system will do this by adding a FleetCheck trigger to tables {{Warning}} ??? and RES_TRAILER_TYPE.
The system will do this by adding a FleetCheck trigger to the table RES_TRAILER_TYPE.


DP_FLEETCHECK.UPDATE_EXTERNAL_TYPE will call the FleetCheck web service method to update External Types, method .
DP_FLEETCHECK.UPDATE_EXTERNAL_TYPE will call the FleetCheck web service method to update External Types, method: "UpdateExternalType.ashx".
 
Method: "UpdateExternalType.ashx"


Parameters:
Parameters:
* Authentication parameters - set from the new system parameters.
* Authentication parameters.
* ''ExternalTypeId'' - p_strId
* ''ExternalTypeId'' - p_id
* ''ExternalTypeDescription'' - p_strDesc
* ''ExternalTypeDescription'' - p_desc




=== Category ===
=== Category ===


To add or update Categories (home fleet carriers)
To add, update or delete FleetCheck Categories (home fleet carriers)
 
Whenever carriers are added to C-TMS, edited or deleted (i.e. in a database trigger), the system will call DP_FLEETCHECK.UPDATE_CATEGORY, passing in parameters of:
* p_action - (A)dd, (U)pdate or (D)elete.
* p_id - the carrier ID (RES_CARRIER.CARRIER_ID).
* p_name - the carrier name (RES_CARRIER.CARRIER_NAME).
 
The system will do this by adding a FleetCheck trigger to table RES_CARRIER.


Method: UpdateCategory
DP_FLEETCHECK.UPDATE_CATEGORY will call the FleetCheck web service method to update Categories, method: "UpdateCategory.ashx".


Parameters:  
Parameters:  
* Authentication parameters.
* Authentication parameters.
* ''CategoryName''
* ''CategoryName'' - p_name
* ''CategoryId'' - {{Warning}} Required?
* ''CategoryId'' - p_id




Line 908: Line 1,032:
To update driver carrier assignment.
To update driver carrier assignment.


Method: UpdateDriverCategory
Whenever drivers are assigned to carriers in C-TMS, edited or deleted (i.e. in a database trigger), the system will check and attempt to update FleetCheck.
 
The system will do this by adding a FleetCheck trigger to table RES_PERSON_CARRIER.
 
When a driver carrier record is created or INACTIVE set to "N", the process will call DP_FLEETCHECK.UPDATE_DRIVER_CATEGORY, passing in parameters of:
* p_action - (A)dd, (U)pdate or (D)elete.
* p_id - the carrier ID (RES_PERSON_CARRIER.CARRIER_ID).
* p_driver - the driver ID (RES_PERSON_CARRIER.ID).
* p_user - the user making the amendment.
 
The procedure DP_FLEETCHECK.UPDATE_DRIVER_CATEGORY will check the user (p_user) making the amendment.
 
If this is not the default FLEETCHECK user, the process will retrieve the carrier name CARRIER_NAME using the carrier ID provided (p_id) from RES_CARRIER.


Note: this is a method available to either system. Therefore, if updating carrier assignment from this method, this method should not then send an update out through the other system web service method.  
Then the procedure will call the FleetCheck web service method to update Driver Categories, method: "UpdateDriverCategory.ashx".


Parameters:  
Parameters:  
* Authentication parameters.
* Authentication parameters.
* ''DriverId''
* ''DriverId'' - p_driver
* ''AssetId''
* ''CategoryName'' - the retrieved carrier name from RES_CARRIER.CARRIER_NAME.
 
Furthermore, all other entries for that driver against other carriers will be set to INACTIVE = "Y". The process will update all of these records at the end of the process.




Line 922: Line 1,060:
To update vehicle carrier assignment.
To update vehicle carrier assignment.


Method: UpdateVehicleCategory
Whenever tractors are assigned to carriers in C-TMS, edited or deleted (i.e. in a database trigger), the system will check and attempt to update FleetCheck.
 
The system will do this by adding a FleetCheck trigger to table RES_TRACTOR_CARRIER.
 
When a tractor carrier record is created or INACTIVE set to "N", the process will call DP_FLEETCHECK.UPDATE_TRACTOR_CATEGORY, passing in parameters of:
* p_action - (A)dd, (U)pdate or (D)elete.
* p_id - the carrier ID (RES_TRACTOR_CARRIER.CARRIER_ID).
* p_vehicle_id - the vehicle registration (RES_TRACTOR_CARRIER.TRACTOR_ID).
* p_user - the user making the amendment.
 
The procedure DP_FLEETCHECK.UPDATE_TRACTOR_CATEGORY will check the user (p_user) making the amendment.
 
If this is not the default FLEETCHECK user, the process will retrieve the carrier name CARRIER_NAME using the carrier ID provided (p_id) from RES_CARRIER.


{{Note}} This is a method available to either system. Therefore, if updating carrier assignment from this method, this method should not then send an update out through the other system web service method.  
Then the procedure will call the FleetCheck web service method to update Vehicle Categories, method: "UpdateVehicleCategory.ashx".


Parameters:  
Parameters:  
* Authentication parameters.
* Authentication parameters.
* ''VehicleRegistration''
* ''VehicleRegistration'' - p_vehicle_id
* ''CategoryName''
* ''CategoryName'' - the retrieved carrier name from RES_CARRIER.CARRIER_NAME.
 
Furthermore, all other entries for that tractor against other carriers will be set to INACTIVE = "Y". The process will update all of these records at the end of the process.




Line 936: Line 1,088:
To update trailer carrier assignment.
To update trailer carrier assignment.


Method: UpdateVehicleCategory


**Note:** This is a method available to either system. Therefore, if updating carrier assignment from this method, this method should not then send an update out through the other system web service method.  
Whenever trailers are assigned to carriers in C-TMS, edited or deleted (i.e. in a database trigger), the system will check and attempt to update FleetCheck.
 
The system will do this by adding a FleetCheck trigger to table RES_TRAILER_CARRIER_GROUP.
 
When a tractor carrier record is created or INACTIVE set to "N", the process will call DP_FLEETCHECK.UPDATE_TRAILER_CATEGORY, passing in parameters of:
* p_action - (A)dd, (U)pdate or (D)elete.
* p_id - the carrier group ID (RES_TRAILER_CARRIER_GROUP.NAME).
* p_vehicle_id - the trailer ID (RES_TRAILER_CARRIER_GROUP.TRAILER_ID).
* p_user - the user making the amendment.
 
The procedure DP_FLEETCHECK.UPDATE_TRAILER_CATEGORY will check the user (p_user) making the amendment.
 
If this is not the default FLEETCHECK user, the process will retrieve the carrier name CARRIER_NAME of the first carrier found in this carrier group using the carrier group ID provided (p_id) from RES_CARRIER.
 
Then the procedure will call the FleetCheck web service method to update Vehicle Categories, method: "UpdateVehicleCategory.ashx".


Parameters:  
Parameters:  
* Authentication parameters.
* Authentication parameters.
* ''TrailerId''
* ''VehicleRegistration'' - p_vehicle_id
* ''CategoryName''
* ''CategoryName'' - the retrieved carrier name from RES_CARRIER.CARRIER_NAME.
 
Furthermore, all other entries for that trailer against other carrier groups will be set to INACTIVE = "Y". The process will update all of these records at the end of the process.
<!-- INTERNAL COSTS
 
Description                                         Days Notes                                                             System
 
Inbound from FleetCheck to CTMS
General RESTful web service project in .NET     3.0     Plus security/insertion checks. General error handling             .NET
BAL/DAL:                                                                                                             .NET
BAL (Business logic)                             3.75 .NET. 5 required (one for each method plus authorisation) @0.75e .NET
DAL (Data Access, specific to CTMS)             2.5     .NET and also potentially Oracle Packages. 5 @ 0.5ea             .NET/CTMS
Authentication fields/parameters                 0.5                                                                     CTMS
Outbound from CTMS to FleetCheck
System parameters for FC web service             0.5                                                                     CTMS
Immediate update of FleetCheck when data updated 3.0 5 different processes, added as triggers, running if FC I/F enabled     CTMS


Total 13.25
-->
<!-- NEW PAGE -->  
<!-- NEW PAGE -->  
{{Doc_AppendixNew
{{Doc_AppendixNew
|Appendix=A
|Appendix=A
|Estimate=N
|Estimate=Y
|Glossary=CTMS
|Glossary=CTMS
|Ref1=[[REQ 370536 FleetCheck Interface]]
|Ref1=[[REQ 370536 FleetCheck Interface]]
|RefV1=0.3
|RefV1=0.3
|RefDate1=06/5/2020
|RefDate1=06/05/2020
|REQ=0
|REQ=0
|EST=0
|EST=0
|FS=0
|FS=3.00
|TS=0
|TS=0
|DEV=0
|DEV=13.25
|ST=0
|ST=3.00
|IMP=0
|IMP=2.00
|PM=0
|PM=2.25
|Client={{#var:Client}}
|Client={{#var:Client}}
|Year={{#var:Year}}
|Year={{#var:Year}}

Latest revision as of 17:06, 19 May 2020






Aptean Logo.png







OBS Logistics Ltd

FleetCheck Interface

Functional Specification

19th May 2020 - 0.4
Reference: FS 370536















FUNCTIONAL OVERVIEW

Client Requirement

An interface is required between FleetCheck resource management software and CALIDUS systems (initially C-TMS).


Solution Overview

The expected phase 1 functionality will be as follows:

  • Initial set up of vehicle (tractor) and trailer types will be performed in CTMS. This will automatically send this type information over to FleetCheck to be used when setting up vehicles.
  • Initial set-up of carriers will be performed within CTMS. This will automatically send this information over to FleetCheck, so that drivers can be assigned to categories (areas or carriers, in CTMS terms).
  • Vehicles, trailers and assets are created and maintained in FleetCheck. Once all the information is correctly entered, including the type information, this is automatically sent across from FleetCheck to CTMS and tractors, trailers and equipment are automatically created. The interface between the systems will track the creation and update of these resources in CTMS.
  • FleetCheck or CTMS can be used to maintain carrier/Category assignment - when changed in one system, that will be automatically updated in the other.
  • FleetCheck functionality will be used to control vehicle defect checks, VOR, availability of resources and reporting, capturing information from all systems that FleetCheck is connected to, including (if enabled) vehicle tracking, automatic tyre status, maintenance and repair schedules, with statistical reporting and business information.
  • When required (through the above fleet operational processes), the resources can be made unavailable. CTMS will be informed immediately that that resource is then unavailable.
  • When a resource is made available, CTMS will also be informed immediately.


Future phases may include the following (not included in this phase):

  • Better trailer functionality within FleetCheck.
  • Linking of Tractor and Trailer.
  • Linking of driver with tractor/trailer.
  • CTMS updating FleetCheck with current job information.
  • CTMS Taking information from FleetCheck for debrief information.
  • FleetCheck improved use of type to prevent repetitive keying of vehicles.
  • More information captured from FleetCheck regarding reasons for unavailability.
  • Capture information for when vehicle might be available again, for forward planning.

Much of this is dependent on the functionality becoming available within FleetCheck to support this level of integration.


Scope

This change will be applied to system version 11.36 on test database JAKTTST and once approved JAKTPRD.

  • Requires Types in FleetCheck to be definable rather than fixed, so that we can align this to the CTMS vehicle/trailer types. Alternatively, a new External Type field can be added.
  • Tractor/Trailer carrier assignment is supported in FleetCheck through categories.
  • FleetCheck is responsible for maintaining drivers, vehicles, equipment, trailers.
  • FleetCheck is responsible for reporting usage stats on driver, vehicle, trailer, equipment.
  • Drivers, Vehicles and trailers can only be part of a single carrier (category) in FleetCheck.
  • Vehicle Tracking or keyfob systems will be responsible for driver/vehicle assignment if present, else CTMS will be responsible for this.

It is expected that the following are the responsibilities of the systems:

  • CTMS:
    • Maintain trailer types (external type) and carriers (categories) - inform FleetCheck of the data.
    • Tractor/Trailer/Driver carrier assignment (TBC)
  • FleetCheck:
    • Creation or amendment of drivers, vehicles, trailers and assets.
    • Availability of drivers, vehicles, trailers and assets.
    • Tractor/Trailer/Driver carrier assignment (TBC)

Note Note:

  • Tractor/Trailer/Driver carrier assignment may be achieved in either CTMS, FleetCheck or both.
  • Carrier (Category) creation and maintenance may be achieved in either CTMS, FleetCheck or both. As CTMS holds a mass of data regarding carriers, this should be the responsibility of CTMS.
  • Carriers and Category may be maintained separately without an interface, but this may result in messages failing to be processed.
  • Vehicle and trailer types should be created and maintained within CTMS. As this is a CTMS convention rather than a FleetCheck one, this should be the responsibility of CTMS.


Note Note: This interface is at system level, and therefore any carriers with named resources will be managed through FleetCheck, when this system is enabled. In the future, the system may be modified to enable/disable the interface on a per-carrier basis.

Note Note: It may be that, when adding a record into CTMS and therefore triggering the add of the record in FleetCheck, that this may already exist. In this case, the process will log the failure, if a failure code is returned - it will not then attempt to call the web service method again to update the existing record. It is expected that, if this were required, then the FleetCheck web services should support that automatically, as the CALIDUS web services will.


Impact

All resources will be managed through FleetCheck and availability will be controlled through that application.


CONFIGURATION SET-UP

Pre-requisites

The web services .NET project must be installed on a server that can access the CTMS database it feeds.

CTMS must be configured for the FleetCheck interface, pointing to the correct FleetCheck URL, and configured with the correct authorisation parameters.


Menu Structure

The EDI Log is accessible from Administration/EDI/Interface Errors, the EDI audit is available on tab EDI Audit.


Data

N/A


Implementation Advice

N/A


FUNCTIONAL DESCRIPTION

CTMS Web Service, for FC->CTMS

This web service shall be hosted through the standard URL of the system, whatever that may be. For example: 

   hcrprd.calidus-tms.com

Webservices will be accessed through the /ws sub-domain, followed by the version and then the area to be accessed. For example: 

   hcrprd.calidus-tms.com/ws/v1.0/resources

The currently accessible areas are:

  • resources.

This in this area, the following resources are accessible:

  • Driver - to add or update a driver, and to update carrier assignment.
  • Vehicle - to add or update a vehicle, and to update carrier assignment.
  • Equipment - to add or update equipment (assets).
  • Trailer - to add or update a trailer, and to update carrier assignment.

For example: 

   hcrprd.calidus-tms.com/ws/v1.0/resources/drivers

These are RESTful web services and generally support only the POST and PUT actions.

Responses will be sent as per HTTP standards:

  • 200 - OK
  • 201 - CREATED
  • 202 - ACCEPTED
  • 400 - BAD REQUEST
  • 401 - UNAUTHORISED
  • 404 - NOT FOUND

Errors will be indicated through the response status above, supported by a JSON error response payload: 

    {
      "error" : {
        "code" : "",
        "message" : ""
      }
    }

Parameters will be provided through the querystring on the URL or post data and are in the following groups:

  • Authorisation - common parameters for authorisation to use the web service.
  • Action-specific - specific parameters for that action.

For example, to add a driver "JOHN SMITH" and assign to carrier "FLEET" for organisation JAK-CC: 

    hcrprd.calidus-tms.com/ws/v1.0/resources/drivers?authcode=12345ABCDE&system=FLEETCHECK&org=JAK-CC
    &surname=SMITH&forename=JOHN&job=DRIVER&inactive=N&carrier=FLEET


Authorisation parameters consist of:

  • authcode - an authorisation code provided by OBS Logistics for accessing this system's web services only. Required.
  • system - the system accessing the web services. Expected to be hard-coded to "FLEETCHECK". May be used in the future to control slight functionality differences if other systems use this interface. Not required.
  • org - the organisation (cost centre) being updated. Up to 12 characters. Required.

This information will be linked to an account within the CTMS system with default authorisations such as:

  • Accessible options.
  • Configuration.


Actions taken when updating data will be audited in the system through this user account.


Driver

To add or update a driver, and to update carrier assignment.

Web Service Method: /drivers

Actions supported:

  • POST - create.
  • PUT - update.

Parameters:

  • Authorisation parameters
  • id - unique numeric ID. Used when updating an existing driver.
  • surname - must be provided when creating a new driver. Maximum 50 characters. If id is not provided, surname and forename will be used to identify the driver.
  • forename - must be provided when creating a new driver. Maximum 50 characters. If id is not provided, surname and forename will be used to identify the driver.
  • job - must be provided when creating a new driver. Maximum 50 characters.
  • inactive - Optional. Will be assumed to be "N" when creating a new driver is not provided. Values "Y" or "N"
  • agency - Is this an agency driver. "Y" or "N". Optional. Assumed to be "N" when creating a new driver if not provided.
  • agencyname - provide the agency name. Maximum 100 characters. Required if agency = "Y".
  • carrier - must be a valid carrier id. Maximum 12 characters. Optional. Assumes driver is not assigned to a carrier if omitted when creating a new driver.
  • carriername - must be a valid carrier name. Maximum 50 characters. Optional. Assumes driver is not assigned to a carrier if omitted when creating a new driver.


Tractors

To add or update a vehicle, including VOR, and to update carrier assignment.

Web Service Method: /tractors

Actions supported:

  • POST - create.
  • PUT - update.


Parameters:

  • Authorisation parameters
  • id - unique ID. Used when updating an existing tractor. Use the registration.
  • type - must be a valid trailer type in the system. Required when creating a tractor.
  • desc - Required when creating a tractor. Maximum length 50.
  • inactive - Optional. Will be assumed to be "N" when creating a new tractor if not provided. Values "Y" or "N".
  • mpg - Optional. Decimal number, 3 decimal places.
  • vin - optional. Maximum length 17.
  • carrier - must be a valid carrier id. Maximum 12 characters. Optional. Assumes tractor is not assigned to a carrier if omitted when creating a new tractor.
  • carriername - must be a valid carrier name. Maximum 50 characters. Optional. Assumes tractor is not assigned to a carrier if omitted when creating a new tractor.


Trailer

To add or update a trailer, including VOR, and to update carrier assignment.


Web Service Method: /trailers

Actions supported:

  • POST - create.
  • PUT - update.


Parameters:

  • Authorisation parameters
  • id - unique ID. Used when updating an existing trailer.
  • type - must be a valid trailer type in the system. Required when creating a trailer.
  • inactive - Optional. Will be assumed to be "N" when creating a new trailer if not provided. Values "Y" or "N".
  • carrier - must be a valid carrier id. Maximum 12 characters. Optional. Assumes trailer is not assigned to a carrier if omitted when creating a new trailer.
  • carriername - must be a valid carrier name. Maximum 50 characters. Optional. Assumes trailer is not assigned to a carrier if omitted when creating a new trailer.


Equipment

To add or update Equipment (Assets), and to update carrier assignment.


Web Service Method: /equipment

Actions supported:

  • POST - create.
  • PUT - update.

Parameters:

  • Authorisation parameters
  • id - unique ID. Used when updating an existing tractor.
  • desc - Required when creating equipment. Maximum length 255. If id not provided, this will be used to identify the equipment.
  • qty - Optional. If not provided when creating new equipment, defaults to 1.


FC Web Service, for CTMS->FC

This web service is hosted by FleetCheck and will be accessible through the a URL similar to the following: 

   https://api.fleetcheck.co.uk/api/obs/v1/

The FleetCheck OBS API is a REST API using JSON posts and responses. All HTTP response codes are standards and error messages will be returned in the JSON Body of the response.

Parameters will be provided through post data only and are in the following groups:

  • Authentication - common parameters for authentication to use the web service.
  • Action-specific - specific parameters for that action.

For example, to assign vehicle reg "KU60XUD" to carrier "FLEET" for organisation "EUPPCF": 

    curl --location --request POST 'https://api.fleetcheck.co.uk/api/obs/v1/UpdateVehicleCategory.ashx'
    --data-raw '{
      "FleetKey":"EUPPCF",
      "AccessToken":"00000000-0000-0000-0000-000000000000",
      "VehicleRegistration":"KU60XUD",
      "CategoryName":"FLEET"
    }'


Authentication parameters consist of:

  • AccessToken - These tokens are only generated by FleetCheck and will be provided when the service is live.
  • FleetKey - the fleet being updated.


This web service should support the following methods:

  • Type - to add or update Types (vehicle and trailer types)
  • Category - to add or update Categories (home fleet carriers)
  • Driver Category Assignment - to update category assignment.
  • Vehicle Category Assignment - to update category assignment.
  • Trailer Category Assignment - to update category assignment.

Not required for phase 1, but included here to show the potential evolution of the interface:

  • Asset Vehicle Assignment - to assign as asset to a vehicle.
  • Driver Vehicle Assignment - to assign a driver to a vehicle or vice versa.


External Type

To add or update External Types (vehicle and trailer types).

Method: UpdateExternalType

Parameters:

  • Authentication parameters.
  • ExternalTypeId
  • ExternalTypeDescription


Category

To add or update Categories (home fleet carriers)

Method: UpdateCategory

Parameters:

  • Authentication parameters.
  • CategoryName
  • CategoryId


Driver Carrier Assignment

To update driver carrier assignment.

Method: UpdateDriverCategory

Note: this is a method available to either system. Therefore, if updating carrier assignment from this method, this method should not then send an update out through the other system web service method.

Parameters:

  • Authentication parameters.
  • DriverId
  • CategoryName


Vehicle Carrier Assignment

To update vehicle carrier assignment.

Method: UpdateVehicleCategory

Note Note: This is a method available to either system. Therefore, if updating carrier assignment from this method, this method should not then send an update out through the other system web service method.

Parameters:

  • Authentication parameters.
  • VehicleRegistration
  • CategoryName


Trailer Carrier Assignment

To update trailer carrier assignment.

Method: UpdateVehicleCategory

Note Note: This is a method available to either system. Therefore, if updating carrier assignment from this method, this method should not then send an update out through the other system web service method.

Parameters:

  • Authentication parameters.
  • TrailerId
  • CategoryName


Asset Assignment

To update asset assignment to a vehicle.

Method: UpdateVehicleAsset

Note Note: This is not required for phase 1, but is included here to show the potential evolution of the interface.

Parameters:

  • Authentication parameters.
  • VehicleRegistration
  • AssetId


Driver Vehicle Assignment

To update vehicles against drivers.

Note: If FleetCheck is configured to update this through other systems, for example vehicle tracking or key fob, this message should be ignored. CTMS should be configured to not send this message at all.

Note Note: This is not required for phase 1, but is included here to show the potential evolution of the interface.

Parameters:

  • Authentication parameters.
  • VehicleRegistration
  • DriverId

TECHNICAL NOTES

CTMS Web Service, for FC->CTMS

This interface will be created as a web service, written in .NET, accessing the host system data directly.

In the primary case, this data access layer will access the C-TMS database. This method will allow the process to be modified at a later date to work with CTL-TMS or C-ePOD, if required.

This in this area, the following resources are accessible:

  • Driver - to add or update a driver, and to update carrier assignment.
  • Vehicle - to add or update a vehicle, and to update carrier assignment.
  • Equipment - to add or update equipment (assets).
  • Trailer - to add or update a trailer, and to update carrier assignment.

For example: 

   hcrprd.calidus-tms.com/ws/v1.0/resources/drivers

These are RESTful web services and generally support only the POST and PUT actions.


General Notes

All code to process the received data from FleetCheck should be in package DP_FLEETCHECK.


Responses

Responses will be handled by the .NET code.

Responses will be sent as per HTTP standards:

  • 200 - OK
  • 400 - BAD REQUEST
  • 401 - UNAUTHORISED
  • 404 - NOT FOUND

Errors (those responses in the 400 range) will be indicated through the response status above, supported by a JSON error response payload: 

    {
      "error" : {
        "code" : "",
        "message" : ""
      }
    }


Parameters

Parameters will be extracted and validated in the .NET code.


Parameters will be provided through the querystring on the URL or post data and are in the following groups:

  • Authorisation - common parameters for authorisation to use the web service.
  • Action-specific - specific parameters for that action.

For example, to add a driver "JOHN SMITH" and assign to carrier "FLEET" for organisation JAK-CC: 

    hcrprd.calidus-tms.com/ws/v1.0/resources/drivers?authcode=12345ABCDE&system=FLEETCHECK&org=JAK-CC
    &surname=SMITH&forename=JOHN&job=DRIVER&inactive=N&carrier=FLEET

All parameters passed in to all web service methods will be checked to ensure that there is no SQL insertion, as well as standard checks for requirement, length and basic type.

Parameters will be extracted from the call to the web service. They will be passed to the appropriate procedure within CTMS package DP_FLEETCHECK.


Authorisation

Authorisation parameters consist of:

  • authcode - an authorisation code provided by OBS Logistics for accessing this system's web services only.
  • system - the system accessing the web services.
  • org - the organisation (cost centre) being updated.

This information will be linked to an account within the CTMS system with default authorisations such as:

  • Accessible options.
  • Configuration.

A default FLEETCHECK user will be created. This FleetCheck user will be used solely by the .NET web service system for connection purposes.

A new user parameter will be created called FLEETCHECK_AUTHCODE. This will be set against the default FLEETCHECK user - many may be created, but only one expected, and is an optional parameter.

The authorisation procedure in .NET will call package DP_FLEETCHECK.AUTHORISE_USER, accepting the authcode parameter above, returning an error code, and with in/out parameters for username, password and errors (if any).

The procedure will find the user set up with FLEETCHECK_AUTHCODE set to the passed-in Auth Code.

Any issues should be returned with a false return code (negative integer), and the description of the issue, for example:

  • -1 - Authcode not valid.


Actions taken when updating data will be audited in the system through this default FleetCheck user account.

Any issues should also be logged by the .NET code to a local logging file. These files should be created new every hour.


General Processing

Procedure code should exist in package DP_FLEETCHECK dedicated to the particular web service, for example, DRIVER.

The .NET code should call the correct procedure associated to the web service, passing in the specific parameters in the process, as well as the following:

  • p_message - error descriptions, if any.
  • p_action - the action derived from the HTTP action above:
    • A - Add
    • U - Update

The procedure should also return a basic error code (0 or negative number to identify the specific error) or 1 if all worked as expected.

The procedure should update or create records on appropriate tables, as detailed in the specific descriptions.

The .NET code written should be separated into DAL and BAL objects. BAL objects should define the actions being taken for each web service method, for example AddDriver, UpdateDriver or AddUpdateDriver. These will call define DAL object methods. DAL objects should contain the call the the CTMS Oracle package code - Oracle should not be referenced in any other places in the code, as this web services project may be converted to work with SQL Server for CTL TMS or for C-ePOD.

If adding a record that already exists, the process should look to update it. If updating a record that doesn't already exist, if the process has enough key information to create the user, then the process should create it instead.


Audit Logging

Actions taken when updating data will be audited in the system through this user account.

All package code will audit to ADM_EDI_AUDIT, for success and failure.

Field Comment
STMT Generated
PROG_NAME Package and procedure, dot delimited e.g. DP_FLEETCHECK.DRIVER
ORI_USER As normal
USER_SESSION As normal
ERR_TYPE 'ERROR' if an error, 'INFO' otherwise. 'AUDIT' may be used for debugging statements, but should be limited.
DATE_CREATED System date and time
ERR_MESSAGE The generated error message for an error plus an indication of the data e.g. "Error updating Driver XXX: YYYY", otherwise a success message indicating the action taken, identifying the data e.g. "Driver XXX updated".
SCHED_NAME N/A
CUSTOMER_ID N/A
LOCATION_ID N/A


Driver

To add or update a driver, and to update carrier assignment.

Web Service Method: /drivers

Actions supported:

  • POST - create.
  • PUT - update.

Parameters:

  • Authorisation parameters
  • p_id - unique numeric ID. Used as the key when adding or updating a driver.
  • p_surname - must be provided when creating a new driver. Maximum 50 characters. If id is not provided, surname and forename will be used to identify the driver.
  • p_forename - must be provided when creating a new driver. Maximum 50 characters. If id is not provided, surname and forename will be used to identify the driver.
  • p_job - must be provided when creating a new driver. Maximum 50 characters.
  • p_inactive - Optional. Will be assumed to be "N" when creating a new driver is not provided. Values "Y" or "N"
  • p_agency - Is this an agency driver. "Y" or "N". Optional. Assumed to be "N" when creating a new driver if not provided.
  • p_agencyname - provide the agency name. Maximum 100 characters. Required if agency = "Y".
  • p_carrier - must be a valid carrier id. Maximum 12 characters. Optional. Assumes driver is not assigned to a carrier if omitted when creating a new driver.
  • p_carriername - must be a valid carrier name. Maximum 50 characters. Optional. Assumes driver is not assigned to a carrier if omitted when creating a new driver.

Procedure: DP_FLEETCHECK.DRIVER.

Table RES_PERSON:

Field Type Notes
ID NUMBER p_id
SURNAME VARCHAR2(50) p_surname
FORENAME VARCHAR2(50) p_forename
JOB_TITLE VARCHAR2(50) p_job
LOCATION_ID VARCHAR2(12)  
CREATED_BY VARCHAR2(40) When adding, CTMS Username
CREATED_DATE DATE When adding, SYSDATE
UPDATED_BY VARCHAR2(40) When updating, CTMS Username
UPDATED_DATE DATE When updating, SYSDATE
CONTACT_NO VARCHAR2(50) N/A
INACTIVE VARCHAR2(1) p_inactive
AGENCY VARCHAR2(1) p_agency
SMARTPHONE_ENABLED VARCHAR2(100) N/A
EPOD_USERNAME VARCHAR2(10) N/A
TOMTOM_ENABLED VARCHAR2(1) N/A
HUB_LOCATION VARCHAR2(12) N/A
START_AT_HUB VARCHAR2(1) N/A
RETURN_TO_HUB VARCHAR2(1) N/A
AGENCY_NAME VARCHAR2(100) p_agencyname


If a carrier or carrier name is provided, the carrier should be updated.

To update driver carrier assignment.


First, the process should find the carrier. This may be through the ID provided or the carrier name. If the carrier is not found, do not perform the update of the carrier assignment. Return an error.

If the carrier is found, check whether the driver has a carrier entry. If it does not, one should be created. If found, it should be updated.

Table RES_PERSON_CARRIER

Field Type Notes
INACTIVE VARCHAR2(1) p_inactive
PC_ID NUMBER(10) p_id
ID NUMBER N/A
CARRIER_ID VARCHAR2(12) The carrier ID found
RAG VARCHAR2(1) N/A

Note Note: As FleetCheck supports only one category assigned to each resource, then changing the category should make the prior carrier unavailable and this carrier available. The process should find all other carrier records and mark them inactive, if the user is being marked as active to this carrier. This is handled in the CTMS-FleetCheck interface, defined below.

Note Note: This is a method available to either system. Therefore, if updating carrier assignment from this method, this method should not then send an update out through the other system web service method.


Tractors

To add or update a vehicle, including VOR, and to update carrier assignment.


Web Service Method: /tractors

Actions supported:

  • POST - create.
  • PUT - update.


Parameters:

  • Authorisation parameters
  • p_id - unique ID. Used when updating an existing tractor. Use the registration.
  • p_type - must be a valid trailer type in the system. Required when creating a tractor.
  • p_desc - Required when creating a tractor. Maximum length 50.
  • p_inactive - Optional. Will be assumed to be "N" when creating a new tractor if not provided. Values "Y" or "N".
  • p_mpg - Optional. Decimal number, 3 decimal places.
  • p_vin - optional. Maximum length 17.
  • p_carrier - must be a valid carrier id. Maximum 12 characters. Optional. Assumes tractor is not assigned to a carrier if omitted when creating a new tractor.
  • p_carriername - must be a valid carrier name. Maximum 50 characters. Optional. Assumes tractor is not assigned to a carrier if omitted when creating a new tractor.


Procedure: DP_FLEETCHECK.TRACTOR.

Table RES_TRACTOR:

Field Type Notes
TRACTOR_ID VARCHAR2(12) p_id
TRACTOR_TYPE VARCHAR2(12) p_type
DESCRIPTION VARCHAR2(50) p_desc, if provided
INACTIVE VARCHAR2(1) p_inactive, if provided
LOCATION_ID VARCHAR2(12) N/A
TRACKING_ENABLED VARCHAR2(50) N/A
CONTACT_NO VARCHAR2(50) N/A
MPG NUMBER(6,3) p_mpg, if provided.
TRACK_REF VARCHAR2(30) N/A
VIN_NO VARCHAR2(17) p_vin if provided.
FLEET_ID VARCHAR2(100) N/A
BLUE_LIGHT VARCHAR2(1) N/A
TAIL_LIFT VARCHAR2(1) N/A
TOMTOM_ENABLED VARCHAR2(1) N/A
EPOD_ENABLED VARCHAR2(1) N/A
RAG VARCHAR2(1) N/A


If a carrier or carrier name is provided, the carrier should be updated.

To update vehicle carrier assignment.


First, the process should find the carrier. This may be through the ID provided or the carrier name. If the carrier is not found, do not perform the update of the carrier assignment. Return an error.

If the carrier is found, check whether the vehicle has a carrier entry. If it does not, one should be created. If found, it should be updated.


Table RES_TRACTOR_CARRIER

Field Type Notes
ID NUMBER(10) N/A
TRACTOR_ID VARCHAR2(12) p_id
CARRIER_ID VARCHAR2(12) The carrier ID found
INACTIVE VARCHAR2(1) p_inactive

Note Note: As FleetCheck supports only one category assigned to each resource, then changing the category should make the prior carrier unavailable and this carrier available. The process should find all other carrier records and mark them inactive, if the user is being marked as active to this carrier.

Note Note: This is a method available to either system. Therefore, if updating carrier assignment from this method, this method should not then send an update out through the other system web service method. This is handled in the CTMS-FleetCheck interface, defined below.


Trailer

To add or update a trailer, including VOR, and to update carrier assignment.


Web Service Method: /trailers

Actions supported:

  • POST - create.
  • PUT - update.


Parameters:

  • Authorisation parameters
  • p_id - unique ID. Used when updating an existing trailer.
  • p_type - must be a valid trailer type in the system. Required when creating a trailer.
  • p_inactive - Optional. Will be assumed to be "N" when creating a new trailer if not provided. Values "Y" or "N".
  • p_carrier - must be a valid carrier id. Maximum 12 characters. Optional. Assumes trailer is not assigned to a carrier if omitted when creating a new trailer.
  • p_carriername - must be a valid carrier name. Maximum 50 characters. Optional. Assumes trailer is not assigned to a carrier if omitted when creating a new trailer.

Procedure: DP_FLEETCHECK.TRAILER

The process should first check the authorised user parameters. If the user does not have a default cost centre, return an error and do no more processing.

Table RES_TRAILER

Field Type Notes
TRAILER_ID VARCHAR2(12) p_id
TRAILER_TYPE VARCHAR2(12) p_type
INACTIVE VARCHAR2(1) p_inactive
TRACKING_ENABLED VARCHAR2(50) N/A
COST_CENTRE_NAME VARCHAR2(12) from the user cost centre parameter


To update trailer carrier assignment.

First, the process should find the carrier. This may be through the ID provided or the carrier name. If the carrier is not found, do not perform the update of the carrier assignment. Return an error.

If the carrier is found, check whether the vehicle has a carrier group entry for the carrier group of that carrier. If it does not, one should be created. If found, it should be updated.

Table RES_TRAILER_CARRIER_GROUP

Field Type Notes
ID NUMBER(10) N/A
TRAILER_ID VARCHAR2(12) p_id
INACTIVE VARCHAR2(1) p_inactive
NAME VARCHAR2(35) Carrier Group, taken from RES_CARRIER.GROUP_NAME

Note Note: This is a method available to either system. Therefore, if updating carrier assignment from this method, this method should not then send an update out through the other system web service method. This is handled in the CTMS-FleetCheck interface, defined below.

Note Note: Assigning a trailer to a carrier will check the carrier group of that carrier and assign the trailer to that carrier group. As trailers can only be assigned to one category in FleetCheck, if this trailer is assigned to another carrier group, this should be made unavailable to that prior carrier group.


Equipment

To add or update Equipment (Assets), and to update carrier assignment.


Web Service Method: /equipment

Actions supported:

  • POST - create.
  • PUT - update.

Parameters:

  • Authorisation parameters
  • p_id - unique ID. Used when updating an existing tractor.
  • p_desc - Required when creating equipment. Maximum length 255. If id not provided, this will be used to identify the equipment.
  • p_qty - Optional. If not provided when creating new equipment, defaults to 1.


Procedure: DP_FLEETCHECK.EQUIPMENT

Table RES_EQUIPMENT

Field Type Notes
EQUIPMENT_TYPE VARCHAR2(12) p_id. Note Note: This will be used as a unique identifier rather than a type.
EQUIPMENT_DESCRIPTION VARCHAR2(255) p_desc
RPE NUMBER 0
WEIGHT NUMBER 0
TRIP_FREQUENCY VARCHAR2(20) N/A
QUANTITY NUMBER p_qty if provided, else 1.
LOADING_TIME NUMBER 0


FC Web Service, for CTMS->FC

This web service is hosted by fleetcheck and will be accessible through the a URL similar to the following: 

   https://api.fleetcheck.co.uk/api/obs/v1/

The FleetCheck OBS API is a REST API using JSON posts and responses. All HTTP response codes are standards and error messages will be returned in the JSON Body of the response.

Parameters will be provided through post data only and are in the following groups:

  • Authentication - common parameters for authentication to use the web service.
  • Action-specific - specific parameters for that action.

For example, to assign vehicle reg "KU60XUD" to carrier "FLEET" for organisation "EUPPCF": 

    curl --location --request POST 'https://api.fleetcheck.co.uk/api/obs/v1/UpdateVehicleCategory.ashx'
    --data-raw '{
      "FleetKey":"EUPPCF",
      "AccessToken":"00000000-0000-0000-0000-000000000000",
      "VehicleRegistration":"KU60XUD",
      "CategoryName":"FLEET"
    }'


Authentication parameters consist of:

  • AccessToken - These tokens are only generated by FleetCheck and will be provided when the service is live.
  • FleetKey - the fleet being updated.


This web service should support the following methods:

  • Type - to add or update Types (vehicle and trailer types)
  • Category - to add or update Categories (home fleet carriers)
  • Driver Category Assignment - to update category assignment.
  • Vehicle Category Assignment - to update category assignment.
  • Trailer Category Assignment - to update category assignment.


System Parameters

System parameters are required to control access to the FleetCheck interface.

  • FC_URL - the base URL for the FleetCheck system.
  • FC_ACCESS_TOKEN - the FleetCheck Access Token, provided by FleetCheck.
  • FC_FLEET_KEY - the FleetCheck fleet being updated by C-TMS.
  • FC_TIMEOUT - the amount of time to wait when trying to update FleetCheck.


General Notes

All code to send data to FleetCheck should be in package DP_FLEETCHECK.

Any triggers that must update FleetCheck should call the appropriate procedure within DP_FLEETCHECK.

All triggers should be named appropriately to the table following system conventions.

For example: 

TRG_RES_TRAILER_TYPE_BUI

All FleetCheck code should be clearly marked in these triggers (as they may already exist and the code will be added to them).


General Package Procedure Description

Each sending process in DP_FLEETCHECK identified below will follow a similar process.

The procedures will receive several parameters, predominantly driven by the data to send to FleetCheck. One is common:

  • p_action - (A)dd, (U)pdate or (D)elete.

This will be determined by whether we are adding, updating or deleting data.


The procedures will call the FleetCheck web service method required to update the data being changed in C-TMS.

The procedures will check the FC_URL parameter - this will form the base of the web service call.

This will be appended with the specific web service method for that data type. This is specific to each procedure and will be hard-coded within the procedure. For example "UpdateExternalType.ashx".


The connection will include the postdata required for each parameter that that call requires. Again, this is predominantly driven by the data to send to FleetCheck. The following are common:

  • AccessToken - From FC_ACCESS_TOKEN.
  • FleetKey - from FC_ACCESS_FLEET.

The action for the web service call will be determined by the parameter p_action:

  • A - POST
  • U - PUT
  • D - DELETE


The procedure will then execute the call and wait for a response - this will post the data directly to the FleetCheck database.

The FleetCheck process will return a status. This should be audited so that it is visible in the existing EDI Log screen.

If this is in the success range (200), this should be audited so that it is visible in the existing EDI Log screen as a successful send.

If this is in the error range (400), this should be audited so that it is visible in the existing EDI Log screen as an error. Any data included in the error returned should be kept as part of the audit.


Note Note: It may be that, when adding a record into CTMS and therefore triggering the add of the record in FleetCheck, that this may already exist. In this case, the process will log the failure, if a failure code is returned - it will not then attempt to call the web service method again to update the existing record. It is expected that, if this were required, then the FleetCheck web services should support that automatically, as the CALIDUS web services will.


Audit Logging

Actions taken when updating data will be audited in the system through this user account.

All package code will audit to ADM_EDI_AUDIT, for success and failure.

Field Comment
STMT Generated
PROG_NAME Package and procedure, dot delimited e.g. DP_FLEETCHECK.UPDATE_EXTERNAL_TYPE
ORI_USER As normal
USER_SESSION As normal
ERR_TYPE 'ERROR' if an error, 'INFO' otherwise. 'AUDIT' may be used for debugging statements, but should be limited.
DATE_CREATED System date and time
ERR_MESSAGE The generated error message for an error plus an indication of the data e.g. "Error updating trailer type XXX: YYYY", otherwise a success message indicating the action taken, identifying the data e.g. "Trailer type XXX updated".
SCHED_NAME N/A
CUSTOMER_ID N/A
LOCATION_ID N/A


External Type

To add, update or delete FleetCheck External Types (trailer types).

Whenever trailer types are added to C-TMS, edited or deleted (i.e. in a database trigger), the system will call DP_FLEETCHECK.UPDATE_EXTERNAL_TYPE, passing in parameters of:

  • p_action - (A)dd, (U)pdate or (D)elete.
  • p_id - the trailer type (RES_TRAILER_TYPE.TRAILER_TYPE).
  • P_desc - the trailer type description.

The system will do this by adding a FleetCheck trigger to the table RES_TRAILER_TYPE.

DP_FLEETCHECK.UPDATE_EXTERNAL_TYPE will call the FleetCheck web service method to update External Types, method: "UpdateExternalType.ashx".

Parameters:

  • Authentication parameters.
  • ExternalTypeId - p_id
  • ExternalTypeDescription - p_desc


Category

To add, update or delete FleetCheck Categories (home fleet carriers)

Whenever carriers are added to C-TMS, edited or deleted (i.e. in a database trigger), the system will call DP_FLEETCHECK.UPDATE_CATEGORY, passing in parameters of:

  • p_action - (A)dd, (U)pdate or (D)elete.
  • p_id - the carrier ID (RES_CARRIER.CARRIER_ID).
  • p_name - the carrier name (RES_CARRIER.CARRIER_NAME).

The system will do this by adding a FleetCheck trigger to table RES_CARRIER.

DP_FLEETCHECK.UPDATE_CATEGORY will call the FleetCheck web service method to update Categories, method: "UpdateCategory.ashx".

Parameters:

  • Authentication parameters.
  • CategoryName - p_name
  • CategoryId - p_id


Driver Carrier Assignment

To update driver carrier assignment.

Whenever drivers are assigned to carriers in C-TMS, edited or deleted (i.e. in a database trigger), the system will check and attempt to update FleetCheck.

The system will do this by adding a FleetCheck trigger to table RES_PERSON_CARRIER.

When a driver carrier record is created or INACTIVE set to "N", the process will call DP_FLEETCHECK.UPDATE_DRIVER_CATEGORY, passing in parameters of:

  • p_action - (A)dd, (U)pdate or (D)elete.
  • p_id - the carrier ID (RES_PERSON_CARRIER.CARRIER_ID).
  • p_driver - the driver ID (RES_PERSON_CARRIER.ID).
  • p_user - the user making the amendment.

The procedure DP_FLEETCHECK.UPDATE_DRIVER_CATEGORY will check the user (p_user) making the amendment.

If this is not the default FLEETCHECK user, the process will retrieve the carrier name CARRIER_NAME using the carrier ID provided (p_id) from RES_CARRIER.

Then the procedure will call the FleetCheck web service method to update Driver Categories, method: "UpdateDriverCategory.ashx".

Parameters:

  • Authentication parameters.
  • DriverId - p_driver
  • CategoryName - the retrieved carrier name from RES_CARRIER.CARRIER_NAME.

Furthermore, all other entries for that driver against other carriers will be set to INACTIVE = "Y". The process will update all of these records at the end of the process.


Vehicle Carrier Assignment

To update vehicle carrier assignment.

Whenever tractors are assigned to carriers in C-TMS, edited or deleted (i.e. in a database trigger), the system will check and attempt to update FleetCheck.

The system will do this by adding a FleetCheck trigger to table RES_TRACTOR_CARRIER.

When a tractor carrier record is created or INACTIVE set to "N", the process will call DP_FLEETCHECK.UPDATE_TRACTOR_CATEGORY, passing in parameters of:

  • p_action - (A)dd, (U)pdate or (D)elete.
  • p_id - the carrier ID (RES_TRACTOR_CARRIER.CARRIER_ID).
  • p_vehicle_id - the vehicle registration (RES_TRACTOR_CARRIER.TRACTOR_ID).
  • p_user - the user making the amendment.

The procedure DP_FLEETCHECK.UPDATE_TRACTOR_CATEGORY will check the user (p_user) making the amendment.

If this is not the default FLEETCHECK user, the process will retrieve the carrier name CARRIER_NAME using the carrier ID provided (p_id) from RES_CARRIER.

Then the procedure will call the FleetCheck web service method to update Vehicle Categories, method: "UpdateVehicleCategory.ashx".

Parameters:

  • Authentication parameters.
  • VehicleRegistration - p_vehicle_id
  • CategoryName - the retrieved carrier name from RES_CARRIER.CARRIER_NAME.

Furthermore, all other entries for that tractor against other carriers will be set to INACTIVE = "Y". The process will update all of these records at the end of the process.


Trailer Carrier Assignment

To update trailer carrier assignment.


Whenever trailers are assigned to carriers in C-TMS, edited or deleted (i.e. in a database trigger), the system will check and attempt to update FleetCheck.

The system will do this by adding a FleetCheck trigger to table RES_TRAILER_CARRIER_GROUP.

When a tractor carrier record is created or INACTIVE set to "N", the process will call DP_FLEETCHECK.UPDATE_TRAILER_CATEGORY, passing in parameters of:

  • p_action - (A)dd, (U)pdate or (D)elete.
  • p_id - the carrier group ID (RES_TRAILER_CARRIER_GROUP.NAME).
  • p_vehicle_id - the trailer ID (RES_TRAILER_CARRIER_GROUP.TRAILER_ID).
  • p_user - the user making the amendment.

The procedure DP_FLEETCHECK.UPDATE_TRAILER_CATEGORY will check the user (p_user) making the amendment.

If this is not the default FLEETCHECK user, the process will retrieve the carrier name CARRIER_NAME of the first carrier found in this carrier group using the carrier group ID provided (p_id) from RES_CARRIER.

Then the procedure will call the FleetCheck web service method to update Vehicle Categories, method: "UpdateVehicleCategory.ashx".

Parameters:

  • Authentication parameters.
  • VehicleRegistration - p_vehicle_id
  • CategoryName - the retrieved carrier name from RES_CARRIER.CARRIER_NAME.

Furthermore, all other entries for that trailer against other carrier groups will be set to INACTIVE = "Y". The process will update all of these records at the end of the process.

APPENDIX A: QUOTE & DOCUMENT HISTORY

Cost Details
Activity Estimate
No. of Days		 No. of Days Rate per Day (£) Cost (£ Exc. VAT)
Requirements 0.00 0.00 0 £0.00
Change Request Evaluation 0.00 0.00 0 £0.00
Functional Specification 3.00 3.00 0 £0.00
Technical Specification 0.00 0.00 0 £0.00
Development 13.25 13.25 0 £0.00
Testing and Release 3.00 3.00 0 £0.00
Implementation 2.00 2.00 0 £0.00
Project Management 2.25 2.25 0 £0.00
 
TOTAL 23.50 23.50   £0.00
Estimate excludes training, release to live and go live support.

References

Ref NoDocument Title & IDVersionDate
1REQ 370536 FleetCheck Interface0.306/05/2020


Glossary

Term or Acronym Meaning
Ad Hoc Collection Ad Hoc Collections are collections at a consignee or other point, where the actual items to be collected have not been defined, allowing for a free-form scanning of items.
AI In barcode terms, an Application Identifier; some pre-defined characters in a barcode that define the data content rather than the format.
Asset A traceable DU; the item that is tracked during delivery and collection. This Asset has a type (e.g. Cage, Tet, etc).
Audit Log A log of events that have happened in the C-TMS system. It could include information, error, debug or audit messages. Users are able to search for messages of a certain type, on a certain day and from a certain area of the system.
Backloads Orders that are placed on a pre-existing trip at the end of the trip before returning to the depot. They may be for customers other than the customer that is paying for the full trip and may result in a rebate to the customer, and a charge to the backload order’s customer.
Booking A quantity of a single Product Type on a single DU Type to be delivered from one location to another on particular date but not at a particular time. These records are usually created by the Auto Summary process. These records are displayed in the main view on the Bookings form.
Carrier The carrier completing the trip. Can comprise any carrier configured in the system, but normally Home Fleet (usually a carrier per depot), 3rd-party carriers, supplier-/customer-own transport, own collection, etc.
Case A Case of individual packets of a product e.g. a case of Cornflake packets.
Consolidating Centre A depot that takes delivery of goods from several origins and consolidates them for trunking to outbases (q.v.) or final delivery to destinations. See also Consolidation.
Consolidation In execution terms, this is the act of taking several jobs and combining them into a single execution job. This can be by several criteria but is broadly defined as: Same Location consolidation, where the delivery/collection points are identical; Linked Location, where the deliver/collection points have been configured to be seen as the same point within C-TMS and; Manual (Ad Hoc) Consolidation, where the driver decides that two jobs should be delivered/collected at the same time.
Containerisation The action of taking items and placing them inside another item for tracking purposes. See also Asset.
Cost Centre A part of an organization to which costs may be charged for accounting purposes. For C-TMS, this is used for accounting purposes, and also to generally configure the system.
C-Portal CALIDUS Portal, Aptean's web-enabled external access system to the Calidus systems. Also, any electronic internet-based system designed to access functionality for a particular purpose (for example, customer enquiries, supplier activity, track and trace, etc.)
Cross-Dock Also a specific location at which product is exchanged.
C-ePOD; EPOD, APOD Electronic Proof of Delivery. The Aptean EPOD system is CALIDUS ePOD or Aptean POD.
C-TMS CALIDUS TMS, Aptean's Transport Management System.
CSB This refers to Carrier Self Billing, the process that C-TMS uses to produce and send invoices to carriers.
Customer In 3PL terms, the customer on behalf of which the transport is being operated.
DDL Drop-down list - a series of pre-designated answers to a particular question on a device, rather than requiring the user to key the answer in in full.
Debrief Comprises 3 parts: Trip debrief, where general trip notes and vehicle information is captured; Stop debrief, where actual arrival and departure times against a trip are entered; Order debrief, where actual product and item quantities are entered; Driver/Trip debrief, where additional information is captured from the driver relating to the trip.
Delivery Types This defines the category of the order, and is intrinsically linked to revenue and cost tariffs.
Demurrage; Detention Any time spent loading, unloading or waiting that is outside contractual obligation in execution of a trip. This usually incurs additional charges.
Depot Any location that schedules and controls transport.
Despatch In transport terms, the process of loading and despatching items out of a depot. In this implementation, the process of loading and despatching is predominantly controlled by C-MCS (q.v.). See also Loading.
DMS Document Management Systems: Systems than manage the storage and viewing of (predominantly) scanned documents. Usually these systems also include some automation and indexing routines.
DOT Delivery On Time - see OTIF.
Driver Comprising drivers and crew assigned to a trip.
Drivers Day A schedule of work that a driver would undertake in a day including any rest periods and breaks.
Drop A stop on a trip.
DU Distribution/Despatch/Deliverable Unit - box, tray, cage, tet, etc.; Also Asset, Asset Type.
EDI Electronic Data Interchange - a mechanism by which 2 systems can communicate normally without user intervention.
ERP Enterprise Resource Planning
Fixed Route Template A template in C-TMS that provides a series of timed slots into which orders will fit. This can be used to create fixed routes (q.v.) and also as a template for cross-docking and grouping similar orders together.
Fixed Route In transport terms, a fixed route is a trip comprised of a series of fixed stops that are typically always visited. A C-TMS fixed route template (q.v.) can be used to create these.
Fixed Schedule An order that occurs at a fixed time. Differing from the above, the order will be created in the schedule; Also Milk Run.
Fuel Surcharge An additional charge that may be applied to a Transport charge to reflect the increasing price of fuel.
Isotrak A third party software package that allows users to be informed of the whereabouts of their vehicles using GPS technology. Interfaces with C-TMS in order to provide ‘actuals’ information for trips (i.e. the time a trip arrived at a stop and the amount of pallets that were delivered).
Item A single item for delivery/collection.
Load C-TMS: A trip that encompasses just a vehicle-full of items, or one journey out and back to a depot.
Loading In transport terms, the process of loading and despatching items out of a depot. In this implementation, the process of loading and despatching is predominantly controlled by C-MCS (q.v.). See also Despatch.
Location In C-TMS terms, a trip comprises visits or drops to many locations. A location can be of many different types.
Location Types Usually one of: Depot, Customer, Delivery/Collection Location, Store, etc.
MCS Mobile Control System
OBD On-Board Diagnostics - an automotive term referring to a vehicle's self-diagnostic and reporting capabilities. Also CANbus.
OMS Ref A unique transport movement ID, referring to a single transport movement request.
OPS13 Vehicle Checks; Defect Reporting
Optimisation Route Building and Optimisation
Order Equiv: OMS Ref; a transport movement.
Order Line An order can be made up of different order lines (i.e. an order from one location to another can contain many lines such as 20 ambient pallets and 20 chilled pallets)
Order Status The lifecycle of an order, usually UNSCHEDULED->SCHED-COLL->SCHEDULED->DELIVERED/FAILED/CANCELLED.
OTIF On Time In Full - Metrics to measure successful collection or delivery.
Outbase A depot whose purpose is to deliver to final delivery destination within a geographically-restricted subsection of the whole catchment area; also ROC, RDC.
Payment Monies paid by a cost centre to a third party such as a carrier.
Plan A term used to describe the result from scheduling Orders onto Trips. The first set of Trips may be referred to as ‘Plan A’, with a subsequent, more accurate plan later in the day being referred to as ‘Plan B’.
Post Schedule The period after Orders have been scheduled in the Scheduling Program and then returned to C-TMS. Any subsequent manipulation of these Orders would be Post Schedule manipulation.
Pre Schedule The period before Orders have been scheduled in the Scheduling Program and then returned to C-TMS. Any manipulation of these Orders would be Pre Schedule manipulation.
Product Item Another term for a case or SKU
Product Quantity A quantity of a single Product Item or SKU to be delivered from one location to another on particular date but not at a particular time. These records are created by the inbound Bookings interface process. These records are displayed in the View Detail screen on the Bookings form.
Product Summary Another term for Booking
Product Type The category that a Product Item, Case or SKU falls in to, usually associated with temperature e.g. FROZEN, PERISHABLE, AMBIENT
Reason Codes Of many types: Adjustment, Non-conformance, Order.
Recalculate Distance and Times A C-TMS function that is applied to a trip. The function checks the properties of the trip to ensure that it meets the defined rules for a trip in respect of drive times and driver’s breaks.
Receipt In transport terms, the process of receiving and uploading items into a depot. In this implementation, the process of receipt and unloading is predominantly controlled by C-MCS (q.v.). See also Unloading.
Region Geographical Region. Also, Postal Region. Regions are allocated to Depots and are used to determine ownership of a particular Order.
Resources Drivers, Crew, Tractors, Vehicles, Trailers
Revenue Monies received by a cost centre from a third party such as a customer.
Route A route is a fixed route that is repeated. A Trip is a unique trip, which may be created from a route.
ROC Regional Operating Centre; a depot whose purpose is to deliver to final delivery destination within a geographically-restricted subsection of the whole catchment area; also Outbase.
RDC Regional Distribution Centre.
RPE Regular Pallet Equivalent - This is used to estimate volume and therefore capacity of vehicles within C-TMS.
Schedule A day's plan, usually consisting of 24 hours, not necessarily from midnight to midnight.
Service Levels; Service Types Typically used to determine additional services for an order, or a quicker transport service. This defines the order windows i.e. the collection and delivery windows and offsets relating to the service level, through schedule rules.
Shunt A trunk (q.v.) movement between depots using the trunk network, typically of a much shorter length than a trunk movement.
Sourcing Unit A second entity that can be applied to a Lane, and all charges relating to that Lane will then be applied to the Sourcing Unit and not the Customer.
Stop Also Trip Stop. A stop on a trip. In this solution, Drop is the pre-assigned fixed route drop number, whereas Stop is the generated CTMS stop ID.
Surcharges Any changes applied to an invoice at invoice stage, rather than generated from the order or trip itself. Examples are: Fuel Surcharge/Rebate, Demurrage.
Tariffs Rate Cards, forming the basis of generating trip/carrier costs and order revenue.
TI Transport Instruction – another term for an Order.
TLM Transport Logistics Manager
Tractor The driver cab, pulling the trailer.
Trailer The trailer carrying the goods. Can be several types.
Transport The transport management office.
Trip C-TMS: A selection of work to be completed, specifically a workload that lasts for an entire shift for a driver.
Trip Manipulation The manipulation of Scheduled Trips, whether it be to add a Carrier or to completely recalculate times on the Trip.
Trip Status The lifecycle of a trip
Trunk A route between depots, transporting goods usually to be delivered from the destination depot, but any transfer of goods from the original receiving or originating depot in the network to the final delivery depot (the out-base).
TTM CALIDUS TTM; Track and Trace Module; Aptean's application dedicated to tracking and tracing order events with inputs from several external systems.
Unloading The process of receiving and uploading items into a depot. In this implementation, the process of receipt and unloading is predominantly controlled by C-MCS (q.v.). See also Receiving.
WCS Warehouse Control System
WMS Warehouse Management System


Authorised By


Phil Harding
OBS Project Manager
_____________________________
Retrieved from ‘https://calidusassist.adcservices.apteancloud.com/calidus-assist/OBS/index.php?title=FS_370536_FleetCheck_Interface&oldid=8852’