Status Updates Export (EDI)

Summary / Purpose

Use this article to automatically send consignment status updates from TransVirtual to customers or external systems.

This guide explains how to notify recipients when key delivery events occur, such as when a consignment is on delivery or approaching the destination.

Overview

In Transvirtual, there is the ability to create Consignment Status Export EDI (Electronic Data Interchange) rules that send out status update information about a consignment, to a location via FTP, Email, etc. This page can be found under Import/Export > Data Export > Status Updates.

This article runs through a common setup that most Transvirtual users implement, sending On Delivery notifications to a customer (indicating their freight has been loaded and is on its way).

Step-by-Step Instructions

Create/Add a New Rule

To create a new rule, go to the Export Consignments Status Updates page, where you will see a similar screen as shown below.

On the Export Consignment Status Updates page, click on the "New Rule" button as shown above. A pop up of 'Create a new export rule' will display, as shown below.

Manually enter the Rule Name in the rule name field and select the Export Framework with the help of the drop-down button, then click on Create as shown above.

This example selects "OnDelivery Email Notification to customer" as the rule name and Email as the export framework.

Once the rule is created, it will be added to the Export Rules list and highlighted in orange color as shown below.

Now, click on the newly added rule; the details of this rule will appear on the right side of the page as shown below.

In the rule detail section, the rule details can be added or updated as described in the Update/Edit the Rule section.
Before updating the rule, first set the data filter as described below.

Data Filter

The data filter is the driving force behind when the rule will and won't apply to a consignment.

To see the data filter tab, navigate to the bottom of the page where the Data Filter section is located.
On the data filter section, select the details for Select Field (Screen 01), Logic (Screen 02) and Select Value (Screen 03) and then click on Add Rule. The rule detail will display on the Data Filter screen (Screen 04) as shown below.

This example selects Status Name in Select Field, Equal in Logic and OnDelivery in Select Value field.

If notification emails should only be sent for a specific consignment customer, add an extra line to the Data Filter that specifies the desired customer: select Customer Name in Select Field, Equal in Logic and then the Customer's Name in Select Value. This example sends notifications for all customers, so it uses only the first line of logic.

Update/Edit the Rule

To update/edit the rule details, first click on the applicable rule, and the details of that rule will display on the right side of the screen as shown below.

The details can be updated as follows:

Rule Name: This is the name given to the rule. It can be changed at any point but should reflect what the rule will be used for or does. This example keeps the rule name as it was set during initial creation.
Trigger Period: This determines how often this EDI rule will run for new files to export. This example sets it as Every 2 mins, though it can be updated at any time.
Limit Exports: This setting controls how many times an EDI can be performed for the same event/consignment. This example selects Not Required.
Export Framework: This specifies how the information will be exported from Transvirtual. This example selects Email. The export framework setting can be updated by clicking Settings next to this field.

The FTP, Email, Webservice, Printer, Account Package and SMS settings can all be customised using the Settings button.

Export Framework Setting

Once the Export framework setting is selected, a pop-up to edit the email settings for this export rule will display.

Fill in the email details — see the Email Export Framework section of the General Information article for more detail.
On the edit Email setting page, click the Email Body tab. The email body section allows a message to be entered manually that will be sent. This example uses the message shown below:

The @Model.ConsignmentTracking URL is a special coding function that sends a link the customer can select to view the tracking of their consignment. Ensure this code is spelt exactly as shown above.

The Validate button at the bottom of this window can be used to preview what the email will look like, and it also checks that any coding functions are correct and will not cause issues. Use this button to confirm the setup is correct.

Once done, click Update to save the changes.

Export File Type: This determines the type of file sent with the email, if any. Select the export file type using the drop-down button. This example selects None.
Enable Export: To enable the new rule, click the toggle to the Yes position, then click Update to save the changes. Once completed, the rule's color will change to white, indicating it is enabled.

The Memo and Email EDI Errors fields are not mandatory, so this example leaves them blank.

Any successful EDI rules that have triggered on a consignment will appear under the communications tab of that consignment.

The example above shows this consignment currently has a status of On Delivery; therefore, it is eligible for this EDI rule.

Delete the Rule

To delete the rule, click the delete icon. A confirmation dialog will pop up — click Yes and the rule will be deleted from the database, as shown below.

Delivery Updates at 30 and 15 Minutes from Location

In addition to the above, Transvirtual also has the ability to send out notifications to consignment customers, senders and receivers to provide notifications when their consignment is roughly 30 or 15 minutes away from being delivered.

This setup is normally done via SMS, and the example below uses that method; it is also set up under the Status Updates page, which can be found under Import/Export > Data Export > Status Updates.

The Route Optimisation module must be enabled for this process to work.

SMS sending in TransVirtual is a paid function. Each text message sent from the account will incur a charge. Further information can be found in the Rates and Modules page of the account: go to Configuration > Transvirtual Account > Rates and Modules.

To set up a rule for delivery updates at 15 and 30 minutes via SMS, go to the Export Status Updates page and add a new rule by clicking the New Rule button.
Follow the same steps as described in the Create/Add a New Rule section above. This example uses SMS, so select SMS in the Export Framework.
Click on the newly added rule; the details of the rule will display on the right side of the page as shown below.

