OroCommerce Shipping Tracking From iPaaS.com Mapping Documentation

When a Transaction Tracking Number is created or updated in iPaaS.com, this integration writes a corresponding Shipping Tracking record into OroCommerce against the Sales Order that the tracking number belongs to. The flow runs FROM iPaaS.com TO OroCommerce and is triggered when a Transaction Tracking Number record is created or updated. Its purpose is to keep OroCommerce order shipping lines in sync with the shipping method and tracking number captured in iPaaS.com.

Before You Begin

Confirm the following prerequisites are in place before relying on this flow.

iPaaS.com Requirements

Each Transaction Tracking Number record must have a valid Tracking Number and Shipping Method.
The parent Transaction (Sales Order) must exist and be linked to the tracking number.
The parent Transaction must already have been transferred to OroCommerce before its shipping tracking record is created.

OroCommerce Requirements

The associated Sales Order must already exist in OroCommerce.
The OroCommerce API credentials configured in iPaaS.com must have permission to create and update shipping tracking records.

ID Format

When manually transferring a Transaction Tracking Number from iPaaS.com, enter the iPaaS.com Transaction Tracking Number record ID into the input field on the iPaaS.com manual sync page. The integration reads the portion of that ID before the pipe (|) separator to resolve the parent Transaction, and then resolves the OroCommerce order that the tracking number should be written against.

Example: 197689

External ID Format

The OroCommerce Shipping Tracking record ID is saved as the external ID in iPaaS.com once the record is created.

Example: 288

Custom Field Support

This flow does not support the use of custom fields. All synchronized data is carried by the standard mappings described below.

Mapping Collection Status

Status: Enabled
Trigger Events: Create, Update

The collection applies a mapping filter (see the Mappings section). A record is only transferred when the integration can resolve an existing OroCommerce order for the tracking number's parent Transaction. Tracking numbers whose parent Transaction has no matching OroCommerce order are skipped.

Duplicate or Conflicting Mappings

This is a standalone collection. It does not operate as a parent or child of another collection, and there are no sibling Shipping Tracking collections for this entity. No collision handling between Shipping Tracking collections is required.

System Caveats

OroCommerce Caveats

The record Type must be set to ordershippingtrackings. This value is case-sensitive.
The order relationship Type must be set to orders. This value is case-sensitive.
A Shipping Method (Attributes_Method) is required to create or update the shipping tracking record.
A Shipping Tracking Number (Attributes_Number) is required to create or update the shipping tracking record.
The Order ID is required to associate the tracking information with the corresponding Sales Order. The order that the tracking number resolves to must already exist in OroCommerce.

iPaaS.com Caveats

The transfer depends on the parent Transaction already having been synchronized to OroCommerce as an order. If the integration cannot resolve an external OroCommerce Order ID for the parent Transaction, the tracking record is skipped and no transfer occurs.
OroCommerce authentication uses OAuth 2.0 (Authorization Code grant) to obtain an access token, which authorizes the API requests used during the transfer. Ensure credentials are stored securely within the iPaaS.com credential manager.

Authentication and Security

OroCommerce authentication uses OAuth 2.0 (Authorization Code grant) to obtain an access token, which authorizes the OroCommerce API requests made during each transfer. Credentials are stored securely within the iPaaS.com credential manager.

Integration Flow

The integration processes iPaaS.com Transaction Tracking Number records as follows:

A Transaction Tracking Number is created or updated in iPaaS.com.
The mapping filter extracts the parent Transaction ID from the record ID and resolves the external OroCommerce Order ID for that Transaction.
If no matching OroCommerce order is found, the record is skipped and no transfer occurs.
iPaaS.com authenticates with OroCommerce using OAuth 2.0.
The record type, order relationship type, resolved order ID, shipping method, and tracking number are mapped onto an OroCommerce shipping tracking record.
The shipping tracking record is created or updated under the resolved Sales Order via the OroCommerce API.
The OroCommerce Shipping Tracking record ID is saved as the external ID in iPaaS.com.
Transfer status and any errors are logged in iPaaS.com.

