REQ 370536 FleetCheck Interface

From Calidus HUB
Revision as of 15:17, 14 May 2020 by Anw (talk | contribs) (v0.4 - Correction to parameters for driver carrier assignment)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)






Aptean Logo.png







OBS Logistics Ltd

FleetCheck Interface Requirements

Requirements

14th May 2020 - 0.4
Reference: REQ 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

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


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


APPENDIX A: DOCUMENT HISTORY

References

Ref NoDocument Title & IDVersionDate
1   


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=REQ_370536_FleetCheck_Interface&oldid=8832’