Product description
LabLink
Web Services
Version:
2.3.14274
01.10.2014
Document for use and description of LabLink Web
Services.
Tieto
Corporation 
DOCUMENT HISTORY
|
Version |
Date |
Edited
by |
Comments |
|
0.1 |
19.03.2004 |
Jørn Agnar Solheim |
First draft |
|
0.2 |
25.03.2004 |
|
Minor changes and proof reading. |
|
1.0 |
01.06.2004 |
|
Minor changes to installation doc and first
version. |
|
2.0 |
31.03.2005 |
Jørn Agnar Solheim |
Updated for RoS 2 changes. New methods
SaveRequisition, GetRequisitionNumber and ListRequesters |
|
|
|
|
|
|
2.0.1 |
09.05.2004 |
Jørn Agnar Solheim |
Revised after QA. LabLinkWS Installation and
Configuration moved to separate document. |
|
2.3.12047 |
16.02.2012 |
Jørn Agnar Solheim |
Added new web service ReportWS and new method
RequisitionWS SaveRequisitionAny |
|
2.3.12048 |
17.02.2012 |
Jørn Agnar Solheim |
Added AnpWS documentation. Some minor changes
to ReportWS |
|
2.3.12080 |
20.03.2012 |
Jørn Agnar Solheim |
Minor changes to list of methods for LAB
systems |
|
2.3.13044 |
13.02.2013 |
Jørn Agnar Solheim |
Added information for FlexLab Chemistry and
Micro |
|
2.3.13065 |
07.03.2013 |
Jørn Agnar Solheim |
Added development information |
|
2.3.14174 |
01.10.2014 |
Jørn Agnar Solheim |
Changed Url for WS and WSDL |
1.3 About LabLink Web Services
1.4 LabLink Web Services as modules
1.5 Naming in LabLink Web Services
1.10.1 Microsoft Visual Studio
1.11 Common Errors from LabLink Web Services
1.11.1 Common errors from many LIS
1.11.2 Error Messages from methods using HIS-90 LIS (NSL/NSML)
3.1 Common Errors from LabLink Web Services
3.3 Web Service ResponseHeader
1
Introduction
LabLink Web Services is a set of services to
give Tieto and third party applications the opportunity to access laboratory
information stored in a LIS. Some LIS that uses LabLinkWS are: HIS90 NSL, HIS90
NSML, FlexLab Chemistry, FlexLab Micro and FlexLab Sympathy.
The LabLink Web Services are available to
developers/applications that wish to integrate with a LIS. This user
documentation is intended for use by developers or other which needs technical
information about LabLink Web Services. The security on both authentication and
the limitations of information based on this authentication is taken care of by
the Web Services or the PasLink Web Services.
LabLink Web Services is a licensed product from
Tieto and all applications using LabLink Web Services must be registered. The
customer, to whom the product is licensed, is responsible for the registration
of all applications integrated with the LIS through LabLink Web Services in his
environment. Tieto reserve the right to change LabLink Web Services if
necessary. The provider of registered applications will be notified in advance
of such changes.
LabLink Web Services can dependent on PasLink
Web Services for authentication and authorization if this is used by LabLinkWS
to a specific LIS.
1.1 Definitions
|
|
|
|
HIS |
Health Information System, general
description of PAS systems. |
|
LIS |
Laboratory Information Systems,
general description of laboratory systems. |
|
NSL or HIS90 NSL |
Tieto’s HIS90 NSL Laboratory
system/LIS , clinical chemical lab |
|
NSML or HIS90 NSML |
Tieto’s HIS90 NSML Laboratory
system/LIS , micro biology lab |
|
HIS90 PAS |
Tieto’s HIS90 Patient
administration application on HP NonStop servers. |
|
FlexLab Sympathy |
Tieto’s FlexLab Sympathy LIS, for
pathology lab |
|
FlexLab Chemistry |
Tieto’s FlexLab Chemistry LIS, for
clinical chemical lab |
|
FlexLab Micro |
Tieto’s FlexLab Micro LIS, for
micro biology lab |
|
LabDeliveryService |
Tieto’s LabDeliveryService, a
delivery service for sending documents out from a LIS by using LabLinkWS |
1.2 About this document
LabLink Web Services is grouped under several
modules.
The documentation for the modules is divided
into several parts with one main document and several sub documents for each
module/web service.
To view or print the entire master document,
expand the subdocuments and switch to normal view, and then print it as usual.
To specify the amount of detail to print, use the following procedure.
1.3 About LabLink Web Services
LabLink Web Services is designed as two main
layers, one independent layer that contains generic methods/the interface and
one dependent layer containing specific interfaces and modules for each LIS
system/database. When most of the changes are made in the interface against
generic LIS, the methods should stay unchanged and compatible with previous
versions of LabLink. Only the independent part is affected and must be
rewritten for a new communication interface.
This means that applications using LabLink Web
Services rarely needs to be changed as a result of changes in the communication
between LabLink Web Services and the LIS database as this will be backward
compatible.
It is important to know that LabLink Web
Services is offering a collection of methods for use by other
applications. The providers of these applications are responsible for how these
methods are used and implemented. As an example, LabLink Web Services contains no
methods for login in and authentication of users. Only through using PasLinkWS
methods an application gets an authentication to use with the LabLinkWS
methods. The provider of a third party application is responsible to make use of
the login and authentication methods (to get and store the Ticket/Security
token) before they make use of other methods if the LabLinkWS
implementation used has implemented authentication/security.
1.4 LabLink Web Services as modules
LabLink Web Services consists of several
modules, so the client does not need to load unnecessary code. Methods
containing similar logic are grouped together:
·
AnpWS
– Methods used by ANP application to get requests/results and save
reports/results. Generic but with ANP specific interfaces.
·
InvestigationWS
– List and get investigation or investigation groups.
·
RequisitionWS – Save
a requisition
·
SampleWS
– Update or delete samples(requisitions)
·
RequesterWS
– List all requesters
·
ReportWS
– Get reports form LIS and handling status on the report
1.5 Naming in LabLink Web Services
The following naming standard is applied in the
Web Services for the methods:
|
|
|
|
GetX() |
Get one set of information’s. |
|
ListX() |
Get a list or collection of data. |
|
SaveX() |
Save (insert or/and updates) one set of data. |
|
DeleteX() |
Delete a chosen set of data form the
database. |
|
|
|
There
are methods where it is not practical to follow this naming standard. The name
of the method will reflect what function the method has.
1.6 Version
Versioning
information in this documentation can be on several levels, both on main
document/page and within each Web Service document.
The
version number on main document/page is the release version number of the
complete document; this does not necessarily match the Web Service Package release
version.
1.7
Web
Service Compatability
Web
service method’s request and response are normally kept compatible with
previous version’s WSDL.
If
compatibility is broken this is either notified before this happens so changes
can be made or normally a new method will be created if compatibility is
broken.
Compatibility
with older WSDL is kept if: New information (properties/field) is added to the
request or response (WSDL) as optional information. Information
(properties/field) changes placement within same level it is defined. Data
types is changed from number to string(as long as client applications does not
update its WSDL it is compatible, after update of WSDL at client applications
it might need some code changes from number to string also).
Compatibility
is broken if: Information (properties/field), request or response is
restructured. Information (properties/field) is renamed or deleted, or
information (properties/field) is moved to other placement in request/response
that is not the same level as before. (Note: There can be problems with keeping
compatibility on WSDL proxies generated at client side if this is not done
correctly, see note for Visual
Studio)
If
compatibility is broken a new method with generation extension is created. A
generation extension is for example 2G, 3G 4G … Some if there would be a new
version of the method ListOrganization due to compatibility breaks, the next
generation version would be ListOrganizations2G
1.8 System information
The
LabLink Web Services can access several different LIS.
At
the top of every method description there is a system information bar to tell
which system this method is valid in. There can be more systems available then
listed in this document or more web service methods in the actual WSDL. But
generally these are methods/systems under development or internal
methods/systems for special cases that shall not be used by developers. Only
documented methods/systems shall be used.
Example:
Applicable LIS for the method:
|
NSL |
NSML |
Sympathy |
FlexLab Chemistry |
FlexLab
Micro |
|
|
This
system info bar tells that this method is implemented for the LIS.
List of Web Services/Methods and
which systems they are applicable for
(X=Implemented, - =Not applicable,
Blank = Not implemented):
|
Web Service |
Method |
NSL |
NSML |
Sympathy |
FlexLab Chemistry |
FlexLab Micro |
|
|
|
Number of
methods per system-> |
21 |
6 |
2 |
3 |
3 |
|
|
|
|
AnpWS |
AddInvestigations |
X |
|
|
|
|
|
|
|
|
FormatServReqId |
X |
|
|
|
|
|
|
|
|
GetAnalysedSubjectReferences |
X |
|
|
|
|
|
|
|
|
GetFormattedAnalysedSubjectIdentity |
X |
|
|
|
|
|
|
|
|
GetPatientResults |
X |
|
|
|
|
|
|
|
|
GetServiceRequests |
X |
|
|
|
|
|
|
|
|
ReportAnswers |
X |
|
|
|
|
|
|
|
InvestigationWS |
GetInvestigation |
X |
|
|
|
|
|
|
|
|
ListInvestigationGroups |
X |
|
|
|
|
|
|
|
|
ListInvestigations |
X |
|
|
|
|
|
|
|
RequisitionWS |
GetRequisitionNumber |
X |
|
|
|
|
|
|
|
|
GetRequisitionNumbers |
X |
|
|
|
|
|
|
|
|
SaveRequisitionAny |
X |
X |
X |
X |
X |
|
|
|
|
SaveRequisitionEHCM |
X |
|
|
|
|
|
|
|
|
SaveRequisitionKITH |
X |
X |
|
|
|
|
|
|
SampleWS |
DeleteSample |
X |
|
|
|
|
|
|
|
|
UpdateSample |
X |
|
|
|
|
|
|
|
RequesterWS |
ListRequester |
X |
|
|
|
|
|
|
|
ReportWS |
GetNextReport |
X |
X |
X |
X |
X |
|
|
|
|
ListReportStatuses |
X |
X |
|
|
|
|
|
|
|
SaveReportStatus |
X |
X |
|
X |
X |
|
|
1.9
Parameter
description
required Bold declares this parameter as required
normal Parameter can be
empty/unitialized.
[optional] Parameter
can be omitted
1.10
Development
tools
1.10.1
Microsoft
Visual Studio
If
Microsoft Visual Studio (VS) is used as tool to access/consume the web
services, the web service must be added to VS as Web Reference NOT as Service
Reference.
The
proxies generated through Web Reference allow more compatibility with PasLink
changes, as new properties/fields can be added and compatibility with older
WSDL proxies can be kept without needing to update them if none of the new
properties/fields are used.
The
reason for not using Service Reference is that is it too tight coupled to
Microsoft’s WCF thoughts, and then the binding to properties/fields in the
proxies generated is absolute to order index of the property/field not to
property/field name. As Tieto’s web services follow the w3c.org standard/basic
profile and are asmx based this allows inserting new properties/field within an
existing WSDL definition and keeping compatibility, order of property/field is
not important. With using Service Reference to generate proxies this will not
go as it uses absolute order index, a new property/field in the middle will
render the WSDL proxy useless.
Using
Web Reference to generate/update proxies to Tieto’s web services will bind to
property/field name not the order/index, and new properties/fields will be
“invisible” until WSDL proxy is updated and as long as new properties/fields is
not used there is no need to update WSDL proxy and still be compatible.
Tieto
will change a web services WSDL according to usage of Web Reference proxies and
keep compatibility to this. Any use of Service Reference proxies is not supported
by Tieto’s web services and must be updated with each WSDL change.
1.11 Common Errors from LabLink Web
Services
Errors
from LabLinkWS methods are always returned in the ResponseHeader ErrorInfomation
block. See web service
response header chapter.
More
information about errors, warning and general information in LabLinkWS can be
found in logs or windows event log for LabLinkWS, please contact a system or
operation responsible for the LabLinkWS installation for accessing logs.
Code
Description
0 No error, method completed
successfully.
<>0 Error
1.11.1
Common
errors from many LIS
Code
Description
0 No error, method completed
successfully.
1 Invalid Ticket/Security token provided
in the request.
2 Ticket/Security token is blank or missing
in the request.
3 Ticket/Security token has expired,
please authenticate/log on again,
5 RequestHeader is missing or blank, a
RequestHeader to the Web Service method is required.
7 Invalid encryption keys for the
Ticket/Security token.
8 Encryption keys for the
Ticket/Security token is missing/cannot be created.
-1 Internal error in the Web Service,
check ResponseHeader\ErrorInformation for error description and severity.
-10 General database error
-20 Input data is invalid or wrong
-21 Input data is invalid type
-22 Input data is invalid length
>0 Error in Web Service Request or from the
database, check ResponseHeader\ErrorInformation for error description and
severity.
1.11.2
Error
Messages from methods using HIS-90 LIS (NSL/NSML)
These
error codes is only valid if the LabLinkWS is configured for the HIS90 NSL or
NSML system
|
Possible errors from CSL/network |
|||||
|
Code |
|
||||
|
From |
To |
SubCode |
Recoverable |
Module |
Description |
|
100000 |
|
0 |
N |
CSL |
Undefined error/message from CSL |
|
100001 |
>108191 |
? |
N |
0 |
The CSL API has reported an error |
|
108192 |
>112287 |
? |
Some |
4 |
Pathway Server class has reported an error |
|
112288 |
>153247 |
? |
N |
7 |
Guardian File open has reported an error |
|
153248 |
>157343 |
? |
N |
8 |
Guardian Write Read has reported an error |
|
157344 |
>188999 |
? |
N |
3 |
TMF Subsystem has reported an error |
|
189001 |
|
0 |
N |
|
Session was rejected by ACS |
|
189002 |
|
0 |
N |
|
Session with the same alias already logged in |
|
189003 |
|
0 |
N |
|
Invalid session alias |
|
189004 |
|
0 |
N |
|
Cannot connect specified terminal |
|
189005 |
|
0 |
N |
|
Terminal does not configured for this version of
client |
|
189006 |
|
0 |
N |
|
Error communicating ACS |
|
189007 |
|
0 |
N |
|
No connection to host |
|
189019 |
|
0 |
N |
CSL |
No transaction in progress |
|
189027 |
|
0 |
N |
CSL |
Transaction in progress |
|
190000 |
|
1 |
Y |
CSL |
TCP connection/network failed |
|
190101 |
|
0 |
N |
CSL |
Error reading INI file |
|
190102 |
|
0 |
N |
CSL |
Check format of INI parameters |