2. Service operation overview

Order delivery

There are two mechanisms of sending an order (a delivery list):

• Upload an order via FTP. The user can upload an XML file into an FTP directory.
• Send a web request to the Connect web service.

Order processing status

There are two ways to receive information about the status of the order. They correspond to the order delivery mechanism. Both status messages have the same structure and are returned to the Connect user in the following formats:

• XML file in a dedicated log folder in the FTP directory (when sending orders via FTP)
• Web service response (when sending orders via the web service)

Processing the orders

Orders are processed in two stages:

• When an order is received (either via the web service or by uploading an order XML file in the FTP directory), it is initially stored in the database and then processed immediately. Historical records of the processing are generated and can be used further for reporting and issue tracking.
• On regular basis (i.e. every hour), the oldest failed orders are re-processed (but not those failed within the last 24 hours).

3. Description of functionalities

Brief description

In order to use the web service, a username and a password are required. Those are provided by Cobuilder. The communication with the service is secured as described below. Every request to the service will process only one order. The hours for sending messages (orders?) through the service, if nothing else has been agreed, are between 06.00 – 20.00 CET (GMT+1). Any deviation from these times must be agreed upon. Messages (orders?) sent outside this time period, could end up not being processed, e.g. in case of maintenance of hardware or software.

Technical specification

• URL for test environment: http://130.185.253.34:8005/ProductService.svc?wsdl
  • This is test server
  • Username: to be provided by Cobuilder
  • Password: to be provided by Cobuilder
  • PartyIdentifier: to be provided by Cobuilder
• URL for production environment:
  • This is production server.
  • User’s public IP is required for activation
  • Username: to be provided by Cobuilder after public IP is received
  • Password: to be provided by Cobuilder after public IP is received
  • PartyIdentifier: to be provided by Cobuilder
• Protocol for exchange of information: SOAP 1.1
• Maximum request message size: 9,500 kilobytes
• The average time for processing a delivery list is:
  • 1.4 seconds for 2 items
  • 2.4 seconds for 50 items
  • 2.5 seconds for 300 items

Security

