Customization mapping in Magento

Customization mapping allows any extra information captured on the Magento side to be included on the customer and order in Brightpearl. These can be captured in Brightpearl custom fields, or in some cases in the standard Brightpearl field:

Capture in the standard Brightpearl order field:

  • Lead source (order.leadSourceId)
  • Delivery date (order.shipping.deliveryDate)
  • Invoice address mobile (customer.billingAddress.mobile)
  • Delivery address mobile (customer.deliveryAddress.mobile)

Capture these things in an order custom field:

  • Delivery instructions
  • Coupon code
  • Gift messages*
  • Any Magento field not already captured
  • Custom fields added to Magento by an extension

* There are specific configuration options for gift messages if preferred

Order comments will automatically be captured in the Brightpearl order notes and payment history without mapping.

Capture in the standard Brightpearl customer field:

  • Lead source (customer.leadSourceId)
  • Telephone 2 (customer.secondaryPhone)
  • Mobile (customer.mobile)
  • Trade status (customer.isTrade)
  • Any standard or custom order field in Magento not already captured (customer.customFields.PCF_xxx)

Configuring customization mapping

Customization mapping is done within the Brightpearl Magento extension at:

Magento 1: Interactions > Brightpearl > Configuration > Interaction : Export order

Magento 2: Brightpearl > Brightpearl integration > Configuration > Interaction : Export order

The customization mapping:

  • Evaluate is where to look on the Magento order to get the information. This could be just one, or several places. Enter a comma separated list of field names as 'getMagentoDatabaseFieldName'. And to define a default to use when the field(s) is empty use [square brackets].
  • Transform can be used to specify whether the information should be formatted, like changing how a date is displayed.
  • Output is where the destination field in Brightpearl is defined.
  • On failure controls what happens when nothing is found in the fields and no default is set, such as skip to leave it blank.

Read more detailed explanations below.

magento-customisation-map.png

Evaluate - select a Magento field

The evaluate field is used to specify where in Magento the information can be found, and if it's empty what should be used instead.

How to complete the evaluate field

  1. Enter the Magento field name, or names, where the information is stored.

    Note: Field names are for demonstration purposes only and may not be the same in your system. Check field names with your Magento developer.

    For example:

    'getCouponCode' will look in the coupon code field.

    'getBillingCompanyName' will look for company name within the billing address**

    Enter a comma separated list of fields names to check more than one place on the order. They will each be checked in turn until an entry is found. For example, enter:

    'getBillingCompanyName,getShippingCompanyName,getDefaultCompanyName' will check the billing company name first and if there is nothing in that field the shipping company name will be checked, if there is something stored in that field then the evaluation is complete and that entry will be transferred into Brightpearl.

  2. (Optional) Use square brackets to define a default. The default is used when all the fields specified are blank. For example, enter:

    'getShippingComments,getOrderComments,[No delivery details included]'

    When both fields are blank 'No delivery details included' will be added to the relevant field in Brightpearl. To leave the field blank in Magento, do not provide a default.

    magento-customization-mapping-evaluate.png

    magento-customization-mapping-defaultresult.png

Transform

This defines how to format the information found in the evaluate field.

This can be used to change the Magento data into a format accepted by Brightpearl, for example, ensuring a date is formatted in the correct way. It can also be used to perform a lookup from a list or include some additional string of text.

How to complete the transform field

To format a date:

Enter the date format to be applied within square brackets, for example, a date of 8th December 2017 could be transformed using:

  • [d M Y] to post '08 Dec 2017'
  • [M d Y] to post 'Dec 08 2017'
  • [d/m/y] to post '08/12/17'

To include a string:

Using sprintf expressions, the detail can be altered in ways such as adding the detail into a sentence. For example, when there isn't a specific field in Brightpearl and instead a generic custom field is used, it could be useful to label the type of information that's being posted, such as prefixing coupon codes with 'Coupon code:' - this transformation would be entered as 'Coupon code: %s'.

To do a look up from a list:

When the field in Magento could contain multiple different results, which each need to be transformed into something different the lookup list can be used. This might be used where the Magento database field stores details in a way which isn't useful to the user, such as a zero to mean no, a 1 to mean yes. To show 'Yes' or 'No' in Brightpearl use this transformation: {0=No,1=Yes} 

Output - select the Brightpearl field

This field is used to specify where the information should be recorded on the Brightpearl order or customer record.

Use the output section to specify which field should be populated when the order is created in Brightpearl. This could be a standard Brightpearl customer or order field (i.e. not an order row), or it could be a customer or sales order custom field.

How to complete the output field

  1. Enter a Brightpearl custom field

    If the information is to be entered into a custom field on the Brightpearl order use the following:

    order.customFields.PCF_CUSTOMFIELDCODE

    The custom field code can be found in Brightpearl at Settings > Custom fields > Sales orders.

    customer.customFields.PCF_CUSTOMFIELDCODE

    The custom field code can be found in Brightpearl at Settings > Custom fields > Customers.

  2. Or, enter a standard Brightpearl field

    If the information is to be entered into a standard Brightpearl field on an order, enter:

    order.fieldName

    Supported fields: Lead source (order.leadSourceId), Delivery date (order.shipping.deliveryDate), Invoice address mobile (customer.billingAddress.mobile), Delivery address mobile (customer.deliveryAddress.mobile)

    If the information is to be entered into a standard Brightpearl field on a customer, enter:

    customer.fieldName

    Supported fields: Lead source (customer.leadSourceId), Telephone 2 (customer.secondaryPhone), Mobile (customer.mobile), Trade status (customer.isTrade)

