Setting up API communication by REST services with TerraIndex for laboratories - Lab result file - SIKB0101 v14

Page / - last modified by Robin Huisman on 2025/02/27 09:44

Lab result file - SIKB0101 v14

last modified by Robin Huisman

on 2025/02/27 09:44

Table of Contents

Reporting lab results to TerraIndex for a customer

What is a Lab result file?

Model Structure

Metadata

Labassignment

LabAssignmentStatus

LabAssignmentCertificate

LabAssignmentRequest

Project

Sample (AnalysisSample)

Analysis

AnalyticResult (inherited from MeasureResult)

AnalysisProcess

What to exchange to bind the results to the correct sample?

SIKB 14 Parameter result combinations

Samples with their Types

Reporting lab results to TerraIndex for a customer

Returning the labresults to the client, that requested the analysis on samples.

More information about SIKB0101 can be found here: https://www.sikb.nl/datastandaarden/sikb0101-bodembeheer

Reporting lab results to TerraIndex for a customer

What is a Lab result file?

Model Structure

Metadata

Labassignment

LabAssignmentStatus

LabAssignmentCertificate

LabAssignmentRequest

Project

Sample (AnalysisSample)

Analysis

AnalyticResult (inherited from MeasureResult)

AnalysisProcess

What to exchange to bind the results to the correct sample?

SIKB 14 Parameter result combinations

Samples with their Types

What is a Lab result file?

A lab result file is an XML file contains all the lab results. The results are mapped tot their analyses samples. A lab result will be matched to the corresponding analyses sample based on the: “Labassignment Guid/SIKB-ID, projectCode, AnalysisSample Guid/SIKB-ID”

Example files: labresult_IndividualGw.xml, labresult_IndividualGr.xml, labresult_MixedSampleGr.xml

XSD: Ask or SIKB Members can download from: https://www.sikb.nl/datastandaarden/richtlijnen/sikb0101

Controle XSLT: Labresult_Controle.xsl

Domaintable files: immetingen lookup v14.8.0.xml imsikb0101 lookup v14.8.0.xml
extracted from: https://codes.sikb.nl

Reporting lab results to TerraIndex for a customer

What is a Lab result file?

Model Structure

Metadata

Labassignment

LabAssignmentStatus

LabAssignmentCertificate

LabAssignmentRequest

Project

Sample (AnalysisSample)

Analysis

AnalyticResult (inherited from MeasureResult)

AnalysisProcess

What to exchange to bind the results to the correct sample?

SIKB 14 Parameter result combinations

Samples with their Types

Model Structure

Metadata

Attribute name	Description	Unit
version	The SIKB version of the lab results file. This must be: 14.8.0 or 14.9.0	string
application	This is the application code of your LIMS system that you will get from TerraIndex. Be careful this is not the same code as your laboratory number. Your applicationcode can be requested of found here: https://codes.sikb.nl/tablet/domain-table-details/50be26c9-5e66-46c9-9373-9d402762876f	Integer
reportDate	The date on which the lab result file was made	date yyyy-mm-dd
supplier	The number you get from TerraIndex. This needs to be the same as the laboratorium number in the lab delivery file. Your supplier code can be requested of found here: https://codes.sikb.nl/tablet/domain-table-details/dc2ad4df-f958-4146-aee8-31f8c2f1c74b	string
dataflow	Should be '1' in this case, what stands voor 'AnalysisResults'. Other option can be found here: https://codes.sikb.nl/tablet/domain-table-details/79365ded-f56a-4f10-ba45-16bac69752d9	integer

Labassignment

The labassignment is the same as in the labassignment file: Lab assignment file - SIKB0101 v14

With 3 differences/additions:

Status on the labassignment itself

Status on the labassignment.sample link

The labassignment Report number can be send in: LabAssignmentCertificate

Attribute	Notes
identification NEN3610ID	A unique code that is created when the object is created for the first time.
operatingLab GenericName	Code of the laboratory to which the assignment is assigned. Domaintable: Meetinstantie / Measuring Company
startTime DateTime	Dispatch date of the lab assignment
customerCode CharacterString	Client code or debtor number of the client as known by the laboratory

LabAssignmentStatus

Attribute Name	Description
statusType GenericName	The status of the lab assignment. Use the value '5' for final reported results. Use other values, or '4', for conceptual values. Domain table: Labassignment Status
dateExpected DateTime	The date the results can be expected, in case of conceptual results. If final, fill with datetime.now.

LabAssignmentCertificate

Attribute Name	Description
labCertificateNumber CharacterString	The number of the certificate that will be send to the user/client, and what is used in the PDF file as order or report number of the laboratory.
certification GenericName	Under which certificate the analyses has been done. If you do not find you code leave this field empty Domain table: Certification Coding

LabAssignmentRequest

The connection between the labassignment and the samples with analysisrequests, as send in the labassignment.

