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.

Authentication for Azure Service Bus

• 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 

Consuming Events from Azure Service Bus

ServiceBusClientBuilder documentation

Troubleshooting Guide for Azure Service Bus 

Sample C# code:

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 : 

sb://prod-sb-tcx-0-0-02.servicebus.windows.net/95f81ff5758c063ce6f8c401/subscriptions/63656de2130b27042cc320cd/

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

Authentication for Event Receiver

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

Request Access Token

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

Using TTC's Event Receiver to Send Data

See the DVIR vehicle-inspection.repaired documentation for more details. 

API Gateway

Coming Soon