HubTran Trimble Integration setup

First available in: TMW Web Products, V.2019.3.2

Requirements:

  1. You must have these Trimble Web Products and modules installed:

    • Licensing
      Licensing API
      For details, see Installing Web Products in the Trimble Web Products help.

    • SystemsLink

      • SystemsLink RESTFUL API

      • SystemsLink External API

      • SystemsLink Core API

        For details, see Installing SystemsLink in the SystemsLink help.

    • WorkCycle

      • WorkCycle Management

      • WorkCycle SystemsLink Objects

      • WorkCycle Service

        For details, see Installation in the WorkCycle help.

  2. You must run the ETSDBMods.sql that comes with the Web Products installation on your TMW Operations database.

  3. Obtain the tokens need for SystemsLink to access HubTran from your HubTran representative.

  4. Integration with HubTran requires you to specify a TMW Operations user ID and password as workflow parameters. For sending data to HubTran, any valid user ID and password is allowed. However, to receive data from HubTran using a webhook, we recommend that you have a specific user profile that represents HubTran. This ID is required for the passing of tokens to SystemsLink endpoints. This allows you to easily identify operations performed by HubTran integration when checking logs. Whether you create a user to represent HubTran or use an existing user, the profile you associate with the integration should be a System Administrator in TMW Operations. The profile should have the Allow user to delete pay checkbox selected.

  5. You are running V.2019.3 of TMW Operations.

Preparing WorkCycle to export Trimble data to HubTran

Before you can export data from TMW Operations to HubTran, you must verify that:

  • The HubTran.dll that you downloaded from ClientCenter is in your WorkCycle/Plugins folder. The .dll adds the WorkCycle Activities needed for HubTran integration. Once the dll is placed in the folder, you must restart your WorkCycle service.

  • The SQL files you downloaded from ClientCenter have been applied to your TMW Operations database. These files are:

    • GetAllCarrierInfoForHubtran_sp.sql

    • GetCarrierInfoByIDForHubtran_sp.sql

    • getExportData_Hubtran.storedprocedure.sql

    • getExportDataByOrder_Hubtran.storedprocedure.sql

If you want, you can log messages to the logout.text file so you can view them. To do this, open the Workflow.exe config file and set the Logtofile property to True. You access the logout.text file in the WorkCycle directory.

Downloading .dll and .sql files

The required .dll and SQL files are available for downloading on ClientCenter. For instructions, see Downloading product updates in the ClientCenter online help.

On the Build Delivery page, after selecting TMWSuite as the Line of Business, select Special Products as the Product. Download these files:

  • HubTran_2019.x .dll file

  • HubTran_2019.x.sql file

Performing the initial data upload

The first time you export data to HubTran you do three different uploads. You create separate WorkCycle Workflows to accomplish each of the uploads.

Exporting all carriers

To export carriers:

  1. Start WorkCycle.

  2. Drag and drop the BulkCreateUpdateCarriers workflow activity from the Activities pane on the right to the Designer pane.

    image1

  3. In the Options pane, set the following options:

    • Batch size
      Number of carrier records to send in each communication

      Trimble recommends 100.

    • HubTran Token
      The customer specific login information provided by HubTran

    • Service URL
      Your HubTran service in SystemsLink

      Default URL is

      http://localhost/TMWSystemsLinkExternal/HubTran/HubTranService.svc

    • TMW SERVER
      Enter the name of the server on which your TMW Operations database resides.

    • TMW DB
      Enter the name of your TMW Operations database.

    • TMW ID
      Enter the User ID used to access your TMW Operations database.

    • TMW PW
      Enter the password linked to the User ID you entered.

  4. Save the workflow.

  5. Go to Test > Run Now On Server.
    WorkCycle executes the workflow and start sending carrier data to HubTran.

You can open and examine the logout.txt file in your WorkCycle directory to check any errors.

Exporting load data

