FS 370536 FleetCheck Interface

From Calidus HUB
Revision as of 17:17, 6 May 2020 by Anw (talk | contribs) (v0.1 - Initial draft version - incomplete)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)






Aptean Logo.png







OBS Logistics Ltd

FleetCheck Interface

Functional Specification

6th May 2020 - 0.1
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 vehicle types (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.


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

Data

Implementation Advice

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 vehicle 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 - Warning Warning: Required?


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
  • AssetId


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.

Responses

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 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.
  • 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.

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.


System Processing

Table RES_PERSON:

Field Type Notes
ID NUMBER
SURNAME VARCHAR2(50)
FORENAME VARCHAR2(50)
JOB_TITLE VARCHAR2(50)
LOCATION_ID VARCHAR2(12)
CREATED_BY VARCHAR2(40)
CREATED_DATE DATE
UPDATED_BY VARCHAR2(40)
UPDATED_DATE DATE
CONTACT_NO VARCHAR2(50)
INACTIVE Use this for unavailability
AGENCY VARCHAR2(1)
SMARTPHONE_ENABLED VARCHAR2(100)
EPOD_USERNAME VARCHAR2(10)
TOMTOM_ENABLED VARCHAR2(1)
HUB_LOCATION VARCHAR2(12)
START_AT_HUB VARCHAR2(1)
RETURN_TO_HUB VARCHAR2(1)
AGENCY_NAME VARCHAR2(100)


To update driver carrier assignment.

Note 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.


Table RES_PERSON_CARRIER

Field Type Notes
INACTIVE VARCHAR2(1) Warning Warning: Use for availability
PC_ID NUMBER(10)
ID NUMBER Warning Warning: Irrelevant?
CARRIER_ID VARCHAR2(12)
RAG VARCHAR2(1) Warning Warning:  ???


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 vehicle 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.


System Processing

Table RES_TRACTOR

Field Type Notes
TRACTOR_ID VARCHAR2(12)
TRACTOR_TYPE VARCHAR2(12)
DESCRIPTION VARCHAR2(50)
INACTIVE VARCHAR2(1) Use this for availability
LOCATION_ID VARCHAR2(12)
TRACKING_ENABLED VARCHAR2(50)
CONTACT_NO VARCHAR2(50)
MPG NUMBER(6,3)
TRACK_REF VARCHAR2(30)
VIN_NO VARCHAR2(17)
FLEET_ID VARCHAR2(100)
BLUE_LIGHT VARCHAR2(1)
TAIL_LIFT VARCHAR2(1)
TOMTOM_ENABLED VARCHAR2(1)
EPOD_ENABLED VARCHAR2(1)
RAG VARCHAR2(1)

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.


Table RES_TRACTOR_CARRIER

Field Type Notes
ID NUMBER(10)
TRACTOR_ID VARCHAR2(12)
CARRIER_ID VARCHAR2(12)
INACTIVE VARCHAR2(1)


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.


System Processing

Table RES_TRAILER

Field Type Notes
TRAILER_ID VARCHAR2(12)
TRAILER_TYPE VARCHAR2(12)
INACTIVE VARCHAR2(1) Use this for availability
TRACKING_ENABLED VARCHAR2(50)
COST_CENTRE_NAME VARCHAR2(12) Defaulted through authorisation user


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.

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.

Table RES_TRAILER_CARRIER_GROUP

Field Type Notes
ID NUMBER(10) Warning Warning: Irrelevant?
TRAILER_ID VARCHAR2(12)
INACTIVE VARCHAR2(1) Use this for availability?
NAME VARCHAR2(35) Carrier Group, taken from RES_CARRIER.CARRIER_NAME


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.


System Processing

Note Note:

  • Should we allow deletion?
  • Should/Do we have availability flags for equipment?


RES_EQUIPMENT

Field Type Notes
EQUIPMENT_TYPE VARCHAR2(12) Make this a unique identifier instead of a type.
EQUIPMENT_DESCRIPTION VARCHAR2(255)
NUMBER
NUMBER
VARCHAR2(20)
NUMBER
NUMBER


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

Warning Warning: System parameters to control access to 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.

Warning 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.


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, and suffixed with "_FLEETCHECK".

For example: 

TRG_RES_TRAILER_TYPE_FLEETCHECK


Warning Warning: All auditing ?


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_strAction - (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_strAction:

  • 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. Warning Warning: Any data included in the error returned should be kept as part of the audit.


External Type

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:

  • p_strAction - (A)dd, (U)pdate or (D)elete.
  • p_strId - Warning Warning: the vehicle type or trailer type ID.
  • P_strDesc - the vehicle type of trailer type description.

The system will do this by adding a FleetCheck trigger to tables Warning Warning:  ??? and RES_TRAILER_TYPE.

DP_FLEETCHECK.UPDATE_EXTERNAL_TYPE will call the FleetCheck web service method to update External Types, method .

Method: "UpdateExternalType.ashx"

Parameters:

  • Authentication parameters - set from the new system parameters.
  • ExternalTypeId - p_strId
  • ExternalTypeDescription - p_strDesc


Category

To add or update Categories (home fleet carriers)

Method: UpdateCategory

Parameters:

  • Authentication parameters.
  • CategoryName
  • CategoryId - Warning Warning: Required?


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
  • AssetId


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


APPENDIX A: DOCUMENT HISTORY

References

Ref NoDocument Title & IDVersionDate
1REQ 370536 FleetCheck Interface0.306/5/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=8823’