Carriers
3M has identified you as a possible carrier to collaborate with?
Connecting to Viya for 3M will contain the following:
- Despatch-advice communication:
- For direct Road consignments the information for the load can be shared with you through Viya.
- Air/Ocean, reconstruction and express flow through M3, use your M3 contact.
- Labelling of the handlingUnits is done by warehouse, so no label is produced by Viya.
- Tracking communication
- For any consignment shipped, tracking information is expected.
- All tracking events can flow through Viya, with the exception of Air and Ocean which goes directly to 3M SAP.
Test vs Production:
- Viya has a test environment available for testing the integration. We recommend creating a test environment and keeping that available for future changes.
Implementation process
From the moment you (the carrier) are identified to be added to the portfolio, up to the first live shipments:
below are the typical steps we take you through during implementation:
- Kick-off call: introduce each other, share intentions & capabilities on scope and timeline.
- Per message type (Despatch-advice and/or Tracking):
- Agree on format: see the integrations below for options of the format to exchange.
- Provide specifications & samples: A session is typically planned between Viya and Carrier to verify any questions on the specifications. It depends on carrier capabilities if a carrier standard or Viya/3M standard is used.
- Develop: One party develops the integration, the other party likely configures it.
- Agree on communication method: See the integrations below for available communication methods. Note that each integration can have a different communication method.
- Handshake with chosen communication method: Short step to validate that the ‘pipeline’ between Viya and the Carrier is working. E.g., place a file on SFTP or do an HTTP call to a REST endpoint.
- Integration test: Carrier and Viya go through basic tests to confirm the connection, and basic scenarios, are working.
- End-to-End test: 3M will send transactions from their SAP Test system to verify the test process works, various scenarios can be run here. Communication between Carrier and 3M.
- Soft go-live: First go-live with a limited set of consignments to verify all production configurations are ok.
- Go-live: All shipments start as per SOP.
Despatch advice
This message is transmitted for consignments that are loaded at the shipper’s location. It confirms the load details and includes the reference number to provide tracking information against.
Depending on the integration capabilities the following payloads are available:
- GS1 Transport Instruction (GS1-TI)
- This is the most comprehensive format, it contains all information including dangerous goods details, reference information, shipments inside the consignment.
- When also integrating with M3, this is typically the format used.
- Keep in mind that there are minor differences between the M3 and Viya implementation of GS1-TI, mostly where Viya will send out 1 consignment per GS1-TI, M3 can send out 1 GS1-TI with multiple consignments.
- Implementation details can be found here: gs1-ti
- Communication method: SFTP
- GS1 Transport capacity booking (GS1-TCB)
- High level format that contains the load summary, references on consignment level. In essance it indicates: bring x cubic meters of goods from location a to b in this timeline.
- See for details gs1-tcb
- Communication method: SFTP
- IFTMIN
- D96A, see for details iftmin D96A
- D01B, see for details iftmin D01B
- D13B, see for details iftmin D13B
- Communication method: SFTP
- Email
- Receive an email with the despatch advice information.
- See for details: despatch advice email
- Communication method: Email
- Custom: If you would like to use your own format or prefer an API integration, please contact us to discuss the options.
Communication methods
- SFTP: Viya will place the despatch advice file on an SFTP server hosted by the carrier.
Tracking
To update the shipper’s teams and their customers on the status of the consignments, tracking information is to be provided. The tracking information can be shared in the following formats, in order of preference:
- API webhook or HTTP POST to Viya, see tracking webhook
- This is the preferred method, as it allows for real-time updates and is easy to implement.
- Alternatively you can suggest a payload in JSON or XML format which Viya can consume.
- API/Webservice where Viya pulls the tracking information from the carrier’s system
- This is a good alternative if the carrier prefers to expose an API for Viya to pull the tracking information.
- The carrier is in the lead to provide the API documentation and access to Viya.
- GS1 Transport Status (GS1-TS), see gs1-ts
- Communication method: SFTP
- IFTSTA, see iftsta
- Currently all the status information is taken from the STS loop (segment group 5). The following records hold the information needed:
- STS (status code and/or description)
- RFF (tracking reference)
- DTM (event datetime)
- Communication method: SFTP
- Currently all the status information is taken from the STS loop (segment group 5). The following records hold the information needed:
- Manual on Viya portal
- In combination with the Email despatch advice, the carrier can manually enter the tracking information on the Viya portal.
- This is useful for very small volumes or for carriers that do not have an automated system.
- See for details: despatch advice email
- Custom: If you would like to use your own format (CSV, xml, ..), please contact us to discuss the options.
Event data
The minimal data required for every event:
- Date/time of event with timezone
- Event code (status code)
- Link to the consignment (tracking reference)
To improve the user experience it is recommended to also provide:
- Location of the event (country, postal code, city, if available: coordinates)
- Description of the event (status description)
- Image of the event (eg. proof of delivery, damage, etc.)
Communication methods
- SFTP: Carrier will place the tracking file on an SFTP server hosted by Viya. Viya will invite the carrier to connect to the SFTP server.
Tracking events
The following events are requested to be sent to 3M besides the Pickup & Delivery events. The events with a “mandatory” label are the minimum required events to be sent to 3M.
| Viya event code | 3M Description | mandatory | comments |
|---|---|---|---|
| PickupRequestedCustomerPickupIncomplete | CUSTOMER WILL PICK UP GOODS HIMSELF - MISSING | ||
| PickupRequestedCustomerPickup | CUSTOMER WILL PICK UP GOODS HIMSELF | Y | |
| PickupRequestedCustomerPickupDamaged | CUSTOMER WILL PICK UP GOODS HIMSELF - DAMAGE | ||
| PickupCompleted | PICKED UP SHIPMENT | ||
| PickupCompletedDamaged | PICKED UP SHIPMENT - DAMAGED | ||
| PickupCompletedIncomplete | PICKED UP SHIPMENT - MISSING | Y | |
| BookingRequested | BOOKING CREATED | ||
| DeliveryAppointmentPlanned | CUSTOMER AGREED ON APPOINTMENT DATE | ||
| DeliveryPlannedArrivalNoticeProvided | ARRIVAL NOTICE TO THE CONSIGNEE | Y | |
| CustomsDelayedIncorrectOrMissingInformation | CUSTOMS - DOCUMENT INCOMPLETE/INCORRECT | ||
| CustomsInProgress | CUSTOMS CHECK | ||
| CustomsReleased | CUSTOMS CLEARED | ||
| ExceptionDamagedDestroyed | DAMAGED - DESTROYED | ||
| DeliveryCompletedPartlyDamaged | SHIPMENT DAMAGED - PARTIALLY DELIVERED | Y | |
| ExceptionDamagedUnderInvestigation | SHIPMENT DAMAGED - UNDER INVESTIGATION | Y | |
| ExceptionDamagedRequiresInputShipper | SHIPMENT DAMAGED - UNDER INVESTIGATION (SHIPPER) | ||
| ExceptionDamagedUnderInvestigation | SHIPMENT DAMAGED - UNDER INVESTIGATION (CARRIER) | ||
| DeliveryInProgressArrived | ARRIVAL AT CONSIGNEE | Y | |
| DeliveryInProgressOutForDelivery | OUT FOR DELIVERY | ||
| DeliveryInProgressShortDistance | SHORT DISTANCE DELIVERY | ||
| DeliveryAppointmentRequested | FIXED DATE FOR DELIVERY | Y | |
| ExceptionDelayedIncorrectAddress | SHIPMENT DELAYED - INCORRECT/INCOMPLETE ADDRESS | Y | |
| ExceptionDelayedNotLoadedAsDangerousGoods | SHIPMENT DELAYED - NOT LOADED AS DANGEROUS GOODS | ||
| ExceptionMissingLost | SHIPMENT LOST | ||
| ExceptionDelayedMissing | SHIPMENT MISSING - PARTIALLY MISSING | ||
| ExceptionDelayedMissingUnderInvestigation | SHIPMENT MISSING - UNDER INVESTIGATION | Y | |
| BookingCancelledOther | SHIPMENT CLOSED AS IT CANNOT BE DELIVERED | ||
| Other | SHIPMENT THEFT - UNDER INVESTIGATION | Include in the description what happened | |
| DeliveryCompletedPartly | PARTIALLY DELIVERED | Y | |
| ExceptionMissingUnderInvestigationShipper | SHIPMENT MISSING - UNDER INVESTIGATION (SHIPPER) | ||
| ExceptionMissingUnderInvestigationCarrier | SHIPMENT MISSING - UNDER INVESTIGATION (CARRIER) | ||
| PickupFailedOther | SHIPMENT DELAYED - NOT LOADED FOR TRANSPORT | ||
| ExceptionDelayedWrongRouting | SHIPMENT DELAYED - SORTED WRONG ROUTING | ||
| DeliveryPlannedRescheduledOnRequestOfRecipient | SHIPMENT DELAYED - CONSIGNEE REQUESTED A NEW DELIVERY DATE | Y | |
| DeliveryFailedAbsentRecipient | SHIPMENT DELAYED - ABSENT CONSIGNEE | Y | |
| DeliveryFailedWaitingTimeExceeded | SHIPMENT DELAYED - WAITING TIME AT CONSIGNEE EXCEEDED | Y | |
| DeliveryFailedRecipientMoved | SHIPMENT DELAYED - CONSIGNEE MOVED | ||
| ExceptionDelayedAccident | ACCIDENT/TRUCK BROKEN | Y | |
| ExceptionDelayedOther | SHIPMENT DELAYED - GOODS WERE HANDED OVER TO AGENT ON THE ISLAND | ||
| ExceptionDelayedAdministrativeRectivication | SHIPMENT DELAYED - ADMINISTRATIVE RECTIFICATION | ||
| ExceptionDelayedIncorrectLabelling | SHIPMENT DELAYED - INCORRECT LABEL | Y | |
| ExceptionDelayedNotLoadedAsBondedGoods | SHIPMENT DELAYED - NOT LOADED AS CUSTOM BONDED GOODS | ||
| ExceptionDelayedWaitingForEdi | SHIPMENT DELAYED - WAITING FOR EDI DATA | ||
| PickupFailedGoodsNotReady | SHIPMENT DELAYED - WAITING FOR CONSIGNMENT | ||
| ExceptionDelayedBankHoliday | SHIPMENT DELAYED - BANK HOLIDAY | Y | |
| ExceptionDelayedBankHoliday | SHIPMENT DELAYED - REGIONAL HOLIDAY | ||
| ExceptionDelayedForceMajeure | SHIPMENT DELAYED - FORCE MAJOR | ||
| DeliveryFailedRecipientClosed | SHIPMENT DELAYED - CONSIGNEE CLOSED | Y | |
| ExceptionDelayedIndustrialDispute | SHIPMENT DELAYED - INDUSTRIAL DISPUTE | ||
| DeliveryFailedAdditionalEquipmentRequired | SHIPMENT DELAYED - UNABLE TO DELIVER AS ADDITIONAL DEVICE WAS REQUIRED | ||
| ExceptionDelayedOther | SHIPMENT DELAYED - INCORRECT SHIPMENT DECLARATION AT GBW INTERMEDIATE HUB | ||
| ExceptionDelayedMissingDocuments | SHIPMENT DELAYED - MISSING DOCUMENTS | Y | |
| ExceptionDelayedMissingDocumentsFromShipper | SHIPMENT DELAYED - MISSING DOCUMENTS (SHIPPER) | ||
| ExceptionDelayedMissingDocumentsFromCarrier | SHIPMENT DELAYED - MISSING DOCUMENTS (CARRIER) | ||
| ExceptionDelayedTemperatureExceeded | SHIPMENT DELAYED - TEMPERATURE EXCEEDED | ||
| ExceptionDelayedLackOfTransportCapacity | SHIPMENT DELAYED - OVERLOAD, NOT FORWARDED | ||
| DeliveryCompletedPartlyMissing | SHIPMENT MISSING - PARTIALLY DELIVERED | Y | |
| ExceptionReturnToSenderIncident | INCIDENT TRIGGERED FOR SHIPMENT BACK TO 3M | ||
| Other | SHIPMENT THEFT - PARTIALLY DELIVERED BILLED | Include in the description what happened | |
| ExceptionDelayedDeliveryAppointmentRequired | SHIPMENT DELAYED - DELIVERY APPOINTMENT NEEDED | Y | |
| DeliveryCompletedPartlyCustomerPickup | CUSTOMER PICKUP - PARTIAL DELIVERY | ||
| BookingCancelledIncorrectInformation | SHIPMENT CLOSED DUE TO INCORRECT INFORMATION FROM SHIPPER | ||
| DeliveryAppointmentRescheduled | SHIPMENT DELAYED - DELIVERY APPOINTMENT | ||
| ExceptionDelayedOther | SHIPMENT DELAYED - SPECIFIC REASON FOR NON DELIVERY | ||
| ExceptionDelayedGeneralTimeConstraint | SHIPMENT DELAYED - TIME CONSTRAINT | ||
| ExceptionDelayedMissedConnection | SHIPMENT DELAYED - TRUCK ARRIVED LATE AT THE INTERMEDIATE HUB | ||
| ExceptionDelayedUnknown | SHIPMENT DELAYED - UNKNOWN REASON | Y | |
| PickupFailedGoodsNotReady | SHIPMENT DELAYED - WAITING TO BE COMPLETED AND SHIPPED | ||
| ExceptionMissingAtUnloadingIntermediateHub | SHIPMENT DELAYED - MISSING AT THE TIME OF UNLOADING AT INTERMEDIATE HUB | ||
| Other | SHIPMENT SHORTAGE | Include in the description what happened | |
| Other | DIFFERENT PALLET QUANTITIES | Include in the description what happened | |
| Other | SHIPMENTS RECEIVED WITH EXTRA QUANTITY | Include in the description what happened | |
| ExceptionReturnToSenderOther | SHIPMENT CLOSED - BACK TO 3M | Y | |
| ExceptionDelayedLackOfUnloadingSpace | SHIPMENT DELAYED - LACK OF SPACE FOR DELIVERY | Y | |
| TransitHubActivityArrived | ARRIVAL AT THE HUB | Y | |
| TransitHubActivityDeparted | DEPARTURE FROM HUB | Y | |
| TransitHubActivityDepartedDamaged | DEPARTURE FROM HUB - DAMAGED | ||
| TransitHubActivityDepartedPartiallyMissing | DEPARTURE FROM HUB - PARTIALLY MISSING | ||
| DeliveryCompleted | POD | Y | |
| DeliveryCompletedConsigneeIndicatesMissing | POD - CONSIGNEE INDICATES SHIPMENTS MISSING | ||
| DeliveryCompletedConsgineeIndicatesSurplus | POD - CONSIGNEE INDICATES SURPLUS | ||
| ExceptionDamagedDelivered | POD - DAMAGED AND DELIVERED | ||
| DeliveryCompletedOther | POD - DELIVERED WITH A SPECIFIC REASON | ||
| DeliveryCompletedManuallyRegistered | POD - MANUALLY REGISTERED POD | ||
| DeliveryCompletedWithPermissionToLeaveGoods | POD - NO SIGNED POD, DELIVERED WITH PERMIT TO PLACE GOODS | ||
| DeliveryCompletedDelayed | SHIPMENT DELIVERED - WITH DELAY | ||
| PickupCompletedCustomerPickup | CUSTOMER PICKUP | Y | |
| DeliveryCompletedPartlyDamaged | PARTIALLY DELIVERED AND PARTIALLY REFUSED DUE TO DAMAGE | ||
| DeliveryFailedRefusedByRecipientRequestedOtherDeliveryDate | REFUSED BY CONSIGNEE - ANOTHER DELIVERY DATE | ||
| DeliveryFailedRefusedByRecipient | SHIPMENT REFUSED BY CONSIGNEE | Y | |
| DeliveryFailedRefusedByRecipientIncorrectContactDetails | SHIPMENT REFUSED BY CONSIGNEE - INCORRECT CONTACT DETAILS | ||
| DeliveryFailedRefusedByRecipientRequestedOtherDeliveryDate | SHIPMENT REFUSED BY CONSIGNEE - ANOTHER DELIVERY DATE | Y | |
| DeliveryFailedRefusedByRecipientDamaged | SHIPMENT REFUSED BY CONSIGNEE - DAMAGED | Y | |
| DeliveryFailedRefusedByRecipientNotOrdered | SHIPMENT REFUSED BY CONSIGNEE - DID NOT ORDER THE SHIPMENT | ||
| DeliveryFailedRefusedByRecipientMissingDocuments | SHIPMENT REFUSED BY CONSIGNEE - DOCUMENTS MISSING | ||
| DeliveryFailedRefusedByRecipientInventory | SHIPMENT REFUSED BY CONSIGNEE - INVENTORY REASON | ||
| DeliveryFailedRefusedByRecipientLateDelivery | SHIPMENT REFUSED BY CONSIGNEE - LATE DELIVERY | ||
| DeliveryFailedRefusedByRecipientShipmentIncomplete | SHIPMENT REFUSED BY CONSIGNEE - MISSING | ||
| DeliveryFailedRefusedByRecipientCancelled | SHIPMENT REFUSED BY CONSIGNEE - ORDER CANCELLED | ||
| ExceptionReturnToSenderPartially | SHIPMENT REFUSED BY CONSIGNEE - PARTIALLY BACK TO 3M | ||
| DeliveryFailedRefusedByRecipientShipmentIncomplete | SHIPMENT REFUSED BY CONSIGNEE - PARTIALLY DELIVERED | ||
| DeliveryFailedRefusedByRecipientIncompleteDueToMissing | SHIPMENT REFUSED BY CONSIGNEE - PARTIALLY MISSING | ||
| ExceptionReturnToSenderCancelledByShipper | SHIPMENT REFUSED BY CONSIGNEE - BACK TO 3M (3M DECISION) | ||
| ExceptionReturnToSenderRefusedAtDelivery | SHIPMENT REFUSED BY CONSIGNEE - BACK TO 3M (NON 3M DECISION) | ||
| TransitTransport | IN TRANSIT | Y |
Note: Only deviate from the minimum tracking events in agreement with 3M.