Stanlab2x Specifications
- Tom Birch Hansen
Here you will find information on the Danish Regions use of Stanlab 2x API for Laboratory requisition and reporting. The information is relevant for laboratories implementing Stanlab 2x for use in Danish regions.
For generel information about inplementing Stanlab, see https://github.com/danmarksmiljoeportal/stanlab
and the swagger definitions on https://stanlab-api.miljoeportal.dk/openapi/
Submit/Pull requisitions:
https://stanlab-api.miljoeportal.dk/openapi/#operation/SubmitRequisition :
One requisition contains info for only one sample.
Field | Information | Examples |
|---|---|---|
Contact: | The contact information for the person who is responsible for the requisition. Will in many cases be the same as the reqestor. The order-confirmation by the laboratory should be sent to this contact. |
|
SamplingContact | Contact info of the person who undertook the sampling. |
|
OrderReference | Our reference to be used on the invoice. Will contain our ‘lokalitetsnummer' and ‘lokalitetsnavn’ and possible also the consultants own case-number. The lab must use this field-value for accumulating multiple requisitions/orders to a single invoice, and for placing this information on the electronic invoice. | 711-1112 Østergade 11 (sag 23233) |
OrderLineReference | info to go on the invoice for the individual requisition. | B1 2,0-4,0 m.u.t. B2 (dgu 22.1234) indtag 1 |
Personreference | personreference to go on the electronic invoice. this field is only relevant if the billingaccount does not contain individual persons (see billingaccounts). When the Vanda system is used, this field is never filled. In stead the person is defined in the billingaccount.
| tomhan
|
Contracts
Contains info on the billing accounts and available packages and package-parameters.
https://stanlab-api.miljoeportal.dk/openapi/#tag/Contract
Field | Information | Example |
|---|---|---|
BillingAccount | contains info in the billing account (EAN number reference, and possible person-reference). The ‘reference’ is the laboratorys reference to the billingaccount.
There are two possible implementations of this:
When the Vanda system is used for requisition, the option 2 must be used, as ‘Vanda' does not fill in personreference value.
The ‘name’ field is used by the requisition-system to select the right account, therefore it must contain a precise and readable value.e
| { |
Packages - name | This field is used by the requisition-system to select the right packages. Therefore it must have an easily readable value. The value should not be more than 60 characters long. Any characters beyond 60 characters are unlikely to be visible in the UI. The value should preferable also contain the labs packagenumber in parenteses. | (ABC123) BTEXN og chl. opl. midler m. nedbr.
|
Sample status
The laboratory must report the status of the requisition as the order is processed at the laboratory.
This is achieved using the following four post-calls, where the id is the requisition-id :
https://stanlab-api.miljoeportal.dk/openapi/#operation/ConfirmRequisition (where the laboratoryTestReference is labs internal unique id for the requisition (not sampleId)
https://stanlab-api.miljoeportal.dk/openapi/#operation/NotifySampleRegistered (when the sample is recieved by the lab)
https://stanlab-api.miljoeportal.dk/openapi/#operation/NotifyAnalysisStarted
https://stanlab-api.miljoeportal.dk/openapi/#operation/NotifyAnalysisFinished
There is currently no way to report that the sample is too old for analysis or that is has been discarded.
Submit laboratory results
https://stanlab-api.miljoeportal.dk/openapi/#operation/SubmitLaboratoryTest
Important!
When submitting results, the ‘reference' must be a unique identifer for the requisition. The ‘reference’ IS NOT the samples idefication number. For instance, if multiple requisitions have been sent for the same sample, the reference-number will be different for each requisition.
The laboratory results submitted must only contain the results for what was orderen in the requisition. For example; When first a user request PID analysis and later a user requests BTEX analysis on the same sample, the the laboratory must give the PID result for the response of the first requisition (usinge the labs reference for the first requisition), and the BTEX results as response of the second requistion (using the labs reference for the second requisition).
The submit laboratory test resultat (and delete laboratory results) may be rejected by the endpoint system (GeoGIS/Vanda) if the sample has been fully accepted (by a user or system).
For the individual analysis (array) the laboratory performing the individual analysis can be specified as text. Preferably with added parentheses with laboratory number from the Stancode codelist 1025 found at https://dce.au.dk/overvaagning/stancode/stancodelister for instance: Laboratory : “AnalysisLab AB (123)“
Get Sample
To get information like sampledate, sampled by, sample site name, field measurements ect, the get-sample must be used:
https://stanlab-api.miljoeportal.dk/openapi/#operation/GetSample
field | info | examples |
|---|---|---|
label | the label used for the sample by the requisition system. The default text is the samplesitename including DGU nummer, intakeno and depth. | B1-1 (88.1232) B2 (2,0-2,1 m.u.t.) IL5 IL5(2) OBL1 (0,2 m.u.t) |
observation-facility-name | a destriptive name of the specific samplesite (for instance a borehole intake or soil sample site) | B1-1 (88.1232) B2 PL5 OBL1
|
observations | can contain observational info on a sample (for instance colour). Currently we are not implementing this in GeoGIS |
|
measurements | contains field measurements for the sample like pH, air-volumen, redox ect. All codevalues are Stancode values. | "measurements": [ |
location | 751-23232 | The site-locationnumber (projectno) from GeoGIS. For the Vanda system this field will be empty. |
For the Vanda system, the ‘get-sample’ is very limited in what is exposed. No observations, measurements, sampler or label is supplied.
Requestor
Information on the requestor (rekvirent) isn’t currently availabe in the get-sample call.
You can get the requestor’s name (but not phone or email) by using a graphQL call:
{requisitions (sampleId:"94599a76-d2f3-4f20-8432-b2743670a949"){requisitionId,sample{sampleId}user{name}}
}Other
The following api calls are not implementet for the regions systems (GeoGIS and Vanda):
submit sample
delete sample
Order confirmation emails
For the lab to send order confirmation, use the following api calls:
email to sent orderconfirmation to:
requisition: Contact>email
sample overall location info :
requisition: orderReference
Sampleinfo for the sample:
requisition: orderReferenceLine
Sampledate:
get sample: sampling>samplingEnded
Packages:
requisition>packages
Invoicing:
invoicing should be bundled pr location pr ? weeks. This can be done by bundling by the value of the requisition>‘orderReference’ field.
The invoicing billing account can be found on the requisition>billingaccount
The invoicing person-reference can be found in the requisition>personreference field, or alternatively indirectly by a person specific billing-account.
The values from orderReference should go on the header of the invoice, and requisition>orderReferenceLine should go on the individual sample-requisitions.
Sampledata can be found from get sample: sampling>samplingEnded
Sampler-info: requisition>samplingcontact
PDF/Excel analysisreport:
(not relevant for Vanda)
Field measurements from get-sample>FieldMeasurements
Sampler: requisition>samplingContact>name
Samplingdate:get-sample>samplingEnded
Samplelocation: sample->location
Samplesite (pointno, DGU, intake, depth ect): sample->observationfacility>Name
Sampleno/label: sample>label
Submit to: requisition>contact>Email