Purpose: This article provides an overview of how Integrate Salesforce B2C Commerce using the Sendcloud LINK cartridge Version 21.1.0
1. About
The Sendcloud LINK cartridge contains all modifications needed to integrate Salesforce B2C Commerce with Sendcloud. Clients may use this LINK cartridge to ensure a quick and hassle-free time-to-market.
Component overview
2.1 Functional overview
2.1.1 Creating connections between Salesforce B2b Commerce and Sendcloud
A Business Manager module has been added to facilitate creating a connection between Salesforce B2B Commerce and Sendcloud.
2.1.2 Synchronize orders with Sendcloud
All new orders will be exported to Sendcloud. Any orders created before the integration with Sendcloud was established can optionally also be exported to Sendcloud. Sendcloud can then process the orders (such as printing labels and shipping them) and send status updates to Salesforce B2C Commerce.
2.1.3 Service points
The Sendcloud service point picker can be enabled for a shipping method. This ensures the customer can select service points from those carriers configured in Sendcloud, and that the correct service point details will be part of the order export to Sendcloud.
2.1.4 Checkout
In Sendcloud the client can configure delivery methods to be used in the checkout. This configuration can be published to Salesforce B2C Commerce where this will be imported as standard shipping methods. This ensures the customer can use those delivery methods configured in Checkout, and that the correct details will be part of the order export to Sendcloud.
2.1.5 Internationalization
Extra product attributes have been added which are needed for customs declarations when shipping outside the EU.
2.2 Use cases
With the integration, the cartridge supports the use case of a Salesforce B2C Commerce user who wants to improve the shipping process by allowing the consumers to select their preferred delivery date and carrier in the checkout.It is also supported to select a service point to which the ordered items will be sent to.
The orders will be sent to Sendcloud. The labels for the orders can be created in Sendcloud directly.
The systems that have this functionality are often enterprise resource planning systems or warehouse management systems. Sendcloud offers plug-and-play integrations as well as an API to connect with those systems. A full list of systems that are connected with Sendcloud can be found at: https://app.sendcloud.sc/v2/settings/integrations/manage.
2.3 Limitations, Constraints
2.3.1 Service points
Currently, it is not possible to configure a service point delivery method in the Sendcloud checkout. If service points are to be supported on the storefront a shipping method should be configured or imported manually in the Business Manager.
2.3.2 Currencies
The delivery methods configured in Sendcloud do not contain any shipping cost information, so are also not linked to any currency. When importing a checkout configuration in Salesforce B2C Commerce the same Sendcloud delivery method is imported multiple times: once for each enabled currency.
- When new currencies are added it will be needed to re-publish the checkout configuration.
After importing new delivery methods in Salesforce B2C Commerce the shipping cost will be set to 0.
2.3.3 Locales
A single ‘external title’ can be specified for delivery methods configured in Sendcloud, this name will be imported in the shipping method in Salesforce B2C Commerce as the display name in the default locale.
If localized display names are desired these should be configured in the Business Manager after the checkout configuration is imported in Salesforce B2C Commerce. Re-publishing the checkout configuration will not overwrite the localized display names for existing shipping methods.
The service point picker only supports some locales. If another locale is used in the storefront this will be mapped to a locale supported by the service point picker. If it cannot be mapped then the default locale as configured in the site preferences will be used for the service point picker.
2.3.4 Multiple shipments
Multiple shipments per order are not fully supported, some modifications will be needed to support this.
2.4 Compatibility
This LINK cartridge is developed and tested with B2C Commerce version 21.7, compatibility mode 21.7, and SFRA version 6.0.0. All locales are supported, except for what is mentioned in section 2.3.3.
2.5 Privacy, Payment
This cartridge exports order data to Sendcloud. Among others this contains the customer’s name, email address and shipping address.
3. Implementation Guide
3.1 Setup of Business Manager
3.1.1 Upload cartridges
First install the node modules using this command: npm install
Build clientside .css and .js files using this Node command: npm run build
Add a jw.json file to the root of the link folder and upload the int_sendcloud and bm_sendcloud cartridges to your Salesforce B2C Commerce instance using this command: npm run uploadCartridge
3.1.2 Cartridge path
In the Business Manager go to Administration > Sites > Manage Sites > [Site] > Settings and add the int_sendcloud cartridge to the storefront cartridge path. Place this cartridge somewhere between your storefront cartridge and the app_storefront_base cartridge.
Go to Administration > Sites > Manage Sites > Business Manager and add the bm_sendcloud cartridge to the cartridge path.
3.1.3 Metadata
- In the metadata/site_import_sendcloud/sites folder rename the RefArch folder to the ID of your site, or remove this folder if you do not want to import a shipping method for service points.
- In the metadata/site_import_sendcloud/jobs.xml file rename RefArch to the ID of your site.
- ZIP the metadata/site_import_sendcloud folder and import the resulting .zip via Administration > Site Development > Site Import & Export. This will import the needed metadata, the jobs and a service.
3.2 Configuration
3.2.1 Site preferences
Go to Merchant Tools > Site Preferences > Custom Preferences > Sendcloud to configure the site preferences needed for the integration with Sendcloud. The following preferences can be set:
Preference |
Description |
sendcloudCheckoutImportShippingMethods |
Specifies if the Sendcloud checkout delivery methods should be imported or not. Usually, this will be enabled on all instances except production (which will get the delivery methods from staging using data replication). |
sendcloudCheckoutShippingMethodDefaultEnabled | Specifies if new shipping methods published by Sendcloud checkout are imported in Salesforce B2C Commerce as enabled or disabled. |
sendcloudMaxFailedAttempts | The maximum number of order export attempts that will be made to Sendcloud. If the order export to Sendcloud still fails after this number of attempts the order will not be exported to Sendcloud. The default value is 3. |
sendcloudLogApiOrderNotes |
Indicates if Sendcloud API requests and responses should be logged as notes on the order. When storefront protection is enabled this should be set to ‘storefront’, otherwise any username can be used. |
sendcloudNotificationUsername |
The username with which Sendcloud will connect to Salesforce B2C Commerce when sending webhook notifications. When storefront protection is enabled this should be set to ‘storefront’, otherwise any username can be used. |
sendcloudNotificationPassword |
The username with which Sendcloud will connect to Salesforce B2C Commerce when sending webhook notifications. When storefront protection is enabled this should be set to ‘storefront’, otherwise any username can be used. |
sendcloudPointPickerDefaultCountry |
The default country for the service point picker. The default is ‘nl’. |
sendcloudPointPickerDefaultLocale | The default UI language for the service point picker if the current locale cannot be matched to any of the locales supported by the service point picker UI. |
3.2.2 Jobs
During the metadata import see 3.1.3 these two jobs have been imported:
• Sendcloud - export orders
• Sendcloud - process notifications
Both these jobs are scheduled to run every five minutes for every storefront, if desired this can be changed in the Business Manager at Administration > Operations > Jobs.
These jobs have some parameters. Both can be disabled if needed. On the export orders job also these parameters can be configured:
• orderAgeDaysLimit: All orders created this number of days in the past will be eligible for export to Sendcloud. The default is 30, so that when Sendcloud is initially integrated with your storefront all orders up to 30 days ago will be sent to Sendcloud.
• batchSize: The number of orders that will be exported to Sendcloud in a single batch. The default is 10. If needed multiple batches will be executed within a single job run.
3.2.3 Permissions
In the Business Manager go to Administration > Organization > Roles & Permissions > Administrator > Business Manager Modules > Sites, scroll to the bottom, enable write access for the Sendcloud module and click Update.
3.2.4 Connection to Sendcloud
- In the Business Manager go to Merchant Tools > Site Preferences > Sendcloud and click on the Connect button.
- This will open a new browser tab with the Sendcloud panel where you are asked to approve the connection between Salesforce B2C Commerce and Sendcloud. After accepting this connection a webhook notification will be sent to Salesforce B2C Commerce, once that is processed by the ‘Sendcloud - process notifications’ job the connection will have been established.
- On PIG instances (development, staging and production) this job is scheduled to run automatically every five minutes, on sandboxes, it will be needed to manually start this job.
- On every instance that needs a connection between Salesforce B2C Commerce and Sendcloud this connection will need to be established in this way, so among others on both staging and production, this connection should be made.
- In the Sendcloud panel at Settings > Integrations all connections are listed.
3.2.5 Shipping methods
After publishing the Sendcloud checkout configuration (see section 3.3.2) you can edit some aspects of the generated shipping methods in the Business Manager. Go to Merchant Tools > Ordering > Shipping Methods and specify localized display names, descriptions, enabled flag, and shipping costs as desired.
3.2.6 Additional sites
If additional sites are used then the site preferences and the connection to Sendcloud should be set for all sites. The ‘Sendcloud - export orders’ job can be configured to run for multiple sites. This is not supported for the ‘Sendcloud - process notifications’ job, as some job parameters contain site-specific folder paths. For this job, you will need to duplicate the entire flow with all steps.
3.3 Sendcloud Panel
3.3.1 Service points
To enable service points open the Sendcloud Panel and go to Setting > Integrations. Click Edit on the integration and enable the ‘Service Points’ checkbox and the checkboxes of the carriers you want to support. Click ‘Save’ to submit your changes.
A webhook notification will be sent to Salesforce B2C Commerce, after this has been processed by the ‘Sendcloud - process notifications’ job the service point shipping method should be visible in the checkout.
3.3.2 Dynamic Checkout
In the Sendcloud Panel go to Dynamic Checkout to configure the delivery methods. Please refer to this article for more information on delivery methods.
Once this configuration is complete press ‘Publish’. In the Business Manager run the ‘Sendcloud - process notifications’ job to import the checkout configuration as shipping methods.
For configuring a checkout configuration on the connection of the Salesforce B2C Commerce production environment there are two possibilities:
1. Set the value of the sendcloudCheckoutImportShippingMethods
site preference to true for production and configure and publish the checkout configuration also for the production connection. In this case replication of shipping methods should be disabled as production will receive its own shipping methods from Sendcloud. Any changes to shipping methods as mentioned in 3.2.5 will need to be done in the production Business Manager.
2. Set the value of the sendcloudCheckoutImportShippingMethods
site preference to false for production and configure the shipping methods to be used on production on the staging connection in Sendcloud. In this case, ensure that shipping methods are part of the scheduled data replication from staging to production. This option is recommended.
3.4 External Interfaces
3.4.1 Sendcloud shipment API
Orders in Salesforce B2C Commerce are exported to Sendcloud by calling the Sendcloud Shipment API at: https://app.sendcloud.sc/api/v2/integrations/{id}/shipments.
Read more here: https://docs.sendcloud.sc/api/v2/shipping/#inserting-shipments-into-an-integration for the documentation. As mentioned in this documentation this API endpoint is opt-in only, but it will be enabled for the integration with Salesforce B2C Commerce.
3.4.2 Webhook
Sendcloud will send various messages to Salesforce B2C Commerce using webhooks, see https://docs.sendcloud.sc/api/v2/shipping/#webhooks. Upon receival, these messages will be stored in custom objects of type SendcloudNotification.
3.5 Firewall Requirements
Both the interfaces listed in section 3.4 are using https, so port 443. No firewall changes are needed at Salesforce B2C Commerce or Sendcloud.
4. Testing
4.1 Creating connection between Salesforce B2C Commerce and Sendcloud
Once the steps mentioned in section 3.2.4 are completed the details of the connection can be seen in the Business Manager at Merchant Tools > Custom Objects > Custom Object Manager, select object type 'SendcloudConnection' and press Find.
A single instance of this custom object should be present, with ID ‘CONNECTION’. Opening this custom object will show the details of the connection.
4.2 Synchronize orders with Sendcloud
Place an order and mark it as ‘Exported’, after this the order is eligible for export to Sendcloud. Run the job ‘Sendcloud - export orders’. Open the order in the Business Manager and on the Attributes tab the ‘Sendcloud export status’ attribute should be set to ‘Exported’. Also, this order should now be visible in the Sendcould panel.
4.3 Service points
Once the steps mentioned in section 3.3.1 are completed open the details of the SendcloudConnection custom object (see 4.1).
Here the two attributes for the service point picker should match what you have configured in the Sendcloud panel. Also, the service point picker should be available in the checkout on the storefront.
4.4 Checkout
Once the steps mentioned in section 3.3.2 are completed the shipping methods should be visible in the Business Manager at Merchant Tools > Ordering > Shipping Methods. The shipping methods imported from the Sendcloud checkout configuration will have a UUID followed by a currency code as ID.
The shipping methods should also be available in the checkout on the storefront, but of course, only those that are applicable for the specified shipping address.
4.5 Internationalization
Three extra product attributes should be visible when opening a product in the Business Manager: ‘Country of origin’, ‘Harmonized System Code’ and ‘Weight (kilograms)’.
5. Operations, Maintenance
5.1 Data Storage
The data stored in Salesforce B2C Commerce consists of:
• Site preference values.
• Custom attribute values on Order, Product, Shipment and Shipping Method.
• One instance of the SendcloudConnection
custom object per site. This will not be cleaned up as it is needed during the lifetime of the connection between Salesforce B2C Commerce and Sendcloud.
• Multiple instances of the SendcloudNotification
custom object. These will be created when webhook notifications are received from Sendcloud, and will be removed after they have been processed by the scheduled job ‘Sendcloud - process notifications’.
5.2 Availability
5.2.1 Uptime
The uptime of the Sendcloud platform is being measured daily and can be viewed on:
https://status.sendcloud.com/.
(This shows the uptime of the Sendcloud platform, the carriers, and the integrations.)
5.3 Failover/Recovery Process
There are two scenarios that could result in the service not being available:
- The sendcloud platform is not available
- A carrier is not available.
5.3.1 Sendcloud not available
In case of Sendcloud not being available, the orders from Salesforce B2C Commerce cannot be sent over to Sendcloud. When Sendcloud is available again, the order synchronization can be picked up again and no data is lost.
5.3.2 Carrier not available
In case of a carrier not being available, the orders from Salesforce B2C Commerce will still be sent over to Sendcloud. The labels cannot be created for that specific carrier, but the user can still change the carrier to a different one to avoid losing time on shipping.
5.4 Support
Sendcloud customers can contact Sendcloud support in case any problems arise. How Sendcloud support can be contacted is described in https://app.sendcloud.sc/v2/support.
6. User Guide
6.1 Roles, Responsibilities
- No recurring tasks are needed on PIG instances.
- On sandboxes, it will be needed to manually run the two jobs.
6.2 Business Manager
6.2.1 Business Manager module
A new Business Manager module is added, located at Merchant Tools > Site Preferences > Sendcloud. Here the connection between Salesforce B2C Commerce and Sendcloud can be established.
6.2.2 Site preferences
The site preferences are described in section 3.2.1.
6.2.3 Jobs
Two jobs are used by this integration:
• ‘Sendcloud - export orders’: this will export orders to Sendcloud using the Sendcloud shipment API, see also section 3.4.1. Only orders that have been exported to backend systems (ERP/OMS), so those that have with export status ‘EXPORTED' are sent to Sendcloud.
• ‘Sendcloud - process notifications’: this will process any webhook notifications coming in from Sendcloud, see also section 3.4.2.
See section 3.2.2 for the job configuration options.
6.3 Storefront Functionality
- On the storefront, only the shipping methods shown in the checkout are changed by this LINK cartridge.
- When a nominated day delivery method is used this will be shown with a delivery date picker:
- When a service point delivery method is used then this will be shown with a service point picker:
7. Known Issues
On the basket page, all shipping methods are shown in the ‘Shipping’ dropdown, so this does not only list those shipping methods applicable to a specific country.
The reason is that no shipping address has yet been provided by the customer. This is behavior of the SFRA storefront, not due to any changes in this LINK cartridge.
8. Release History
Version Date Changes
- 21.1.0 2021-08-01 Initial release