If not retreived in a labassignment, make it yourself so we can import is as new samples.
Just fill what you can fill, otherwise leave field empty, based on documentation here: Labassignment file - SIKB0101 v14

Project

Activity that leads to the collection of soil data, as send in the labassignment.
It will be used to search the correct project/investiation to bind or create the samples.

Attribute	Notes
identification NEN3610ID	The unique identifier of the Project in TerraIndex and in the whole Exchange Chain, as send in the labassignment
name CharacterString [0..1]	The name of the project where the lab results are for, as send in the labassignment
projectCode CharacterString	The project code of the project where the lab results are for, as send in the labassignment

Sample (AnalysisSample)

The analysissamples with analysisrequests, as send in the labassignment. The fieldsamples form the labassignment can be skipped in the results file.

If not retreived in a labassignment, make it yourself so we can import is as new analysissamples.
Just fill what you can fill, based on documentation here: Labassignment file - SIKB0101 v14

Please keep these scenario's in mind: Analysissample scenario's

Attribute	Notes
identification NEN3610ID	The unique identifier of TerraIndex for the analyses sample, to keep this value unique forever in the whole exchange chain.
name CharacterString [0..1]	Name given to the sample
specimenType GenericName [0..1]	Type of Sample- Fieldsample, Analysissample For analysissamples fill with value '10'. Domaintable: MonsterType / SampleType
materialClass GenericName	An SIKB code for the matrix type. Soil, Groundwater etc.. Domaintable: Compartiment / Matrix

Analysis

The measured parameter with it's value and process.

Attribute Name	Description
identification NEN3610ID	The unique identifier of the AnalysisResult, to keep this value unique forever in the whole exchange chain. If not possible to store this in the Lims, generate on the fly.
physicalProperty PhysicalProperty	The combination of Quantity, Parameter and Condition to provide the parameter that has been measured. See this chapter for the combinations, and the CAS-NR's.
result AnalyticResult	The result of the analysis, see next chapter.
procedure AnalysisProcess	The process that has been used to measure/determine the result, see next chapter.

AnalyticResult (inherited from MeasureResult)

The actual reported value, result of detection limit.

Attribute Name	Description
numericValue Measure	Numeric Value - the numerical value of the observation. When no unit for the measurement is known, the unit 'Dimensionless' should be used. Domaintable for Units: Eenheid
valueProcessingMethod GenericName	Value Processing Method - a mathematical/statistical operation that is applied while the method of value determination/analysis standard remains unchanged. The operation can be applied to a series of measurement values with the same parameter (quantity/component or typing or taxon or object) or to a series of measurement values with the same analysis method that are summed up to a sum parameter. Default the value '5' meaning 'Not available' can and should be used, besides leaving it empty. Domain table: Value Processing Method
qualityIndicatorType GenericName	Quality Indicator/Judgement -> Detection limit, etc. Default the value '0' meaning 'Not available' can and should be used, besides leaving it empty. If there is a detectionlimit/reportinglimit, use: '4', meaning 'determenated with full detection limit' Domain table: Quality Judgement
limitSymbol CharacterString	LimietSymbool, allowed values: '&lt;' en '&gt;'. '&lt;' stands for 'less than the lowest threshold' '&gt;' stands for 'greater than the highest threshold' The boundary for the limit symbol can be specified in the DeterminationLimits (LimitSymbolReferenceCode) as a reference with the actual value of the limit. The value can be included in the exchange in two ways: 1) as a CData block: <![CDATA[<]]> or <![CDATA[>]]> 2) as HTML code: '&amp; lt;' or '&amp; gt;' Default the value is leaving it empty. If there is a detectionlimit/reportinglimit, use: '<'
alphanumericValue CharacterString	Textual value associated with an analysis result

AnalysisProcess

The process that has been used to detemine the measured value or result.

Attribute Name	Description
identification NEN3610ID	The unique identifier of the AnalysisProcess, it can be bound to multiple results at once.
analyticalTechnique GenericName	The used analytical technique to detemine the result. Domain table: AnalyticalTechnique
certification GenericName	The used certification to detemine the result. Domain table: CertificationCode
valuationMethod GenericName	The used valuation method to detemine the result. Domain table: ValuationMethod

What to exchange to bind the results to the correct sample?

The data stream ‘Lab Result’ is the feedback of analysis results on the requested lab assignment at a laboratory. At import we need to bind it onto the correct sample.

This requires importand field to match the samples in the xml to the samples in our database.

Important fields:

Entity	Fixed value	Remark
Project	lokaalID (GUID)	As submitted in the Lab assignment XML
projectCode	As submitted in the Lab assignment XML
Labassignment	lokaalID (GUID)	As submitted in the Lab assignment XML
Sample (analysis sample)	lokaalID (GUID)	As submitted in the Lab assignment XML, if assignment in SIKB<11, but results in >=11; fill with old BISNR/IDANLMONS.
Name	As submitted in the Lab assignment XML
Sample (field sample)	lokaalID (GUID)	Only if this entity is included, which is optional.

