Deprecation Notice

Please note the BOMcheck API v1 is now deprecated. This API is now considered legacy and will remain to be maintained and available for use but will no longer be formally supported. Please consider the new BOMcheck Platform API (v2) for all future integrations.

Recommendations

Downloading Declaration Data

Using the API to download declaration data for part numbers from BOMcheck into in-house IT systems

The BOMcheck APIs can be used to support a number of different use cases to download declarations data for part numbers from BOMcheck into in-house IT systems, as highlighted below.

The key points to bear in mind when working through the logic of how BOMcheck processes an API request are:

• All declarations that a supplier makes for a part are permanently archived in BOMcheck and are catalogued by the Approval date (date stamp) of the declaration. BOMcheck will always provide the manufacturer with data which has the most recent Approval date. For example, if the supplier created and Approved an FMD for a part on 2010-01-01 and then the supplier created and Approved a new FMD for the same part on 2013-01-01 then when the manufacturer searches for an FMD for this part BOMcheck will provide the FMD data that was Approved on 2013-01-01. Similarly, when the manufacturer searches for an RCD for this part then the manufacturer will find that BOMcheck used the FMD data that the supplier Approved on 2013-01-01 to calculate the RCD for this part.
• When new regulated substances are added to BOMcheck and BOMcheck uses the FMD data to calculate a new RCD (Class C XML) against this new regulated substances list, the Approval date for the FMD stays the same and the Approval date for the new RCD is set to the date that BOMcheck carried out the calculation. For example, BOMcheck was updated to version 3.2 on 17 July 2013 to include the new REACH SVHCs published 20 June 2013 and so at that point all RCDs generated from FMDs were given new Approval dates of 17 July 2013.
• If the supplier provides an FMD with up to 5% undeclared substances and the Manufacturer requests a Class D XML for this part (either by using the Manual interface or by including “D” or “Check D then C” in the API request parameters) then BOMcheck will provide a Class D+C XML. The Approval Date for the Class D+C XML is taken as the date that the supplier Approved the incomplete FMD. In other words, the Approval Date for the Class D+C XML is not set to the most recent date that BOMcheck calculated a new RCD from the FMD data.
• The Start Date parameter in the API enables you to request BOMcheck to only provide data which has an Approval date which is younger than the Start Date.

When a new supplier part (often termed a ‘manufacturer external part’) is created in the in-house IT system, then the IT system can send an API request to download any data which the BOMcheck supplier has already declared in BOMcheck for this part. In this case the API request should not include a startdate. This API request can use the checkDthenC variable to ask BOMcheck to check if FMD is available (and if so provide the Class D XML or Class D+C XML) and if not then check if RCD is available (and if so provide the Class C XML). For example, if a supplier has provided 100% FMD for parts A, B, C, D and only RCD data for parts 1, 2, 3, 4 and BOMcheck receives an API request with formatClass = checkDthenC then BOMcheck will return two XML files for this supplier - a Class D XML for parts A, B, C, D and a Class C XML for parts 1, 2, 3, 4.

If the part is not yet available to the Manufacturer in BOMcheck then this part number and BOMcheck supplier code can be added to a batch process which can resend the API request every day until the part is available and data is downloaded to the in-house IT system. In some cases the part is not available to the Manufacturer because the supplier has not declared it yet in BOMcheck. In other cases, the supplier may have already declared the part but made it confidential to other customers on BOMcheck. If the supplier adds the Manufacturer to their confidentiality settings then this part will now become available to the Manufacturer with its existing Approval Date. Therefore this API request should also not include a startdate and can include the checkDthenC variable to ask BOMcheck to check if FMD is available (and if so provide the Class D XML or Class D+C XML) and if not then check if RCD is available (and if so provide the Class C XML).

