ByggeBasen Connected Service

ByggeBasen is the Danish product database for the building industry. The ByggeBasen connected service keeps your product data and product documentation in Encodify up to date automatically, so you don't have to copy specifications, prices or files by hand.

The service imports product data and files from ByggeBasen into your Encodify modules. You choose which ByggeBasen values to import and which Encodify fields to store them in. Imports run through actions, either when an item changes or on a schedule.

Data flows one way only: ByggeBasen updates Encodify items, and Encodify never changes data in ByggeBasen.

Please note: The ByggeBasen connected service must be enabled for your workspace.
Don't see it in your workspace? Contact your Encodify Engagement Manager to request access. You also need your ByggeBasen account details: the service URL, user number, user name and password.

Configuration

The configuration has five steps. Steps 2–4 follow the three pages of the connected service setup: Account Configuration, Service Configuration and Mappings. Use Next and Previous to move between the pages.

Step 1: Prepare Your Modules

The service uses two modules: a product module for product data, and an inline module for product files. The file module must be linked to the product module, and it can't be the same module as the product module. Each file is stored as a separate item.

In Module Configuration, add fields for the ByggeBasen values you want to import. A few fields are mandatory:

The service supports these field types: Text, Integer, Decimal, Date, Select Box, Single File and Multiple Files.

The DB Item No. number identifies a product across the Danish building industry. It was previously known as the TUN number, and many in the industry still use that name. The DB Item No. is the key that links an Encodify item to its product in ByggeBasen, so the service can only import data for items that have one.

Step 2: Account Configuration

1. Go to Sidebar > Configuration > Connected Services.

2. Create a new connected service and select ByggeBasen. The Account Configuration page opens.

3. Fill in the fields:

Click Next.

Step 3: Service Configuration

1. In the Product Module, select the module that stores product data.

2. In Image Inline Module, select the module that stores product files.

3. (Optional) In File Name Regex, enter a Java regular expression for the files to include. Only files whose names match are imported or updated, and all other files are skipped. Leave it empty to import all files.

4. Select Do not import files marked as not valid if you don't want files that ByggeBasen marks as not valid. Files that were imported earlier and later become not valid aren't removed. To track that, map Is Valid (see Step 4).

Click Next.

Please note: ByggeBasen can send file names with URL-encoded characters, for example dampsp%C3%A6rre_2500.pdf for dampspærre_2500.pdf. Keep this in mind when you write a File Name Regex: a pattern that contains special characters such as æ, ø or å may not match.

Step 4: Mappings

The Mappings page has one section for the product module and one for the file module. In each section, Mapped Fields lists the mappings you have set up. Use Search to find a field quickly.

Each mapping row shows the ByggeBasen value on the left and the Encodify field it's mapped to on the right.

To map a predefined value:

1. Find the value in the section for the module.

2. In the dropdown next to it, select the Encodify field to store the value in.

To add a custom mapping:

1. Click Add Custom Mapping in the section for the module. A new mapping row appears.

2. Enter a name for the mapping.

3. In Path, enter the JSONPath that points to the value in the ByggeBasen response. See the examples below.

4. In the dropdown, select the Encodify field to store the value in.

To remove a mapping: click the delete button at the end of the mapping row.

When all mappings are in place, click Save.

Note that

• Each Encodify field can receive only one ByggeBasen value.

• Every custom mapping needs a name and a valid JSONPath. If either is missing or the path is invalid, the connected service can't be saved.

• ByggeBasen leaves empty values out of its response. If there's no value for a mapped property, the Encodify field stays empty.

Product Module Mappings

DB Item No., Updated By ByggeBasen and Successful Update By ByggeBasen are predefined. You can't save the connected service until DB Item No. is mapped.

Custom mapping paths for products start from the root of the product response.

Example: Map the Supplier Item Number

A ByggeBasen product response looks like this (shortened):

