Updating existing products

1. Updating product name or status

   After a product is created, the only essential data that can be updated and changed is the product name, specific type and status.

   To change a product's name, use the Update product endpoint.

   
   

   To change a product's status - expire it or activate it anew, use the Update product status endpoint.




2. Updating the product's template version

   Data templates can be edited and updated - adding a new property, changing a predefined value, etc. When this happens, a new version of the template is created and it receives a new version GUID. In order for the user to be able to fill in values for the newly added properties or select the newly applied predefined values, the template version of the product needs to be updated.

   Important to note: The newer version of the template might exclude entities that were previously featured (f.ex. Properties or predefined values). If the product had property values, based on the removed entities, they will be lost - they will no longer appear on the product.

   To update a product to the latest approved template version, use the Update template to latest version endpoint.

3. Managing product properties

   For managing product properties for which no values were previously provided, updating/editing a property value that was previously entered or delete values for properties, by providing the guid of the property that needs to be deleted use the Manage property values endpoint.

Getting product data

You can go about getting product data in a different order, depending on what kind of information you need. The workflow described in this section is an example one and you can use all GET endpoints in a different order, depending on your needs. The only thing you need to provide to access the information for a product is its Cobuilder ID ("Id").

1. Search for products in the product list

   The search endpoints can be modified, depending on your needs. For more information and examples on how to use them, go back to the "Searching for products" section.

   Important to note: No matter how you structure your search, the returned results will include the products' Cobuilder ID. This is the parameter that you will need to provide in all the GET request URLs, in order to access the information for that product.

   Example response:

   {
     "results": [
       {
         "id": 1000000,
         "country": "NO",
         "name": "My example product",
         "description": "string",
         "spn": "12345",
         "gtin": "123456789",
         "gmn": "93778412894",
         "isExpired": false,
         "specificType": "Regular"
       }
     ],
   }                
               




2. Get information about the product

   To get the essential information for the product - name, identifiers, country of distribution, use the Get Product Details endpoint. To get the information in a specific language, provide a culture code in the request URL.




3. Get a product's construction object

   To get the product's construction object type, use the Get construction object endpoint. To get the information in a specific language, provide a culture code in the request URL.




4. Get a product's template

   To get information on the specific template version that the product is based on, use the Get template. To get the information in a specific language, provide a culture code in the request URL.




5. Get a product's properties

   To get all of the product's property values, use the Get property values endpoint. To get the information in a specific language, provide a culture code in the request URL.

   Here's an example:

   
   

   [
     {
       "propertyTitle": "Title",
       "propertyDefaultTitle": "Default title",
       "unitTitle": "unit",
       "unitDefaultTitle": "unit",
       "standardisedPropertyGuid": "1AaaAAAAA3AB_AEiKWuclN",
       "valueDataType": 5,
       "values": [
         {
           "enumValue": "value",
           "value": "translation string uk",
           "lowerValue": "value",
           "lowerOperator": "eq",
           "upperValue": "value",
           "upperOperator": lt,
           "additionalInformation": "string",
           "isNotApplicable": false,
           "valueTranslations": [
             {
               "text": "translation string no",
               "languageCode": "nb-NO"
             }
           ]
         }
       ],
       "isArchived": false,
       "genericDataSource": "string",
       "propertyGuid": "1AaaAAAAA3AB_AEiKWuclN",
       "unitGuid": "2Bb4BbbBb5tA7aLXxq_b$B"
     }
   ]
   
               




6. Get a product's picture, documents or other attributes

   If you want to access the other data, connected to the product, you can use the different endpoints that are about each asset type:

   • Get photos
   • Get documents
   • Get BIM objects
   • Get BIM files
   • Get components
   To get the information in a specific language, provide a culture code in the request URL.

Searching for products

The Products API offers two kinds of product searches - one which is based on the main product data - identifiers, country of distribution, product specific type, and another one which is based on the product's construction object type and its properties.

