Driver Utility

Driver Utility

At the end of this tutorial, you will have a simple Windows forms application that lets you list units and drivers that are associated with your Fleet account.

This topic contains the following sections:

Creating the project
Building the form
Adding the web service
Connecting to the API
Retrieving drivers and units
Showing driver information
Deleting drivers
Creating drivers
Next Project

Creating the project

Open Visual Studio and create a new C# or VB.NET Windows Forms application. Name the project 'DriverUtility'.

Building the form

Open Designer View and modify the form to match the screenshot below. The textboxes are named textBoxFirstname and textBoxLastname. The buttons are named buttonCreate, buttonRefresh and buttonDelete. The listboxes are named as shown in the screenshot.

Adding the web service

In Visual Studio, ensure that your project has a reference to the Fleet Web Service API:

In Solution Explorer, right-click your project and select Add Service Reference... (.NET 2: then click Advanced (at lower left), and click Add Web Reference).
For the Address (.NET 2: API URL), enter https://<customer>.api.telogis.com/V2/<customer>/wsdl, where <customer> is your account name.
Click Go.
Change the Namespace (.NET 2: Web reference name) to Fleet, then click OK.

Connecting to the API

Begin by adding the following members to the Form1 class. These will be used to hold a local copy of your Fleet drivers and units. To access the Fleet Web Service, use the LegacyTelogisServiceClient (.NET 4) or the LegacyTelogisService (.NET 2) object.

.NET 4

Copy

Fleet.LegacyTelogisServiceClient service;
Fleet.AuthenticationHeader header;
Fleet.Driver[] drivers;
Fleet.Unit[] units;

Dim myService As Fleet.LegacyTelogisServiceClient
Dim header As Fleet.AuthenticationHeader
Dim drivers() As Fleet.Driver
Dim units() As Fleet.Unit

Add a load event to your form. Modify the load event to match the code snippet below.

Note
Some proxy servers can raise an exception. To work around this, set System.Net.ServicePointManager.Expect100Continue to false. The login method takes a customer name, username, and password and returns an authentication token. This authentication token must be stored in the AuthenticationHeader. The Authentication header, in turn, is passed as an argument to API calls (.NET 4) or is assigned to the LegacyTelogisService object.

Note

Some proxy servers can raise an exception. To work around this, set System.Net.ServicePointManager.Expect100Continue to false.
The login method takes a customer name, username, and password and returns an authentication token. This authentication token must be stored in the AuthenticationHeader. The Authentication header, in turn, is passed as an argument to API calls (.NET 4) or is assigned to the LegacyTelogisService object.

.NET 4

Copy

// When the form loads we configure the Fleet Web Service and login
// to the web service
private void Form1_Load(object sender, EventArgs e) {

SetButtonsEnabled(false);

// avoid HTTP417 errors caused by some proxies
System.Net.ServicePointManager.Expect100Continue = false;

// Create a TelogisServiceClient for logging in
Fleet.TelogisServiceClient tsclient = new Fleet.TelogisServiceClient();

// Log in and obtain an authentication token
string authToken=tsclient.Login(String.Format("{0}:{1}", customer, user), pword);

// Now create the LegacyTelogisServiceClient for accessing the API
service = new Fleet.LegacyTelogisServiceClient();
header = new Fleet.AuthenticationHeader();
header.SessionID = authToken;

RefreshContents();
SetButtonsEnabled(true);

}

'When the form loads we configure the Fleet Web Service and login
'to the web service
Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load

SetButtonsEnabled(False)

'avoid HTTP417 errors caused by some proxies
System.Net.ServicePointManager.Expect100Continue = False

'Create a TelogisServiceClient for logging in
Dim tsclient As Fleet.TelogisServiceClient = New Fleet.TelogisServiceClient()

'Log in and obtain an authentication token
Dim authToken As String = tsclient.Login(String.Format("{0}:{1}", customer, user), pword)

'Now create the legacyTelogisServiceClient for accessing the API
myService = New Fleet.LegacyTelogisServiceClient()
header = myService.AuthenticationHeader()
header.SessionID = authToken

RefreshContents()
SetButtonsEnabled(True)
End Sub