• Authorization is executed on the basis of user credentials. The credentials are provided by Cobuilder. User credentials are passed in the Authorization HTTP message headers. (i.e. Authorization: “Basic dXNlcm5hbWU6cGFzc3dvcmQ=” where the string “dXNlcm5hbWU6cGFzc3dvcmQ=” is the combination “username:password” base64 encoded.
• Messages are secured with SSL certificate and the communication is over HTTPS protocol.

Operations

Process (processing delivery list)

Data structure of the input data is described in point 3.3. (section Order) below.

When a request is sent, the service validates the input data. If a validation error occurs, the user receives OrderResponse with Status set to “General Error” with the validation error details described in StatusText. If the user receives such a response, the order should be sent again with corrected data. Orders that did not pass the initial validation will not be processed and will not show up in the customer’s log.

Once the XML validation is performed, the common processing starts (see point 3.3. Common processing).

Signature: public OrderResponse Process(Order order)

Brief description

To process a delivery list via FTP the user should upload an XML file in a designated FTP directory. The hours for sending messages through the service, if nothing else has been agreed, is between 0600 – 2000 CET (GMT+1). Any deviation from these times must be agreed upon. Messages sent outside this time period could end up not being processed, e.g. in case of maintenance of hardware or software. Every user allowed to import their delivery lists will have a designated folder (directory) for their organization. Each such directory will have the following subdirectories:

Name	Additional information
ToProcess	Files in this folder are to be processed. After processing a file from this directory, it will be moved to the Archived folder.
Archived	Files in this folder are already processed. Files appear in this folder after being processed. If a file with the same name is processed, the previous archived file is overwritten.
Logs	Each processed file will output a log file in this directory. Files in this directory will be saved with a timestamp of processing time as a name.
Error	Files in this folder are XML files that did not pass the Schema validation. Each XML order file is validated against the Nordic eBuilding (NeB) standard.
_Old	Files in these folders are files from the folders above older than 10 days, which have been archived in zipped format.

Security

Each user will have access to their own FTP root folder. Folders and credentials are set up by Cobuilder upon request.

Technical specification

• URL for test
  • This is test server.
  • Username: to be provided by Cobuilder
  • Password: to be provided by Cobuilder
  • PartyIdentifier: to be provided by Cobuilder
• URL for production
  • This is production server.
  • Username: to be provided by Cobuilder after public IP is received
  • Password: to be provided by Cobuilder after public IP is received
  • PartyIdentifier: to be provided by Cobuilder
• Restriction for delivery list file is that the file has a .xml extension – non .xml files will not be processed.
• The average time for processing a delivery list is:
  • 1.4 seconds for 2 items
  • 2.4 seconds for 50 items
  • 2.5 seconds for 300 items

Operations

Process (processing delivery list)

When the user uploads an XML file into the ToProcess directory, this file is added to a processing queue. Before any delivery list file is processed, an XML validation is executed. Nordic eBuilding (NeB) standard is used for validation plus some additional fields marked in point 3.3. (section Parameters), as well as in the XSD files (described in Related documents section above).

If the XML structure is not correct, no further actions are taken, and the file is not processed. The file is moved to the Error folder and the user receives the exact row and column of the error in the file. The error information can be found in the respective log file in the Logs folder.

After the XML validation, the common processing starts (see point 3.3. Common processing). Once a delivery list file is processed, the file will be moved into the Archived folder and a log file in the Logs folder will be created. The log files will be named with a timestamp of processing time (yyyyMMddhhmmssff.xml). The data structure of these files is described in section Order.

If a file with the same name is uploaded, the archived file will overwrite the previous one.

Brief description

• If the validation passes, the Cobuilder Connect service tries to map the data for buyer and supplier in the order to existing ProductXchange/Collaborate organizations. It also attaches the documents related to the delivered products. This is done by using the customer’s (buyer’s) organizational identification number (OrgNo) and projectID. The status for these operations is logged in the OrderResponse entity that is to be sent back to the user.
• Users (suppliers) not invited to a project by the customer (buyer) in ProductXchange/Collaborate will be automatically invited to the workplace if the buyer’s OrgNo and projectID are matched to the customer in ProductXchange.
• If a user (supplier) has subscribed to Cobuilder FREE service as well, every time an order is processed for non-subscribers to ProductXchange or Cobuilder PRO, the buyer’s contact (email address stored in the field Order.OrderHeader.BuyerNeB.BuyerContactNeB.EmailAddress) will receive an e-mail to inform them about the newly processed order. The message will contain a link to the order as well as a link for registration on the Cobuilder FREE website.
• Email recipients will be able to permanently unsubscribe from receiving notifications by simply navigating to a URL included in the notification.
• Successfully processed orders can be viewed in the Connect logs section in ProductXchange and on the Cobuilder FREE pages for customers without a ProductXchange agreement.

Order

Below is the structure of the delivery list order request. The format is based on the standard Nordic eBuilding order message format. The format has been slightly modified by adding a few fields to support some of the functionalities provided by Cobuilder’s solutions. For more information on the NeB standard check http://beast.se/standarder/nordic-ebuilding-neb/ordermeddelandet/

Each order consists of 3 sub-entities:
• OrderHeader
• OrderLine (array of the items delivered)
• OrderTrailer.

If a string is not marked with OPTIONAL or REQUIRED, then it is not read and should not be used!

The format of the order response form the service is described below:

There are several special conditions implemented in cases when it is important to be able to bypass required fields.

The fields where it is possible to bypass the required information and the mechanism for doing that are:

• ProjectNumber This is a required field. However, if a project number is not provided by the customer, the predefined code “NOPROJECTNUMBER” should be used. The products will be delivered to the customer in PXC/Collaborate but will not be connected to the project.
• BuyerContactNeb (Name, PhoneNumber, EmailAddress). Send the value NULL represented as string.
• OrderLines There is a validation rule that requires to have a valid ArticleIdentifier and ArticleDescription. There could be some order lines that are not of interest to the customer in terms of purchased articles. These can be referenced with some text to previous orders, transport, and other non-building related articles. To send such, please consider to use SupplierArticleNumber that equals “N/A” and add the sender’s organizational number under “ProductSupplierIdentifier”.
• MeasureUnitNeBType For consistency, it is advised to use UN/ECE Recommendation No.20 http://www.unece.org/fileadmin/DAM/cefact/recommendations/rec20/rec20_rev3_Annex2e.pdf
• Item_Status

This entity is part of the OrderResponse entity. It fills the ErrorList array. Item_Status entity presents information for the product along with its status after the processing.

• ObjectStatus

This entity describes the item status in terms of different factors

Upon request, we will send a development package containing example .NET solution for WCF and ASMX, XSD files and example XML file with the required and optional fields, depending on the choice of solution.

4. Processing delivery lists via web service

1. Create a product with specific type "Product line"

   In order to create a product line, you need to provide the same essential attributes, describing any other product – its name, construction object type, template version, specific type and country of distribution, as well as identifiers and additional optional data about it. Use the same endpoint as creating a single product – the Create product endpoint. The difference is in the specifc type of the product - this time use "ProductLine".

   Here’s an example of a json for a product line which is sold in Norway:

   Important to note: In the Create product endpoint response, we return the Cobuilder ID of the newly created product. The Cobuilder IDs are the unique identifiers of the products in our system and need to be provided each time when an action concerns a particular product - creating properties, updating, deleting or getting data. In this case, the Cobuilder ID is what you will need to provide when connecting single products under the product line. This ID will also be provided in the details of products and other product lines, belonging to this product line via the parameter ParentId.




2. Change the product type to Product line

   In case there is an already existing product in your catalogue that you want to turn into a product line, you can do so by using the Update product endpoint. It can change the specific product type of a product that has been created as "Regular". You can change it from “Regular” to “ProductLine” and vice versa.




3. Add existing products to a product line

   If the products that belong to the product line aren’t created yet, begin with the Create product endpoint in order to create them. If both the product line and the products that should belong to it are available in your ctalogue, use the Add children to product line endpoint to connect them to one another.

   Important to note:

   • The product line and the products under it need to have the same construction object
   • The product line and the products under it need to be based on the same template version
   • You can assign a product line as a part of another product line. The maximum levels such a hierarchy can have is 3
   • Property values, filled in on the parent level will be automatically added on the children levels. See Step 7 for more information

   In the URL – provide the product line Cobuilder ID. In the request body – provide the Cobuilder IDs of the products which should be a part of the product line.




4. Remove products from a product line

   If you need to remove products from a product line, use the Remove children from product line endpoint by putting the product line ID in the URL and providing the IDs of the product you want to remove from the line in the request body.




5. Search for product lines

   If you are specifically searching for product lines within your product catalogue, you can use the Product Search endpoint to filter the products which have specific type "ProductLine". As the hierarchic structure of a product line can have multiple levels and sub-lines, you can additionally filter the results, so that you only get the top level product lines - the one that do not belong to any other line.

   Here's an example of how the request body will look like:

   {
     "filtration": {
       "specificTypes": [
         "ProductLine"
       ],
       "includeExpired": true,
       "filterTopLevelProductLines": true
     },
     "pagination": {
       "skip": 0,
       "take": 50
     }
   }                
               




6. Get product line children

   In order to check which products belong to a product line, use the Get product line children endpoint by putting the product line ID in the request URL.

7. Manage property values for a product, which is a part of a product line – Create, Get, Update

   Property values entered on the parent level will be returned for all products and product lines, which belong to that parent product line. The ParentID parameter in the response will be filled in with the parent product line’s Cobuilder ID, in case the property value is inherited.

   Here's an example:

   The product line “Semi-glossed Cobuilder Paint” (Cobuilder ID: 111111) has the characteristic “finish”, which is common for all products of that group. The Get property values endpoint will return the following:

   [
     {
       "propertyGuid": "ExampleString",
       "unitGuid": "ExampleString",
       "propertyTitle": "finish",
       "propertyDefaultTitle": "finish",
       "unitTitle": "unitless",
       "unitDefaultTitle": "unitless",
       "parentId": 0,
       "values": [
         {
           "value": "semi-gloss",
           "dataType": "string"
         }
       ]
     }
   ]
   

   
   

   The regular product “Semi-glossed Cobuilder Paint 1L” is a part of the “Semi-glossed Cobuilder Paint” product line. When the product was attached, it automatically got the property values, entered on the higher hierarchic level. The response you will get for it will be the following:

   [
     {
       "propertyGuid": "ExampleString",
       "unitGuid": "ExampleString",
       "propertyTitle": "finish",
       "propertyDefaultTitle": "finish",
       "unitTitle": "unitless",
       "unitDefaultTitle": "unitless",
       "parentId": "111111",
       "values": [
         {
           "value": "semi-gloss",
           "dataType": "string"
         }
       ]
     }
   ]
   

   
   

   To add a new property value to the child product, you follow the same flow as with any other product. Send a request through the Create property values endpoint to create a new value. Here’s the GET response after we have added a property value for “color” only on the child product:

                   [
     {
       "propertyGuid": "ExampleString",
       "unitGuid": "ExampleString",
       "propertyTitle": "finish",
       "propertyDefaultTitle": "finish",
       "unitTitle": "unitless",
       "unitDefaultTitle": "unitless",
       "parentId": "111111",
       "values": [
         {
           "value": "semi-gloss",
           "dataType": "string"
         }
       ]
     }
   {
       "propertyGuid": "ExampleString",
       "unitGuid": "ExampleString",
       "propertyTitle": "color",
       "propertyDefaultTitle": "color",
       "unitTitle": "unitless",
       "unitDefaultTitle": "unitless",
       "parentId": 0,
       "values": [
         {
           "value": "Blue",
           "dataType": "string"
         }
       ]
     }
   ]
               

   
   

   When there is a value filled in on the parent level and you want to change it on a particular child product, you can follow the same flow as with any other product – use the Update property values endpoint to change that value.

   Important to note: Changing the property value on the child product level, will NOT change the value entered on the parent level. The property value will be overwritten only for the particular product with was updated and the parent value will no longer be visible for that product. If you want to change a value for the whole product line, you should update the product where it was originally entered – the parent product line.

   Here’s an example for a property value that has been updated on the child level:

   
   

   Get Property Values response for the product line “Semi-glossed Cobuilder Paint”:

              [
     {
       "propertyGuid": "ExampleString",
       "unitGuid": "ExampleString",
       "propertyTitle": "packaging size",
       "propertyDefaultTitle": "packaging size",
       "unitTitle": "litre",
       "unitDefaultTitle": "litre",
       "parentId": 0,
       "values": [
         {
           "value": "1",
           "operator": "gt"
           "dataType": "float"
         }
         {
           "value": "10",
           "operator": "lt"
           "dataType": "float"
         }
   
       ]
     }
   ]
   
          

   
   

   Get Property Values response for the child product “Semi-glossed Cobuilder Paint 1L”:

              [
     {
       "propertyGuid": "ExampleString",
       "unitGuid": "ExampleString",
       "propertyTitle": "packaging size",
       "propertyDefaultTitle": "packaging size",
       "unitTitle": "litre",
       "unitDefaultTitle": "litre",
       "parentId": 0,
       "values": [
         {
           "value": "1",
           "operator": "eq"
           "dataType": "float"
         }
       ]
     }
   ]
   
          

5. Processing delivery lists via FTP

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",
         "isExpired": false,
         "specificType": "Regular"
       }
     ],
   }                
               