Scroll down to the bottom of the page to the data filter section and fill in the details as described below.

Data filters in Transvirtual determine when an EDI rule will and won't apply to a consignment.

On the data filter section, select the Field, Logic and Value as shown below.

These values determine when this EDI rule applies to a consignment.

In this example, the data filter section uses Customer Name in Field, Equal To in Logic and Customer Name (Transvirtual) in Value. This Data Filter applies to consignments for a nominated customer where the consignment status is MobileDeliveryIn15Mins.

Specify the relevant status this applies to by following the same instructions as step 5, but this time in the Field section select Status Name, Logic will be Equal to, and in Select Value use Mobile - Delivery ETA 15 Minutes, then click Add Rule. A new row will be added in the data filter section as shown below.

It may be a good idea to add another condition to the Data Filter, as below, if a similar rule is set up for 30-minute notifications:

To add this, the logic is Previous Status (Any), then Not Equal, then Mobile - Delivery ETA 30mins, then Add Rule.

Note: Adding this extra condition/line to the Data Filter is useful if a 30-minute delivery notification version of this rule is also set up. In that case, both a 30-minute and 15-minute SMS notification may not be wanted. This extra line means the 15-minute text notification will only occur if the system has not previously sent a message/SMS at 30 minutes.

This can help avoid the cost of sending both a 30-minute and 15-minute SMS notification. If only one EDI rule exists, this condition does not apply and can be disregarded.

Once the data filter has been set up, configure the rule details at the top of the page, where the Rule Name, Trigger Period, Limits and Exports, Export Framework, Enable Export, Test Export, Link to Rule ID, Memo and Email EDI Errors can be updated.

Once the details are updated, click Update to save the changes.

Field Information

Rule Name: This is the name of the EDI rule and will already be populated with what was entered when creating the rule. It can be changed again, but the name should be reflective of what the rule will be used for.
Trigger Period: This is the field to specify how often the EDI rule will run. This example sets it as Every 2 Mins:

Framework Setting

Limit Exports: This setting controls how many times an EDI can be performed for the same event/consignment. This example leaves it as Not Required.
Export Framework: This determines how the information is sent out of Transvirtual. This example sets it as SMS. To edit what is sent with the SMS, click the Settings button next to this field as shown below.

Once the settings button is clicked, a pop-up to Edit SMS setting will display as shown below.

Configure where the SMS/texts are sent and what they say. Starting from the top, there are toggles for sending to the Consignment Sender or Receiver Phone.

This example enables the toggle for Send to Consignment Receiver Phone.

To check the consignment receiver phone number, open the consignment and go to the consignment details section to check the Receiver information as shown below.

To customise the message sent to this phone number, type the desired text into the SMS Message field in the SMS Message section as shown below.

@Model.ConsignmentNumber is a special coding function that automatically populates the consignment number for each consignment this rule triggers against. It is very important that this code is typed exactly as shown above for it to work properly.

If necessary, use the Validate button to check the setup is correct — the screen will turn white and display an example SMS if the setup is correct.

As the message is typed, the message length and approximate credits used will display, indicating how long the message is and how many credits will be used to send each SMS.

The more credits used, the higher the cost, so it is best to keep the message short to minimise costs.

Once configured, click Update to save the changes. The rule is now configured for this example.
Enable this rule by clicking the Enable Export toggle to YES, then click Update to enable this EDI rule.

Once the rule is enabled, the rule appears white in the list on the left, indicating it is now active, as shown below.

How Does This Actually Work?

Once set up, the rule will work automatically to apply to any consignments where Transvirtual is the customer (for this example) and the current status is "Mobile - Delivery ETA 15 Mins".

This status is achieved by Transvirtual communicating with the driver's mobile device. Each device (as long as it is turned on and GPS is enabled) sends back GPS data periodically to Transvirtual, letting the system know its location. When Transvirtual receives this information, it can calculate how far away a driver/device is from a location, and if 15 minutes away, the system assigns applicable consignments the status of "Mobile - Delivery ETA 15 Mins", which then triggers the sending of an SMS to the client, informing them that their delivery will arrive shortly.

This process requires that the device remain on and that the Transvirtual app has GPS permission, along with GPS being enabled in the device settings.
This process also requires that the driver follow the run order listed on their device.
This process is only as good as the GPS data being received back from the device.

Important to note: If for some reason a driver is unable to complete the delivery, they must ensure they 'fail' the delivery so that this export rule does not keep attempting to send the SMS. For help with this, watch this video on failing a delivery, or see the delivery and pickup issue troubleshooting article.

Common Issues & Troubleshooting

Issue: Status update emails or SMS are not being sent
Cause: The rule is disabled or the consignment does not meet the data filter conditions.
Resolution: Ensure the rule is enabled and the status in the data filter matches the consignment status.

Issue: ETA SMS alerts are not triggering
Cause: Route Optimisation or GPS is not enabled on driver devices.
Resolution: Confirm Route Optimisation is active and drivers have GPS turned on.

Issue: SMS sent to the wrong phone number
Cause: Sender or receiver phone details are incorrect.
Resolution: Check phone numbers in the consignment details.

Issue: Tracking link does not work
Cause: The tracking URL field is missing or entered incorrectly.
Resolution: Ensure @Model.ConsignmentTracking is correctly entered in the message.