Overview
This integration transfers Transaction Tracking Number records from Kuehne+Nagel Shipments to iPaaS through manual sync and polling. iPaaS supports the manual and polling synchronization of shipment records from Kuehne+Nagel using its Shipment Tracking API. Subscribing to the polling event shipment/poll ensures that these records are transferred as they are created or updated.
Id Format
When manually transferring data to iPaaS for a Kuehne+Nagel Shipment, enter the Shipment ID in the required format: {BlNumber}|{Scac}. For example, KN123456789|KUEH
The Shipment ID must follow this exact format with the pipe separator for the integration to process correctly.
Mapping Collection Status
Status: Conditional
Trigger Events: This integration runs on a Transaction Tracking polling event, where transaction records are periodically fetched and transferred to iPaaS,
For a shipment to transfer successfully, the ReferenceNumber used on the shipment must match an iPaaS Transaction Number exactly to attach the new iPaaS Transaction Tracking record to the correct iPaaS Transaction.
This means that a corresponding transaction must already exist in iPaaS and be linked to the related Kuehne+Nagel transaction.
System Caveats
Kuehne+Nagel Caveats
• The flow depends on the availability of a valid iPaaS transaction whose Transaction Number matches the Kuehne + Nagel shipment ReferenceNumber.•
Data transfer will not occur if no corresponding iPaaS Transaction Number is found for the provided ReferenceNumber. The iPaaS Transaction ID is resolved only after a successful match.
• Any missing, null, or malformed ReferenceNumber on the shipment will prevent synchronization and result in a transfer error.
iPaaS.com Caveats
The integration requires that an existing iPaaS.com transaction be present before data can be updated.
Integration-Specific Caveats
The integration requires the Shipment ID to be provided in the exact format {BlNumber}|{Scac}.
The integration depends on the Kuehne + Nagel Shipment Tracking API returning at least one shipment detail record. If no shipment details are returned, the transfer cannot proceed.
The integration requires a non-null ReferenceNumber on the returned shipment record. If the ReferenceNumber is missing or null, the integration throws an error and no synchronization occurs.
The shipment ReferenceNumber must exactly match an existing iPaaS Transaction Number. The integration uses this value to locate the corresponding iPaaS transaction prior to transfer.
If no iPaaS transaction exists with a matching Transaction Number, the integration throws an error indicating that the shipment cannot be transferred because the corresponding iPaaS transaction does not exist.
The iPaaS Transaction ID is resolved only after a successful Transaction Number match and is assigned internally for tracking purposes.
Setup Requirements
Kuehne+Nagel Configuration
API Access Request: Access to the Kuehne+Nagel API must be explicitly requested and approved by their technical support team prior to integration setup.
Authentication ID & Client Code: These credentials are issued by the Kuehne+Nagel Helpdesk upon approval and are mandatory for all API requests.
API Endpoint Configuration: The base URL and endpoints for shipment tracking or transaction updates must be configured according to the Kuehne+Nagel API documentation.
Regional Access Control: API access may vary depending on the organization’s service region and contractual terms.
iPaaS.com Configuration
Transaction Mapping Setup: Ensure that all required fields (e.g., Reference Number, BL Number, Status, etc.) are correctly mapped between Kuehne+Nagel and iPaaS.
Existing Transaction Requirement: The system must have an existing iPaaS.com transaction linked to the incoming Reference Number for data to process.
Shipping Method Configuration: All ShippingMethod values used in mappings must already exist in iPaaS, or the transfer will fail; the integration does not add new methods automatically
Duplicate or Conflicting Mappings
This mapping applies only to Kuehne+Nagel Shipment tracking data. Ensure no other mappings target the same iPaaS Transaction Tracking Number entity to prevent data from being overwritten.
Supported Child Collections
This integration does not support any child collections.
Authentication & Security
Kuehne+Nagel uses Authentication ID and Client Code credentials for API access. These credentials are issued by the Kuehne+Nagel Helpdesk upon approval and must be stored securely within the iPaaS credential manager.
Note: For assistance, contact the Kuehne+Nagel Helpdesk.
Integration Flow
The integration processes Kuehne+Nagel shipment tracking records as follows:
The integration is triggered by a shipment update or status message from Kuehne+Nagel, or manually initiated.
The system retrieves shipment details (BL Number, Shipper Code, Status Date/Time, Status Message) from the Kuehne+Nagel API response.
The ReferenceNumber is validated for presence and correct format.
The Shipment ID is validated to ensure it follows the required format: {BlNumber}|{Scac}.
A lookup is executed in iPaaS to find the corresponding Transaction linked to the ReferenceNumber.
Field mappings are applied between Kuehne+Nagel and iPaaS, updating fields such as ParentId, ShippingMethod, TrackingNumber, and Status Details.
The existing Transaction Tracking Number is saved or updated in iPaaS.
The API response and integration execution status are logged for monitoring and audit purposes.
Mappings
Add/Update Kuehne+Nagel Shipment To iPaaS.com
Description
This filter checks whether a valid iPaaS Transaction ID exists for the specified ReferenceNumber. If found, the tracking data proceeds to transfer. If not found, the sync is skipped.
A corresponding transaction must already exist in iPaaS and be linked to the related Kuehne+Nagel transaction.
Mapping Type. | Source Field (Kuehne+Nagel) | Destination Field (iPaaS.com) | Description |
Field | BillToCode | Bill To Code | Maps the Kuehne+Nagel BillToCode to the iPaaS Bill To Code for billing reference. Recommended |
Field | StatusDate | Status Date | Maps the Kuehne+Nagel StatusDate to the iPaaS Status Date. Recommended |
Field | StatusTime | Status Time | Maps the Kuehne+Nagel StatusTime to the iPaaS Status Time. Recommended |
Field | StatusTimeCode | Status Time Code | Maps the Kuehne+Nagel StatusTimeCode to the iPaaS Status Time Code. Recommended |
Field | StatusMessage | Status Message | Maps the Kuehne+Nagel StatusMessage to the iPaaS Status Message. Recommended |
Field | ReasonMessage | Reason Message | Maps the Kuehne+Nagel ReasonMessage to the iPaaS Reason Message. Recommended |
Dynamic Formula |
| Appointment Message | Maps the Kuehne+Nagel AppointmentMessage to iPaaS. Returns default text if empty. Recommended |
Field | AppointmentReasonMessage | Appointment Reason Message | Maps the Kuehne+Nagel AppointmentReasonMessage to the iPaaS Appointment Reason. Recommended |
Field | TransactionId | ParentId | Maps the Kuehne+Nagel TransactionId to the iPaaS ParentId. This links the shipment update to its parent transaction. Required. |
Static | Flat Rate | ShippingMethod | Sets the iPaaS ShippingMethod to the static value Flat Rate. Required. |
Field | ShipperCode | ShippingMethodDescription | Maps the Kuehne+Nagel ShipperCode to the iPaaS ShippingMethodDescription. Recommended |
Field | BlNumber | TrackingNumber | Maps the Kuehne+Nagel BlNumber (Bill of Lading) to the iPaaS TrackingNumber. Required. Recommended |
Error Handling
Missing Reference Number
ReferenceNumber is missing or null in the Kuehne+Nagel shipment record.
Description: The integration cannot proceed without a valid ReferenceNumber to match against an iPaaS Transaction Number.
Resolution:Ensure the Kuehne+Nagel shipment has a valid ReferenceNumber before syncing.
Invalid Shipment ID Format
Shipment ID is not in the required format {BlNumber}|{Scac}.
Description: The system expects the Shipment ID to follow the specific format with a pipe separator.
Resolution: Verify the Shipment ID format matches the required pattern (e.g., KN123456789|KUEH).
Transaction Not Found
No iPaaS Transaction found with a Transaction Number matching the provided ReferenceNumber.
Description: The mapping filter cannot locate a corresponding Transaction in iPaaS. The ReferenceNumber must match an existing iPaaS Transaction Number exactly.
Resolution: Create the Transaction in iPaaS first, then retry the tracking sync.
Missing BL Number
BlNumber (Bill of Lading) is missing or empty.
Description: The TrackingNumber field requires a valid BlNumber from Kuehne+Nagel.
Resolution: Ensure the Kuehne+Nagel shipment has a valid BlNumber before syncing.
Invalid Shipping Method
The ShippingMethod value does not exist in iPaaS.
Description: The static ShippingMethod value (e.g., Flat Rate) must be a configured Shipping Method in iPaaS. The integration does not create new methods automatically.
Resolution: Add the ShippingMethod value to iPaaS configuration before syncing.
Authentication Failure
Invalid Authentication ID or Client Code.
Description: The Kuehne+Nagel API rejected the credentials.
Resolution: Verify credentials are correctly stored in iPaaS credential manager. Contact Kuehne+Nagel Helpdesk if needed.
Testing & Validation
Validation Checklist
ReferenceNumber is present and correctly formatted.
Shipment ID follows the required format {BlNumber}|{Scac}.
A corresponding Transaction exists in iPaaS for the ReferenceNumber.
Authentication credentials are valid and stored securely.
BlNumber (TrackingNumber) is present.
Status fields contain valid date/time values.
Test Scenarios
Scenario 1: Successful Tracking Sync
Create a Transaction in iPaaS with a ReferenceNumber that matches a Kuehne+Nagel shipment. Trigger the sync and verify tracking information (TrackingNumber, ShippingMethod, Status fields) is populated correctly.
Scenario 2: Update Existing Tracking
Modify status fields in Kuehne+Nagel for an existing synced shipment. Verify iPaaS reflects the updated Status Date, Status Time, and Status Message.
Scenario 3: Polling Sync
Subscribe to the shipment/poll event and verify that shipment updates from Kuehne+Nagel are automatically transferred to iPaaS.
Scenario 4: Missing Reference Number (Failure Case)
Attempt to sync a shipment without a ReferenceNumber. Verify the system returns an appropriate error and halts the transfer.
Scenario 5: Transaction Not Found (Failure Case)
Attempt to sync a shipment with a ReferenceNumber that has no matching Transaction in iPaaS. Verify the mapping filter blocks the sync.
Scenario 6: Invalid Shipment ID Format (Failure Case)
Attempt to manually sync with an incorrectly formatted Shipment ID. Verify the system returns a format error.
Additional Notes
A corresponding Transaction must exist in iPaaS before tracking data can be synced.
The Shipment ID format must be {BlNumber}|{Scac} (e.g., KN123456789|KUEH).
ShippingMethod is set statically to Flat Rate for all shipments.
The integration supports both manual sync and polling via the shipment/poll event.
Contact the Kuehne+Nagel Helpdesk at helpdesk@ec.kuehne-nagel.com for API access issues.
API access may vary depending on regional service agreements and contractual terms.