Important to note: However, you structure your search, the returned results will include the products' Cobuilder ID. This is the parameter that you will need to provide in all the GET request URLs, in order to access the information for that product.

Here's how you can use the search endpoints:

1. Search, based on the main product information

   The Product Search endpoint can filter the products in your product list, based on the following criteria:

   • SPN
   • GTIN
   • GMN
   • Identifiers - NOBBNR, ELNR, NRFNR
   • Country of distribution
   • Specific product type
   • Status
   
   The criteria you don't need can be omitted from the request body. Or, for a more specific search, the parameters can also be combined.

   Example for a search that returns all active products existing on the account:

   {
     "filtration": {
         "includeExpired": false
     }
   }

   Example for a search that returns all active products with country of distribution Norway:

   {
     "filtration": {
       "countries": [
         "NO"
       ],
       "includeExpired": false
     }
   }

   Example for a search that returns a product with country of distribution Norway and has a particular SPN:

   {
     "filtration": {
       "spn": "12345",
       "countries": [
         "NO"
       ],
       "includeExpired": false
     }
   }

   Example for a search that returns a product with country of distribution Norway and has a particular Identifier:

   {
     "filtration": {
       "identifiers":[
         {
           "name":"nobbnr",
           "value":"12345"
         }
       ]
       "countries": [
         "NO"
       ],
       "includeExpired": false
     }
   }

   
   

   As mentioned above, the returned results will include the products' Cobuilder ID. This is the parameter that you will need to provide in all the GET request URLs, in order to access the information for that product.

   Example response:

   {
     "results": [
       {
         "id": 1000000,
         "country": "NO",
         "name": "My example product",
         "description": "string",
         "spn": "12345",
         "gtin": "123456789",
         "gmn": "93778412894",
         "isExpired": false,
         "specificType": "Regular",
         "identifiers": [
           {
             "value": "string",
             "name": "string"
           }
         ],
         "productUrl": "string"
       }
     ],
   }                
               




