Configuring the Brightpearl Magento extension

Before Brightpearl and Magento can begin working together they need to be connected and authorised to communicate. Brightpearl will then be able to share key information about channels, warehouses, order statuses and price lists that Magento will need.

You will also want to check the configuration of the extension so you are happy with the number and frequency of interactions that occur between the systems to ensure that your Magento store operates effectively and meets the needs of your website.

Connecting Brightpearl via the Magento extension

Once the Brightpearl Magento extension has been installed on your Magento account you are ready to establish the connection. This will authorise Magento to communicate with your Brightpearl account.

How to connect your Brightpearl account to Magento

1 - Install the Brightpearl Magento extension as per the installation guide.
2 - Ensure you have logged out of your Brightpearl account.
3 - In Magento, go to Hotlink > Brightpearl > Authorisation.


On Magento 1, you would see the below screen: 

Connect MG 1

 

This is the view for Magento 2:

MG1.png

4 - Click Authorise now.


Connect MG 2

5 - Enter your Brightpearl account ID.

MG2.png

6 - Click Submit and you will be directed to authorise with your Brightpearl account. Click Continue to confirm you wish to connect the extension to Brightpearl.

MG3.png

7 - Enter your Brightpearl login details and click Authorise.

MG4.png

8 - A message confirms the extension has been authorised and that the app has been installed in your Brightpearl account. Click Continue.

Connect MG 7


MG5.png

You are returned to Magento and a success message will indicate that the authorisation was successful. Your dashboard will now be displayed in the Magento extension configuration. 

MG6.png

9 - Log into your Brightpearl account and you will find the Magento app listed as one of your installed apps. Go to Settings > Brightpearl apps > Magento, you will see your Magento account listed.

 MG7.png

10 - Next, channels need to be added in Brightpearl. Channels are used for recording from where orders are received. At least one channel is required to download orders from Magento. The number of channels you need depends on your reporting requirements in Brightpearl. Orders from Magento can be separated by website, store or store view.

MG8.png
MG9.png


Click the Add Channel button and select the Magento channel type. Make the following entries:

Channel name: This is how the channel will be seen throughout Brightpearl

Show in channel menu: This can be unchecked if at any time you no longer use this channel and wish to remove it from displays.

Brand: Choose which channel brand to apply to all sales taken via this channel, this allows you to use certain branding on any communication generated against sales from this channel.

Warehouse: Select which warehouse to use for allocating stock orders. When an order downloads from this channel stock will be allocated and reserved from this warehouse. Note that advanced fulfilment allows you to later split the shipment from multiple warehouses.

Your Brightpearl and Magento accounts are now connected and ready to be configured.

Configuring the Brightpearl Magento extension

The first thing you need to do when configuring the Brightpearl Magento extension is to import all the Brightpearl settings, such as the list of channels into Magento so that they can be used in the configuration.

After the Brightpearl setting data has been imported you are ready to begin working through all the extension settings. These are described in detail below.


How to import Brightpearl setting data

  1. Log into your Magento admin and go to Interactions > Brightpearl > Configuration.
  2. In the Interactions: Import Brightpearl settings data section set the interaction as active.

    M10.png

  3. To run the import of the Brightpearl settings data, go to Interactions > Brightpearl > Interactions > Import Brightpearl setting data and click Execute.

    MG11.png

    Note: This interaction will need to be run in the future when new Brightpearl setting data has been created and needs to be added to the extension configuration.

    If the import does not run and the error EXECUTION DENIED (probably by configuration) is shown, ensure that the interaction is active at Interactions > Brightpearl > Configuration. See step 1 & 2

    The results of the Brightpearl setting data import are displayed. Review the execution results for any warnings or errors. Any errors will need to be fixed and the import re-executed.

    MG12.png

  4. The next step is to enable webhooks integration. To do this, please go to Brightpearl >  Configuration > Interaction : Register integration webhooks

    MG13.png

    MG14.png

  5. Choose “Yes” to enable the webhooks. After enabling the webhooks, you have to execute the webhooks. To do that, go to Brightpearl > Interactions > Register integration webhooks.

  6. Now that Brightpearl setting data has been imported the extension can be fully configured. Go to the extension settings at Hotlink > Brightpearl > Configuration, to complete the rest of the configuration.

  7. Configurations:

    Interaction > Brightpearl > Configuration > Scope Summary
    Shared : Stock settings Global Select the Brightpearl warehouses used for inventory sync.
    Interactions : Import stock levels (bulk) Global Activate and configure bulk inventory updates.
    Interaction : Import stock levels (real-time) Global Activate and configure real-time inventory updates.
    Interaction : Import prices Per store view Activate price updates from Brightpearl price lists. Map price lists in the Shared : Price Settings.
    Shared : Order and payment settings Global Map order statuses and payment methods.
    Interaction : Export order Per store view Activate and configure order export and transfer to Brightpearl.
    Interaction : Export order status Per store view Activate and configure order status sync. Map order statuses in Shared : Order and Payment settings.
    Interaction : Export order payment Per store view Activate and configure payment export and transfer to Brightpearl.
    Interaction : Set webhooks Global Activate listening for shipping updates from Brightpearl.
    Interaction : Export SKUs Global Activate the export skus interaction to transfer a list of Magento SKUs to Brightpearl for reporting purposes.
    Flint Interactions : Reporting (Go to Interactions > Core > Configuration) Global Activate monitoring and logging of the extension activity.
    Interaction : Reconcile orders    Reconcile orders for desired fallback date, if they were triggered but not downloaded. 
    Interaction : Reconcile shipments   Reconcile shipments for desired fallback date, if they were triggered but not downloaded.
    Interaction: Import shipments (goods out & drop ship notes)   Import good out notes and drop ship notes from Brightpearl to Magento.