Once the part is available to the Manufacturer in BOMcheck and has been downloaded to the in-house IT system then the IT system can send an API request every day to check if there is updated declaration data for this part number in BOMcheck. This API request can include startdate to only download data which has an Approval Date which is younger than yesterday, b ut this needs to be used carefully. For example, to avoid over-writing Class D FMD data that the in-house IT system has already downloaded for a part with Class C RCD data when BOMcheck uses the FMD data to calculate a new RCD for the part, and so the new Class C RCD has a new Approval Date.

If the in-house IT system has already downloaded Class D FMD data for the part, then the daily API request for any updated data can include a startdate set to yesterday and should specify formatClass = D. In this case, BOMcheck will only return data for the part if a new FMD is available from the supplier for this part (and so there is a new Class D XML which has a new Approval Date).

If the in-house IT system has already downloaded Class C RCD data for the part, then the daily API request for any updated data can include a startdate set to yesterday and can specify formatClass = checkDthenC. In this case, BOMcheck will return data for the part if the supplier has approved a new FMD for the part (in which case the IT system will download a new Class D FMD for the part and then the daily API update request for this part will change to formatClass = D) or if there is a new RCD for the part (in which case the IT system will download a new Class C RCD for the part and the daily API update request for this part will stay as formatClass = checkDthenC).

“CheckDthenC” with Start Date

How BOMcheck processes an API request which includes “CheckDthenC” and a Start Date

The below scenarios clarify the logic for how BOMcheck processes an API request which includes checkDthenC and a Start Date, as at September 2013. The scenarios below assume that BOMcheck has generated an RCD from the FMD data (in other words, that either the supplier has provided 100% FMD data or that if the supplier had up to 5% undeclared substances then they signed the statement to enable BOMcheck to use these FMD data to generate an RCD).

Most recently Approved FMD for a part was made on 2013-01-01 and was 100% complete. The API request specifies checkDthenC and Start Date = 2012-05-30

BOMcheck will return a Class D XML which provides the 100% FMD data which the Supplier Approved on 2013-01-01. This is because BOMcheck starts by looking for the most recently Approved FMD data and finds that FMD data exists for this part and the Approval date for the FMD data is younger than the Start Date in the API request.

Most recently Approved FMD for a part was made on 2013-01-01 and had up to 5% undeclared substances. The API request specifies checkDthenC and Start Date = 2012-05-30

BOMcheck will return the Class D+C XML which provides the > 95% FMD data which the Supplier Approved on 2013-01-01 and the RCD data which BOMcheck calculated from this FMD data on 17 July 2013. This is because BOMcheck starts by looking for the most recently Approved FMD data for this part and finds that FMD data exists for this part and the Approval date for the FMD data is younger than the Start Date in the API request.

Most recently Approved FMD for a part was made on 2012-01-01 and was 100% complete. The API request specifies checkDthenC and Start Date = 2012-05-30

BOMcheck will return a Class C XML which provides the RCD data which BOMcheck calculated from the FMD data on 17 July 2013 (and so the RCD for this part has an Approval Date of 2013-07-17). This is because BOMcheck starts by looking for the most recently Approved FMD data and finds that FMD data exists for this part but the Approval date for the FMD data is older than the Start Date in the API request. So then BOMcheck looks for the most recently Approved RCD data and finds that RCD data exists for this part and the Approval date for the RCD data is younger than the Start Date in the API request.

Most recently Approved FMD for a part was made on 2012-01-01 and had up to 5% undeclared substances. The API request specifies checkDthenC and Start Date = 2012-05-30

(sic) BOMcheck will return a Class C XML which provides the RCD data which BOMcheck calculated from the FMD data on 17 July 2013 (and so the RCD for this part has an Approval Date of 2013-07-17). This is because BOMcheck starts by looking for the most recently Approved FMD data and finds that FMD data exists for this part but the Approval date for the FMD data is older than the Start Date in the API request. So then BOMcheck looks for the most recently Approved RCD data and finds that RCD data exists for this part and the Approval date for the RCD data is younger than the Start Date in the API request.

New CAS Numbers

Recommended approach for importing Class D XML files which contain BOMcheck CAS numbers which are not yet available in in-house IT system

