PortalData Export sends shipment data from nShift to your systems when events occur on a shipment or package. You choose which events are sent, when they are sent, what the file contains, and where it goes.
When to use this
Use PortalData Export when an external system needs to receive shipment events from nShift automatically, such as bookings, carrier tracking updates, or Scan App scans.
Key concepts
-
Export setting: the configuration that defines which events are exported, when they are sent, what the file contains, and where it goes.
-
Event origin: the source of an event, such as the booking system, a carrier, or the nShift Scan App.
-
Installation: the nShift installation whose shipments are exported.
-
Out-profile: the destination that files are forwarded to, such as an FTP server, an HTTP endpoint, email, or SMS.
- Batching: collecting events and sending them together on a schedule instead of sending one file per event.
Request a PortalData Export
Request a PortalData Export to have nShift create an export setting that sends shipment events to your system.
Important:
Only nShift employees can create and edit export settings. To get one, submit a request to customer service.
Steps
- Decide which events to export. See Event origins, Event types, and Filters.
- Decide when files are sent. See Delivery timing.
- Decide what the file contains. See File options and Additional details.
- Decide where files are sent. See Destination types and Delivery methods.
- Submit a request to customer service with the information in the request information table.
nShift creates the export setting and activates it when you confirm that the destination is ready to receive files. Nothing is exported until the setting is active.
Information required for setup
To see the data and fields in nShift's standard file format, see Standard Portal Export setup.
The request information to send to nShift customer service:
| Item | What to include |
|---|---|
| Username | Your nShift Portal username, or the company UUID |
| Installations | The ID of each installation to export |
| Events | The event origins and event types that trigger a file |
| Carriers and services | Optional. The carriers or services to include or exclude |
| Timing | Immediately per event, or the fixed times or interval, and your time zone |
| File format | The file type, and an example of the layout or an XSLT file if you have one, or a request for unprocessed XML |
| File name | The naming convention, if the files need specific names |
| Destination | The destination type and its details. For email, SMS, and file output, include an example of the template. For HTTP, include the API documentation, an example POST request with headers and payload, the endpoint, and the authentication method: API key or token, OAuth with client ID and secret or JSON Web Token, or basic authentication |
Event origins
Event origins decide which kind of event triggers a file. You can select more than one.
| Value | Meaning |
|---|---|
| ShipmentInsert | One export when a shipment is created |
| BookAndPrint | Events from the booking system, including shipment updates after submit. This is the default |
| CarrierData | Tracking events received from carriers |
| ScanApp | Scans made with the nShift Scan App. Required to filter by action center |
| ClientData | Events sent in by the customer |
Important:
ShipmentInsert and BookAndPrint cannot be selected together. A shipment insert already contains the booking events, so the booking would be exported twice.
Event types
Event types narrow the export to certain kinds of events. An event is exported if it has any of the selected types. If you select none, all types are exported.
| Value | Meaning |
|---|---|
| TrackAndTrace | Tracking status events |
| Measurement | Events with weight or dimensions |
| Price | Price events |
Filters
Filters narrow down which events are exported.
| Filter | What it limits |
|---|---|
| Installations | Required for customer companies. Only shipments of the selected installations are exported |
| Event max age | Events older than this number of days are not exported. The default is 365 days. Does not apply to ShipmentInsert |
| Actors | Sender accounts within the selected installations |
| Carriers | The carriers to include or exclude |
| Services | The services of the selected carriers to include or exclude. Shown as Products in the export setting |
| Action centers | Scan App action centers. Only available with the ScanApp origin |
| Orphan shipments | Scans that could not be matched to a shipment |
| Normalized categories and statuses | Only events with these normalized values, for example all delivered events across carriers. The categories are System, In transit, Delivered, Information, Carrier exception, Receiver exception, and Sender exception |
| Status kind and status text | Events matched by numeric event kind ID, or by exact and case-sensitive event name, per event origin |
| Advanced filtering | A custom JavaScript filter for requirements the other filters cannot express. nShift writes it. Not applied to ShipmentInsert |
For actors, carriers, and services, an Exclude switch reverses the list so that everything except the selection is exported.
Delivery timing
Delivery timing decides when files are sent.
| Option | Meaning |
|---|---|
| Immediately | One file per event, sent when the event occurs. This is the default |
| At fixed times | Events are collected and sent together at set times of day in your time zone, for example 06:00 and 18:30 |
| At fixed intervals | Events are collected and sent together every set number of minutes |
| Grouped | Events are collected, grouped by a key such as a customer reference, and sent as one file per group on a schedule. nShift sets up the grouping with custom JavaScript |
Destination types
| Type | Notes |
|---|---|
| Plain text only | |
| SMS | Messages over 160 characters are sent as an extra SMS |
| FTP | FTP and SFTP are both supported. Files can be in the standard format, a customized format, or unprocessed |
| HTTP | POST requests to a single endpoint. Authentication can use basic authentication, bearer token, or a custom header with key and value |
Delivery methods
| Method | Meaning |
|---|---|
| Gateway | Each file is sent immediately to every selected out-profile. This is the default |
| JobManager | Files are queued and sent in jobs per out-profile |
Note: Email and SMS out-profiles do not work with unprocessed XML or with JobManager.
File options
| Option | Meaning |
|---|---|
| Standard format | A CSV or XML file in nShift's standard layout. See Standard Portal Export setup |
| Customized format | A file produced with an XSLT file that defines the layout |
| Unprocessed XML | The nShift export XML sent as is, with no transformation |
| File type | xml, json, csv, edi, or lst. Must match what the transformation produces |
| File name | An optional name template built from tokens such as the setting ID, event barcode, or date. The template must include the file extension. If it is empty, a unique name is generated |
| Compress files | Each file is zipped. Only available with a transformation |
| Single export | None exports every matching event. Shipment sends only the first file per shipment. EventLevel sends only the first file per package, or per shipment for shipment-level events |
| Units | Length, volume, and weight are converted to the units you need, with 0 to 4 decimals. Internally, values are in millimeters, grams, and cubic millimeters |
Additional details
Additional details add extra data to the export XML before it is transformed.
| Value | Adds |
|---|---|
| Driver | Driver name, email, and phone on the event |
| Base64Signature | The signature image embedded as base64. The link is always present |
| Base64Image | The event image, for example a proof-of-delivery photo, embedded as base64 |
| PriceCalculation | The full carrier price calculation document |
| ShipmentDetails | Extra shipment detail collections |
| ReturnLabelUrl | Public URLs and document types for shipment and package documents, such as return labels |
| Articles | Article lists at shipment and package level |
Note: Base64 images and signatures make files much larger. Request them only when the receiving system needs them.