This repository contains the source code and configuration of the commercetools Connect applications built by fufillmenttools. These are Connect applications built in TypeScript using the commercetools Connect Application Kit.
The fulfillmenttools Connect app is a certified integration connector that can be used to exchange information between your commercetools project and your fulfillmenttools project. While fully customizable it is very easy to setup and deploy so you can start fulfilling orders from you e-commerce system without a complicated integration process. It is available in the commercetools Connect Marketplace.
The connector makes use of commercetools subscriptions to get notified once the OrderState of an Order is changed to Confirmed
.
At this state the order information is read and a new order is created in the fulfillmenttools platform.
Depending on the shipping method of the commercetools order, either a Ship-from-Store order or a Click&Collect order is created in fulfillmenttools.
The fulfillmenttools distributed order management system (DOMS) will process the new order and (based on its configuration) route the order to the best fulfillment location. Then the actual fulfillment process of picking, packing, and shipping can be executed in the selected location.
As a result of the order routing process, a pick job will be created in the fulfillmenttools platform. During the life time of the pick job (picking started, finished) and the corresponding handover job (created, handed over) the platform will send out events with status updates. This information is processed by the connector to update custom fields and ultimately the ShipmentState of the commercetools order.
The following events are used to update the commercetools order:
Event | Action |
---|---|
ORDER_CREATED |
Set custom field fft_order_id |
PICK_JOB_CREATED |
Set custom fields fft_pickjob_id , fft_short_id , and fft_facility_id |
PICK_JOB_PICKING_FINISHED |
Set custom field fft_load_units_amount |
HANDOVERJOB_CREATED |
Set custom field fft_handoverjob_id , update ShipmentState to Ready |
HANDOVERJOB_HANDED_OVER |
Update ShipmentState to Shipped |
See the section on customization below for details on the used data fields.
The connector also synchronizes information from commercetools Channels to create or update a fulfillmenttools Facility. Please note that only Channels with the InventorySupply
role are synchronized, other roles are ignored. The created fulfillmenttools Facility will be of type STORE
and have the SHIP_FROM_STORE
and PICKUP
services enabled. In a future version of this connector, we will support Channel custom fields to configure the Facility type and services.
The Channel key
is used as Facility tenantFacilityId
to establish a relationship between the two entities.
When the commercetools Channel has an address, it is used as the Facility's address, otherwise a default is used, because an address is mandatory for a fulfillmenttools Facility. In this case you may have to update/edit the Facility with the correct data, please see the product documentation for details.
When the commercetools Channel is deleted, the related fulfillmenttools Facility is NOT deleted but only set to OFFLINE
. This is to prevent accidental deletion of operational data. You can still delete the Facility via the API or in the backoffice, should you wish to do so.
Currently, the synchronization between Channels and Facilities is in one direction only, i.e. changes made to a fulfillmenttools Facility will not be forwarded to related commercetools Channel.
- commercetools Composable Commerce account and API client
- fulfillmenttools account and API credentials
While you can deploy the connector into your Composable Commerce project using the Connect API, the easiest way to deploy it is using the Merchant Center. In your project go to the Connect marketplace, select the fulfillmenttools Connector, click "Install" and follow the steps for deployment.
Again, you can undeploy the connector from your project using the Connect API or simply use the Merchant Center.
$ nvm use
This repository contains the two Connect apps event
and service
along with a shared
module.
Each app is built and deployed separately.
The shared
module contains functionality that is used by both apps.
All three modules are built in the same way:
$ npm install
$ npm run build
The event
and service
apps can be run locally using one of either goals:
$ npm run start
$ npm run start:dev
When running the app in development mode the .env.local
file will be used (also for running unit tests).
To run the app in production mode, you need to provide a .env
file (but do not check this into the git repository).
Do not check actual passwords etc. into the git repository!
When running unit tests the .env.local
file will be used with dummy settings.
$ npm run test
$ npm run lint
This section describes the necessary steps to integrate the connector with commercetools and fulfillmenttools, so that
- order information is forwarded from commercetools to fulfillmenttools, and
- fulfillment status updates are sent back from fulfillmenttools to commercetools.
Have a look at the commercetools documentation for further details.
For each commercetools project we need an API client (managed in Merchant Center under Settings > Developer settings) with at least the following scopes:
manage_orders
manage_states
manage_subscriptions
manage_types
view_products
view_project_settings
view_published_products
view_stores
Use the received credentials to set CTP_CLIENT_ID
and CTP_CLIENT_SECRET
when deploying the app.
The connect apps use a Configuration Custom Object identified by container fft
and key configuration
with the following settings:
Setting | Description |
---|---|
collectChannelReferenceFieldName |
Name of custom field in a commercetools Order that holds the key of a channel that should be used for a Click&Collect order. This field can freely be defined by the customer. When the fulfillmenttools connect app receives a commercetools Order it checks if this custom field is present. If so, the value of the field is used to identify the fulfillmenttools Facility for a C&C order. |
orderCustomTypeKey |
Name of the commercetools Custom Type that is used for the Orders. This can freely be chosen by the customer. When the fulfillmenttools connect app receives a commercetools Order it checks if it already has this type. Additional Custom Fields are then added to this type and filled with information from the fulfillmenttools process. |
shippingMethodMapping |
This is a map where the key is the key of a commercetools Shipping Method. For each shipping method you want to use in your commercetools project you have to define a mapping. The value object of the mapping is used to select the Delivery Preferences of the fulfillmenttools Order. |
Here's an example of the configuration object. The shipping method with key dhl
is mapped to the DHL_V2
carrier. The shipping method with key cc
designates a Click&Collect order. In commercetools the shipping methods keys can be freely defined while the fulfillmenttools carrier keys are fixed by the platform:
{
"collectChannelReferenceFieldName": "fft_supply_channel_for_click_and_collect",
"orderCustomTypeKey": "orderCustomFields",
"shippingMethodMapping": {
"dhl": {
"serviceType": "SHIPPING",
"serviceLevel": "DELIVERY",
"carriers": ["DHL_V2"]
},
"gls": {
"serviceType": "SHIPPING",
"serviceLevel": "DELIVERY",
"carriers": ["GLS"]
},
"cc": {
"serviceType": "CLICK_AND_COLLECT"
}
}
}
The following Order Custom Fields are used by the connect apps and the configured custom Type is automatically extended with these fields:
fft_order_id
fft_pickjob_id
fft_load_units_amount
fft_handover_job_id
fft_shortid
fft_facility_id
fft_parcels
This is automatically done byΒ the connector:post-deploy
script which is invoked after the app has been deployed into a commercetools environment.
This is automatically done byΒ the connector:post-deploy
script which is invoked after the app has been deployed into a commercetools environment.
- Connector solution should be lightweight in nature
- Connector solutions should follow test driven development. Unit , Integration (& E2E) tests should be included and successfully passed to be used
- No hardcoding of customer related config. If needed, values in an environment file which should not be maintained in repository
- Connector solution should be supported with detailed documentation
- Connectors should be point to point in nature, currently doesnt support any persistence capabilities apart from in memory persistence
- Connector solution should use open source technologies, although connector itself can be private for specific customer(s)
- Code should not contain
console.log
statements, use the included logger instead.
All code in this repository is licensed under the MIT license.
We'd love to have your helping hand on this ecosystem! Please see CONTRIBUTING.md for more information on our guidelines.
Thanks for all your contributions and efforts towards improving the fulfillmenttools commercetools Connect app. We thank you for being part of our β¨ community β¨!