Anw: v0.4 - Correction to parameters for driver carrier assignment

2020-05-14T13:17:32Z

v0.4 - Correction to parameters for driver carrier assignment

← Older revision		Revision as of 15:17, 14 May 2020
Line 5:		Line 5:
	{{#vardefine:SystemCode\|CTMS}}		{{#vardefine:SystemCode\|CTMS}}
	{{#vardefine:Doc_Title\|FleetCheck Interface Requirements}}		{{#vardefine:Doc_Title\|FleetCheck Interface Requirements}}
	{{#vardefine:Version\|0.3}}		{{#vardefine:Version\|0.4}}
	{{#vardefine:Date\|~~6th~~ May 2020}}		{{#vardefine:Date\|14th May 2020}}
	{{#vardefine:Reference\|370536}}		{{#vardefine:Reference\|370536}}
	{{#vardefine:Year\|2020}}		{{#vardefine:Year\|2020}}
Line 321:		Line 321:
	* Authentication parameters.		* Authentication parameters.
	* ''DriverId''		* ''DriverId''
	* ''~~AssetId~~''		* ''CategoryName''

Anw: Minor formatting changes.

2020-05-06T13:20:32Z

Minor formatting changes.

← Older revision		Revision as of 15:20, 6 May 2020
Line 9:		Line 9:
	{{#vardefine:Reference\|370536}}		{{#vardefine:Reference\|370536}}
	{{#vardefine:Year\|2020}}		{{#vardefine:Year\|2020}}
			{{#vardefine:Type\|REQ}}
	{{ #vardefine: Figure \| 0 }}{{ #vardefine: Example \| 0 }}		{{ #vardefine: Figure \| 0 }}{{ #vardefine: Example \| 0 }}
	<!--		<!--
	Sample Xref:		Sample Xref:
	{{Xref		{{Xref
	\|\|Type=Figure		\|Type=Figure
	\|\|Num={{ #vardefineecho: Figure\| {{ #expr: {{ #var: Figure}} * 1 }} }}		\|Num={{ #vardefineecho: Figure\| {{ #expr: {{ #var: Figure}} * 1 }} }}
	\|\|Text=Data Upload - Import screen.}}		\|Text=Data Upload - Import screen.}}
	-->		-->
	</div>		</div>
	{{Doc_TitleNew		{{Doc_TitleNew
	\|\|Client={{#var:ClientName}}		\|Client={{#var:ClientName}}
	\|\|System={{#var:System}}		\|System={{#var:System}}
	\|\|Title={{#var:Doc_Title}}		\|Title={{#var:Doc_Title}}
	\|\|Reference=~~REQ~~ {{#var:Reference}}		\|Reference={{#var:Type\|FS}} {{#var:Reference}}
	\|\|Version={{#var:Version}}		\|Version={{#var:Version}}
	\|\|Date={{#var:Date}}		\|Date={{#var:Date}}
	\|\|Year={{#var:Year}}		\|Year={{#var:Year}}
			\|Type={{#var:Type}}
	}}		}}

Anw: Minor correction

2020-05-06T11:39:50Z

Minor correction

← Older revision		Revision as of 13:39, 6 May 2020
Line 22:		Line 22:
	\|\|System={{#var:System}}		\|\|System={{#var:System}}
	\|\|Title={{#var:Doc_Title}}		\|\|Title={{#var:Doc_Title}}
	\|\|Reference=FS {{#var:Reference}}		\|\|Reference=REQ {{#var:Reference}}
	\|\|Version={{#var:Version}}		\|\|Version={{#var:Version}}
	\|\|Date={{#var:Date}}		\|\|Date={{#var:Date}}

Anw: Minor correction

2020-05-06T11:39:20Z

Minor correction

← Older revision		Revision as of 13:39, 6 May 2020
Line 3:		Line 3:
	{{#vardefine:ClientName\|OBS Logistics Ltd}}		{{#vardefine:ClientName\|OBS Logistics Ltd}}
	{{#vardefine:System\|''CALIDUS'' TMS}}		{{#vardefine:System\|''CALIDUS'' TMS}}
	{{#vardefine:SystemCode\|~~CTLTMS~~}}		{{#vardefine:SystemCode\|CTMS}}
	{{#vardefine:Doc_Title\|FleetCheck Interface Requirements}}		{{#vardefine:Doc_Title\|FleetCheck Interface Requirements}}
	{{#vardefine:Version\|0.3}}		{{#vardefine:Version\|0.3}}

Anw: Categorisation of document pages

2020-05-06T11:38:50Z

Categorisation of document pages

← Older revision		Revision as of 13:38, 6 May 2020
Line 400:		Line 400:
	\|Rev1Title=OBS Project Manager		\|Rev1Title=OBS Project Manager
	}}</div>		}}</div>
	[[Category:{{#var:Client}} FS]]		[[Category:{{#var:Client}} REQ]]
	[[Category:{{#var:SystemCode}}]]		[[Category:{{#var:SystemCode}}]]

Anw: v0.3 - After discussion with FleetCheck

2020-05-06T11:38:12Z

v0.3 - After discussion with FleetCheck

New page

<div class="noprint">
{{#vardefine:Client|PROD}}
{{#vardefine:ClientName|OBS Logistics Ltd}}
{{#vardefine:System|''CALIDUS'' TMS}}
{{#vardefine:SystemCode|CTLTMS}}
{{#vardefine:Doc_Title|FleetCheck Interface Requirements}}
{{#vardefine:Version|0.3}}
{{#vardefine:Date|6th May 2020}}
{{#vardefine:Reference|370536}}
{{#vardefine:Year|2020}}
{{ #vardefine: Figure | 0 }}{{ #vardefine: Example | 0 }}

</div>
{{Doc_TitleNew
||Client={{#var:ClientName}}
||System={{#var:System}}
||Title={{#var:Doc_Title}}
||Reference=FS {{#var:Reference}}
||Version={{#var:Version}}
||Date={{#var:Date}}
||Year={{#var:Year}}
}}


<div class="noprint">
= 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}}
* 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:

<pre>
{
"error" : {
"code" : "",
"message" : ""
}
}
</pre>

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:
<pre>
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
</pre>

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

<pre>
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"
}'
</pre>

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}} 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}} 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''

=== Asset Assignment ===

To update asset assignment to a vehicle.

Method: UpdateVehicleAsset

{{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}} This is not required for phase 1, but is included here to show the potential evolution of the interface.

Parameters:
* Authentication parameters.
* ''VehicleRegistration''
* ''DriverId''


{{Doc_AppendixNew
|Appendix=A
|Estimate=N
|Glossary=CTMS
|Ref1= 
|RefV1= 
|RefDate1= 
|REQ=0
|EST=0
|FS=0
|TS=0
|DEV=0
|ST=0
|IMP=0
|PM=0
|Client={{#var:Client}}
|Year={{#var:Year}}
|FSEST=Y
|Rev1=Phil Harding
|Rev1Title=OBS Project Manager
}}</div>
[[Category:{{#var:Client}} FS]]
[[Category:{{#var:SystemCode}}]]

REQ 370536 FleetCheck Interface - Revision history

Anw: v0.4 - Correction to parameters for driver carrier assignment

Anw: Minor formatting changes.

Anw: Minor correction

Anw: Minor correction

Anw: Categorisation of document pages

Anw: v0.3 - After discussion with FleetCheck