Shared : Stock settings

Use the shared stock settings to control which Brightpearl warehouses are used for managing inventory levels on Magento. These settings apply to both the bulk and real-time stock level imports. The imported inventory levels will apply to all Magento websites.

MG15.png

Field Description
Brightpearl warehouse(s) Select 1 or more warehouses - hold down CTRL to select multiple. The combined on-hand inventory level from the selected Brightpearl warehouse(s) will be used to update product inventory quantity in Magento.
Skip unmanaged

Select Yes to skip importing stock availability for products with 'Manage Stock' No.

Select No to import stock availability even when 'Manage Stock' is No.

Back in stock

Select Yes to set product back in stock when availability grater than out of stock threshold.

Select No to leave product out of stock. Qty is updated in both cases.

Qty zero when availability missing Select Yes to set qty to 0 when availability missing in Brightpearl response.

Select No to reject the SKU.

Note: If no options are listed or they are missing, you will need to import Brightpearl settings data first.

Interaction : Import stock levels (bulk)

Use these settings to activate and configure bulk inventory updates. When enabled this feature will update all inventory levels in Magento on request, or automatically at a specified time and frequency.

NOTE: In order to activate this feature, it is necessary to set up cron expression.

MG16.png

Field Description
Import Stock Levels (Bulk)
Interaction Enabled Set to Yes to activate the bulk update of inventory levels.
Trigger Interaction
On cron schedule Set to Enable to run an automatic update of inventory levels at a specified time and frequency.
Monitor Schedule (shows only when cron schedule is enabled)
Cron Expression Specify when the automatic inventory update should run using a cron expression. Learn more about cron expressions. We recommend setting this to run once a day during out of hours.
General
Batch Size When the bulk inventory update is run this batch size specifies how many products will be updated at a time. The process will continue to update batches of this size until all products have been completed. The size of the batch will depend on the average length of the SKUs, as the API request can only process 512 characters at a time.  This includes other items, so to allow for error, if the average SKU is 20 characters long, use batches of 20 to be on the safe side.
Sleep Time

This helps regulate the speed at which Magento attempts to process the inventory updates. A sleep time helps prevent overloading the server and causing it to run slowly. A sleep time of 5000 microseconds is recommended but your developer may want to tweak this based on how your own server performs.

Indexing
During Interaction

Specify whether to index product data during the inventory update. Select System to let Magento to decide if/which index should be run. Select Enable to set Magento’s indexer to “Real time mode” which reindexes on product save. Select Disable to only reindex when manually run (unless next setting is set to Yes).

Reindex after interaction Select Yes to rebuild the product index after an inventory update. Select No if reindexing should not be automatically run after an inventory update.
Index If previous setting is Yes, select which Magento product indexes should be updated.
Email Notification
Email success report When the inventory update successfully completes send a confirmation email to the entered email address(es).
Email error report If errors are encountered during the inventory update send an email to the entered email address(es).
API
Timeout Specify how long the extension should wait for a response from Brightpearl before the service times out and fails.

Interaction: Import stock levels (real-time)

Use these settings to enable and configure real-time inventory updates.  This feature is used to update individual inventory levels in Magento at certain trigger points (on a store view). Using this feature ensures that accurate inventory levels are maintained in Magento for the products that are being viewed and purchased at the time, preventing overselling. Read more about how inventory is updated.

