Webshop Data Mapping
Applies to: Sana Commerce Cloud 10.0.17 and higher in Microsoft Dynamics AX.
In Microsoft Dynamics AX click: Webshop > Common > Webshops. Select the necessary webshop and click Webshop data mapping at the top of the window.
There are two ways how you can use Webshop data mapping:
-
Map different fields to save certain values to the specified fields when data is coming from the Sana webshop to Microsoft Dynamics AX, such as sales orders or customers. You can do this on the Save API FastTab.
-
Map fields for retrieving data from Microsoft Dynamics AX by Sana. You can do this on the Get API FastTab.
Save API
On the Save API FastTab click New value, if you need to set values for certain fields or click New mapping, if you need to map the fields.
The data mapping can be used for the order and quotation creation, online customer registration and presentation of a prospect by a sales agent. Whether a customer places an order or a quotation, or a customer registers online in the Sana webshop, or a sales agent creates a prospect in the Sana webshop, the necessary data is saved to the relevant tables in Microsoft Dynamics AX.
You firstly need to select the necessary table to create a rule. The following options are available:
-
SalesTable – select this option if you need to create rules for the fields from the sales order header table.
-
SalesLine - select this option if you need to create rules for the fields from the sales order line table.
-
SalesQuotationTable - select this option if you need to create rules for the fields from the sales quotation header table.
-
SalesQuotationLine – select this option if you need to create rules for the fields from the sales quotation line table.
-
CustTable - select this option if you need to create rules for the fields from the customer table.
-
ContactPerson - select this option if you need to create rules for the fields from the contact table.
When the table is selected, you can create a rule for any field from this table or you can create a mapping between the fields from this table. Also you can create a mapping between different tables and copy or move field values between these tables.
You can activate or deactivate webshop data mapping rules, set the priority of the rules and copy the rules from one webshop to another webshop starting from Sana Commerce Cloud 10.0.38 in Microsoft Dynamics AX.
You can ignore the Sana field values using the Override checkbox starting from Sana Commerce Cloud 10.0.70 in Microsoft Dynamics AX.
Creating mapping rules between different tables and moving values is possible starting from Sana Commerce Cloud 10.0.75 in Microsoft Dynamics AX.
Using the Override checkbox, you can ignore the Sana field values and give priority to the default field values set in the webshop data mapping rules. The Override checkbox works in the following way:
-
You set the default value for the Sana field using the Default value field and you do not select the Override checkbox for this rule. Then if the Sana field has a value, the default value from the data mapping rule will be ignored. In case the Sana field is coming empty from the Sana webshop, then the default value from the data mapping rule will be saved to the Sana field.
-
You set the default value for the Sana field using the Default value field and you select the Override checkbox for this rule. Then the Sana field value coming from the webshop will be ignored and the default value from the data mapping rule will be saved to the Sana field.
Using the Move checkbox, you can move field values within the same table and between different tables.
Using the Active checkbox, you can activate or deactivate any webshop data mapping rule. If the webshop data mapping rule is deactivated, it will not work in your webshop.
You can set the order in which rules should be executed, using the Priority field. The priority is crucial if you combine several rules and create more complicated scenarios. In this case the rules should be executed in a specific order.
If you have several webshops, you can copy the webshop data mapping rules from one webshop to another. To do this, click Create a copy at the top of the window, then specify a webshop to which the rules should be copied.
Webshop Data Mapping Rules Recommendations
We strongly recommend to check the following points before creating any rules:
-
Use only the fields you are familiar with to create rules. If you are going to use some unknow field, try to find out its purpose firstly before creating a rule. Make sure that the created rule works correctly, otherwise it can cause problems in the work of Microsoft Dynamics AX.
-
When you create data mapping rules, take into consideration the priority of the fields. If you create a data mapping rule where you set the default value for the Sana field using the Default value field, then the priority of the fields will be determined by the Override checkbox. The mapping between two fields works differently. In case, you created a mapping, for example, between two Sana fields, the value will be passed to the mapped field in any case. If the mapped Sana field has its own value it will be ignored. Unlike the rules with default value, the rules which you create to map two fields have higher priority, that is why if the mapped field has some value in Sana, it will be ignored.
In the previous versions, the data mapping rules worked in the following way: when a rule was created using the Default value field, the default value overrode any other values coming from Sana.
Starting from Sana Commerce Cloud 10.0.30 in Microsoft Dynamics AX the Default value field works differently. Now, if some values are coming from Sana, then they will be saved to the relevant fields in Microsoft Dynamics AX, the default value set in the rule will be ignored. The default value from the created data mapping rule is used only in case if no values are coming from Sana.
Starting from Sana Commerce Cloud 10.0.70 in Microsoft Dynamics AX you can control which fields should have the priority, using the Override checkbox.
In the previous versions the rules where you mapped fields worked in the following way: if two fields were mapped, the field value was passed to the mapped field, the source field remained empty. Starting from Sana Commerce Cloud 10.0.75 in Microsoft Dynamics AX, if you map two fields, the field value is copied to the mapped field and the source field keeps its value. In case you need the source field to pass its value to the necessary field and remain empty, you can do this by selecting the Move checkbox when you create the mapping between fields.
How to Use Webshop Data Mapping?
Data mapping rules can be configured differently and can serve different purposes. There are 6 main scenarios presented below which show how data mapping can be used. You can use data mapping for the cases we described or for some other cases to fit your business needs.
Scenario 1
Usually the sales order data coming from the Sana webshop is saved to the relevant Sana fields in the sales order table in Microsoft Dynamics AX. Using Webshop data mapping, you can save the sales order data to a different field from the sales order table or to a field from a different table.
For example, when customers place an order in the Sana webshop, they can enter the reference number on the Order Overview checkout step. By default, the reference number is saved to the Customer reference Sana field in the sales order table in Microsoft Dynamics AX. On the Save API FastTab, you can create a mapping between the Sana field and the field you want the reference number to be saved to.
If you create a mapping between fields, the value of the field specified in Source field name will be passed to the field specified in Mapped field name. If you do not need the field specified in Source field name to keep its value, make sure that the Move checkbox is enabled. See the screenshot below.
If such a rule is created, then when a customer enters the reference number while placing an order in the Sana webshop, the reference number will be saved to the Customer requisition field in the sales order table in Microsoft Dynamics AX, instead of the Customer reference Sana field. The Customer reference Sana field will be blank.
In case the field specified in Source field name has no value, the field specified in Mapped field name will be saved to Microsoft Dynamics AX with no value as well.
For example, you have mapped the fields Payment reference (PaymentReference_EE) and Comments (FederalComments). See the screenshot below.
Both of these fields are available on the customer registration form in the Sana webshop. If a customer during registration fills in the Comments field, but leaves the field Payment reference empty, the Comments field will be saved in the customer table in Microsoft Dynamics AX with no value.
The data mapping rules in which you create a mapping between two fields have higher priority. That is why, for example, if the mapped field is the Sana field and it has value in the Sana webshop, this value will be ignored. The value of the Sana field will change according to the rule set on the Save API FastTab.
If you map the fields, the value of the field specified in Source field name will be always passed to the field specified in Mapped field name. Check the following cases:
If the Move checkbox is disabled, the field specified in Source field name will keep its value.
Case 1
Source field name: field has value
Mapped field name: field has no value
The Move checkbox is enabled
Result: the value of the field specified in Source field name is passed to the field specified in Mapped field name. The field specified in Source field name remains empty.
Case 2
Source field name: field has value
Mapped field name: field has value
The Move checkbox is enabled
Result: the value of the field specified in Source field name is passed to the field specified in Mapped field name overriding the value of the mapped field. The field specified in Source field name remains empty.
Case 3
Source field name: field has no value
Mapped field name: field has value
Result: the field specified in Mapped field name becomes empty.
Scenario 2
You may have created some custom fields in Microsoft Dynamics AX which Sana does not use, but you need to save some sales order data to these custom fields. On the Save API FastTab, it is possible to create a rule where you can specify a value for a custom field. See the screenshot below.
If such a rule is created, then when a customer places an order in the Sana webshop, the custom field will be always shown in the sales order table in Microsoft Dynamics AX with the value you set for this field on the Save API FastTab.
Scenario 3
There are some standard fields in Microsoft Dynamics AX which are not used by Sana.
You can save some values to these fields, if necessary. For example, the field Pool in the sales order table is not used by Sana and it is always empty. On the Save API FastTab, it is possible to create a rule where you can specify a value for a certain field. See the screenshot below.
If such a rule is created, the value 03 (Retail order pool) will be saved to the Pool field in the sales order table for all sales orders placed from the Sana webshop.
Scenario 4
There are some Sana fields which are coming from the webshop with their own values, but you need these fields to be saved in Microsoft Dynamics AX with the default value or you need them to be empty.
For example, you do not want the cash discount set for a customer to be applied to the sales order and you need a different cash discount to be used instead and to be applied to a sales order in Microsoft Dynamics AX. On the Save API FastTab it is possible to create a rule which will override the field values. See the screenshot below.
If such a rule is created, then the 4%D20 cash discount will be applied to a sales order. The cash discount set for a customer will be ignored. When you create rules, using which you override some field values coming from Sana, make sure that the Override checkbox is selected.
There is also another scenario. For example, you want to completely ignore the field values coming from Sana. To do this, you just need to create a rule for the necessary field, leave the Default value empty and select the Override checkbox. See the screenshot below.
If such a rule is created, then the cash discount will not be applied to a sales order. If there is the cash discount set for a customer, it will be ignored.
Scenario 5
You can even combine different rules and create more complicated scenarios.
As mentioned before, if you map two fields, the field specified in Source field name will always pass its value to the field specified in Mapped field name and the field in Source field name will remain empty or keep its value depending on whether the Move checkbox is selected or not. You can configure data mapping in such a way, that the field specified in Field name will pass its value to the field specified in Mapped field name and then some value will be saved in the field specified in Source field name. See the screenshot below.
If you create several interrelated rules, it is important to specify the order in which they will be executed. You can set the order using the Priority field. For such scenario the Move checkbox should be enabled.
In this case, in the first rule the field Notes (BankCentralBankPurposeText) is mapped to the field Comments (FederalComments) and the priority of the rule is set to 1. In the second rule the default value Demo comment 1 is set for the field Comments (FederalComments) and the priority of the rule is set to 2.
If such two rules are created, then the first rule will be executed, according to this rule the value of the field Comments will be passed to the mapped field Notes. For example, a customer enters Demo comment 2 in the Comments field during registration in the Sana webshop. The value Demo comment 2 will be saved to the Notes field in Microsoft Dynamics AX.
Then, the second rule will be executed, according to this rule the value Demo comment 1 will be saved to the Comments field.
As a result, both fields will be saved in the customer table in Microsoft Dynamics AX with values. The Comments field will be saved with the value Demo comment 1 and the Notes field with the value Demo comment 2.
Scenario 6
If necessary, you can move the value of the field to another field in the same table or a different table.
For example, when customers place an order in the Sana webshop, they can enter the reference number on the Order Overview checkout step. By default, the reference number is saved to the Customer reference Sana field in the sales order header table in Microsoft Dynamics AX. Let’s say you want to save the reference number to a different field in the sales order lines instead of the sales order header.
It is possible to create a rule where you can specify to which field in which table the value should be moved. See the screenshot below.
If such a rule is created, then when a customer enters the reference number while placing an order in the Sana webshop, the reference number will be moved from the Customer reference field in the sales order header to the Text field (Name) in the sales order lines in Microsoft Dynamics AX. The Customer reference field will remain empty. If you need the value to be copied, then disable the Move checkbox. In this case, the reference number will be available in both the Customer reference field and in the Text field.
Get API
Applies to: Sana Commerce Cloud 10.0.75 and higher in Microsoft Dynamics AX.
Applies to: Sana Commerce Cloud 10.0.17 and higher in Microsoft Dynamics 365 for Finance and Operations.
On the Get API FastTab you can map fields for retrieving data from Microsoft Dynamics AX by Sana. This feature is intended for technical people, but you can use it to change the response for any API method without any development.
It is possible to:
-
Use a value for a field that is used by Sana in the response from another field.
-
Use the default value for a certain field in the response.
-
Add a custom node to the response (field and value).
Disable Webshop Data Mapping
Applies to: Sana Commerce Cloud 10.0.38 and higher in Microsoft Dynamics AX
If you do not want the webshop data mapping rules to be applied to your webshop, you can disable them globally in the Webshop optimization window. If you select the Disable data mapping checkbox, then webshop data mapping rules configured in Microsoft Dynamics AX will not be applied to your webshop.
For more information, see Webshop Optimization.