Feature Overview
A connector is the integration configuration record that links Shipping Manager to a specific shipping broker or third-party logistics (3PL) provider. Each connector holds the credentials, endpoint URLs, and behavioural settings for one broker connection. When you send a waybill, it is transmitted through the connector specified on that waybill.
Connectors are not specific to a single shipping agent. A single connector might handle multiple shipping agents and services offered by the same broker. Shipping agents available through a connector are mapped using the Connector Shipping Agent ID setup, which links Business Central shipping agents to the external identifiers used by the broker's API. The connector also specifies which unit of measure to use for length, weight, and volume when transmitting data — ensuring the broker receives values in the format it expects.
Beyond waybill transmission, connectors can be configured to synchronise warehouse shipments, warehouse receipts, and items with the connected system. Automatic posting of warehouse documents is also supported. The Automatically Create Waybill option causes the system to create a waybill automatically whenever a sales order or warehouse shipment is created for a customer associated with that connector.
Key Facts
| Item | Detail |
|---|---|
| Main pages | Connector List, Connector Card, Connector Shipping Agent IDs |
| Connector types | Defined per connector (extensible enum — specific types added by connector apps, e.g., DHL, GLS, PostNord) |
| Credentials storage | User name and password are stored securely in isolated storage (not as plain text) |
| UOM mapping | Length, Weight, and Volume units of measure are validated against the connector's supported unit set |
| Sync options | Sync Waybills, Sync Items, Sync Warehouse Shipments, Sync Warehouse Receipts |
| Auto-posting | Auto. Post Shipments, Auto. Post Receipts |
| Error notifications | Email for error messages can be set per connector |
| Auto waybill creation | Connector-level flag causes waybills to be created automatically for associated orders |
Getting Started
- Go to Connectors from the Shipping Manager role centre or via search.
- Choose New to create a connector.
- Enter a unique ID (e.g., DHL-DK) and a Description.
- Set the Type to match the broker app installed (e.g., DHL Connector, GLS, PostNord). The available types depend on which connector apps are installed.
- Enter the Email for Error Messages so integration failures are reported to the right person.
- Set the Weight Unit of Measure, Length Unit of Measure, and Volume Unit of Measure to match what the broker's API expects (e.g., KG, CM, M3). These values are validated against a built-in list of supported codes.
- Enter the User Name and Password (or equivalent credentials). These are stored encrypted in isolated storage.
- Set the endpoint URLs if required by the connector type (the specific URL fields vary by connector app).
- Go to Connector Shipping Agent IDs and map each shipping agent and service in Business Central to the corresponding external ID used by the broker.
- Return to Shipping Manager Setup and set this connector as the Default Shipping Connector if it is your primary broker.
Related Features
Waybills are the primary output managed through a connector — every waybill must reference a connector. Packaging Types indirectly affect connectors through unit of measure mapping: the connector's configured UOMs determine how package weight and dimensions are transmitted. Pickup Points are scoped per connector; the list of available pickup points for a given connector is populated by that connector's API integration. Waybill Line Setup references a connector as its primary key, so automatic package line creation is also connector-specific.
User Stories
US-01: Set up a new shipping Agent/broker connector
As a IT Manager
I want to create a connector record for a shipping Agent/broker
So that Shipping Manager can transmit waybills to that Agent/broker via its API
Setup:
- Go to Connectors and choose New.
- Enter a unique ID and a Description for the broker (e.g., ID: GLS-DK, Description: GLS Denmark).
- Set the Type matching the installed broker connector app.
- Enter the Email for Error Messages.
- Set Weight Unit of Measure, Length Unit of Measure, and Volume Unit of Measure to the values supported by the broker API.
- Enter credentials (User Name and Password).
- Enter the required URL fields for the broker API endpoints.
- Save the record.
Note: Supported unit of measure values are validated at entry time. If the code you enter is not in the connector's supported list, an error is shown.
US-02: Map shipping agents to broker-specific product codes
As a IT Manager
I want to map Business Central shipping agents and services to the external IDs used by the broker
So that when a waybill is sent, the correct broker product code is transmitted
Setup:
- Open the Connector card for the relevant connector.
- Choose Connector Shipping Agent IDs on the action bar.
- For each combination of Shipping Agent Code and Shipping Agent Service Code that you use with this broker, create a line.
- Enter the Shipping Agent ID External — the product code used by the broker (e.g., the GLS product code for Express delivery).
- Save. This mapping is used when building the API payload for each waybill.
US-03: Test the connector configuration before going live
As a IT Manager
I want to test the broker API connection before processing real shipments
So that I can verify credentials and endpoint configuration without risking production data
Setup:
- Open the Connector card.
- Use the Test Connection action (available on the connector card).
- The system uses the Tester Type configured on the connector to run a test against the configured endpoints.
- Review the result. If the test fails, check the credentials, URL fields, and unit of measure configuration.
US-04: Configure error notification recipients for a connector
As a IT Manager
I want to set an email address for connector error notifications
So that the right person is alerted immediately when a waybill transmission fails
Setup:
- Open the Connector card.
- Enter one or more email addresses in the Email for Error Messages field.
- When a waybill transmission returns an error, the system sends a notification to this address.
US-05: Manage credentials securely for a connector
As a IT Manager
I want to store broker API credentials securely in Business Central
So that credentials are not visible as plain text and are protected at rest
Setup:
- Open the Connector card.
- Enter the User Name in the User Name field. The value is stored in isolated storage and the field displays as masked.
- Enter the Password in the Password field. The value is encrypted in isolated storage (when encryption is available and the value is under 215 characters).
- Credentials are never stored in plain text in the database.
Note: The User Name and Password fields were replaced by internal key fields (User Name Key and Password Key). If you see these as masked GUIDs, that is expected — the actual values are in isolated storage.
Field Reference
| Field | Where to find it | What it does | Default |
|---|---|---|---|
| ID | Connector Card | Unique identifier for the connector | (required) |
| Description | Connector Card | Human-readable name for the connector | (blank) |
| Type | Connector Card | The broker/connector type (set by the installed connector app) | (required) |
| Email for Error Messages | Connector Card | Email address(es) for integration error alerts | (blank) |
| Length Unit of Measure | Connector Card | Length UOM expected by the broker API (e.g., CM) | (blank) |
| Weight Unit of Measure | Connector Card | Weight UOM expected by the broker API (e.g., KG) | (blank) |
| Volume Unit of Measure | Connector Card | Volume UOM expected by the broker API (e.g., M3) | (blank) |
| Automatically Create Waybill | Connector Card | Auto-creates a waybill when an order is created for this connector | Disabled |
| Sync Waybills | Connector Card | Enables waybill status synchronisation back from the broker | Disabled |
| Sync Items | Connector Card | Enables item data synchronisation to the connected system | Disabled |
| Sync Warehouse Shipments | Connector Card | Sends outbound warehouse shipments to the connected 3PL | Disabled |
| Sync Warehouse Receipts | Connector Card | Sends inbound warehouse receipts to the connected 3PL | Disabled |
| Auto. Post Shipments | Connector Card | Automatically posts warehouse shipments when confirmed by 3PL | Disabled |
| Auto. Post Receipts | Connector Card | Automatically posts warehouse receipts when confirmed by 3PL | Disabled |
| Tester Type | Connector Card | Which test implementation to use when testing the connection | (set by connector app) |
| Shipping Agent ID External | Connector Shipping Agent IDs | The broker's internal product code for the shipping agent + service combination | (required) |