2. Advanced search, based on additional product characteristics

   The Product Search endpoint can filter the products in your product list, based on the following criteria:

   • Product name
   • Product type-related characteristics - one of the following:
   • Construction object
   • Data template
   • Specific version of a data template
   • Property values
   
   The criteria you don't need can be omitted from the request body. Or, for a more specific search, the parameters can also be combined.

   Example for a search that returns all products containing a key word in their name (you need to provide at least 3 characters for the search to work):

   {
     "filtration": {
       "name": "Cobuilder product"
     },
     "pagination": {
       "skip": 0,
       "take": 50
     }
   }
   

   Example for a search that returns all products that have the same construction object:

   {
     "filtration": {
       "constructionObjectGuid": "exampleConstructionObjectGuid",
     },
     "pagination": {
       "skip": 0,
       "take": 50
     }
   }
   

   Example for a search that returns all products that are based on the same template, regardless of template version:

   {
     "filtration": {
       "templateGuid": "exampleTemplateGuid",
     },
     "pagination": {
       "skip": 0,
       "take": 50
     }
   }
   

   Example for a search that returns all products that are based on the same template version:

   {
     "filtration": {
       "templateVersionGuid": "exampleTemplateVersionGuid",
     },
     "pagination": {
       "skip": 0,
       "take": 50
     }
   }
   

   Example for a search that returns all products which have a certain property value. Providing the construction object is required when you are searching for property value matches:

   {
     "filtration": {
       "constructionObjectGuid": "exampleConstructionObjectGuid",
       "parentId": 0,
       "properties": [
         {
           "propertyGuid": "examplePropertyGuid",
           "values": [
             {
               "value": "5",
               "operator": "eq"
             }
           ]
         }
       ]
     },
     "pagination": {
       "skip": 0,
       "take": 50
     }
   }
   

   Example for a search that returns all products which have a certain property value:

   {
     "filtration": {
       "constructionObjectGuid": "exampleConstructionObjectGuid",
       "parentId": "111111",
       "properties": [
         {
           "propertyGuid": "examplePropertyGuid",
           "values": [
             {
               "value": "5",
               "operator": "eq"
             }
           ]
         }
       ]
     },
     "pagination": {
       "skip": 0,
       "take": 50
     }
   }
   
   

   
   

   As mentioned above, the returned results will include the products' Cobuilder ID. This is the parameter that you will need to provide in all the GET request URLs, in order to access the information for that product.

   Example response:

   {
     "results": [
       {
         "name": "string",
         "Id": 0,
         "parentId": 0,
         "specificType": "Regular"
       }             
               

Creating a document

The Products API allows enriching your product catalogue with product assets - documents, pictures, BIM objects. You can create documents independently from products or connect them directly to multiple products.

The Create document endpoint creates a document, based on a file to upload and a set of essential attributes, describing the document - name, type, countries where applicable. The available document types and countries are preset and can be found in the Relevant nomenclatures page.

Important to note: One file can only be uploaded once. An error will be returned if another upload of the same file is attempted.

Here's an example of creating a single document, not connected to a product:

Use content type: multipart/form-data

Example with curl (automatically determines the correct content type)

curl --location --request POST 
"https://api-test.cobuilder.no/products-management/api/v2/documents"
--header "Authorization:Bearer {token}"
--form "file=@"C:\Users\test\Desktop\Documentation.pdf""
--form "Type=Brochure"
--form "Countries=GB"
--form "Countries=NO"
--form "Name=Document name"

Here's an example of creating a single document, which is connected to a product upon its creation:

curl --location --request POST 
"https://api-test.cobuilder.no/products-management/api/v2/documents"
--header "Authorization:Bearer {token}"
--form "file=@"C:\Users\test\Desktop\Documentation.pdf""
--form "Type=Brochure"
--form "Countries=GB"
--form "Countries=NO"
--form "Name=Document name"
--form "ProductIds=123456"
--form "ProductIds=123457"

Updating a document

After a document is created, the file that was originally uploaded cannot be altered. The metadata for the document can, however, be changed. You can update the name, type and status of the product through the Update document endpoint .

Here's an example of changing the name and status of the document:

{
  "type": "Warranty",
  "status": "Expired",
  "name": "New name of document"
}

Searching for documents

A document can only be uploaded once. In case you have a product that needs to be connected to a document that was previously created, you can use the Search documents endpoint to browse through the documents that already exist on your account.

You can filter through the documents, based on different criteria like type, name and status. For a translation of the document type, you can also provide a culture code for the target language.

Here's an example of a search where we want to get only documents with document type Technical Data Sheet and with status Active:

{
  "filtration": {
    "status": "Active",
    "documentTypes": [
      "TechnicalDatasheet"
    ]
  },
  "pagination": {
    "skip": 0,
    "take": 50
  }
}

Relating documents and products

One document can apply to more than one product and the Products API accounts for that with the endpoints for relating and unrelating products and documents.

You have the opportunity to link multiple documents to multiple products or vice versa.

1. Adding relations between documents and products

   You can link one document to multiple products. Through the Add relations between documents and products endpoint you can do that for more than one documents.

   [
     {
       "productId": 123456,
       "documentId": 1
     },
     {
       "productId": 123457,
       "documentId": 1
     },
     {
       "productId": 123458,
       "documentId": 2
     }
   ]
   

2. Removing the relations between documents and products

   Sometimes a document needs to be unlinked from one or more products. The Remove relations between documents and products endpoint allows you to do that with multiple documents and products.

   Here's how you can unlink two documents from a few of their related products:

   [
     {
       "productId": 123456,
       "documentId": 1
     },
     {
       "productId": 123457,
       "documentId": 1
     },
     {
       "productId": 123458,
       "documentId": 2
     }
   ]