API-Explanation: EPEA Product Compliance Assessment Service (ProCA)

Background Info

This short briefing shall give you an overview about the purpose and functioning of the EPEA Product Compliance Assessment Service API (Application Programming Interface).


Structure



Green-Building Schemes

  • There are several important Green-Building Schemes that will be implemented in the API in the nearby future. Currently available are the following:
 ⁠⁠DGNB Version 2018⁠ 
QNG
EU-Taxonomy
BNB
DGNB 2023
LEED v4.1
WELL
BREEAM (to be released in December 2024)


Product Categories

  • In order to make all products comparable we divide them in different categories. Every product will be assigned to one category.
  • To make sure we are working with a cross-sector categorising-system, we use the  "BAU-Warengruppenschlüssel" (BWGS) . A system that is also used by distributors, producers and suppliers and provides a unique nine digit number for every product category.
  • We reduced the BWGS by excluding all categories, that are not relevant for rating products for the available schemes. For example: Tools, Accessories for Gardening, Animal Supplies, repeating categories with the same content, etc.


Product Attributes

  • To decide if a certain product matches the relevant criteria, we created product attributes that describe the product in addition to its category.
  • These product attributes are based on the  buildingSMART UTC (Universal Type Code) . A service provided by buildingSMART to standardize product attributes across the construction sector. That means the product attributes that the API processes are compatible for easy exchange and comparison across the industry.


Rules & Preconditions

  • To select which exact part of the criteria a product corresponds to, we created "Rules" that are linked to the product categories. A Rule corresponds to a single formulated compliance requirement within the given system. That means, if a product category is selected, the API automatically selects a number of possible rules that are applicable for that category.
  • To decide whether a rule is applicable to a product or not, we implemented "Pre-Conditions": These process a check based on a reduced set of product attributes requesting less information than the rules themselves.

Pre-Conditions check which rule is applicable for a product, while rules check which result a product will achieve within a certain rating system.



Step-By-Step Guide for the API

The following Step-By-Step Guide will lead you through the process of using the API at the current testing stage.


Keycap 1 Select product category

  • Using the BWGS-List, you can select the right "CategoryID" for the product, you want to check.
The product categories are sorted in a hierarchical structure. Be sure to use the 8-Digit "id" in the last level for API calls. e.g. "11010504" for "XPS"


Keycap 2 Get "Preconditions" and required product attributes


  • By using the function "RequiredAttributesForPreconditions" you receive all product attributes relevant to select which criteria is applicable.


Input:

  • Insert the "CategoryID" (enable the "Try it out"-button first).

Example for a Request:
"https://app.conpli.eu/api/Proca/GetPreconditions/?categoryId=11010502&gbsIds=QNG23&gbsIds=DGNB18&gbsIds=EUTAX24"

Result:

  • As a response the requiredAttributes for fulfilling the Pre-Condition are given. For Example:
  • The requiredAttributes are important for the next step and need to be added to the provided product information.

[
  {
    "name": {
      "de-de": "Anwendungsbereich ist innen",
      "en-us": "Application Area is indoors"
    },
    "type": "boolean",
    "codeName": "UsedIndoors",
    "createdAt": "2023-08-04T09:19:12",
    "modifiedAt": "2024-05-31T06:07:04",
    "values": [],
    "UTC-ID": "ET08-USE3",
    "unit": ""
  },
  {
    "name": {
      "de-de": "Produkt ist rissüberbrückend ",
      "en-us": "Product is crackbridging "
    },
    "type": "boolean",
    "codeName": "CrackBridging",
    "createdAt": "2023-08-14T15:18:05",
    "modifiedAt": "2023-11-24T15:46:24",
    "values": [],
    "UTC-ID": "",
    "unit": ""
  },
  {
    "name": {
      "de-de": "Produkt besteht aus Mineralfaserwolle",
      "en-us": "Product consists of mineral wool"
    },
    "type": "boolean",
    "codeName": "MineralWool",
    "createdAt": "2023-09-07T16:21:14",
    "modifiedAt": "2023-11-24T15:46:24",
    "values": [],
    "UTC-ID": "ET05-MWOL",
    "unit": ""
  },
  {
    "name": {
      "de-de": "Produkt besteht aus Schaumglas",
      "en-us": "Product consists of foam glass"
    },
    "type": "boolean",
    "codeName": "FoamGlass",
    "createdAt": "2023-09-07T16:23:03",
    "modifiedAt": "2023-11-24T15:46:24",
    "values": [],
    "UTC-ID": "",
    "unit": ""
  },
  {
    "name": {
      "de-de": "Produkt ist Drän- oder Wasserspeicherelement aus Hartschaum",
      "en-us": "Product is a drainage or water storage element made of rigid foam"
    },
    "type": "boolean",
    "codeName": "RigidFoam",
    "createdAt": "2023-09-07T16:25:07",
    "modifiedAt": "2023-11-24T15:46:24",
    "values": [],
    "UTC-ID": "",
    "unit": ""
  },
  {
    "name": {
      "de-de": "Produkt wird als Dichtstoff für die Bereiche Glasbau, Fassade oder Brandschutz verwendet",
      "en-us": "Product is used as sealant for glass construction, facade or fire protection"
    },
    "type": "boolean",
    "codeName": "SealantForGlass",
    "createdAt": "2023-10-17T09:57:05",
    "modifiedAt": "2023-11-24T15:46:24",
    "values": [],
    "UTC-ID": "",
    "unit": ""
  },
  {
    "name": {
      "de-de": "Produkt ist Klebeband",
      "en-us": "Product is adhesive tape"
    },
    "type": "boolean",
    "codeName": "AdhesiveTape",
    "createdAt": "2023-10-17T14:00:49",
    "modifiedAt": "2023-11-24T15:46:24",
    "values": [],
    "UTC-ID": "",
    "unit": ""
  },
  {
    "name": {
      "de-de": "Das Produkt trägt (üblicherweise) einen relevanten Beitrag zu den gesamten Baukosten eines Projektes bei (>0,5%)",
      "en-us": "The product (usually) makes a relevant contribution to the total construction costs of a project (>0.5%)"
    },
    "type": "boolean",
    "codeName": "RelevantContributionToCost",
    "createdAt": "2024-03-18T14:03:42",
    "modifiedAt": "2024-04-05T08:57:37",
    "values": [],
    "UTC-ID": "",
    "unit": ""
  }
]