Remarks:

The entity ‘Analysis Result’ does not yet have a fixed lokaalID (GUID), connected laboratories cannot yet guarantee that a unique ID will be generated.

For Asbestos and Asphalt, new samples are also created at the Lab, which are therefore fed back with a reference to the sample from which they are derived.

There is still a desire to feedback from a lab whether an analysis sample has been modified at the lab in terms of sub-samples. For example, if a jar has broken and been replaced with another jar. This has not yet been included in current practices.

Importing the data will be done based on the following steps:

Search Project with Project.lokaalID (as placed in the Lab assignment XML).

Search Project with Project.ProjectCode (as placed in the Lab assignment XML) if searching on Project.LokaalID yields no results.

Search Project and Lab assignment with Labassignment.LokaalID (as placed in the Lab assignment XML) if the Project has not yet been found.

Search Project (if Project not yet found) and Analysis Sample with Sample.LokaalID as GUID (as placed in the Lab assignment XML, version 11 and higher).

Search Project (if Project not yet found) and Analysis Sample with Sample.LokaalID as BISNR (as placed in the Lab assignment XML, versions lower than 11, 'old' idanlmons/BISNR).

Search Analysis Sample with Sample.Name within the project, if the Analysis Sample has not been found but the project has.

What can be imported?

If an Analysis Sample is found, the Analysis Results are always updated or added.

If Project is found, but the analysis sample is not; then this analysis sample is imported as a new analysis sample with all results.

(If it concerns water samples, a new fictional/temporary measuring point and filter could be created.)

SIKB 14 Parameter result combinations

In the SIKB0101 version 14 exchange of labresults is combination needed for exchanging the result parameters of the Lab analysis.
It's based on PhysicalProperty, the combination of Quantity, Parameter and Condition.
*small remark, condition will be used as: [0..1]

Domaintables bound to these fields:

Quantity - Parameter, but only group/groep: Grootheid (Quantity)

Parameter - Parameter, but mainly group/groep: Chemische Stof (Chemical substance)

Condition - Condition, but not group/groeps that refer to Chemical substance.

The combinations are defined for different compartiments like soil/ground, groundwater, wastewater.
Below are some examples, and some attachments included to support all combinations.

2 Examples for Soil:

Parameter Name	Parameter ID	Quantity ID	Quantity name	Condition ID	Condition Name
lood (lead)	1116	2725	Massafractie (Massfraction)	1	t.o.v. drooggewicht (relative to dry weight)
minerale olie (minerale oil)	1200	2725	Massafractie (Massfraction)	93	koolwaterstoffractie C10-C40 / drooggewicht (hydrocarbon fraction C10-C40 / dry weight)

2 Examples for Groundwater:

Parameter Name	Parameter ID	Quantity ID	Quantity name	Condition ID	Condition Name
cyanide-complex	2595	2720	(massa)Concentratie	9	opgeloste fractie (bijv. na filtratie)
som 29 dioxines (TEQ)	2160	2720	(massa)Concentratie	10	uitgedrukt in Toxiciteit equivalenten

2 Examples for Wastewater:

Parameter Name	Parameter ID	Quantity ID	Quantity name	Condition ID	Condition Name
cyanide-complex	2595	2720	(massa)Concentratie	8	Niet van toepassing
som 29 dioxines (TEQ)	2160	2720	(massa)Concentratie	10	uitgedrukt in Toxiciteit equivalenten

DOWNLOAD EXCELSHEET
Full combinations sheet: Full List of AnalysisResult combinations 02-2025.xlsx

We can help you with the right combinations and mappings to your own codes.

Samples with their Types

For different compartments, the links between samples and analysisResults can differ a little bit.
Below the way the enitity Sample can be filled in the xml.

Soil Samples
- FieldSample – BO01-1, matrix = GR (SampleType = 1)
o Container – Jar BO01-1, barcode: fdmsakfds
o Link to AnalysisSample: M1
- AnalysisSample – M1, matrix = GR (SampleType = 10)
o Link to SubSample: BO01-1
o Labanalysis Requests
o LabResults
Water Samples (with multiple bottles) / Air Sample
- FieldSample – WA1, matrix = GW (SampleType = 1)
o Container – Bottle WA1-1, barcode: dfsfdslasd
o Container – Bottle WA1-2, barcode: fdsvfdsvfs
o Container – Bottle WA1-3, barcode: kjhgfvvxx
o Link to AnalysisSample: WA1_Sample
- AnalysisSample – WA1_Sample, matrix = GW (SampleType = 10)
o Link to SubSample: WA1
o Labanalysis Requests
o LabResults