Repository files navigation

This repository contains the source code and configuration ofthecommercetools Connect applications built byfufillmenttools.These areConnect applications built in TypeScript using thecommercetools Connect Application Kit.

The fulfillmenttools Connect app is a certified integration connector that can be used to exchange information between yourcommercetools project and yourfulfillmenttools 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 ConnectMarketplace.

The connector makes use of commercetoolssubscriptions to get notified once theOrderState of an Order is changed toConfirmed.At this state the order information is read and a new order iscreated 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 theShipmentState of the commercetools order.

The following events are used to update the commercetools order:

See the section oncustomization below for details on the used data fields.

The connector also synchronizes information from commercetoolsChannels to create or update a fulfillmenttoolsFacility. Please note that only Channels with theInventorySupply role are synchronized, other roles are ignored. The created fulfillmenttools Facility will be of typeSTORE and have theSHIP_FROM_STORE andPICKUP services enabled. In a future version of this connector, we will support Channel custom fields to configure the Facility type and services.

The Channelkey is used as FacilitytenantFacilityId 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 theproduct documentation for details.

When the commercetools Channel is deleted, the related fulfillmenttools Facility is NOT deleted but only set toOFFLINE. 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.

1. commercetools Composable Commerceaccount andAPI client
2. fulfillmenttoolsaccount andAPI credentials

While you can deploy the connector into your Composable Commerce project using theConnect 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 theConnect API or simply use the Merchant Center.

• Node.js 20 withNVM and npm
• Docker (optional)

$ nvm use

This repository contains the two Connect appsevent andservice along with ashared module.Each app is built and deployed separately.

Theshared module contains functionality that is used by both apps.

All three modules are built in the same way:

$ npm install$ npm run build

Theevent andservice apps can be run locally using one of either goals:

$ npm run start$ npm run start:dev

When running the app indevelopment mode the.env.local file will be used (also for running unit tests).

To run the app inproduction mode, you need to provide a.env file (but do not check this into the git repository).

Donot check actual passwords etc. into the git repository!

When running unit tests the.env.local file will be used with dummy settings.

$ npm runtest

$ 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 thecommercetools documentation for further details.

For each commercetools project we need anAPI 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 setCTP_CLIENT_ID andCTP_CLIENT_SECRET when deploying the app.

The connect apps use a ConfigurationCustom Object identified by containerfft and keyconfiguration with the following settings:

Here's an example of the configuration object. The shipping method with keydhl is mapped to theDHL_V2 carrier. The shipping method with keycc 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 OrderCustom Fields are used by the connect apps and the configured customType 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 theconnector:post-deploy script which is invoked after the app has been deployed into a commercetools environment.

This is automatically done by theconnector:post-deploy script which is invoked after the app has been deployed into a commercetools environment.

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 tofalse when installing the connector.

• 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 containconsole.log statements, usethe included logger instead.

All code in this repository is licensed under theMIT license.

We'd love to have your helping hand on this ecosystem! Please seeCONTRIBUTING.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 ✨!