Keycap 4 Execute Pre-Conditions and get additional attributes


You can process the Pre-Conditions by inserting the Product-JSON in the "ExecutePreconditions" function.

This needs to be done per Green-Building System one after the other

Input:

To execute the preconditions, a complete product needs to be provided, that includes the relevantAttributes received in Step 2 within a product. For example:

First to rate after QNG:
{
  "categoryId": "11010502",
  "name": "XPS-Produkt",
  "product": {
    "attributes": {
      "RelevantContributionToCost": true,
      "UsedIndoors": false,
      "CrackBridging": false,
      "SealantForGlass": false,
      "AdhesiveTape": false,
      "MineralWool": false,
      "FoamGlass": false,
      "RigidFoam": false
    }
  },
  "assessmentId": "QNG23"
}

Then to rate after DGNB18
{
  "categoryId": "11010502",
  "name": "XPS-Produkt",
  "product": {
    "attributes": {
      "RelevantContributionToCost": true,
      "UsedIndoors": false,
      "CrackBridging": false,
      "SealantForGlass": false,
      "AdhesiveTape": false,
      "MineralWool": false,
      "FoamGlass": false,
      "RigidFoam": false
    }
  },
  "assessmentId": "DGNB18"
}

Once your product has been written as a .json file you can insert it in the "ExecutePreconditions" function.
Be sure to provide all "Required Attributes" that you received in Step 1 under "product"."attributes" - otherwise the call will result in an error


