732-661-0400

The Astrix Blog

Expert news and insights for scientific & technology professionals.

The Life Science Industry Blog for R&D Professionals

Astrix Professional Services – SampleManager – Software Technology Brief

Streamline Data Management with Simplified Data Exchange using Thermo Scientific™ SampleManager™ LIMS REST API

As organizations strive to improve data quality and strengthen data integrity, many are turning to modern application programming interfaces (APIs) to streamline data management. The Thermo Scientific™ SampleManager™ LIMS REST API is one such solution that enables users to securely connect different software applications and databases for simplified data exchange. By using the open-source REST API, developers can easily access SampleManager LIMS data and functionality, eliminating the need for custom development or integration.

Overview:

As you may already know, since version 11.2, the SampleManager WCF (Windows Communication Foundation) service has been extended to include a REST (Representational State Transfer) interface, a new SampleManager Web API providing access to SampleManager data and functions.

The REST API was initially designed to be used by the SampleManager Mobile app, but it has been extended to allow SampleManager to become even more modular, flexible and adaptable, with multiple clients able to access SampleManager business logic. The SampleManager client-server architecture is as follows:

SampleManager Client-Server Architecture

samplemanager architecture

Each SampleManager LIMS instance has one SampleManager WCF service, which provides two interfaces:

  • LIMSML interface – Handles transactions encoded in LIMSML, an XML schema used to transfer data between the SampleManager LIMS database and external applications, such as Thermo Scientific Integration Manager.
  • REST interface – Handles transactions using REST, a software architectural style used for simple client-server instances.

The SampleManager WCF service is named smpWCF<instance>. For the examples presented in this article, we are using an instance named VGSM.

For tips on initializing and testing the smpWCF service, please refer to the end of this article.

Technical Tips & Practical Applications:

The REST API allows for a wide range of interactions with SampleManager, making it possible to integrate SampleManager with other systems and applications. The API can be used to create, retrieve, update and delete data within SampleManager, as well as to carry out other actions such as running workflows and triggering notifications.

SampleManager REST API is commonly used to integrate with other systems such as:

  • SAP-QM (Quality Management)
  • SRM (Supplier Relationship Management) – Integrates with IMS (Inventory Management System) Module within SampleManager
  • Web Portals – Real time data extraction – Mostly used for reports/dashboards/import results
  • Downloading SampleManager attachments (i.e., Final Reports, etc..)
  • Logging Samples, Tests, and Results by external interfaces

Tech Tip: Once SampleManager is installed, we can test that the service is accessible using a web browser. Assuming the web browser is opened within the SampleManager application server*, the address used to interact with WCF is “localhost:<port number>”. The port numbers are found in the Windows services list file: C:\Windows\System32\drivers\etc\services. At the bottom of the file is a list of SampleManager services.


samplemanager code

The basic WCF service which communicates with Integration Manager is named smpWCFvgsm, port 56104**. Type localhost:<WCF port> into the browser address field and hit enter. The content should be similar to the image below.


LIMS web service

The REST component of WCF is named smpwcfrestvgsm, port 56105**. Type localhost: <REST Port> into the browser and then press enter. It appears the service is not working properly.


localhost


This is because the address we’ve provided is not redirected to a homepage. Let’s try a more specific address – localhost:56105/help.


sm tech brief


The help page contains a list of all the commands exposed by the WCF REST service. The operation that can be utilized to view samples returned by a criteria is mobile/browses/{entity}. Details can be found at the address http://localhost:56105/help/operations/BrowseDataGet.  The URL can be expanded with optional parameters for page, page size, filter text (i.e., explorer grid filter), and saved criteria.  To see the first 50 authorized samples, try the address:

http://localhost:56105/mobile/browses/sample?&criteria=AUTHORIZED

The response from the service is a JSON formatted string containing the requested data. To see the data in table format, type ‘json to table’ in a browser search engine to find a site that can be used for conversion by pasting the text.

Because we can search for any entity using any saved criteria, the webservice can be useful for other functions such as checking stock inventory expirations on the stock batch table. For example, a criteria that searches for stock batches within 30 days of expiration can be queried using a saved criteria that utilizes the expiry date field.

Another feature of the browse operation is text filtering. This queries the specified table using the filter functionality found in SampleManager explorer grids, shown below.

samplemanger tech brief 2


To view equivalent results from your system as JSON in the web browser, use the address:

http://localhost:56105/mobile/browses/sample?&filter=Cancelled

In some cases, the browser will display a set of results different from those found in SampleManager Explorer. In this example, the response returns two rows instead of the three that were displayed in the grid.


sample manager code


This is because more fields are exposed in the explorer grid than in the web service’s definition of sample table. The fields available to the web service can be adjusted in one of the following ways: browse attributes in sample structure definition or Global Table Defaults. The Global Table Defaults configuration has priority over structure definition in the web service. To make the adjustment in the global table defaults, open the configuration folder and choose the Columns tab. On this tab, select the option ‘Use pre-defined column list’. Add the columns already in the JSON response as well as any that were used to return explorer grid results. The Description field needs to be added for the WCF response to match the samples displayed in SampleManager. The image below shows the new column configuration.


samplemanager tech brief 5



Note that the WCF service may need to be restarted for the change to take effect. Now the response to our request for samples filtered on the word ‘Cancelled’ aligns with the explorer grid’s contents:


sample manager tech brief 8


In this example we:

  • Identified the WCF service and ports
  • Connected to the WCF services from a browser
  • Queried the Sample table using saved criteria and a filter string
  • Added fields to the JSON response by reconfiguring SampleManager

The REST service can be utilized for more functions such as Sample location changes and receiving. If none of the commands in the Help list meet your needs, auxiliary reports and .Net extensions can enhance the web service with additional features.

SM Rest API Video: How to Create a Simple Shortcut

The following video provides a step-by-step tutorial on creating a simple shortcut to view SampleManager information from any IOS device.

 

Summary

If you are developing a new application or integration that needs to access SampleManager data, we recommend using the REST API. The SampleManager LIMS REST API provides a number of advantages. REST-based services are format agnostic and therefore are generally easier to implement than existing SOAP-based web services and provide greater efficiency in terms of bandwidth and processing time, enabling higher data streaming performance when working with large datasets.

*You can also access the WCF address using “hostname:<port number>”, if you are trying to access outside of SampleManager application server, just need to make sure these ports are enabled in the firewall.

**Default SampleManager WCF Ports

About Astrix

For over 25 years, Astrix has been a market-leader in delivering innovative solutions through world class people, process, and technology that fundamentally improves scientific outcomes and quality of life everywhere. Founded by scientists to solve the unique challenges life sciences and other science-based business face. Astrix offers a growing array of strategic, technical, and staffing services designed to deliver value to clients across their organizations. To learn the latest about how Astrix is transforming the way science-based business succeed today, visit www.astrixinc.com.