Versioning

The examples use OData version "3.0" and an API version of "34.0", the most current versions at the time of writing.

Authentication

In this example we use Basic Authentication. The username and password should be combined like username:password, for example test@test.com:test123. This string should be converted to bytes (using UTF8-encoding) and converted back to string using Base64, and preceded by the term "Basic ". When applied to the example, it should look like "Basic dGVzdEB0ZXN0LmNvbTp0ZXN0MTIz". In every request to CCP, the header "Authorization" should be present having this value.

Prerequisites

• Knowledge of the OData protocol and basic knowledge of entities in CCP and their relation. There is a lot of documentation about this subject. See other pages on the Docs site
• The Transporter user account, used for assigning, has to be a SubTransporter of the planning Transporter. Please contact your Transporter for access and the user account. If needed, the Transporter can contact Euphoria for additional help with this.

Data Preparation

For an executing Transporter to access the data needed to assign Vehicles and Drivers, Vehicles and Drivers must be prepared by the planning Transporter. When we look at the metadata of the Vehicle and the Driver we see a field called AssignedTransporterId and the linked Navigation Property AssignedTransporter. The planning Transporter must assign this field with your TransporterId. Only then you have access from your account to your own Vehicles and Drivers. If the planning Transporter uses Cabman Centrale software this functionality is built-in. If they don't know how to assign this data they should contact Euphoria. If they use different software, ask the Transporter if this functionality is supported from their software.

Retrieving Vehicles and Drivers

Without Vehicles and Drivers you cannot assign the Trips. In the previous step the planning Transporter prepared the data so retrieving Vehicles and Drivers should be pretty straightforward. It's recommended that you request the Vehicles and Drivers only once en keep them in-memory in your application for assignment. Also sort them in-memory. You simply want to retrieve all Vehicles and all Drivers that are assigned to you. Perform the following GET requests.

/VehiclesSummary?$select=VehicleId, LicensePlate, VehicleNr, VehicleType, Make, Model

/Drivers?$select=DriverId, FirstName, LastName, NamePrefix

Retrieving Trips for Assignment

When the prerequisites are met and the data is prepared by the planning Transporter you can request your first batch of Trips for assignement. Retrieving Trips is nothing more than a GET request to the uri:

/Trips

The problem with this approach is that it returns everything starting with the very first Trip assigned to your SubTransporter. We need to filter the data that we're requesting. The CCP platform does some prefiltering on the requested data to only return data you're allowed to see. On top of that we need to provide some extra filters like a daterange and possibly filters to only return Trips without a Vehicle and/or Driver. We also need take batch sizes into account. If you make a request to CCP, and the resultset has thousands of records, they will not be returned in one response. Instead they're returned in fixed-size batches.

If we want to filter on a daterange there are more entities needed than just Trip. That's because the Trip entity is a container of sorts for one or more Movements. Each pickup and dropoff moment for a Traveler is a Movement. A simple Trip from A to B has one Movement but more complex combinations are possible that result in multiple Movements. For most cases we are just interested in the first and last movement. For convenience we have a special entityset called TripsSummary which contains the most used fields of Trip and Movement en much more to quickly and simply query for Trips without complex parameters like $expand.

Execute the following request using GET to retrieve Trips of a single day with a select set of fields needed for assignment. Expand the $select parameter with additional fields if needed.

/TripsSummary?$filter=PlannedStartingTime ge datetime'2019-01-25T00:00:00.000' and PlannedStartingTime le datetime'2019-01-25T23:59:59.999'&$select=PlannedStartingTime, PlannedEndingTime, TripId, VehicleId, DriverId, FirstAddress, LastAddress, CalcTravelerCount, ContractorName