To export loads:

  1. Start WorkCycle.

  2. Drag and drop the CreateUpdateLoad workflow activity from the Activities pane on the right to the Designer pane.

    image2

  3. In the Options pane, set the following options:

    • Days back
      The number of days back which you would want to start sending legheader data. Trimble recommends 60 days.

    • HubTran Token
      The customer specific login information provided by HubTran

    • Leg Header
      Leave this field blank.

      Specifying a legheader number will send only that leg.

    • Service URL
      Your HubTran service in SystemsLink

      Default URL is

      http://localhost/TMWSystemsLinkExternal/HubTran/HubTranService.svc

    • ShipmentsFlag
      Set to 0 (zero) on the initial upload

    • TMW SERVER
      Enter the name of the server on which your TMW Operations database resides.

    • TMW DB
      Enter the name of your TMW Operations database.

    • TMW ID
      Enter the User ID used to access your TMW Operations database.

    • TMW PW
      Enter the password linked to the User ID you entered.

  4. Save the workflow.

  5. Go to Test > Run Now On Server.
    WorkCycle executes the workflow and start sending legheader data to HubTran.

Exporting shipment data

To export shipments:

  1. Start WorkCycle.

  2. Drag and drop the CreateUpdateShipment workflow activity from the Activities pane on the right to the Designer pane.

    image3

  3. In the Options pane, set the following options:

    • Days back
      The number of days back which you would want to start sending shipment data. Trimble recommends 60 days.

    • HubTran Token
      Enter the login information provided to you by HubTran.

    • Order Header Number
      Leave this field blank.

      Specifying an order header number will send only that order.

    • Service URL
      Your HubTran service in SystemsLink

      Default URL is

      http://localhost/TMWSystemsLinkExternal/HubTran/HubTranService.svc

    • TMW SERVER
      Enter the name of the server on which your TMW Operations database resides.

    • TMW DB
      Enter the name of your TMW Operations database.

    • TMW ID
      Enter the User ID used to access your TMW Operations database.

    • TMW PW
      Enter the password linked to the User ID you entered.

  4. Save the workflow.

  5. Go to Test > Run Now On Server.
    WorkCycle executes the workflow and start sending legheader data to HubTran.

Setting up the system to upload updated data

Once the initial upload is complete, you set up the system to send updated data to HubTran. Whenever a change is made to a carrier profile, a legheader, or shipment record, the record is resent to HubTran, replacing previous versions of the record.

  1. Activate the listener workflow that monitors data and sends any changes to HubTran.

    To activate it, set the HubTranIntegration General Info Table setting String1 field to Y.

  2. Download the .xml workflow templates.

    1. Go to the ClientCenter Build Delivery page

    2. After selecting TMWSuite as the Line of Business, select Special Products as the Product.

    3. Download these files:

      • HubTranCarrierUpdates.xml

      • HubTranLoadUpdates.xml

  3. Install them on the internal server in:

    C:\TrimbleProducts\WorkCycle_2019.xx\Plugins

    where xx is the version number.

  4. Start WorkCycle designer.

  5. Go to File > Import.
    The Open window opens.

  6. Locate your template xml files and import them.

Creating the workflow to monitor changes to carrier records

To have changes in carrier records uploaded to HubTran, you must set the options for the CreateUpdateCarrier activity.

  1. Start WorkCycle.

  2. In the Activities pane, select CreateUpdateCarrier and drag it to the Designer pane.

    image4

  3. In the Options pane, set the following options:

    • Carrier ID
      The default entry is Carrier_ID. Do not change the entry.

    • HubTran Token
      The customer specific login information provided by HubTran

    • Service URL
      Your HubTran service in SystemsLink

      Default URL is http://localhost/TMWSystemsLinkExternal/HubTran/HubTranService.svc.

    • TMW SERVER
      Enter the name of the server on which your TMW Operations database resides.

    • TMW DB
      Enter the name of your TMW Operations database.

    • TMW ID
      Enter the User ID used to access your TMW Operations database.

    • TMW PW
      Enter the password linked to the User ID you entered.

  4. Save the workflow.

  5. Go to Options > Manage Workflow Launching.
    The WorkflowLaunching window opens.

    image5

  6. In the Workflow Timer section:

    • Verify the Enabled checkbox is selected.

    • In the Run Every fields, enter the number in the first field and select the increment in the second field.

    • In the Between fields, set the start and end times.

    • In the Days of the Week section, select the checkbox for each day you want the workflow to run.

  7. Click Update to save your entries.