The SetButtonsEnabled method is listed below and simply enables or disables the buttons on the form. This prevents interleaving of commands which would cause an exception.

Copy

// Enable/disable the Create/Delete/Refresh buttons,
// this prevents interleaving of commands
private void SetButtonsEnabled(bool enabled) {
buttonCreate.Enabled = buttonDelete.Enabled    = buttonRefresh.Enabled = enabled;
}

'Enable/disable the Create/Delete/Refresh buttons,
'this prevents interleaving of commands
Private Sub SetButtonsEnabled(ByVal isEnabled As Boolean)
buttonCreate.Enabled _
= buttonDelete.Enabled _
= buttonRefresh.Enabled = isEnabled
End Sub

Retrieving drivers and units

The following method uses the API to retrieve and store an array of units (vehicles) and drivers. Units are loaded into listBoxUnits and drivers are loaded into listBoxDrivers.

.NET 4

Copy

// Refresh the Drivers/Units listboxes by retrieving
// data from the Fleet service
// 
private void RefreshContents() {
SetButtonsEnabled(false);

listBoxDrivers.Items.Clear();
listBoxProperties.Items.Clear();
listBoxUnits.Items.Clear();

// get drivers
drivers = service.ListDrivers(header, 0, 128);
foreach (Fleet.Driver d in drivers) {
String row = d.Name + " [" + d.ID + "]";
listBoxDrivers.Items.Add(row);
}

// get units
units = service.ListUnits(header, 0, 128);
foreach (Fleet.Unit u in units) {
String row = u.Name + " [" + u.ID + "]";
listBoxUnits.Items.Add(row);
}

SetButtonsEnabled(true);
}

'Refresh the Drivers/Units listboxes by retrieving
'data from the Fleet service
Private Sub RefreshContents()
SetButtonsEnabled(False)

listBoxDrivers.Items.Clear()
listBoxProperties.Items.Clear()
listBoxUnits.Items.Clear()

'get drivers
drivers = myService.ListDrivers(header, 0, 128)
Dim d As Fleet.Driver
For Each d in drivers
Dim row As String = d.Name + " [" + d.ID.ToString() + "]"
listBoxDrivers.Items.Add(row)
Next d

'get units
units = myService.ListUnits(header, 0, 128)
Dim u As Fleet.Unit
For Each u in units
Dim row As String = u.Name + " [" + u.ID.ToString() + "]"
listBoxUnits.Items.Add(row)
Next u

SetButtonsEnabled(True)
End Sub

Connect this method to the refresh button's click event using the following method:

Copy

// When the refresh button is clicked we refresh the Drivers and Units
private void buttonRefresh_Click(object sender, EventArgs e) {
RefreshContents();
}

'When the refresh button is clicked we refresh the Drivers and Units
Private Sub buttonRefresh_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) _
Handles buttonRefresh.Click

RefreshContents()
End Sub

Showing driver information

In this tutorial, we'll use the FirstName and LastName properties to identify drivers. Both of these properties are recognized by Fleet.

Tip
Most Fleet objects have as a member an array of Property objects, which are key-value pairs. Whenever you search for objects, you can typically filter the results on these properties.

Wire the method below to the driver's listbox SelectedIndexChanged event. This method will load the properties of the selected driver into the bottom-right listbox.

Because the drivers listbox is a simple visual representation of the drivers array, we can use the selected index of the listbox to map straight to the Driver object that we want to get the properties for.

Copy

// Updates the properties shown in the DriverProperties listbox
// when a driver (in the Drivers listbox) is selected

private void listBoxDrivers_SelectedIndexChanged(object sender, EventArgs e) {
listBoxProperties.Items.Clear();
Fleet.Driver d = drivers[listBoxDrivers.SelectedIndex];
foreach (Fleet.Property p in d.Properties) {
String row = p.Name + " = " + p.Value;
listBoxProperties.Items.Add(row);
}
}

'Updates the properties shown in the DriverProperties listbox
'when a driver (in the Drivers listbox) is selected

Private Sub listBoxDrivers_SelectedIndexChanged(ByVal sender As System.Object, ByVal e As System.EventArgs) _
Handles listBoxDrivers.SelectedIndexChanged

