Overview:
The Trimble Transportation Cloud (TTC) is used to facilitate the data exchange between a number of Trimble systems.
multi-tenant, cloud-based platform for Trimble Transportation products
one-stop shop for common data across Transportation
allows customers to authorize and manage data with partners through Trust Center
domain-driven platform comprising Core Services and Data Management
Trimble Solutions natively accessing domain-specific data
foundational to modernizing and simplifying access to data, enabling richer solutions and integrations - faster.
TTC uses Azure Service Bus to route a variety of messages to you. DVIR is one type of data that can be consumed from TTC's Azure Service Bus.
Prerequisites
Familiarity with Azure Service Bus will help. More information here on the supported languages for Azure. - General Azure information for a variety of programming languages. Find the library for your preferred language.
The firewall needs to allow traffic on the following ports: 443 (HTTPS), 5671 and 5672 (AMQP) and 9354 (Net Messaging/SBMP). Depending on the library used, other ports may be used.
First, make a request to get a SAS (Shared Access Signature) token.
URL = https://api.trimble-transportation.com/api/v1/identity/oauth/token
Request SAS Token
Response
access_token
sr - URL-encoded URI of the resource being accessed.
sig - URL-encoded HMACSHA256 signature. The hash computation looks similar to the following pseudo code and returns base64 of raw binary output.
se - Token expiry instant. Integer reflecting seconds since the epoch 00:00:00 UTC on 1 January 1970 (UNIX epoch) when the token expires.
skn - Name of the authorization rule
token_type = "Bearer"
expires_in = This option is irrelevant and can be ignored.
For more details - https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-sas
ServiceBusClientBuilder documentation
Troubleshooting Guide for Azure Service Bus
static string getToken()
{
var url = https://api.trimble-transportation.com/api/v1/identity/oauth/token;
var httpRequest = (HttpWebRequest)WebRequest.Create(url);
httpRequest.Method = "POST";
httpRequest.ContentType = "application/x-www-form-urlencoded";
httpRequest.Headers["Authorization"] = "Basic *your base64 ClientID:SecretID*";
var data = "grant_type=client_credentials&audience=sas_token";
using (var streamWriter = new StreamWriter(httpRequest.GetRequestStream()))
{
streamWriter.Write(data);
}
var httpResponse = (HttpWebResponse)httpRequest.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
var result = streamReader.ReadToEnd();
return result;
}
}
Grab the return string, extract out from the sb part of the token :
Namespace: prod-sb-tcx-0-0-02.servicebus.windows.net
Topic: 95f81ff5758c063ce6f8c401
Subscription: 63656de2130b27042cc320cd
And the whole SAS key: SharedAccessSignature sr=sb%3a%2f%2fprod-sb-tcx-0-0-02.servicebus.windows.net%2f95f81ff5758c063ce6f8c401%2fsubscriptions%2f63656de2130b27042cc320cd%2f&sig=shXN0Zrd4XscAH5OdC%2f13ZbpSJzrCEM2e%2fdAqyD%2fqJU%3d&se=1669230696&skn=ListenSharedAccessKey
Use the Token:
static async Task ProcessMessages(string[] s, string x)
{
var sasToken = x;
var credential = new AzureSasCredential(sasToken);
client2 = new ServiceBusClient(
s[2], //This is the Namespace
credential);
// create a processor that we can use to process the messages
// s[3] being the topic s[5] being the subscription
processor = client2.CreateProcessor(s[3].Trim(), s[5].Trim(), new ServiceBusProcessorOptions());
try
{
// add handler to process messages
processor.ProcessMessageAsync += MessageHandler;
// add handler to process any errors
processor.ProcessErrorAsync += ErrorHandler;
// start processing
await processor.StartProcessingAsync();
Console.WriteLine("Wait for a minute and then press any key to end the processing");
Console.ReadKey();
// stop processing
Console.WriteLine("\nStopping the receiver...");
await processor.StopProcessingAsync();
Console.WriteLine("Stopped receiving messages");
}
finally
{
// Calling DisposeAsync on client types is required to ensure that network
// resources and other unmanaged objects are properly cleaned up.
await processor.DisposeAsync();
await client2.DisposeAsync();
}
}
Add a Message handler and an Error handler:
async static Task MessageHandler(ProcessMessageEventArgs args)
{
string body = args.Message.Body.ToString();
Console.WriteLine($"Received: {body} from subscription.");
// complete the message. messages is deleted from the subscription.
await args.CompleteMessageAsync(args.Message);
}
// handle any errors when receiving messages
static Task ErrorHandler(ProcessErrorEventArgs args)
{
Console.WriteLine(args.Exception.ToString());
return Task.CompletedTask;
}
Sending Events to TTC
TTC uses an API called Event Receiver to allow client applications to send any events to destination systems through TTC. Read here for more information about Event Receiver.
https://sites.google.com/trimble.com/tcx/event-registry/cloud-event
A separate key will be provided to you. (The same key cannot be used for both receiving events from Azure Service Bus and sending events using Event Receiver.) TTC uses its own token for Event Receiver.
TTC Documentation - https://developers.dev.trimble-transportation.com/Core/Event%20Receiver%20API#tag/AuthenticationService
Make a request to the Authentication service - Retrieve Access Tokens
grant_type - "client_credentials"
Response will contain base64 encoded access token, token_type and expires_in
{
"access_token": "eyJraWQiOiIyMjY5YzYzZi1lNTUyLTR1NjMtOGEzNy0xOWNjMzAx",
"token_type": "Bearer",
"expires_in": 3600
}
Develop some mechanism to detect that the token has expired and make a request to get a new token. If a new request is submitted before the current token has expired, the same token will be returned again.
See the DVIR vehicle-inspection.repaired documentation for more details.
Coming Soon