ByggeBasen

Overview

The ByggeBasen connected service is provided to syncronize the data between ByggeBasen and Encodify systems.

Configuration

1. Feature flag

   In order to enable/disable the connection to ByggeBasen you need to add the following feature flag to webapp.yaml file:

   encode.webapp.connections.list.{index}.type	BYGGEBASEN
   encode.webapp.connections.list.{index}.enabled-sites	*

2. CreateProduct and Image modules.

   1. Product module with the following fields:

      Field Name	Field Type	Field Content
      DB Item ID (required)	Text field	Integer
      Updated By ByggeBasen (need to be mapped to work with actions)	Text field	Date
      Effective Date	Text field	Date
      BB_User_ID	Text field OR Text Box	Text OR Integer
      Supplier_ID	Text field OR Text Box	Text OR Integer
      EAN_ID	Text field OR Text Box	Text OR Integer
      UPC_ID	Text field OR Text Box	Text OR Integer
      SUPPLIER_ITEM_ID	Text field OR Text Box	Text OR Integer
      ITEM_TEXT_1	Text field OR Text Box	Text
      ITEM_TEXT_2	Text field OR Text Box	Text
      ITEM_TEXT_3	Text field OR Text Box	Text
      Information Text	Text field OR Text Box	Text
      ITEM_GROUP_ID	Text field OR Text Box	Text OR Integer
      PRODUCT_TYPE_ID	Text field OR Text Box	Text OR Integer
      UNSPSC	Text field OR Text Box	Text OR Integer
      UNIT_1	Text field OR Text Box	Text
      LIST_PRICE	Text field OR Text Box	Text OR Decimal
      INDICATIVE_PRICE	Text field OR Text Box	Text OR Decimal
      Producer	Text field OR Text Box	Text
      Product Type	Text field OR Text Box	Text
      MODEL_TYPE	Text field OR Text Box	Text
      Color	Text field OR Text Box	Text
      Width	Text field OR Text Box	Text OR Decimal
      Height	Text field OR Text Box	Text OR Decimal
      Length	Text field OR Text Box	Text OR Decimal
      Unit Width	Text field OR Text Box	Text OR Decimal
      Unit Height	Text field OR Text Box	Text OR Decimal
      Unit Length	Text field OR Text Box	Text OR Decimal
      Thickness	Text field OR Text Box	Text OR Decimal
      Unit Thickness	Text field OR Text Box	Text OR Decimal
      Size	Text field OR Text Box	Text OR Decimal
      Unit Size	Text field OR Text Box	Text OR Decimal
      Tariff Item Number	Text field OR Text Box	Text OR Integer
      Country of Origin	Text field OR Text Box	Text
      FSC / PEFC marking	Text field OR Text Box	Text
      Volume	Text field OR Text Box	Text OR Decimal
      Weight	Text field OR Text Box	Text OR Decimal
      Construction Delivery Clause	Text field OR Text Box	Text
      e-commerce item	Text field OR Text Box	Text
      Convert 2	Text field OR Text Box	Text OR Decimal
      Unit 2	Text field OR Text Box	Text
      Convert 3	Text field OR Text Box	Text OR Decimal
      Unit 3	Text field OR Text Box	Text
      EAN No. 3	Text field OR Text Box	Text OR Integer
      Convert 4	Text field OR Text Box	Text OR Decimal
      Unit 4	Text field OR Text Box	Text
      EAN No. 4	Text field OR Text Box	Text OR Integer
      Order Unit	Text field OR Text Box	Text
      Special request item	Text field OR Text Box	Text
      Updated on	Text field OR Text Box	Date
      Logistics Unit1_Width	Text field OR Text Box	Text OR Decimal
      Logistics Unit1_WidthDesignation	Text field OR Text Box	Text
      Logistics Unit1_Height	Text field OR Text Box	Text OR Decimal
      Logistics Unit1_HeightDesignation	Text field OR Text Box	Text
      Logistics Unit1_Length	Text field OR Text Box	Text OR Decimal
      Logistics Unit1_LengthDesignation	Text field OR Text Box	Text
      Logistics Unit1_Scope	Text field OR Text Box	Text
      Logistics Unit1_Weight	Text field OR Text Box	Text OR Decimal
      Logistics Unit2_Width	Text field OR Text Box	Text OR Decimal
      Logistics Unit2_WidthDesignation	Text field OR Text Box	Text
      Logistics Unit2_Height	Text field OR Text Box	Text OR Decimal
      Logistics Unit2_HeightDesignation	Text field OR Text Box	Text
      Logistics Unit2_Length	Text field OR Text Box	Text OR Decimal
      Logistics Unit2_LengthDesignation	Text field OR Text Box	Text
      Logistics Unit2_Scope	Text field OR Text Box	Text
      Logistics Unit2_Weight	Text field OR Text Box	Text OR Decimal
      Logistics Unit3_Width	Text field OR Text Box	Text OR Decimal
      Logistics Unit3_WidthDesignation	Text field OR Text Box	Text
      Logistics Unit3_Height	Text field OR Text Box	Text OR Decimal
      Logistics Unit3_HeightDesignation	Text field OR Text Box	Text
      Logistics Unit3_Length	Text field OR Text Box	Text OR Decimal
      Logistics Unit3_LengthDesignation	Text field OR Text Box	Text
      Logistics Unit3_Scope	Text field OR Text Box	Text
      Logistics Unit3_Weight	Text field OR Text Box	Text OR Decimal
      Logistics Unit4_Width	Text field OR Text Box	Text OR Decimal
      Logistics Unit4_WidthDesignation	Text field OR Text Box	Text
      Logistics Unit4_Height	Text field OR Text Box	Text OR Decimal
      Logistics Unit4_HeightDesignation	Text field OR Text Box	Text
      Logistics Unit4_Length	Text field OR Text Box	Text OR Decimal
      Logistics Unit4_LengthDesignation	Text field OR Text Box	Text
      Logistics Unit4_Scope	Text field OR Text Box	Text OR Decimal
      Logistics Unit4_Weight	Text field OR Text Box	Text OR Decimal
      Successful Update By ByggeBasen (need to be mapped for scheduled action)	Select Box, Radio buttons, Status field	Text, default text: No Options: Yes, No
      Scheduled Update By ByggeBasen* (need to be mapped for scheduled action) *Mapping option removed in v.18	Text field	Date

      Only the DB Item ID field is required. It is a key field in mapping. All other fields are optional and can be mapped depending on what data needs to be transferred.
      Note! DB Item ID fields should contain unique values.

   2. Image Module with the following fields:

      Field Name	Field Type	Field Content
      File	File Field,Multiple File Field	File or Multiple Files
      File Size	Text field	Integer

      Image Module cannot be the same as Product module, product images are planned to be stored within an inline module, every file as the separated item.

