This user guide outlines the structure and set-up of 'Base Distances' and 'Base Distance Routes', and their application to Journeys within WSX.
Routes associated to journeys within WSX are based on a combination of a Base Distance and Base Distance Route, with a single Base Distance having one or many Base Distance Routes. This data is applied in WSX to:
Facilitate the assignment of journey routes to journeys,
Calculate truck utilization metrics, etc
Facilitate the assignment of Off-Highway status to journeys
Facilitate the assignment of weight permits to journeys, where trucks can carry greater weights than they would otherwise be able to, to allow for more intelligent overweight reporting than would be possible without such data being present
Allow for the assignment/recording of weighbridges and forest gates against journeys where different routes from an uplift point to a customer exist
The application of the appropriate route to a journey within WSX is determined by a number of factors associated to both the route and the journey, which include,
The date period in which a journey is undertaken
Exclusions based on the truck undertaking a journey’s ‘Truck Type’
Requirements for ‘Permits’ to be assigned to the truck
Checks on the ‘max bolster height’ set against the truck
Within the WSX database, Base Distances with associated Base Distance Routes can be manually added or uploaded.
Base Distances are almost universally set up, in pairs as a ‘forward’ and ‘reverse’ distances, or ‘Loaded’ and ‘Empty’ segments, as below:
The most common approach is that shown above, i.e. ‘per-compartment’ distances, where a distance exists for the empty leg from Customer/Home Base location to each Forest Compartment, and another for the loaded leg from the Forest Compartment to the Customer. However, if per-compartment distances are not available it is possible to utilise,
Per-forest distances, to ensure that at least some estimation of journey travel times and truck utilization can be made.
Per-Setting distances if this level of data is available in a consistent format. Per-Setting distances are the most accurate but also require the highest level of management as each setting requires a new distance.
Examples of Per-Forest and Per-Setting Distances,
It is not recommended to mix either per forest and per compartment distances for the same forest, or per compartment and per setting distances for the same compartment.
It is easiest to illustrate this with the ‘per forest AND per compartment’ distance situation. The most likely motivation for attempting to use a set-up like this would be that compartment-level distance data may not be available until after trucks begin taking loads out of the corresponding gang location. By adding a ‘per-forest’ distance, there will at least be some estimation of truck travel time and distance for planning and reporting purposes.
However, as the ‘per-forest’ distances are valid routes for the loads (if not ‘preferred’ when ‘per-compartment’ or ‘per-setting’ distances exist) they will not be replaced on journeys when a user adds ‘per-compartment’ distances and runs the process to ‘update’ the old distances.
It is possible to use the ‘Journey Route Review’ screen to update these less specific distance/routes after more specific ones have been added. If a mixed per-forest/per-compartment/per-setting distance setup is being contemplated, then use of the route review screen needs to be considered. Note that there is no one report that will identify where per-forest distances have been used, so if one intends to work in this way, it will be necessary to either:
Be certain that per-compartment distances will be provided and imported in due course, allowing the journey route review screen to be used to update those distances
Monitor this in some other way and add/request per-compartment distances. This would have to be done by comparing the distance routes available (from a ‘Details’ report) and the compartments to which trucks have gone (perhaps from a ‘Truck Data Extract’-’Uplifts’ report).
Only one entry for a Base Distance (Source to Destination) can exist. Each Base distance can, however, have multiple base distance routes associated, but each must be unique. The uniqueness of Base Distance Routes is based on the fields listed below and where the data in all of these fields for a base distance route matches another record attempting to be inserted, it will be prevented*.
Source
Destination
Weighbridge
Forest Gate
Start Date
Distance - Total
Off Highway Only (flag)
Max Bolster Height
Exclusions
Permits Required
Assoc Weight Permits
*One exception to this is the ‘Overwrite’ option for Importing distances. When this is utilised base distance routes in WSX that match a route in the import file may be overwritten by the data in the import file - see section on Importing Distance Data below for more details.
Base Distances and Base Distance Routes are added in the TurboTruck DBAdmin application by selecting the 'Distance Data -> Base Distances' menu option.
Base Distances - Comprise of selecting a source and destination, with the ability to also associate a Weighbridge. One or more Base Distance Routes may then be assigned to a Base Distance. Base Distances can be manually added withing WSX or uploaded from a CSV file.
Manually Adding a Base Distance
From within the Base Distances window, to add a Base Distance click on the Insert button below the list of Base Distances (left-hand panel). The ‘Select a Forest Record’ window that appears prompts for the Source location, either the Forest or Customer from which the journey is to originate.
If choosing a Forest as the Source, you are initially prompted for the Forest and Compartment.
If preferred, you can choose to select to the Forest level only by clicking Close on the ‘Select a Compartment’ window.
If choosing a Customer as the Source (by selecting the forest CUST) you will be automatically prompted and are required to select down to the Compartment and then Setting level.
Once the Source has been selected you are then prompted to select a Destination.
As with the Source, if the selected Destination is a Forest you can select to any level, however if selecting a Customer as the Destination (by selecting forest CUST) you are required to select to the Compartment and Setting level.
Following selection of Source & Destination you are then prompted to select a Weighbridge. Selection of a weighbridge is optional so if you do not wish to hold a weighbridge against the Base Distance you can click 'Close'.
Note: When adding a Base Distance, a ‘reverse’ base distance record will also be automatically created, e.g. If you add a base distance KIDP/3065894 to CUST/LOCTN/SAWM a reverse base distance record of CUST/LOCTN/SAWM to KIDP/3065894 will be generated.
Editing a Base Distance
From within the Base Distance window, to edit a Base Distance, highlight the record you require and click 'Change'. All fields within this record can be edited following the steps outlined above.
Base Distance Routes
Once a Base Distance has been established, Base Distance Routes can then be added.
Base Distance Routes can be added either within the main Base Distance browse screen by selecting the 'Insert' button below the 'Forward distance' or 'Reverse distance' sections, or within the 'Adding/Changing Base Distance' screen for the selected Base Distance.
Utilising the 'Insert + Reverse' option from within the Base Distances window also allows for a Base Distance Route with a matching Reverse distance to be added. Note that when the Insert + Reverse option is utilised you cannot add a Weighbridge or a Forest Gate at the time of initial addition of the base distance route; you must edited the record once added to assign these. The reason for this is that it cannot be assumed that both the Empty and Loaded portions of the route will utilise the same Forest Gate or Weighbridge.
Base Distance Routes comprise of the following,
Base Distance - Selected - As previously established
Weighbridge - Select from weighbridges. Where specified this weighbridge is associated to journeys, superseding any weighbridge specified against the base distance.
Forest Gate - Select from Forest Gates. Utilised in some circumstances for in-cab job provision & navigation
Start Date - Date from which distance is to apply. Set as 01/01/2000 by default, however, it is critical this is set accurately to cover the period in which the route is to be utilised
End Date - Date to which a route is to apply. Post the End Date the route is deemed to be ‘closed’ and no longer available for assignment to journeys
Distance & Time - Assigned as follows,
Off Highway: Distance of route on an off-highway road
On Highway: Distance of route on highway
Total: Sum of Off + On Highway distance (non-editable)
From Gate: Distance from Forest Gate to Loading Site (does not add to the total, total includes this distance)
Est: Average time taken to travel the route. Where recorded is utilised for the journey time calculations in WSX instead of the standard ‘distance x time’ calculations
Off Highway Only: Flag that can be set that deems the route to be off highway only. Where this is set no on highway distance can be recorded against the route.
GPS Options: Not Currently Implemented - For future development
Max Bolster Height - Set as maximum bolster height that can travel on this route, e.g. may be required where a low bridge or a tunnel exist on the route. Where max bolster height is assigned to a route only trucks &/or their associated trailers that either have no bolster height set or a set bolster height lower than that specified will be presented with or have automatically assigned these routes
Exclusions (Truck Type) - Select from Truck Types. Where Truck Types are assigned as exclusions these routes will not be available or automatically assigned to trucks of those types
Permits Required - Select from Permits (filtered to exclude weight permits). Where required permits are assigned to a route only trucks &/or their associated trailers that hold such permits will be presented with or automatically assigned these routes.
Assoc Weight Permits - Select from Permits (filtered to only display weight permits). Where weight permits are assigned to a route these routes with associated permit will only be presented for journeys where the truck &/or trailer hold a matching route. Where matching routes between the truck &/or trailer and journey exist, if the route is selected or automatically assigned the permit will also then be assigned to the journey record.
Comments - Free text comments associated to a route. Not currently displayed anywhere outside of this screen.
Notes:
Base Distance Routes must be unique, with the exception being they cannot be unique simply by distance, i.e. you cannot have two On Highway Base Distance Routes that have exactly the same set-up with the exception of different On Highway distances. The reason for this is there is no way for WSX or a user to distinguish between the two routes. Two routes may have the same distance if they have differing properties such as Bolster Height, Truck Type, Permits, etc.
While a reverse Base Distance is automatically added when adding a Base Distance, a reverse Base Distance Route is not automatically added when a Base Distance Route is added, unless the Insert + Reverse option is utilised. The reason for this is the reverse distance may have differing properties in terms of required permits, On/Off Highway status, Weighbridge, Forest Gate, etc., so it cannot be assumed to be an exact reverse match.
Editing a Base Distance Route
To edit a Base Distance Route, from within the Base Distance window, highlight the Base Distance Route and select 'Change'. All fields within this record can be edited following the steps outlined above.
The 'Update Journey Distances' option within the Base Distances screen allows for any journey with an associated Base Distance Route to have the distance value updated, if the Base Distance Route data has changed subsequent to the Journey being completed. Notes,
ONLY the distance value is updated, if other changes to the Base Distance Route have been made these will not be applied to the journey through this process.
This function will not NOT remove a route associated to a journey, even if that route is no longer valid.
To manage any of the possible changes required as listed in the notes above, these should be viewed and where necessary modified using the Journey Route Review screens (see below)
Note - Running this process can take some time if the selected period over which the journeys are to be reprocessed is large, e.g. 1+ months. When initiated, leave running until the Base Distances screen closes (indicating the processing has finished) - do not close WSX until the process is completed.
Distance data records can be imported or updated within WSX from a CSV file. When importing distance data all relevant properties can be included in the import data and associated to the base distance and route.
The required format and data of the CSV file listed below from column 'A' to column 'V', with those marked with an * being mandatory.
A: FromForest* - The Base Route Distance Source Forest
B: FromCompartment - The Base Route Distance Source Compartment
C: FromSetting - The Base Route Distance Source Setting
D: ToForest* - The Base Route Distance Destination Forest
E: ToCompartment - The Base Route Distance Destination Forest
F: ToSetting - The Base Route Distance Destination Forest
G: TotalDistance* - Total Distance
H: StartDate* - Start Date (in format dd/mm/yyyy)
I: EndDate - End Date (in format dd/mm/yyyy)
J: OnHighwayDistance* - Distance On Highway
K: OffHighwayDistance* - Distance Off Highway
L: EstimatedTime - Estimated Travel Time (in format hh:mm [24 Hr])
M: PermitList - List of associated Required Permits (separate with ‘&’)
N: TruckTypeExclusions - List of excluded Truck Types (separate with ‘&’)
O: WeighBridgeName - Weighbridge associated to the route
P: GateName - Forest Gate associated to the route
Q: GateDistance - Distance from Gate to Loading Area
R: MaxBolsterHeight - Maximum allowable bolster height on the route
S: MaxGross - Maximum allowable gross weight on the route
T: Comments - Comments
U: AddReverse - Ability to create a reverse distance at the same time ('Y' to add)
V: WeightPermits - List of Weight Permits that can be used on the route (separate with ‘&’)
To import distance data, from within the Database Admin application select the menu option 'Distances > Import Distances'. You are then required to select the file from which you wish to import the distance and select the required import option, as described below.
Add - This function will only add new Base Distance or Base Distance Route records from the data being imported, i.e. records where the key uniqueness constraints do not match any other record already in the database. This option will not update (overwrite) any existing distances matching those in the file.
Add & Overwrite - This function will both add new records where no match is found to existing and overwrite existing records where a complete match is found. For an overwrite to occur the record must match on all elements of the distance record, as listed below,
Source
Destination
Weighbridge
Forest Gate
Start Date
Distance - Total
Off Highway Only (flag)
Max Bolster Height
Exclusions
Permits Required
Assoc Weight Permits
Notes
Where a full match is not identified a new record will be added.
Where a matching distance record is identified this function does not ‘add’ data to it, it replaces the existing record with the new record, i.e. if the existing record has two weight permits associated and you want to add a third, then the import record must contain all three permits. If you import the data simply with the additional permit against the distance, then that will be the only permit associated to the route following the import.
When creating journeys in TurboTruck, the means by which a route for the 'Loaded' portion of the journey are attributed to a journey are controlled by the ‘UseRouteSelect_LogOrg’ setting in the database for the Log Org (contact Trimble Forestry Support to discuss). This setting determines if routes are assigned automatically where available, or if the user is to be prompt to select a preferred route where more than one option exists.
Note for the 'Empty' portion of the journey, where available, the route is always automatically assigned based on the best match.
For the Loaded portion, where UseRouteSelect_LogOrg is,
Not Activated - Where a matching route(s) for the journey criteria are available, the best match route is automatically applied.
Activated - Where the available routes matching the journey criteria are
Single - This route is automatically applied to the journey
Multiple - You will be prompt to select the preferred route from the available list of routes for the journey
Automatic Route Assignment Rules
Auto-Assignment of the most optimal route is based on the following constraints:
Open Routes - Only routes with start and end dates within which the date of the journey falls are utilised,
Exclusions - Routes are excluded where the Truck &/or Trailer do not meet specified criteria such as Truck Type Exclusions, Max Bolster Height, Required Permits.
And the following hierarchy:
Route Specificity - Selection of a route is made first for any routes established to a ‘Setting’ level, if none then by a ‘Compartment’ level, if none then by a ‘Forest’ level, then
On/Off Highway - Off highway routes are prioritised over On Highway, i.e. where an Off Highway route exists, even if longer than On Highway, it will be assigned. Note: For trucks flagged as Off Highway in the database only off highway routes will present. Both on and off highway routes will present for on highway trucks. Then,
Weight Permits - Where weight permits are associated to the truck &/or trailer, the route with the highest grossing weight permit matching that associated to the truck &/or trailer is selected. Note: Where Auto-Assign without prompting is set, the requirement for a route with a weight permit that matches the permit(s) added to a journey is not enforced, i.e. a route will be added to the journey if all other constraints outside of permit are met. Then,
Shortest Route - The shortest route will be preferred.
Where the setting by Log Org allows for prompting for route selection, where more than one route exists, the ‘Select Route’ screen will present.
Within the Uplift Add/Edit screen in WSX, the Select Route screen presents the routes available to the truck & trailer associated to the journey. This screen will present either via prompting, as described above, or the user can manually open by selecting the 'Route' button.
To select a route, highlight the line and double-click or choose the ‘Select’ button.
Notes,
Routes will display in order of most optimal at the top, least optimal at the bottom, based on the same criteria as used to determine the most optimal route for auto-assignment (as described above).
Route specificity is highlighted by different background shading, i.e. by Setting routes display with no shading, by Compartment routes display with light grey shading, by Forest routes show with darker grey shading
Where routes exist with more than one weight permit associated, a line item will display in the Select Route screen for each route & permit combination, i.e. they will appear as if they are individual routes. This occurs to allow for faster selection of a route with the required permit, as only a single weight permit can be applied to a journey.
'Show Broader Route Selection' - When the select route screen initially presents it will show the most specific routes only, i.e. if both By Setting and By Compartment routes exist, only the By Setting routes will initially display. Where less specific routes exist the ‘Show Broader Route Selection’ button will display and when selected, will present all possible routes associated to the journey.
Off-Highway Routes display in green text. Note, It is important to recognise that there is a distinction between establishing a Route that is ‘Off Highway Only’ and having a Journey flagged as ‘Off Highway’, i.e.
Off Highway Routes - Routes can be set as ‘Off Highway Only’. Auto-assignment or selection of a route that is set as ‘Off Highway Only’ will automatically flag the journey as ‘Off Highway’
Off Highway Journeys - Journeys can be flagged as an ‘Off Highway’ journey and,
If no route exists for the journey this flag may still be manually set/retained against the journey
Where the ‘Off Highway’ flag is set on a journey where routes exist but none are set as Off Highway, on completion of journey creation/modification a warning presents to the user and the Off Highway flag is removed, i.e. either no routes or an Off Highway route must exist for a journey to be flagged as Off Highway.
Where data is being passed from WSX to a docket processing application and off highway status is required, the journey must be flagged as Off highway
Note: If the gang location and/or customer for a journey flagged as Off Highway is changed, the Off Highway flag will not be automatically removed if the newly chosen gang location or customer has no routes associated - you will need to manually change the Off Highway flag on the journey in such cases where required.
Routes may also associated to a journey either when,
Starts are imported
Journeys are created from WSX Mobile
In both of these cases, the route associated to the journey is based on the logic described above for manual journey creation in WSX.
The Journey Route Review screens (Loaded & Empty) allow you to view journeys where a potentially more optimal route exists than that currently assigned to a journey. Loaded and Empty routes have differing properties and management, hence they have been separated into two screens.
This screen is designed to present journeys where Loaded routes are available but where either no route is associated, or a more optimal route than that associated is available. Notes,
Journeys can be reviewed for selected date ranges and specified Log Org(s).
Additional filter options allow you to filter the data set based on either selected Trucks, and/or Crews, and/or Customers. Note the options to the right of the filter boxes are as follows: S = Select a single entity, M = Select multiple entities and All = Select all entities (clears the filter)
Note: The 'Refresh' button must be selected after any changes to the date range or filters are made to initiate an update of the dataset.
The data displayed in the Journey Route Review - Loaded screen is broken into three main sections,
Journey List
This section displays a list of journeys where a potentially more optimal route exists than that currently associated to the journey. The 'Error Text' field against the journey record presents the potential error associated to the selected route, as described below,
Potential Route Errors & Hierarchy
Incorrect on/off highway setting - Displays for journeys where either a), set with the Off Highway flag but has been assigned an On-Highway route (if one exists), or b) journey is assigned an Off highway route but are not flagged as Off-Highway
Invalid route - Displays for any journeys where the associated route is no longer valid, e.g. journey exists outside either start or end date of associated route, or associated route has been deleted entirely.
Off highway route available - Displays for journeys where an On-Highway route has been used where an Off-Highway route exists
Shorter Route available - Displays for journeys where a shorter route is available than that associated
Missing Distance - Distance Available - Displays for journeys where a route is not associated but is available
Alternate route suggested - Displays for journeys where a more optimal route is available, e.g. two routes exist with the same distance, one with a weight permit matching that associated to the truck and the other does not, and journey has not been assigned the route with the weight permit.
Incorrect Weight Permit - Displays for journeys where a more appropriate weight permit exists on the route associated to the journey, i.e. a better permits exists matching a permit associated to the truck but has not been applied to the journey record
No route - Displays journeys where no route is associated and no route exists in the database. Note: these journeys cannot be fixed in this screen until routes are added to the database.
Notes:
Only a single route error will display for a journey at any time, however, multiple potential errors may exist. Where multiple potential errors exist, the error that displays is based on the set hierarchy outlined below, with the error ranking the highest displaying.
Due to the potential for multiple errors to exist, resolving one error may not remove the journey from this screen entirely, as it may then reappear based on another error still existing (after a screen Refresh).
The available data presented within the Journey List may be further filtered using the options presented above the list, which allows the exclusion of specific journey route errors as followings,
Off-Highway Flag Error - Displays journeys where the Off Highway flag has been assigned but an Off Highway route is not associated (if one exists), or an Off highway route has been associated but the journey is not flagged as Off-Highway
Off-Highway Available - Displays journeys where an On-Highway route has been used where an Off-Highway route exists
Shorter Route - Displays journeys where a shorter route is available than that associated to the route
Route Available - Displays journeys where a route is not assigned but is available
Incorrect Permit - Displays journeys where a more appropriate weight permits exist on an alternate route than that associated to the journey
Invalid Route - Displays any journeys where the associated route is no longer valid, i.e. journey exists outside either start or end date
No Route - Displays journeys where no route is associated and no route exists in the database. Note: these journeys cannot be fixed in this screen until routes are added to the database.
Exclude Rail - Allows for filtering out of journeys where the associated Truck Type has a description of ‘Train’. Ticked by default.
Note: The 'Refresh' button must be selected after any changes to the filter options above are made to initiate an update of the dataset.
Route Display & Selector
Below the journeys displays the list of the available routes for the highlighted journey with their associated properties. Notes
The available routes will display in the same order as that of the 'Select Route Screen', with the most optimal route display at the top of the list.
Each route displayed in this selection screen, as with the route selector that presents in the Insert/Change Journey screen, may not exist in the database as a separate base distance route. A route line item will display in these selection screens for any unique instance of route and its options/constraints, e.g. if a route has two permits associated, 3 lines will display, one with no permit and one each for the instances with the permits. This allows for single click selection of the preferred route and associated items such as permits when associating to a journey.
Show Broader Route Selection - As with the Route Selection screen in the Insert/Change Journey screen, when routes present in the Route Display & Selector, initially only the most specific routes only will display, i.e. if both By Setting and By Compartment routes exist only the by Setting routes will initially display. Where less specific routes exist the ‘Show Broader Route Selection’ button will present and when selected will present all possible routes associated to the journey.
Route Summary
To the right of the journeys a section allowing for 'Route Review' displays. This section allows the user to view the associated Permits, Max Gross (from Weight Permit), Total Distance and Off Highway status of following,
Journey - Displays the properties of the currently assigned route for the journey, where one exists
Best for associated - Displays potentially more optimal additional properties that could be assigned to the journey based on the associated route, e.g. if the route has a permit associated but no such permit is associated to the journey
Best for recommended - Displays the properties for the most optimal available route for the journey.
Updating Routes assigned to Journeys
Where required, new routes may be assigned to journeys within this screen, either adding where there was previously no route assigned, or replacing an existing route. The options to assign a new route to a journey are as follows,
Auto-Assign Recommended Route - Automatically updates the journey with the most optimal route, i.e. that shown in the ‘Best for recommended’ column of the route summary section.
Assign Selected Route - Updates the route associated to the journey with that highlighted in the 'Route Display & Selector' section.
Additional Functions
The following options also exist within this screen,
Change - Opens the Change Journey screen for the highlighted journey. Double-clicking the journey will trigger the same function
Export to CSV - Exports the displayed list of journeys with potential route errors to a CSV file.
This screen presents journeys where a route for the Empty portion is either missing, or a more optimal empty route option exists. Notes,
Journeys can be reviewed for selected date ranges and specified Log Org(s).
Additional filter options allow you to filter the data set based on either selected Trucks, and/or Crews, and/or Customers. Note the options to the right of the filter boxes are as follows: S = Select a single entity, M = Select multiple entities and All = Select all entities (clears the filter)
Note: Note: To initiate an update of the dataset, the 'Refresh' button must be selected after any changes to the date range or filters are made.
The data in this screen is in a single table, with the 'Error Text' field displaying the potential error associated to the selected route, as described below.
Potential Route Errors & Hierarchy
Invalid route - Displays for any journeys where the associated route is no longer valid, e.g. journey exists outside either start or end date of associated route, or associated route has been deleted.
Missing Distance - Distance Available - Displays for journeys where a route is not associated but is available.
Incorrect Route - Displays where a more optimal route exists than that associated to the journey.
No route - Displays journeys where no route is associated and no route exists in the database. Note: these journeys cannot be fixed in this screen until routes are added to the database.
Notes:
Only a single route error will display for a journey at any time, however, multiple potential errors may exist. Where multiple potential errors exist, the error that displays is based on the set hierarchy outlined above, with the error ranking the highest being the one displayed.
Due to the potential for multiple errors to exist, resolving one error may not remove the journey from this screen entirely, as it may then reappear based on another error still existing (after a screen Refresh).
The available data presented within the Journey List may be further filtered using the following options to exclude journeys based on the associated error,
No Route - Displays journeys where no route is associated and no route exists in the database. Note: these journeys cannot be fixed in this screen until routes are added to the database.
Exclude Rail - Allows for filtering out of journeys where the associated Truck Type has a description of ‘Train’ (selected by default).
Note: To initiate an update of the dataset, the 'Refresh' button must be selected after any changes are made to the filter options above.
Updating Routes assigned to Journeys
Where required, new routes may be assigned to journeys within this screen, either adding where there was previously no route assigned, or replacing an existing route. The Assign Optimal Route option when selected will assign a route to a journey where an available route exists that is not not excluded by criteria associated to the truck or the route, as follows
On Highway Truck - Shortest Route, either On or Off-Highway
Off Highway Truck - Shortest Off-Highway Route
Note, this is the same method by which distances are automatically assigned to the empty portion of a journey when creating a journey.
Additional Functions
The following options also exist within this screen,
Export to CSV - Exports the displayed list of journeys with potential route errors to a CSV file.