Scenario: add a new 3PL integration type
Lesson 20 of 25 8 min read
Set up a config-driven integration type for a new 3PL from start to finish, then switch it on for the first customer.
This lesson puts the whole course together. You will follow one implementer setting up a brand-new config-driven integration type for a 3PL, from the routing through to the first customer's live orders, with a checkpoint at each step.
Northbank Fulfilment joins Supply Lens
Northbank Fulfilment is a 3PL with a JSON API. Hilltop Coffee wants to send it warehouse orders and receive shipments back. There is no coded integration and no shared base. Your developer has written the bodies. You are setting up the type northbank-wms, named Northbank WMS.
Hilltop's flow will be: Unleashed sends a warehouse order → create map → send profile → Northbank; Northbank's shipments → receive profile → parse map → a Shipment Document in Supply Lens.
The plan
Step 1: the integration type and its routing
In Administration → Integrations → Integration Types, select Add. Enter the id northbank-wms and the name Northbank WMS. In the Routing section, tick each message type the integration does: Create, Send, Receive and Parse. Choose the service for each row, usually Main integrations service. Select Create.
Then:
- On the Routing tab, check every supported row shows Live.
- Do not add module routes on the Modules tab, and do not add the type to a module group.
- On the Details tab, set Categories, or organisations will not see the type in the add integration dialog.
Checkpoint: four rows, all Live. A row that is supported but Not routed loses its messages.
Step 2: the client profile
In Administration → Maps & Profiles → Client Profiles, select Add. Key: northbank-wms (the type id is allowed; a coded integration's client name is not). Paste the body with Northbank's base address, rate limit, retry rules and sign-in type. Validate, then Save.
Checkpoint: no validation errors. Remember: no versions, so this is live for everyone at once.
Step 3: the connect profile
In Connect Profiles, select Add. Integration type: Northbank WMS. Keep In service on. The body must make at least one call to prove the credentials work. Validate, then Save.
Step 4: the settings shape
Northbank needs each customer's client code. In Settings Schemas, select Add, choose Northbank WMS, leave Document type empty (connection settings), name it, add the client code under Own properties, and Save. Check What a tenant will see.
Step 5: maps and profiles for Hilltop Coffee
Open Hilltop Coffee, then Settings → Maps & Profiles. For each kind, open the list, select Add, choose Northbank WMS and the document type, keep Layers onto as Nothing: this holds a whole specification, paste the body and Create draft. Then Validate, Save and Publish each one.
| Message type | Kind | Document type |
|---|---|---|
| Create | Create map | Warehouse orders |
| Send | Send profile | Warehouse orders |
| Receive | Receive profile | Shipments |
| Parse | Parse map | Shipments |
Publish the create map before the send profile
A send profile is checked against the create maps that feed it when you publish it. Publishing the create map first gives that check something to check against.
Step 6: prove what runs
On Hilltop's overview, open What actually runs and resolve each of the four kinds for Northbank WMS. Each should show Hilltop's own version 1, with no overlays. If any says Nothing is configured for that., that one is still a draft.
Step 7: Hilltop adds the integration
Hilltop (or you, on their behalf) adds the integration in Settings → Integration setup → Integrations → Add integration, fills in the client code and credentials, and the connect profile checks them. Hilltop then sets up the Mappings that send warehouse orders to the new Integration.
Recap
- Order: type and routing, client profile, connect profile, settings shape, then per-organisation maps and profiles.
- Config-driven types need routing and a category, but no module routes or module groups.
- Each supported message type needs a published map or profile of the matching kind.
- Publish create maps before the send profiles they feed.
- Finish by proving each kind with What actually runs.
Your progress is saved in this browser. Create a free account to keep it everywhere, take quizzes and earn certificates.