MG17.png

 

Field Description
Import Stock Levels (real-time)
Interaction Enabled Enabling real-time inventory updates will update individual product inventory levels on the selected triggers.
Trigger Interaction
On shopper view product When enabled the product inventory level will be updated when someone views the product on the website.
On shopper add to basket When enabled the product inventory level will be updated when a shopper adds the item to their basket.
On shopper view basket When enabled the product inventory level will be updated when a shopper views the item in their basket.
On shopper checkout start When enabled the product inventory level will be updated when a shopper goes to checkout.
On shopper checkout place order When enabled the product inventory level will be updated when a shopper attempts to complete checkout.
Time-to-live (TTL)
Trigger Control how frequently the each of the above triggers can send a request to Brightpearl for a new inventory level. For example, if 5 people visit the same product page within 1 minute it isn’t worth requesting an inventory update for each page view so a delay of 5 minutes might be used.
Default If specific TTL times are not set for each trigger the default will be used.
API
Timeout Specify how long the extension should wait for a response from Brightpearl before the service times out and fails.

Interaction : Import prices settings

Use these settings to enable and configure the price imports from Brightpearl. Choose which Brightpearl price lists are used for updating Magento attributes, customer group pricing and tier pricing. If deactivated prices must be managed directly within Magento.

These settings can be applied at a website level if the Price Scope setting at Configuration > Catalog > Catalog > Pricing is “Website”.

MG18.png

Field Description
Import Prices
Interaction enabled Select Yes to enable the updating of prices in Magento from Brightpearl.
Trigger Interaction
On cron schedule Select Enable to run the price import automatically on a defined schedule.
Monitor Schedule (shown only when cron scheduling is enabled)
Cron expression Enter a cron expression to define when and how frequently the price import should run automatically.
Price Type
Magento price type Select which pricing options in Magento should be updated from Brightpearl. Hold CTRL to select multiple.
Price list attribute mapping
Attribute mapping

Map Magento attributes to Brightpearl price lists. The Brightpearl prices will be imported onto any mapped attribute.

When an appropriate price record is not found, the 'Price missing behaviour' column is examined. If "Leave unchanged" the Magento attribute value is left unchanged, and if "Clear value" the Magento attribute value is cleared (emptied). This permits incomplete price lists to be used to update Magento prices e.g. for special prices.
Customer group prices
Group price mapping Use this section to map Brightpearl price lists to Magento customer groups, this can be done per website for the same customer group only where Price Scope is set to “Website” at Configuration > Catalog > Catalog > Pricing.
Tier prices
Tier price mapping

Use this section to map Brightpearl price lists with price breaks to Magento tier pricing. This can be done per website for the same customer group only where Price Scope is set to “Website” at Configuration > Catalog > Catalog > Pricing.

If 'Exclude break 1' the module will not import the first price break where Qty = 1.

If 'Include break 1' the module will import the first price break where Qty = 1.

Performance
Batch size When the price import is run this batch size specifies how many products will be updated at a time. The process will continue to update batches of this size until all products have been completed. The size of the batch will depend on the average length of the SKUs, as the API request can only process 512 characters at a time.  This includes other items, so to allow for error, if the average SKU is 20 characters long, use batches of 20 to be on the safe side.
Sleep time

This helps regulate the speed at which Magento attempts to process the price updates. A sleep time helps prevent overloading the server and causing it to run slowly.

A sleep time of 5000 microseconds is recommended but your developer may want to tweak this based on how your own server performs.

Indexing
During Interaction

Specify whether to index product data during the inventory update. Select System to let Magento to decide if/which index should be run.

Select Enable to set Magento’s indexer to “Real time mode” which reindexes on product save. Select Disable to only reindex when manually run (unless next setting is set to Yes).
Reindex after interaction Select Yes to rebuild the product index after a price update. Select No if reindexing should not be automatically run after a price update.
Index If previous setting is Yes, select which Magento product attributes should be updated.
Email Notification:
Email success report When the price update successfully completes send a confirmation email to the entered email address(es).
Email error report If errors are encountered during the price update send an email to the entered email address(es).

Note: If no options are listed or they are missing, you will need to import Brightpearl settings data first.

Shared : Order and payment settings

These shared order and payment settings allow you to control:

  • The status orders are created on in Brightpearl
  • The currency, payment method and accounting for payments created in Brightpearl

These global settings will apply to all orders and payments from all Magento websites.

MG19.png

Field Description
Currency options
Send amounts in