The server responds with a result 200 (OK) and returns the following payload. In this tutorial we use the JSON wire-format. Include an Accept header in your request with the value of application/json. Without this header the result is returned in the Atom XML format.

	
	{
		"odata.metadata": "http://www.cabmanonline.nl/CCPService/DataServiceCCP.svc/$metadata#TripsSummary&$select=PlannedStartingTime,PlannedEndingTime,TripId,VehicleId,DriverId,%20FirstAddress,%20LastAddress,CalcTravelerCount,%20ContractorName",
		"value": [{
			"TripId": 1432,
			"PlannedStartingTime": "2019-01-25T14:40:28",
			"PlannedEndingTime": "2019-01-25T14:59:59",
			"CalcTravelerCount": 4,
			"ContractorName": "Euphoria",
			"VehicleId": null,
			"DriverId": null,
			"FirstAddress": {
				"Street": "Valentijnkade",
				"Number": 63,
				"Addition": "",
				"PostalCode": "1095JL",
				"State": "",
				"Town": "AMSTERDAM",
				"CountryId": null,
				"Coordinates": {
					"Latitude": null,
					"Longitude": null,
					"FormatName": null
				}
			},
			"LastAddress": {
				"Street": "Dijkwater",
				"Number": null,
				"Addition": "",
				"PostalCode": "1025CV",
				"State": "",
				"Town": "AMSTERDAM",
				"CountryId": null,
				"Coordinates": {
					"Latitude": 52.39975,
					"Longitude": 4.94031,
					"FormatName": null
				}
			}
		},
		{
			"TripId": 1433,
			"PlannedStartingTime": "2019-01-25T08:40:00",
			"PlannedEndingTime": "2019-01-25T08:59:10",
			"CalcTravelerCount": 4,
			"ContractorName": "Euphoria",
			"VehicleId": null,
			"DriverId": null,
			"FirstAddress": {
				"Street": "Dijkwater",
				"Number": null,
				"Addition": "",
				"PostalCode": "1025CV",
				"State": "",
				"Town": "AMSTERDAM",
				"CountryId": null,
				"Coordinates": {
					"Latitude": 52.39975,
					"Longitude": 4.94031,
					"FormatName": null
				}
			},
			"LastAddress": {
				"Street": "Valentijnkade",
				"Number": 63,
				"Addition": "",
				"PostalCode": "1095JL",
				"State": "",
				"Town": "AMSTERDAM",
				"CountryId": null,
				"Coordinates": {
					"Latitude": null,
					"Longitude": null,
					"FormatName": null
				}
			}
		}]
	}
	

The resulting Trips data should be used to populate your application. In combination with the previously retrieved Vehicles and Drivers you can create a system to assign Vehicles and Drivers to Trips. The next step is to update it in CCP.

Updating the Trip in CCP

Updating a Trip is pretty straightforward. Just create a payload with the fields you want to update en execute a PATCH request (DON'T use PUT because then you have to include ALL fields of the original Trip. Otherwise the not included fields will be cleared!) to the URI of the Trip. In this example we update the Trip with TripId 123 and we use JSON as the wire-format. You can also use Atom XML. We update the Driver and the Vehicle. We update the VehicleId and clear the DriverId. This is done to clarify that it's also possible to clear Vehicles and Drivers in CCP which were previously assigned.

PATCH /CCPService/DataServiceCCP.svc/Trips(123) HTTP/1.1
Host: www.cabmanonline.nl
Authorization: Basic dGVzdEB0ZXN0LmNvbTp0ZXN0MTIz
Accept: application/json
Content-Type: application/json
DataServiceVersion: 3.0
MaxDataServiceVersion: 3.0
CabmanCloudPlatformVersion: 34.0
MaxCabmanCloudPlatformVersion: 34.0


{
	"DriverId": null,
	"VehicleId": 3
}

When the update succeeds the CCP service returns a result 200. If it returns any other code > 299 something went wrong and the data will not be updated. Update your software accordingly. When there is an error this is returned in the response. See the errorhandling Guide for more information about error messages. Repeat this process with every assignment to a Trip.