commercetools connect

The fulfillmenttools connector app in the commercetools marketplace is a certified integration connector that synchronizes information between your commercetools and your fulfillmenttools project. It's fully customizable and easy to set up and deploy, so you can start fulfilling orders from your eCommerce system without a complicated integration process.

commercetools Connect lets you add functionality to your project without buying and maintaining dedicated hosting or runtime environments.

Our fulfillmenttools connector app is published as open source under the MIT license. You can check it out from our GitHub repository.

Receiving orders at fulfillmenttools

The fulfillmenttools connector app uses commercetools subscriptions to get notified when the commercetools OrderState of an order is changed to Confirmed. With this status, the commercetools order is ready, and a new order is created in fulfillmenttools.

Depending on the shipping method of the commercetools order, either a ship-from-store or a click-and-collect order is created in fulfillmenttools.

fulfillmenttools will process the new order and (based on its configuration) route the order to the best fulfillment location. Then the selected location executes the fulfillment process: picking, packing, and shipping.

Fulfillment status update at commercetools

As a result of the order routing process, a pick job will be created in fulfillmenttools. During the pick job lifecycle (picking started, finished) and the corresponding handover job (created, handed over), fulfillmenttools will send out events with status updates. The fulfillmenttools connector app processes this information to update the custom fields and the ShipmentState of the commercetools order.

Events for the commercetools order

The following fulfillmenttools 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_shortid, and fft_facility_id
PICK_JOB_PICKING_FINISHED	Set custom field fft_load_units_amount
HANDOVERJOB_CREATED	Set custom field fft_handover_job_id, update ShipmentState to Ready
HANDOVERJOB_HANDED_OVER	Update ShipmentState to Shipped

See the Customization section for details on the data fields used.

Channels in commercetools

The connector also synchronizes information from commercetools channels to create or update a fulfillmenttools facility. 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's used as the facility's address. Otherwise, it uses a default, because an address is mandatory for a fulfillmenttools facility. In this case, you'll need to update/edit the facility with the correct data. See the facility article in our documentation for details.

When you delete the commercetools channel, the related fulfillmenttools facility is not deleted. It is only set to OFFLINE. This prevents accidental deletion of operational data. You can still delete the facility via the API or in Backoffice.

Currently, synchronization between channels and facilities is one-way. Any changes made to a fulfillmenttools facility will not be forwarded to the related commercetools channel.

Deploying the connection

Prerequisites

• commercetools core commerce account and commercetools API client

• fulfillmenttools account and API credentials

Installing the connector

While you can deploy the connector into your core commerce project using the Connect API, the easiest way is to use the Merchant Center.

In your project go to the Connect marketplace, select the fulfillmenttools Connector, click Install and follow the deployment steps.

Uninstalling the connector

You can undeploy the connector from your project using the Connect API or use the Merchant Center.

Development

Prerequisites

• Node.js 20 with NVM and npm

• Docker (optional)

Setup

$ nvm use

Building and running the apps locally

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 either of these 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, provide a .env file (but don't check this into the Git repository).

Don't check actual passwords into the Git repository.

Running unit tests

When running unit tests, the .env.local file uses placeholder settings.

$ npm run test

Linting

$ npm run lint

Integration of commercetools and fulfillmenttools

This section describes the steps to integrate the connector with commercetools and fulfillmenttools so order information is forwarded from commercetools to fulfillmenttools, and fulfillment status updates are sent back from fulfillmenttools to commercetools.

See the commercetools documentation for further details.

commercetools API client

For each commercetools project, we need an API client. Manage this in the commercetools Merchant Center. Go to Settings, and then click Developer settings. The API client needs to have 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.

commercetools customization

The connect apps use a configuration custom object identified by container fft and key configuration with the following settings:

Setting	Description
collectChannelReferenceFieldName	Name of the custom field in a commercetools Order that holds the key of a channel to use for a click-and-collect order. You can define this field as you wish. When the fulfillmenttools Connect app receives a commercetools order, it checks if this custom field is present. If so, it uses the field value to identify the fulfillmenttools facility for a click-and-collect order.
orderCustomTypeKey	Name of the commercetools custom type used for orders. You can choose this name. When the fulfillmenttools Connect app receives a commercetools order, it checks if it already has this type. It then adds additional custom fields to this type and fills them with information from the fulfillmenttools process.
shippingMethodMapping	This maps to 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 mapping's value object selects the delivery preferences of the fulfillmenttools order.

Below is 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-and-collect order. In commercetools, the shipping method keys can be freely defined, while the fulfillmenttools carrier keys are fixed:

{
  "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

A commercetools subscription is automatically set up by the connector:post-deploy script, which is invoked after the app has been deployed into a commercetools environment.

A fulfillmenttools subscription is automatically set up by the connector:post-deploy script, which is invoked after the app has been deployed into a commercetools environment.

Deactivate events/services

By default, all three events/services are activated (order sync, facility sync, and status updates). However, you can deactivate each one individually by setting the corresponding value to false when installing the connector.

Variable	Description
FEAT_ORDERSYNC_ACTIVE	Set to false to deactivate the order sync (default is true)
FEAT_CHANNELSYNC_ACTIVE	Set to false to deactivate the channel sync (default is true)
FEAT_STATUSUPDATES_ACTIVE	Set to false to deactivate the status updates (default is true)

Architecture principles

Below are the architectural principles for building a commercetools Connect application:

• Connector solutions should be lightweight.

• Connector solutions should follow test-driven development. Include unit, integration, and end-to-end tests, and ensure they pass before use.

• No hardcoding of customer-related configuration. If needed, values should be in an environment file and shouldn't be maintained in the repository.

• Connector solution should be supported with detailed documentation.

• Connectors should be point-to-point in nature. Currently, they don't support any persistence capabilities beyond in-memory persistence.

• The connector solution should use open-source technologies, although the connector itself can be private for specific customer(s).

• Code shouldn't contain console.log statements. Use the included logger instead.