3. In the Site Configuration page open ‘Connections’ -> ‘Connected Services’ list and create the connected account and connected service for BygeeBasen:
   Account settings:

   Parameter	Description
   Service Name	Descriptive name of the integration service. The name will be displayed in the configuration of “Send to connected service” action
   Account	You can select from existing accounts or leave “Create new…” to create the new one on this step
   Account Name	Descriptive name of the service account
   URL	Link to the web service
   User Number	Credentials to connect to the web service
   User Name
   Password

   

4. Select the modules created in step #2.

   Parameter	Description
   Product Module	A module in Encodify that will be used for storing product data
   Image Inline Module	A module in Encodify that will be used for storing product files
   File Name Regex	Regex to filter files provided by ByggeBasen only Java Regular expressions can be used If a filename is not matching the regex, the file will be skipped and the corresponding message is added to the log on debug level.

   

5. Map fields:
   Please note:

   • The ‘DB_Item_Id’ field is required. When it is not mapped - the validation triggers and setting can not be saved;

   • More than 1 BB field can not be mapped to the same Encodify field;

   • 'File Size' field becomes required once 'File' field is mapped.

6. Create Action in the Product Module.

   The following events are available for the Send to connected service action:

   • Create

   • Update

   • Delete

   • Сreate and Update

   • Workflow

   • Scheduled

   To create an action:

   1. Click Create Action in Actions menu in Module Configuration.

   2. Enter action name > select the event.

   3. Add filters if needed.

   4. Select Send to connected service in the Action field.

   5. Select the configured  ByggeBasen connected service. 

   6. Save.

   

   Please note, that:

   1. Create/Update Action with BB connected service can be used independently, but Scheduled Action always needs Create/Update Action first.

   2. If a configuration has 2 different Scheduled Actions, every action must have its own pair of 'Scheduled Update By ByggeBasen' and 'Successful Update By ByggeBasen' fields.

   3. When Scheduled Action runs it needs to calculate a fromDate - the time point from which to request changes from BB service:

   • If there are items in the Product module with 'Successful Update By ByggeBasen' == 'Yes' (== at least one item was successfully updated by this Scheduled Action before), then the maximum value of 'Scheduled Update By ByggeBasen' will be taken as fromDate;

   • If there are no items in the Product module with 'Successful Update By ByggeBasen' == 'Yes' (== no one item was successfully updated by this Scheduled Action), then the maximum of 'Update By ByggeBasen' will be taken as fromDate (== item was updated manually and this is a start point to keep this item up-to-date);

   • If 'Update By ByggeBasen' also empty for every item in the module, then do nothing.

   Scheduled action won't be triggered if there were no changes made in products in ByggeBasen since 'fromDate'.

   Usage

   When the configured action triggers - the corresponding data transfers from the ByggeBasen system to Encodify system in mapped fields:

   • Product data will be saved in Product module;

   • Product file will be saved as a new item in the Image module (if file name matches the regex).

   Images will be linked to the corresponding products via the module link to Products in Images module. No additional actions are required for this.

    

   Note, that in case more than 1 module link pointing to "Product" module are present in module "Images", following standard system functionality the 1st module link (the one with smallest field ID) will be populated.

    

   Please note, that there is only one-side transfer. Only Encodify item can be updated by transferred data. The BB item should not be affected by Encodify data.

   To see more messages in the log Debug mode need to be enabled for dk.encode.ebms.connections.byggebasen.ByggeBasenServiceImpl.

   Mapping configuration changes in version 18

   ---

   In version 18, the ByggeBasen connected service is updated for improved integration and efficiency. 

   New concept “Custom mappings”: allows to dynamically add new mappings for the “Product“ module mapping section. This mapping is processed in the same way and uses the same notation to define the path as the response mapping in the HTTP action.

   • REST API Integration with Byggebassen:
     ByggeBasen connected service now utilizes REST API for up-to-date integration with Byggebassen, ensuring a seamless and reliable connection.

   • Dynamic Field Mapping for Products:
     Admin users can dynamically add/remove mapped fields in a connected service, adapting to changes in third-party service response structures.

   • Optimized Synchronization:
     Synchronization of Products and linked files is optimized by using the connected service's API for obtaining IDs of recently changed entities, reducing sync times.

   

   Add Custom Mapping

   • The mapping section of the ByggeBasen connected service has a button “Add custom mapping“ (for the “Product“ module only)

   • Click on the button “Add custom mapping“ creates a new mapping section, where it is possible to specify the custom mapping’s name and path and to map a field definition

   • If a name or a path is not provided or the path is not valid*, on saving the connected service an error message should appear

   • valid path - the same validation applied as during the configuration of the HttpAction (path is valid from the perspective of Jayway library, which is used currently to extract mapped values from a JSON response)

   • it is possible to delete a custom mapping. When it is deleted, it does not appear in the section “Fields that are available to be mapped”

   PRODUCT Module
   Field Name	Custom Mapping Path
   DB Item No.* *Required field	Predefined field - Mapping available from a dropdown
   Successful Update By ByggeBasen	Predefined field - Mapping available from a dropdown
   Updated By ByggeBasen	Predefined field - Mapping available from a dropdown
   BB User Id	$.getProduktResult.Result[0].TUNBRUGERNR
   Color	$.getProduktResult.Result[0].FARVE
   Construction Delivery Clause	$.getProduktResult.Result[0].BYGGELEV_KLAUSUL
   convert 2	$.getProduktResult.Result[0].Omregn_2
   convert 3	$.getProduktResult.Result[0].Omregn_3
   convert 4	$.getProduktResult.Result[0].Omregn_4
   Country of origin	$.getProduktResult.Result[0].OPR_LAND
   e-commerce item	$.getProduktResult.Result[0].eHandlesVare
   EAN ID	$.getProduktResult.Result[0].Ean_1
   EAN No 3	$.getProduktResult.Result[0].Ean_3
   EAN No 4	$.getProduktResult.Result[0].Ean_4
   Effective Date	$.getProduktResult.Result[0].Priser[-1].IKRAFTRAEDDATO
   FSC / PEFC marking	$.getProduktResult.Result[0].PEFC
   Height	$.getProduktResult.Result[0].HOEJDE
   Indicative price* *Value from the newest price object (last object in the list of “Priser“ array)	$.getProduktResult.Result[0].Priser[-1].VEJL_UDSALGSPRIS
   Information text	$.getProduktResult.Result[0].OPLYSNINGSTEKST
   Item Group Id	$.getProduktResult.Result[0].VAREGRUPPEID
   Item text 1	$.getProduktResult.Result[0].VARETEKST1
   Item text 2	$.getProduktResult.Result[0].VARETEKST2
   Item text 3	$.getProduktResult.Result[0].VARETEKST3
   Length	$.getProduktResult.Result[0].LAENGDE
   List price* *Value from the newest price object (last object in the list of “Priser“ array)	$.getProduktResult.Result[0].Priser[-1].LISTEPRIS
   Logistics Unit1_Height	$.getProduktResult.Result[0].LogistikOplysninger[0].Hoejde
   Logistics Unit1_HeightDesignation	$.getProduktResult.Result[0].LogistikOplysninger[0].HoejdeBetegn
   Logistics Unit1_Length	$.getProduktResult.Result[0].LogistikOplysninger[0].Laengde
   Logistics Unit1_LengthDesignation	$.getProduktResult.Result[0].LogistikOplysninger[0].LaengdeBetegn
   Logistics Unit1_scope	$.getProduktResult.Result[0].LogistikOplysninger[0].rumfang
   Logistics Unit1_Weight	$.getProduktResult.Result[0].LogistikOplysninger[0].vaegt
   Logistics Unit1_Width	$.getProduktResul.Result[0].LogistikOplysninger[0].Bredde
   Logistics Unit1_WidthDesignation	$.getProduktResult.Result[0].LogistikOplysninger[0].BreddeBetegn
   Model type	$.getProduktResult.Result[0].MODEL_TYPE
   Order unit	$.getProduktResult.Result[0].ORDREENHED
   Producer	$.getProduktResult.Result[0].PRODUCENT
   Product type	$.getProduktResult.Result[0].PRODUKTTYPE
   Product type id	$.getProduktResult.Result[0].PRODUKTTYPEID
   Size new	$.getProduktResult.Result[0].STOERRELSE
   Special request item	$.getProduktResult.Result[0].ORDREENHED
   Supplier ID	$.getProduktResult.Result[0].LEVERANDOERNR
   Supplier item id new	$.getProduktResult.Result[0].LEVERANDOERVARENR
   Tariff item number	$.getProduktResult.Result[0].TOLDPOSITIONSNR
   Thickness	$.getProduktResult.Result[0].TYKKELSE
   UNIT 1	$.getProduktResult.Result[0].Enhed_1
   unit 2	$.getProduktResult.Result[0].Enhed_2
   unit 3	$.getProduktResult.Result[0].Enhed_3
   unit 4	$.getProduktResult.Result[0].Enhed_4
   Unit Height	$.getProduktResult.Result[0].ENHED_HOEJDE
   Unit length	$.getProduktResult.Result[0].ENHED_LAENGDE
   Unit Size	$.getProduktResult.Result[0].ENHED_STOERRELSE
   Unit thickness	$.getProduktResult.Result[0].ENHED_TYKKELSE
   Unit width	$.getProduktResult.Result[0].ENHED_BREDDE
   UNSPCS	$.getProduktResult.Result[0].unspsc
   UPC ID	$.getProduktResult.Result[0].UPCNR
   Updated on	$.getProduktResult.Result[0].Ajour_dato
   Volume	$.getProduktResult.Result[0].RUMFANG
   Weight	$.getProduktResult.Result[0].VAEGT
   Width	$.getProduktResult.Result[0].BREDDE
   IMAGE Module
   Field Name	Custom Mapping Path
   File* *Required field	Predefined field - Mapping available from a dropdown
   File Size* *Required field	Predefined field - Mapping available from a dropdown

   Custom Mapping Example:

   “Supplier No.“ (LEVERANDOERNR) custom mapping:
   The response of the ByggeBasen POST: http://url/getProdukt contains the property “LEVERANDOERNR“:

   {
       "getProduktResult": {
           "EllapsedMillis": 109,
           "Message": "",
           "Success": true,
           "TypeOfObject": "System.Collections.Generic.List`1[ByggebasenClassLibraries.Produkt]",
           "Result": [
               {
                   "Ajour_Id": null,
                   "Ajour_dato": "/Date(1699265620170+0100)/",
                   "CandListSubs": true,
                   "DBNR": 2052628,
                   "LEVERANDOERNR": "50442002"
                }
            ]
         }
   }

   For our response mapper to work, the correct path to this property should be provided:

   $.getProduktResult.Result[0].LEVERANDOERNR

   For more information about JayWay JsonPath expressions here.

Limitations

1. Until we have the Update access rights for the ByggeBasen system we can not assure the following:

   • Some fields always come from BB to Encodify empty. We can not check the data which might be received.

   • Using of the different special characters in the file names.

   • How the Encodify item is updated when some changes have been performed to the BB item.

   • Updating of 1000+ products. (Only 597 products can be updated at once using provided data)

2. Only the following field types are currently supported:

   • Text,

   • Integer,

   • Decimal,

   • Date,

   • Multiple Files Field,

   • Single Files Field.

3. There was discovered that some Encodify fields receive data that is different from that one that is present in the BB. The examples of the fields: 

   • ‘UNSPSC’, 

   • ‘E-commerce’.

4. Inactive items are not updated by scheduled 'send to connected service' action;

5. It's better to have an interval between scheduled action loops at least 5 min. There are products containing big amount of files, the whole set of files comes at once, it takes time to process all the files, if scheduled action has a 1 minute interval and the second loop of the action starts in 1 minute there is a possibility to have a duplicated items in inline Image module;

6. File Validation is ignored: File from ByggeBasen gets synced (is uploaded to item info sheet) even if it doesn't match configured file name validation.

Related Articles:

Copy to HTTP Server - Map Response Data