The BOMcheck FMD tool includes 216,000 CAS numbers and 524,000 chemical substance names (the list includes common chemical names, synonyms and trade names for these CAS numbers) which BOMcheck purchased from the Canadian Centre for Occupational Health and Safety (www.CCOHS.ca). According to the Canadian Centre for Occupational Health and Safety, this list represents the CAS numbers and substance names for substances which are currently being used in engineering and manufacturing industry.

The listCasNumbers action in the BOMcheck Integration API provides the list of all 216,000 CAS numbers which are currently included in the BOMcheck tool and reports one substance name for each of these CAS numbers. This is permitted within BOMcheck’s license agreement with the Canadian Centre for Occupational Health and Safety, because BOMcheck is not publishing the full list of 524,000 chemical substance names and associated CAS numbers. Including one chemical substance name for each CAS number makes it easier for in-house IT systems to use the listCASNumbers file to look up CAS numbers when the user imports an IPC XML file from BOMcheck which contains a CAS number which is not yet included in the in-house IT system. The structure of the amended XML file is shown below.

@TODO: Image

Please note that BOMcheck can only provide one chemical substance name for each CAS number in the listCASNumbers file. Therefore, the chemical substance name for a CAS number in the IPC 1752A XML file that you download from BOMcheck may often be different to the chemical substance name for the same CAS number in the listCASNumbers file that you download from the BOMcheck Integration API.

BOMcheck recommends that the substance name in the listCASNumbers file should be used as the primary substance name in the in-house IT system. The IT system can detect if an IPC 1752A XML file has been generated by BOMcheck because the IPC 1752A XML file will include Response comment = “BOMcheck”, as highlighted in the below screenshot.

For IPC 1752A XML files which are generated by BOMcheck and contain a different substance name compared to the substance name in the listCASNumbers file, the in-house IT system could allow the user to choose between the following two options on how these different substance names are processed.

Option 1: Add the new BOMcheck CAS number from the listCASNumbers file into the in-house IT system by using the substance name in the listCASNumbers file as the primary substance name, and ignore any substance name associated with this CAS number in the IPC 1752A XML file. When the user views the supplier data in the in-house IT system they may see a different substance name against the CAS number compared to the substance name that the supplier selected for this CAS number in BOMcheck.

Option 2: Add the new BOMcheck CAS number from the listCASNumbers file into the in-house IT system by using the substance name in the listCASNumbers file as the primary substance name, and include any different substance name associated with this CAS number in the IPC 1752A XML file as an acceptable alias for this CAS number if Response comment = ”BOMcheck”. When the user views the supplier data in the in-house IT system then they can see the same substance name that the supplier selected for this CAS number in BOMcheck.

No Published CAS Numbers

How BOMcheck identifies REACH Candidate List substances in an FMD declaration, where ECHA has no published CAS numbers

There are many entries in the REACH Candidate List that are for a group of substances rather than an individual substance. Regarding published CAS numbers these substance groups fall into three scenarios:

1. ECHA has published a complete, exhaustive list of CAS numbers.
2. ECHA has not published CAS numbers but has provided a non-exhaustive, indicative list of CAS numbers in supporting documentation.
3. ECHA has not has not published CAS numbers and has not referenced any CAS numbers in supporting documentation.

Members of the BOMcheck Substance List Working Group share their chemical knowledge of these substance groups to identify CAS numbers which the supplier can select in the BOMcheck FMD tool to declare the presence of these REACH Candidate List substances in their parts.

FMDs with <100% Data

Class D+C XML provided by BOMcheck for parts with an FMD which contains <100% substance data

If a part has a FMD on BOMcheck which contains < 100% substance data (e.g. because the supplier has included up to 5% undeclared substances by screening them against the BOMcheck lists of currently regulated and likely future regulated substances) then the in-house IT system needs to receive a RCD from BOMcheck in addition to the FMD data so that the in-house IT system can set the compliance status for the part correctly when the IPC 1752A XML file is imported.