{
  "getProduktResult": {
    "Success": true,
    "Result": [
      {
        "DBNR": 1494135,
        "LEVERANDOERNR": "79962121",
        "LEVERANDOERVARENR": "206-002",
        "VARETEKST1": "PHØNIX DAMPSPÆRRE 2500   1x10M",
        "Priser": [
          { "IKRAFTRAEDDATO": "/Date(1312149600000+0200)/", "LISTEPRIS": 462 },
          { "IKRAFTRAEDDATO": "/Date(1338760800000+0200)/", "LISTEPRIS": 485.1 }
        ]
      }
    ]
  }
}

To import the supplier item number (LEVERANDOERVARENR), use this path:

$.getProduktResult.Result[0].LEVERANDOERVARENR

Prices are returned as a list, with the newest price last. To import the newest list price, use [-1] to select the last entry:

$.getProduktResult.Result[0].Priser[-1].LISTEPRIS

Common Product Values

For the full list of product properties, see the getProdukt response in the ByggeBasen API documentation, available from ByggeBasen. Paths use standard JSONPath syntax.

File Module Mappings

File, File Size and Is Valid are predefined.

Custom mapping paths for files start from a single file entry, not from the root of the response. For example, ByggeBasen describes a file like this:

{
  "Area": "Dokumentation",
  "Group": "Lovpligtige dokumenter",
  "Text": "CE-mærkning",
  "ContentType": "application/pdf",
  "Created": "01-05-2015",
  "Gyldig": true,
  "Name": "DOP_NR_15_dampsp%C3%A6rre_2500_rev1.pdf"
}

To import the document group, use the path

$.Group

Common File Values

Important:

• ByggeBasen marks each file as valid or not valid, and this can change over time.

• The “Do not import files marked as not valid” setting only stops new files from being imported. It doesn't remove or update files that were imported while valid.

• Map ”Is Valid” to a field in the file module to keep the status up to date in Encodify. You can then use the field to filter, hide or archive files that are no longer valid. This also works when “Do not import files marked as not valid” is selected.

• Files that don't match the “File Name Regex” aren't updated. If you change the regex so that it no longer matches a file that was already imported, that file's Is Valid field keeps its last value.

• You can map “Is Valid” to either a Text Field or a Select/Radio Box with the values Yes and No.

Step 5: Create an Action

Imports run through the Sync with Connected Service action in the product module.

1. Open Module Configuration for the product module, then go to Actions > Create Action. The Edit Action page opens.

2. In Name, enter a name for the action (e.g., "ByggeBasen Scheduled Sync").

3. In Event, select Create, Update, Delete, Create and Update, Workflow or Scheduled.

4. Leave Disable Action cleared so that the action runs.

5. (Optional) Select Suppress on Bulk Operation to stop the action from running when items are changed in bulk.

6. (Optional) Under Filters: Trigger Action if, click Add Filter to limit which items the action runs on.

7. In Action, select Sync with Connected Service.

8. In Connected Service, select your ByggeBasen connected service.

9. If you selected the Scheduled event, choose a Type of Schedule (Minutes, Hourly, Daily, Weekly or Monthly) and set how often the action runs, for example, every 15 minutes.

Click OK.

Don't schedule the action to run more often than every 15 minutes. If a new run starts before the previous one has finished, duplicate files can potentially be created.

Sync Execution Logic

A scheduled action keeps your products up to date without anyone editing them.

When an action runs:

1. Product data is saved in the mapped fields of the product item.

2. Each product file is saved as a new item in the file module and is automatically linked to its product. If the file module has more than one module linked to the product module, the first link is used.

Technical Limitations and Troubleshooting

• Run interval: Schedule the action to run at most every 15 minutes. Some products have many files, and importing them takes time. If a new run starts before the previous one has finished, duplicate files can be created.

• Unique IDs: Keep DB Item No. values unique. Duplicate values cause updates to go to the wrong item.

• Missing values: If a mapped field stays empty, check that the product has a value for that property in ByggeBasen and that the path is spelt exactly as in the response. Paths are case-sensitive.

• Missing files: Check that the file names match your File Name Regex, if you set one, and whether Do not import files marked as not valid is selected.

If the problem continues, contact Encodify Support. Support can turn on detailed logging for the service, if needed.