On failure

An evaluation is considered a failure when no detail is found in any of the defined Magento fields and no default has been specified. Use this section to specify what should happen when this occurs, either:

  • Skip the field and continue
  • Warn with an alert on the Magento exceptions report
  • Stop the order from downloading 

How to map lead source for Magento orders

  1. In Brightpearl, go to Marketing > Lead sources. Keep this window open. These details will  be needed to complete the configuration in Magento.
  2. Log into the Magento admin panel and go to:

    Magento 1: Interactions > Brightpearl > Configuration > Interaction : Export order

    Magento 2: Brightpearl > Brightpearl integration > Configuration > Interaction : Export order

  3. In the Evaluate field enter the details of where the lead source is stored in Magento database.
  4. In the Transform field specify the detail stored in Magento for the lead source and the corresponding ID in Brightpearl. Refer back to the list of lead sources in Brightpearl to find the ID numbers. Brightpearl will only accept the ID so this field is used to convert whatever is seen in Magento to the relevant ID. For example, if the data in Magento is 'Referral' and in Brightpearl the corresponding lead source is ID 8 enter: {Referral=8}. Add a comma separated list of each detail along with the relevant Brightpearl lead source ID within curly brackets.
  5. In the Output field enter 'order.leadSourceId'. This is case sensitive. Mapping to the order won't update the customer record. This will need to be mapped too.

    magento-order-leadsource.png

  6. Finally, specify what should happen if no result is found. Select Skip to download the order anyway, or Stop to stop the order from downloading, or Warn to get a warning in the log.

  7. If a default value is preferred when no entry is found enter this into the Evaluate field in square brackets.

    Map_lead_source.png

  8. Save the configuration.

Once mapped new orders will download with the lead source assigned.

How to map lead source for Magento customers

  1. In Brightpearl, go to Marketing > Lead sources. Keep this window open. These details will  be needed to complete the configuration in Magento.
  2. Log into the Magento admin panel and go to:

    Magento 1: Interactions > Brightpearl > Configuration > Interaction : Export order

    Magento 2: Brightpearl > Brightpearl integration > Configuration > Interaction : Export order

  3. In the Evaluate field enter the details of where the lead source is stored in Magento database.
  4. In the Transform field specify the detail stored in Magento for the lead source and the corresponding ID in Brightpearl. Refer back to the list of lead sources in Brightpearl to find the ID numbers. Brightpearl will only accept the ID so this field is used to convert whatever is seen in Magento to the relevant ID. For example, if the data in Magento is 'Referral' and in Brightpearl the corresponding lead source is ID 8 enter: {Referral=8}. Add a comma separated list of each detail along with the relevant Brightpearl lead source ID within curly brackets.
  5. In the Output field enter 'customer.leadSourceId'. This is case sensitive. Mapping to the order won't update the customer record. This will need to be mapped too.

    magento-leadsource.png

  6. Finally, specify what should happen if no result is found. Select Skip to download the order anyway, or Stop to stop the order from downloading, or Warn to get a warning in the log.
  7. If a default value is preferred when no entry is found enter this into the Evaluate field in square brackets.

    magento-customer-leadsource.png

  8. Save the configuration.

Once mapped the lead source will be recorded on customers in Brightpearl.

How to map trade status for Magento customers

  1. Log into the Magento admin panel and go to:

    Magento 1: Interactions > Brightpearl > Configuration > Interaction : Export order

    Magento 2: Brightpearl > Brightpearl integration > Configuration > Interaction : Export order

  2. In the Evaluate field enter the details of where the trade status is stored in Magento database, for example, this might be defined by the Magento customer group. In which case, enter 'getCustomerGroupId'.

    trade-evaluate.png

  3. In the Transform field specify what the corresponding detail is in Brightpearl for each of the items that might be recorded in Magento. For example, when mapping Magento customer group to Brightpearl trade status, the Magento detail provided is the customer group ID and Brightpearl expects a true/false detail (where true=trade, false=retail, where not provided not known is set).

    Where the Magento customer group IDs are:

    magento-customer-group-ids.png

    Enter '{1=false,2=true,3=false}' this will set general customers to retail, wholesale customers to trade, retail customers to retail and not logged in customers as unknown.

    trade-transform.png

  4. In the Output field enter 'customer.isTrade'. This is case sensitive.

    trade-output.png

  5. Finally, specify what should happen if no result is found. Select Skip to download the order anyway, or Stop to stop the order from downloading, or Warn to get a warning in the log.
  6. If a default value is preferred when no entry is found enter this into the Evaluate field in square brackets.

    trade-default.png

  7. Save the configuration.

magento-trade-status.png

Once mapped the trade status will be set on customers in Brightpearl.

FAQs

What happens if I map to the same field twice?

The mapping table is read in order, this means that the field will continue to to override the field each time a mapping item is read. The last entry will be the one preserved and seen in Brightpearl.

Will updates made in Magento be shown on the mapped fields in Brightpearl?

No. The fields will only be set in Brightpearl when the order is first created.

Will updates made in Brightpearl be shown on the mapped fields in Magento?

No. Changes made in Brightpearl will not be reflected in Magento.

Will customer details get updated?

The next time an order is created in Brightpearl, any new details address details will be added to the existing customer in Brightpearl, without removing any old addresses. Changes to the trade status, lead source, newsletter settings will be updated and name, telephone numbers and other custom fields overwritten.

Have more questions? Submit a request