Creating the workflow to upload updated legheader data

To have changes in carrier records uploaded to HubTran, you must set the options for the CreateUpdateLegactivity.

  1. Start WorkCycle.

  2. In the Activities pane, select CreateUpdateCarrier and drag it to the Designer pane.

    image6

  3. In the Options pane, set the following options:

    • Days Back
      The number of days back which you would want to start sending legheader data. Trimble recommends 60 days.

    • HubTran Token
      The customer specific login information provided by HubTran

    • Leg Header
      The default value is 60. Do not change the value.

    • Leg Number
      The field is blank by default. Do not make an entry.

    • Service URL
      Your HubTran service in SystemsLink

      Default URL is

      http://localhost/TMWSystemsLinkExternal/HubTran/HubTranService.svc.

    • Shipments Flag
      Set to 1 to include changed shipment records in updates sent to HubTran.

    • TMW SERVER
      Enter the name of the server on which your TMW Operations database resides.

    • TMW DB
      Enter the name of your TMW Operations database.

    • TMW ID
      Enter the User ID used to access your TMW Operations database.

    • TMW PW
      Enter the password linked to the User ID you entered.

  4. Save the workflow.

  5. Go to Options > Manage Workflow Launching.
    The WorkflowLaunching window opens.

    image7

  6. In the Workflow Timer section:

    • Verify the Enabled checkbox is selected.

    • In the Run Every fields, enter the number in the first field and select the increment in the second field.

    • In the Between fields, set the start and end times.

    • In the Days of the Week section, select the checkbox for each day you want the workflow to run.

  7. Click Update to save your entries.

Receiving data from HubTran

Once all the required data is sent to HubTran, the following process takes place:

  • When a carrier sends an invoice to HubTran and that invoice matches pay information in TMW Operations, HubTran makes a REST call to a webhook provided by SystemsLink.

  • The webhook allows HubTran integration to provide information in real time, such as releasing pay detail information for a carrier. To facilitate the pushing of information from HubTran to TMW.Suite, we recommend that you create a user profile and ID for HubTran in your TMW.Suite database. This allows HubTran to get a token needed to access the SystemsLink endpoint.

  • The data that HubTran sends is stored in HubTran audit tables in the TMW.Suite database.

    Tables used for Approved pay details:

    • HubTranApproved

    • HubTranApprovedInvoice

    • HubTranApprovedLineItem

    • HubTranApprovedShipments

    • HubTranApprovedEmailMessages

    • HubTranApprovedDocuments

    • HubTranApprovedPages

    Tables used for Exception payloads:

    • HubTranException

    • HubTranExceptionMessages

    • HubTranExceptionEmailMessages

    • HubTranExceptionDocuments

    • HubTranExceptionPages

When the data in HubTran does not match the data in TMW.Suite, you must resolve the conflict manually.

To view information from HubTran, you must log into you HubTran account.

  1. The carrier’s TMW.Suite ID is not used in HubTran.

  2. Load Id in HubTran is the TMW.Suite Order Header number.

  3. Trip statuses that trigger updates are:

    • Planned

    • Started

    • Completed

  4. If you change pay after the trip is completed, the change is sent.

  5. Each time an updated record is uploaded to HubTran, it replaces the previous uploaded version of the record.

  6. HubTran tracks the legheader number and sends back the amounts for the pay details for them. The pyd_number and assign_id for each line item must match.

  7. If you view the carrier’s approved pay for a trip in the Trip Folder’s Profit and Loss tab, the status for the pay details is Released.

  8. You process the pay in Final Settlements. You do not need to do pay review in Trip Settlements.