ERP: Extending an existing integration
The Dynamicweb Integration Framework is a collection of components for transferring data and maintaining data consistency between a Dynamicweb solution and a remote system.
Out of the box the Integration Framework has the following features:
- Price/Inventory lookup (live)
- Calculate order (live)
- Product synchronization (batch)
- Debtor/User synchronization (batch)
- Language synchronization (batch)
- Currency synchronization (batch)
- Manufacturer synchronization (batch)
- Unit synchronization (batch)
You are reading this because you want to extend one of these features, or add new features to an existing integration.
But first a bit of background to help you understand what’s going on.
There are two main types of integration between Dynamicweb and an external system.
- A batch integration is a file-based approach, which uses scheduled tasks to import and export data at intervals (hourly, daily, weekly, etc.).
- A live integration submits real-time requests from a Dynamicweb frontend to the remote system, then uses the data returned to show e.g. live prices or stock
However, from the ERP side both types of integration do the same thing; submit requests for data (Figure 1.1).
Both batch and live features work in the same general manner:
- The Dynamicweb solution makes a request for data in XML format
- The ERP plugin/code unit reacts by extracting data from the ERP
- The data is wrapped in XML format understood by Dynamicweb
- The XML is returned to the Dynamicweb solution as a response
While the request XML varies slightly depending on the type of integration, the response XML always follows the same general structure:
Additionally, the Dynamicweb database expects data to be delivered in specific data type formats, so if you price column suddenly contains string values you’re gonna have a bad time.
The features included in our plugins/code units out of the box are fairly limited – by design, we import only the standard fields from your ERP which are directly relevant for a Dynamicweb solution.
But you can easily extend existing features or add new features to an integration.
Broadly speaking, extending or adding a feature requires you to:
- Modify the ERP plugin/code unit code to extract the correct data from your system when receiving a request
- Wrap it in the appropriate XML format
- Return it to Dynamicweb
Here are some of the most common scenarios explained.
Products & Users Synchronization
To extend product or user synchronization with additional information, simply add more columns to the response and return them with the appropriate data.
There are two possible scenarios when extending product and users sync:
- The data is appropriate for a standard field in Dynamicweb
If the data fits seamlessly into the standard Dynamicweb fields, e.g. if it’s a product description or a tax code, the column name should be named after the system name of the field is in Dynamicweb. If the Dynamicweb side of the integration uses automatic mapping in their integration activities, everything will be linked up automatically.
- Dynamicweb does not contain an appropriate standard field
If Dynamicweb does not contain an appropriate standard field, the Dynamicweb side of the integration must create a custom field for the data to be stored in. The column should be named after the system name of the custom field. Both sides of the integration – your side and the Dynamicweb side – must keep the data type in mind when deciding on the type of custom field needed.
If you want to import variants using the Dynamicweb Provider, you need to add data to the following tables:
- EcomVariantGroups must contain one row for each language version of each variantGroup you are importing.
- EcomVariantsOptions must contain one row for each language version of each option for each group.
So, if you have color and size as variant groups, and color options are red and blue, size options are small and large, this table must contain 4 rows. The VariantOptionId can be any string, as long as it is unique for each variant option, when combined with the languageID.
Naturally, you must also add data to the EcomProducts table – and there are several things you need to be aware of:
- Add one row to the EcomProducts table for each variant and a “base” row for the product. This means that if you have a product “shoe”, which is available in colors red and blue, sizes large and small, you will add 5 rows to the database – one for “shoe” and one for each variant.
- Add values to the ProductVariantCounter. The ProductVariantCounter must contain the total number of variants for this product, so each of the mentioned 5 rows should contain the value 4, since there are a total of 4 variants of the product.
- Add values to the ProductVariantGroupCounter. The ProductVariantGroupCounter must contain the total number of variants for this product, so each of the mentioned 5 rows should contain the value 2, since there are two variant groups, color and size.
- The VariantID column must contain a concatenation of the variantIDs for the variant options a given row fall under, combined by a period. So assuming “red” has variantID V01 and “small” has variantID “V05”, the small red variant row must have variantID “V01.V05”. The order of the variant IDs is not important.
Then you need to associate a product with a variant group, in order to determine which variants are available for the product:
The mandatory fields are:
Finally, you need to import the active variants for a product:
User segmentation/user groups
To extend user synchronization with user segments (groups), you must add the following tables and columns to the user import response:
The AccessUserGroup table contains user groups, and has a column called AccessGroupParentGroupName. This column can contain either the name of the parent group (AccessGroupName) or a groupID. Group names are used if importing from an external source – please note that if you have more than one group with the same name, your product will be added to one of them at random.
To relate users to groups, add the name of the group to the column AccessUserGroups in the AccessUser table. This column can contain a comma separated list of the groups that the user should be added to:
To extend user synchronization with impersonation information, you must add data to the AccessUserSecondaryRelation table.
It has two relevant columns:
Both columns may contain either an AccessUserID (if known) or the AccessUserUserName for both the impersonator and the user being impersonated.
When importing data to these columns, Dynamicweb first checks if a user exists with the included UserID. If that’s not the case, we check if a user exists with an ExternalUserID that matches the included ID.
If not, the row will be ignored.
The AccessUserSecondaryRelationSecondaryUserId column can also contain a customer number - AccessUser.AccessCustomerNumber - which does not have to be a unique number, so several users can share the same customer number.
The following code imports all customers with customer number 1234 to be impersonated by user 321654987 - so if 10 users have the customer number 1234, 10 records will be generated in the AccessUserSecondaryRelation table matching the impersonator and the impersonatees.
Assortments are subsets of a product catalog, which are accessible to only specific users or user segments.
When importing assortments, the target data format is as follows:
The following tables and fields are mandatory:
- AssortmentPermissionAssortmentID (ID of assortment)
- AssortmentPermissionCustomerNumber (customer number the assortment is for)
At least one of these tables and its mandatory fields is also required:
- AssortmentProductRelationAssortmentID (id of assortment)
- AssortmentProductRelationProductID (id of product in the assortment)
- AssortmentGroupRelationAssortmentID (ID of assortment)
- AssortmentGroupRelationGroupID (ID of product group)