Mappings

Add/Update OroCommerce Shipping Tracking FROM iPaaS.com

Mapping Filter

var orderId = await GetExternalIdAsync(Id.Split('|')[0], "Transaction", SpaceportSystemId);
if(orderId == null)
    return false;
return true;

Filter Description. This filter extracts the parent Transaction ID from the tracking record's ID and looks up the external OroCommerce Order ID for that Transaction. Records pass the filter only when an OroCommerce order is found. When no order exists, the filter returns false and the tracking number is not transferred.

This mapping collection creates or updates a Shipping Tracking record in OroCommerce against the Sales Order resolved from the parent Transaction. It maps the record type, the order relationship, the resolved order ID, the shipping method, and the tracking number.

Mapping Type	Source Field (iPaaS.com)	Destination Field (OroCommerce)	Description
Static	ordershippingtrackings	Type	(Required) Specifies the shipping tracking record type. This value is case-sensitive.
Static	orders	Relationships_Orders_Type	(Required) Specifies the order relationship type. This value is case-sensitive.
Dynamic Formula	`return await GetExternalIdAsync(Id.Split('\\|')[0], "Transaction", SpaceportSystemId);`	Relationships_Orders_Id	(Required) Retrieves the external OroCommerce Order ID by extracting the parent Transaction ID. The returned Order ID is used to associate the tracking number with the corresponding Sales Order.
Field	TrackingNumber	Attributes_Number	(Required) Maps the tracking number.
Field	ShippingMethod	Attributes_Method	(Required) Maps the shipping method.

Error Handling

"Order ID not found" — OroCommerce rejects the create or update request because the resolved Order ID does not exist in OroCommerce. Resolution: ensure the associated Sales Order exists in OroCommerce before the shipping tracking record is created, transferring the order first if needed.
"Missing shipping method" — the shipping method (Attributes_Method) is empty or not mapped. Resolution: ensure the iPaaS.com Shipping Method value is populated and correctly mapped.
"Missing tracking number" — the tracking number (Attributes_Number) is empty or not mapped. Resolution: ensure the iPaaS.com Tracking Number value is populated and correctly mapped.

Testing & Validation

Test Scenarios

Create Shipping Tracking — Sync a new Transaction Tracking Number from iPaaS.com whose parent Transaction has already synchronized to an OroCommerce order. A shipping tracking record should be created under that order in OroCommerce with the expected method and number, and the OroCommerce Shipping Tracking record ID should be saved back to iPaaS.com as the external ID.
Update Existing Shipping Tracking — Update the tracking number or shipping method on an existing iPaaS.com Transaction Tracking Number and confirm the OroCommerce shipping tracking record updates accordingly without creating duplicates.
Order Not Found (failure case) — Create a Transaction Tracking Number whose parent Transaction has no corresponding OroCommerce order and confirm the record is skipped by the mapping filter without error.
Missing Required Fields (failure case) — Attempt to transfer a tracking record without a Shipping Method or Tracking Number and confirm the transfer fails with an appropriate error message.

Validation Checklist

The OroCommerce shipping tracking record is attached to the correct Sales Order.
The shipping method value (Attributes_Method) is present, not empty, and matches the iPaaS.com Transaction Tracking Number record.
The tracking number value (Attributes_Number) is present, not empty, and matches the iPaaS.com Transaction Tracking Number record.
The shipping tracking Type is set to ordershippingtrackings and the order relationship Type is set to orders (both case-sensitive).
The dynamic formula for the order relationship ID returns valid output.
The OroCommerce Shipping Tracking record ID is saved back to iPaaS.com as the external ID.

Additional Notes

Dynamic formulas must return valid output; a null or invalid return may cause the transfer to fail.
The mapping filter prevents shipping tracking creation when the associated order does not exist in OroCommerce.
The type values ordershippingtrackings and orders are case-sensitive.
The parent Transaction ID is read from the portion of the record ID before the pipe separator and is used to resolve the associated OroCommerce order.
Sales Orders must be transferred to OroCommerce before their associated shipping tracking records.