2. Get information about the product

   To get the essential information for the product - name, identifiers, country of distribution, ID of the parent product line if it belongs to one, 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.

   Important to note: For products, which are part of a product line, the response will contain both values, filled in for that particular product, as well as values, filled in on the product lines that the product belongs to. Values, which are inherited from a higher hierarchic level will have the ParentID paramenter filled in with the Cobuilder ID of the product line it was originally filled in for.

   Here’s two examples:

   
   

   Property which belongs to the particular product. The “ParentId” is 0:

                   [
     {
       "propertyGuid": "ExampleString",
       "unitGuid": "ExampleString",
       "propertyTitle": "finish",
       "propertyDefaultTitle": "finish",
       "unitTitle": "unitless",
       "unitDefaultTitle": "unitless",
       "parentId": 0,
       "values": [
         {
           "value": "semi-gloss",
           "dataType": "string"
         }
       ]
     }
   ]
   
               

   Property which belongs to a product line that the particular product is a part of. ParentId is filled in with the Id of the parent product line where the property was inherited from:

                   [
     {
       "propertyGuid": "ExampleString",
       "unitGuid": "ExampleString",
       "propertyTitle": "finish",
       "propertyDefaultTitle": "finish",
       "unitTitle": "unitless",
       "unitDefaultTitle": "unitless",
       "parentId": "111111",
       "values": [
         {
           "value": "semi-gloss",
           "dataType": "string"
         }
       ]
     }
   ]
               




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.

6. Common processing

7. Parameters

8. Order response

4. Versions

The service has two endpoints that define the two currently available versions of the service. New clients should use the latest version described in this document.

4.1. Version 1.0.

Namespace: http://tempuri.org

Endpoint name: "basicEndpoint"

Service Contract: Cobuilder.ProductService.V2.IProductService

TEST WSDL URL: https://chemxchange.icb.bg/ ProductServiceV2WCF/ProductService.svc?wsdl

4.2. Version 1.1.

Namespace: http://www.Cobuilder.com/ProductService

Endpoint name: "cobEndpoint"

Service Contract: Cobuilder.ProductService.V2.IProductService_v1_1

TEST WSDL URL: https://chemxchange.icb.bg/ ProductServiceV2WCF/ProductService.svc?wsdl=wsdl0