If you are using multi-currency Brightpearl then set this to “Order Currency”, this means that all orders will be created in Brightpearl their real currency (note that the currencies must exist in Brightpearl). If you are using single currency Brightpearl then set this to “Base Currency”, this means that all orders and payments will be converted to your base currency when they are created in Brightpearl. Note that Brightpearl currently only handles base currency payments, so all foreign currency payments will be converted to the Brightpearl base currency.

The scope of the 'Base currency' is defined by the catalog price scope ("Catalog" > "Price" > "Catalog Price Scope").
Order status
Order status map Map Magento and Brightpearl orders statuses. This mapping is used by the Export Orders interaction so that orders are created on the correct status in Brightpearl. This mapping is also used by the Export Order Status interaction to update the order status in Brightpearl when the status changes in Magento.
Default status If a Magento order is created on a status which is not mapped, the order will be created on this status in Brightpearl.
Order payments
Payment method map For each Magento payment method, specify the Brightpearl nominal code where each payment should be recorded and whether you want to create a payment in Brightpearl for payments with these messages.
Default nominal code If a payment is processed using a payment method which is not mapped to Brightpearl it will default to this nominal code and whether you want to enable the creation of payments in Brightpearl by default.

Note: If no options are listed or they are missing, you will need to import Brightpearl settings data first.

Interaction : Export Order

Use these settings to enable and configure order exports to Brightpearl. This feature is used to export orders placed through Magento and automatically create them in Brightpearl using the configured status, company name, Brightpearl channel, payment, shipping and gift messaging details.

MG20.png

Field Description
Export Orders
Interaction Enabled Select Yes to enable this interaction. If disabled this interaction will not run automatically and cannot be run manually.
Trigger Interaction
On customer checkout success (One Page) Export an order to Brightpearl when checkout is complete.
On customer checkout success (Multi Page) Export an order to Brightpearl when checkout is complete.
On admin place order success Export an order to Brightpearl when an order is saved in back office Magento.
On order status monitor Export an order to Brightpearl when it hits the specified status(es), complete Monitor Order Status section.
Monitor Order Status (shows only if order status monitoring is enabled above)
Cron expression Use a cron expression to define how frequently to check for new orders.
Order status(es) to monitor Select the order status(es) to check for - only orders on the selected status(es) will be exported to Brightpearl.
Sort order field Specify how orders should be checked for processing, and use the next field to indicate in which direction to process them. For example, choose Created date and then a sort order direction of Ascending to process orders from oldest to the most recently placed.
Sort order direction Use in conjunction with the Set order field option to specify in what order to process orders.
Batch size Specify how many orders to check in one go.
Address Options
Company name priority

Provide a list of Magento sources which should be used to extract the contact company name and used on the order in Brightpearl.

Sources will be used in sequence, until a non-empty value is found. If no company name is found after checking all these sources it will be left blank.
Brightpearl Channel
Brightpearl channel Specify against which Brightpearl Channel orders should be created. This can be defined per store view.
Payment Options
Include payment info Select Yes to include payment details in the order export.
Shipping Option
Shipping method map Map Magento shipping methods to Brightpearl shipping methods. The mapped shipping method will be assigned to the order when it is created in Brightpearl.
Default shipping method Select the default shipping method to be assigned against the order in Brightpearl where the shipping method has not been mapped.
Gift Messages
Custom field for gift messages Select the Brightpearl sales order custom field to be used for recording an order gift message.

Note: If no options are listed or they are missing, you will need to import Brightpearl settings data first.

Interaction : Export order status

Use these settings to configure which order statuses are applied to orders in Brightpearl. Magento and Brightpearl order statuses are mapped so that orders are created on the correct status and the Brightpearl order status is updated by changes made in Magento.

MG21.png

Field Description
Export Order Status
Interaction Enabled Select Yes to enable the interaction.
Trigger Interaction
On order status changed Select Enable to update the order status in Brightpearl from changes in Magento.
Monitor Order Status Changed (shown only where order status triggers are enabled)
Cron expression Enter a cron expression to define when and how frequently order status exports are run.
Sort order field Specify how orders should be checked for processing, and use the next field to indicate in which direction to process them. For example, choose Created date and then a sort order direction of Ascending to process orders from oldest to the most recently placed.
Sort order direction Use in conjunction with the Set order field option to specify in what order to process orders.

Interaction : Export order payment

Use these settings to enable and configure order payment exports to Brightpearl. When activated payments will be exported and created in Brightpearl marking the order as paid.

MG22.png