When the user (either by manually logging into BOMcheck or by using the data download API) requests a Class D declaration for a part (and the confidentiality settings allow the user to see FMD data for the part), then BOMcheck will check if there is 100% substance information in the FMD declaration for the part. If yes, then BOMcheck provides a Class D declaration for the part. If no, then BOMcheck provides a Class D + C declaration for the part. The name of the Class is included in the XML file as suffix _C.xml, _D.xml, or _D+C.xml.

Many in-house IT systems will calculate the regulatory compliance from a partial Class D XML – they do not require the Class D XML to have 100% substance information to carry out this calculation. These in-house IT systems automatically add additional substance content so that the declaration for the part in the IT system contains 100% substance data for 100% of the part weight. Other in-house IT systems do not add in additional substance content – instead they store the partial substance data and use the declared part weight to calculate compliance for the part. In both these cases, the in-house IT system reports that the supplier’s XML file did not provide 100% FMD data.

Some in-house IT systems will read in the Class D+C XML from BOMcheck and use the Class C information to set the compliance status of the part. Other in-house IT systems will read in a Class D+C XML from BOMcheck and will compare the regulatory compliance statements in the Class C portion with the regulatory compliance that the IT system calculates from the Class D portion, and report the worst case. For example, if the Class C portion states that the part is compliant to a REACH SVHC but the Class D portion includes this REACH SVHC and the in-house IT system calculates from this Class D data that the part is non-compliant, then the IT system will ignore the Class C statement and report that the part is non-compliant for this REACH SVHC.

In this second case, the Class D+C XML is particularly relevant in the situation where a completely new substance (which is not currently on any substance list in the BOMcheck FMD tool) becomes regulated. If this happens then all suppliers in BOMcheck who have created FMDs with < 100% substance information will be asked to re-declare these FMDs to confirm that the new regulated substance is not included in the undeclared substances. The Class C information for this part will be set to ‘missing information’ for this new substance. When the supplier re -declares the FMD then BOMcheck will calculate a new Class C for this part.

Mapping Suppliers

Recommended process to map BOMcheck Suppliers to Supplier Objects in the in-house IT system

Unique identification of suppliers and supplier parts on BOMcheck

BOMcheck requires every distinct supplier to have one unique Supplier Code on BOMcheck. The supplier is required to choose one of their DUNS numbers which then becomes their unique BOMcheck Supplier Code. BOMcheck chooses to use a DUNS number to generate a unique Supplier Code for a supplier on BOMcheck because:

• A DUNS number is unique to an assigned business and is never re-used (even if the business goes bankrupt). It is therefore impossible for two different suppliers to have the same BOMcheck Supplier Code.
• BOMcheck uses the DUNS number to verify the legal status of the business (one of the checks needed for CFR Part 11 Electronic Signature Regulations)
• DUNS provides a convenient global identification coding system

Each distinct supplier must select only one of their DUNS numbers which will then be used as their Supplier Code on BOMcheck. BOMcheck recommends that the supplier should select their highest level corporate DUNS number. However, BOMcheck will accept any DUNS number which belongs to the supplier.

Each supplier part in BOMcheck is identified by a unique pair of values:

• the unique BOMcheck Supplier Code for that supplier in BOMcheck; and,
• the supplier part number (unique at the supplier but may not be unique on BOMcheck, for example two different suppliers may use the same part coding system and so may use the same part number to represent different items).

For example Vishay Intertechnology, Inc has one product catalogue published at www.vishay.com and one part coding system for all Vishay parts. Vishay has 18 different brands and numerous different business addresses but you can buy exactly the same Vishay part number from any one of these different brands and business addresses. Therefore Vishay has one unique BOMcheck Supplier Code (002327484), as illustrated below.

Vishay has 12 Authorised individuals in BOMcheck who are each responsible for making declarations for their own particular brands at Vishay. All of these Authorised Individuals are connected together on BOMcheck under the same BOMcheck Supplier Code for Vishay. For example, Smita Kurulkar makes declarations in BOMcheck for the MOSFET transistors which are manufactured by Vishay Silconix.