Response:

  • In the "Response body" you will receive all applicable rules in the "rules" and the additional required product attributes to process the rules under "requiredAttributes". For example:
{
  "status": "HasRequirements",
  "rules": [
    {
      "ruleId": "WB117",
      "name": {
        "de-de": "Produkt aus Sekundärrohstoffen",
        "en-us": "Product from secondary material sources"
      },
      "requiredAttributes": [
        "RecycledContentPreConsumer",
        "RecycledContentPostConsumer",
        "NoChildLabor",
        "NoIllegalMining",
        "ProcessingInEurope"
      ]
    },
    {
      "ruleId": "WB110",
      "name": {
        "de-de": "Grundlegende Anforderungen an verantwortungsvoll beschaffte Rohstoffe",
        "en-us": "Basic requirements for responsibly sourced raw materials"
      },
      "requiredAttributes": [
        "NoChildLabor",
        "NoIllegalMining",
        "ProcessingInEurope",
        "CsrAvailable"
      ]
    },
    {
      "ruleId": "WB45",
      "name": {
        "de-de": "40 - Kunstschaum-Dämmstoffe für Gebäude und Haustechnik",
        "en-us": "40 - Artificial foam insulation materials for building and building services engineering"
      },
      "requiredAttributes": [
        "MineralWool",
        "FoamGlass",
        "RigidFoam",
        "HalogenatedBlowingAgentsFree"
      ]
    }
  ],
  "requiredAttributes": [
    {
      "name": {
        "de-de": "Produkt besteht aus Mineralfaserwolle",
        "en-us": "Product consists of mineral wool"
      },
      "type": "boolean",
      "codeName": "MineralWool",
      "createdAt": "2023-09-07T16:21:14",
      "modifiedAt": "2023-11-24T15:46:24",
      "values": [],
      "UTC-ID": "ET05-MWOL",
      "unit": ""
    },
    {
      "name": {
        "de-de": "Produkt besteht aus Schaumglas",
        "en-us": "Product consists of foam glass"
      },
      "type": "boolean",
      "codeName": "FoamGlass",
      "createdAt": "2023-09-07T16:23:03",
      "modifiedAt": "2023-11-24T15:46:24",
      "values": [],
      "UTC-ID": "",
      "unit": ""
    },
    {
      "name": {
        "de-de": "Produkt ist Drän- oder Wasserspeicherelement aus Hartschaum",
        "en-us": "Product is a drainage or water storage element made of rigid foam"
      },
      "type": "boolean",
      "codeName": "RigidFoam",
      "createdAt": "2023-09-07T16:25:07",
      "modifiedAt": "2023-11-24T15:46:24",
      "values": [],
      "UTC-ID": "",
      "unit": ""
    },
    {
      "name": {
        "de-de": "Frei von halogenierten Treibmitteln",
        "en-us": "Free of halogenated propellants"
      },
      "type": "boolean",
      "codeName": "HalogenatedBlowingAgentsFree",
      "createdAt": "2023-09-07T16:29:15",
      "modifiedAt": "2024-03-12T08:26:15",
      "values": [],
      "UTC-ID": "",
      "unit": ""
    },
    {
      "name": {
        "de-de": "Frei von Kinder- und Zwangsarbeit",
        "en-us": "Free from child and forced labor"
      },
      "type": "boolean",
      "codeName": "NoChildLabor",
      "createdAt": "2023-12-20T18:45:36",
      "modifiedAt": "2024-03-11T14:49:24",
      "values": [],
      "UTC-ID": "",
      "unit": ""
    },
    {
      "name": {
        "de-de": "Frei von illegal gewonnenen Rohstoffen",
        "en-us": "Free of illegally extracted raw materials"
      },
      "type": "boolean",
      "codeName": "NoIllegalMining",
      "createdAt": "2023-12-21T08:02:36",
      "modifiedAt": "2024-03-12T08:16:29",
      "values": [],
      "UTC-ID": "",
      "unit": ""
    },
    {
      "name": {
        "de-de": "Materialgewinnung und Verarbeitung in Europa",
        "en-us": "Material extraction and processing in Europe"
      },
      "type": "boolean",
      "codeName": "ProcessingInEurope",
      "createdAt": "2023-12-21T08:06:53",
      "modifiedAt": "2024-03-11T14:49:05",
      "values": [],
      "UTC-ID": "",
      "unit": ""
    },
    {
      "name": {
        "de-de": "CSR-Bericht und Herkunftsnachweise verfügbar",
        "en-us": "CSR report and certificates of origin available"
      },
      "type": "boolean",
      "codeName": "CsrAvailable",
      "createdAt": "2023-12-21T08:08:18",
      "modifiedAt": "2024-03-11T14:50:00",
      "values": [],
      "UTC-ID": "",
      "unit": ""
    },
    {
      "name": {
        "de-de": "Pre-Consumer Recycled Content",
        "en-us": "Pre-Consumer Recycled Content"
      },
      "type": "number",
      "codeName": "RecycledContentPreConsumer",
      "createdAt": "2024-01-01T12:19:24",
      "modifiedAt": "2024-03-11T14:48:49",
      "values": [],
      "UTC-ID": "",
      "unit": "%"
    },
    {
      "name": {
        "de-de": "Post-Consumer Recycled Content",
        "en-us": "Post-Consumer Recycled Content "
      },
      "type": "number",
      "codeName": "RecycledContentPostConsumer",
      "createdAt": "2024-01-01T12:23:33",
      "modifiedAt": "2024-10-07T07:47:47",
      "values": [],
      "UTC-ID": "",
      "unit": "%"
    }
  ]
}
The required attributes for Rules also include the required attributes for Pre-Conditions that were already included in the last step.


Keycap 5 Execute the Assessment and get the result


You can process the Assesment by inserting the Product-JSON in the "Execute Assesment" function.


Input:

  • Add any requiredAttribute received in Step 4 to the Product JSON and execute the Request. For example:
{
"assessmentId": "01",
"categoryId": "07040198",
"product": {
    "productName": "example product",
    "attributes": {
        "FormworkOil": true,
        "Giscode": "BTM10"
        }
    }
}


Result:

The "Response body" shows the aggregated result of the qualification.
  • assessmentResults.result shows you the final Result of the Assessment.
  • Under assessmentResults.ruleResults.value you can find the results for each Rule that has been executed.
{
  "assessmentResults": [
    {
      "resulType": {
        "resultTypeId": "ENV12QL",
        "name": "ENV1.2 Quality Level"
      },
      "result": 3,
      "ruleResults": [
        {
          "ruleId": "DGNBRU14",
          "ruleResultStatus": "RequirementsPassed",
          "value": 3
        }
      ]
    }
  ]
}