listBoxDriverProperties.Items.Clear()
Dim d As Fleet.Driver = drivers(listBoxDrivers.SelectedIndex)
Dim p As Fleet.Property
For Each p in d.Properties
Dim row As String = p.Name + " = " + p.Value.ToString()
listBoxProperties.Items.Add(row)
Next p
End Sub

Deleting drivers

Note
Before you delete a driver (or a sub-user associated with a driver) from Fleet, it is important that six months of ELD reports for the driver or sub-user are downloaded. This includes drivers and sub-users who no longer work for the organization. Once you delete a driver or sub-user, this action cannot be reverted, and reports for that driver or sub-user can no longer be generated.

Wire the method below to the delete button's click event. This method will delete the currently selected driver (from the top- right listbox) from your Fleet user account. Important points to note are:

Because the drivers listbox is an exact visual representation of the drivers array, we can use the selected index of the listbox to map straight to the Driver object that we want to delete.
Driver objects are identified by their ID property. This ID is returned from the Service.CreaterDriver() method and can be accessed through each Driver object's ID property.

.NET 4

Copy

// Deletes the driver currently selected in the Drivers listbox
private void buttonDelete_Click(object sender, EventArgs e) {
if (listBoxDrivers.SelectedIndex != -1) {
service.DeleteDriver(header, drivers[listBoxDrivers.SelectedIndex].ID);
RefreshContents();
}
}

'Deletes the driver currently selected in the Drivers listbox
Private Sub buttonDelete_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles buttonDelete.Click
If listBoxDrivers.SelectedIndex <> -1 Then
myService.DeleteDriver(header, drivers(listBoxDrivers.SelectedIndex).ID)
RefreshContents()
End If
End Sub

Creating drivers

Wire the following method to the create button's click event. This method first checks that a last name and first name has been entered and that a unit has been selected. This method then creates a new driver using the API.

In this tutorial, we'll

force the user to select a unit to associate with the new driver
construct a tag from the driver's first and last names

Note
Each driver should have a unit, a depot, and some means of identification (usually a tag and one or more properties). You can ignore the unit and depot by passing zero.

.NET 4

Copy

// Creates a new driver, and performs simple input validation

private void buttonCreate_Click(object sender, EventArgs e) {
if (listBoxUnits.SelectedIndex != -1
&& textBoxFirstname.Text.Length > 0
&& textBoxLastname.Text.Length > 0) {
Fleet.Property fname = new Fleet.Property();
fname.Name = "FirstName";
fname.Value = textBoxFirstname.Text;

Fleet.Property lname = new Fleet.Property();
lname.Name = "LastName";
lname.Value = textBoxLastname.Text;

String tag = (String)fname.Value + (String)lname.Value;
long unitid = units[listBoxUnits.SelectedIndex].ID;

service.CreateDriver(header, tag, unitid, 0, new Fleet.Property[] { fname, lname });

textBoxFirstname.Text = textBoxLastname.Text = "";

RefreshContents();
} else {
MessageBox.Show("New driver must have two names and a unit");
}
}

'Creates a new driver, and performs simple input validation
Private Sub buttonCreate_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) _
Handles buttonCreate.Click

If listBoxUnits.SelectedIndex <> -1 _
And textBoxFirstname.Text.Length > 0 _
And textBoxLastname.Text.Length > 0) Then
Dim fname As Fleet.Property = New Fleet.Property()
fname.Name = "FirstName"
fname.Value = textBoxFirstname.Text

Dim lname As Fleet.Property = New Fleet.Property()
lname.Name = "LastName"
lname.Value = textBoxLastname.Text

Dim tag As String = fname.Value.ToString() + lname.Value.ToString()
Dim unitid As Long = units(listBoxUnits.SelectedIndex).ID

myService.CreateDriver(header, tag, unitid, 0, New Property() {fname, lname })

textBoxFirstname.Text = textBoxLastname.Text = ""
RefreshContents()
Else
MessageBox.Show("New driver must have two names and a unit")
End If
End Sub

Next Project

That completes the Driver Utility sample project. The next sample project demonstrates how to export markers to Fleet from a CSV file.