Field Description
Export Order Payments
Interaction Enabled Select Yes to enable the interaction. Select No to stop any payments being created in Brightpearl.
Trigger Interaction
On order payment changed Select Enable to activate automatic exports of order payments on a defined schedule.
Monitor Order Payment Changed (shown only when order payment changes are enabled)
Cron expression Enter a cron expression to define when and how frequently order payments are exported to Brightpearl.
Sort order field Specify how orders should be checked for processing, and use the next field to indicate in which direction to process them. For example, choose Created date and then a sort order direction of Ascending to process orders from oldest to the most recently placed.
Sort order direction Use with the Set order field option to specify order sequencing.

Interaction : Reconcile orders

Use this settings to enable and set up the orders reconciliation. If the order was triggered, but not downloaded - you can reconcile orders with ease.

MG23.png

Field Description
General
Interaction Enabled Select Yes to enable shipping updates to be recorded in Magento from Brightpearl.
Batch Number of queue items in a batch for the reconciliation.
Sleep Pause between database saves (in millionths of a second).
Delay Select the time for the batch in the queue to not be processed.
Requeue errors Select Yes to requeue orders with Brightpearl errors. Select No otherwise.
Trigger
On cron schedule What will trigger the interaction - set up cron expression for this.
Monitor Schedule
Cron Expression Enter a cron expression to define when and how frequently system attempts to reconcile orders.
Email
Email success report Add email address to receive success report.
Email success report Add email address to receive error report.

Note: If no options are listed or they are missing, you will need to import Brightpearl settings data first.

Interaction : Reconcile shipments

Use this settings to enable and set up the orders reconciliation. If the order was triggered, but not downloaded - you can reconcile orders with ease. 

MG24.png

Field Description
General
Enabled Select Yes to enable this interaction. Select No otherwise.  
Lookbehind How far in the past Magento has to reconcile orders from.
Sort by Field to sort API results by desired filters.
Sort direction How is the data sorted. Options:  Ascending or descending.
Batch Number of records to fetch per each Brightpearl query.
Sleep Pause between database saves.


Interaction: Register integration webhooks

Use these settings to enable and configure the webhook listening interaction. This interaction will listen for shipment updates from Brightpearl. When items are shipped in Brightpearl a shipment will be created on the order in Magento with the mapped shipping method and any tracking reference entered in Brightpearl.

MG25.png

Field Description
General
Enabled Select Yes to enable this interaction

*Note*: If no options are listed or they are missing, you will need to import Brightpearl settings data first.

Interaction: Import shipments (real-time)

Use these settings to enable and configure the webhook listening interaction. This interaction will listen for shipment updates from Brightpearl. When items are shipped in Brightpearl a shipment will be created on the order in Magento with the mapped shipping method and any tracking reference entered in Brightpearl.

MG26.png

Field Description
General
Enabled Select Yes to enable this interaction. Select No otherwise.
Trigger
On Goods-out Note notification (webhook) Select trigger for this interaction.
On Drop-ship Note notification (webhook) Select trigger for this interaction.

 

Interaction : Export SKUs

Use these settings to enable and configure the webhook listening interaction. This interaction will listen for shipment updates from Brightpearl. When items are shipped in Brightpearl a shipment will be created on the order in Magento with the mapped shipping method and any tracking reference entered in Brightpearl.

MG27.png

Field Description
Export SKUs
Enabled Select Yes to tell Brightpearl which SKUs you have in Magento. This will allow you to use the ‘Connected to’ filter on the product list.

 

Core interactions - monitoring & logging

Use these settings to enable interaction monitoring and reports. This interaction will provide updates on how the integration is performing and whether anything needs action. These settings are found at Interactions > Core > Configuration.

MG28.png

Navigate to > Log Cleaning:

MG29.png

Field Description
Reporting
Interaction Reports log path
Interaction reports email levels Select what type of messages emails should be included in the email, choose from: Fatal, Error, Warning, Information, Debug, Trace e.g. if you do not select DBG the email will not contain Debug messages
Write report gzip header This setting is set to Yes as default, but merchant's developer may want to tweak this based the server configuration.
Scheduler
Email success report Enter one or more email addresses to receive emails for successful scheduler actions.
Email error report Enter one or more email addresses to receive emails for scheduler actions had errors.

 

API string limits in the Magento extension

This is the number of characters Brightpearl API accepts in a single post. There is no need to change this unless we advise we have changed it in the future.

Any batches that exceed this value will automatically be split into smaller batches that respect this character limit.

Have more questions? Submit a request

0 Comments

Article is closed for comments.