The systematic and unique identification of suppliers in BOMcheck is rarely reflected in the organisation of supplier objects which BOMcheck observe in many Manufacturers’ purchasing systems. For example, we often find that a typical Manufacturer has many different supplier objects for Vishay, often more than 18 and in one case as high as 82 different supplier objects for Vishay. In some cases these multiple supplier objects have arisen as a result of company acquisitions and subsequent merging of purchasing systems. In other cases these multiple supplier objects arise through poor management of suppliers in the purchasing system. If the purchasing officer can not immediately find the supplier company name in their purchasing system then they can too easily create a new supplier object.

There is one exception to the BOMcheck rule that each distinct supplier must select only one of their DUNS numbers which will then be used as their Supplier Code on BOMcheck. If a supplier has several different brands and each brand has its own product catalogue and part coding system then each brand must have its own BOMcheck Supplier Code. For example, Toshiba Electronics Europe GmbH and Toshiba Europe GmbH are both owned by Toshiba. But Toshiba Electronics Europe GmbH sells semiconductors (for example, memory chips, microcontrollers, ASICs) using one part coding system and product catalogue, and Toshiba Europe GmbH sells equipment (for example, laptops, computers) using a different part coding system and product catalogue. To avoid any possibility that these two part coding systems may overlap, Toshiba Electronics Europe GmbH has its own BOMcheck Supplier Code (321832354) and Toshiba Europe GmbH also has its own BOMcheck Supplier Code (323690412).

BOMcheck recommendation to add BOMcheck Supplier Code attribute to the supplier objects in the in-house IT system

To find a declaration for a supplier part in BOMcheck, the Manufacturer must know the BOMcheck Supplier Code and the supplier part number. As highlighted in section 8.1, at a typical Manufacturer the in-house IT system will have several supplier objects for the same BOMcheck supplier code. To ensure that the in-house IT system uses the correct BOMcheck supplier code in the API request, BOMcheck recommends that the IT system should add a new attribute = “BOMcheck Supplier Code” to the supplier object in the IT system.

In a typical in-house IT system, each Object may have three mandatory attributes: Object Type, Object Name and Revision. For a Supplier Object, the Object Type may be set to “Company” and the Object Revision may be set to “-”. The Supplier Object Name may be a unique 8 digit alphanumeric, for example a sequential number which comprises two groups of 4 digits.

A typical in-house IT system may also provide optional additional attributes for Supplier Object including Organisation ID, Alternate Company Name and DUNS number. In general, the DUNS number attribute is not maintained in the in-house IT system and is not used to provide unique identification of the Supplier Object. Instead, in a typical in-house IT system the Supplier Object Name is used to provide unique identification of a Supplier Object.

As highlighted in Section 8.1, a Supplier in BOMcheck can have multiple Supplier Objects in the in-house IT system. For example, there may be multiple Supplier Objects for Vishay in the in-house IT system. To ensure that the in-house IT system uses the correct BOMcheck supplier code in the API request, BOMcheck recommends that the IT system should include a new dedicated attribute in the Supplier Object = “BOMcheck supplier code”. In most in-house IT systems, this is a small customisation which is relatively easy to implement.

This new dedicated attribute should be used to include the 9 digit BOMcheck Supplier Code in all Supplier Objects which belong to the same Supplier on BOMcheck . In a typical in-house IT system, all Supplier Objects may have element type = Company. In his case one option is to include the new “BOMcheck supplier code” attribute as a new attribute in the Company element.

BOMcheck recommendation to customize the importer in the in-house IT system to load IPC 1752A XML files from BOMcheck

Many in-house IT systems provide processes for the user to email a blank IPC 1752A XML file (which contains the user’s details for the supplier company name and the part number) to a supplier for them to complete the declaration and return by email. These completed IPC 1752A XML files are stored in a folder within the in-house IT system, ready for an importer program to load these data against the manufacturer’s part numbers. When the importer program loads the completed 1752A XML the importer looks for a match between:

• the part number reported in the itemNumber element in the XML file and the part number in the in-house IT system, AND
• the supplier name reported in the SupplyCompany name element in the XML file and the supplier company name in the in-house IT system. In particular, the supplier name in the XML file must match to an existing Company Name for a Supplier Object in the in-house IT system (Company Name is an attribute of the Company element). In practice, the supplier often changes their company name in the XML file, or supplies an XML file which they have generated and contains a different company name, in which case this matching process will fail.

One of the benefits of adding a new BOMcheck Supplier Code attribute to the supplier objects in the in-house IT system (as described in section 8.2) is that the importer program can be customized to ensure accurate loading of all IPC 1752A XML files which are downloaded from BOMcheck. All IPC 1752A XML files which are downloaded from BOMcheck include comment = “BOMcheck” and report the BOMcheck Supplier Code in the CompanyID element in the XML file.

The importer program can be customized so that if the IPC 1752A XML file has Response comment = “BOMcheck” then the importer program looks for a match between:

• the part number reported in the itemNumber element in the XML file and the part number in the in-house IT system, AND
• the BOMcheck Supplier Code reported in CompanyID element in the 1752A XML file and the BOMcheck Supplier Code attribute in the Supplier Object in the in-house IT system. This provides a robust match because the BOMcheck Supplier Code is permanently fixed on BOMcheck whereas a supplier’s company name may change.

BOMcheck recommendation for in-house IT system to provide a User Interface to enable the user to map a BOMcheck supplier to multiple supplier objects for that supplier in the IT system

The listSuppliers action in the BOMcheck Integration API provides the list of supplier company names, contact details and BOMcheck supplier codes (DUNS numbers) for all suppliers on BOMcheck.

BOMcheck recommends that the in-house IT system should use the BOMcheck Integration API to download the listSuppliers and provide a user interface (UI) to enable the user to map a BOMcheck supplier to the multiple supplier objects for that BOMcheck supplier in the IT system. When a mapping is made, the UI can load the BOMcheck Supplier Code into the BOMcheck Supplier Code attribute for these selected supplier objects in the in-house IT system.

Ideally, the UI should assist the user to match the BOMcheck supplier to the multiple supplier objects for that BOMcheck supplier in the in-house IT system. There are several approaches that the UI can employ to help the user make a match by filtering the supplier objects in the in-house IT system to display possible matches to the BOMcheck supplier. These include:

1. Filter all supplier objects in the in-house IT system where the email extension for the contact email address for the supplier object is the same as the email extension for the contact email address for the BOMcheck supplier. For example, the contact email addresses for the Authorised Individuals at Vishay on BOMcheck all have email extension = @vishay.com. The UI can display all supplier objects in the in-house IT system which have a contact email address which also has this same email extension = @vishay.com.
2. Run a program to remove all common words which are separated by spaces (the, and, company, limited, GmbH, Corp, Ltd, Ltd., Inc, Inc., Co, Co., KG, LLC, SA, NV, KG,) and then remove all dots, dashes, hyphens, slashes, spaces etc and then display all supplier object names in the in-house IT system which more than 6 consecutive alphanumerics the same as the BOMcheck supplier name. These possible supplier name matches could be listed alphabetically to help the user to make the mapping. Once the user has carried out an initial mapping from the BOMcheck suppliers to the supplier objects in the in-house IT system, then the UI should also support the user to carry out a regular update process (e.g. once per week) to map new suppliers who have recently joined BOMcheck to supplier objects in the in-house IT system. The BOMcheck Integration API includes an optional Start Date variable for use with this listSuppliers action. This Start Date variable enables the API request to select listSuppliers data for suppliers where the Date Joined is younger than the Start Date. The Start Date must be provided in ISO8601 format as YYYY-MM-DD.

BOMcheck recommends that the UI should use the Start Date parameter to select all new suppliers that have joined BOMcheck in the past week. The UI can then assist the user to match a new BOMcheck supplier to the multiple supplier objects for that BOMcheck supplier in the in-house IT system, by using the approaches discussed above.