SmartQC

Integrations

SmartQC

SmartQC is the SmartLabSys app where producers and traders manage quality control and order lab testing. This page explains how SmartLIMS receives SmartQC requests, turns them into your own requests, and keeps SmartQC informed while you work.

Who this is for: Laboratory owners and administrators who set up the connection, and lab staff who receive QC requests · You need: the "Manage QC (SmartQC) integration" permission; to turn a QC request into a request you also need "Manage requests"

The idea in short

Your customer creates a testing request in SmartQC and sends it to your laboratory. SmartLIMS picks it up, and you decide when to turn it into a normal SmartLIMS request.

Step Where What happens
1. Connect Settings › Lab Integrations You add your laboratory's access key from SmartQC once.
2. Map Settings › QC Request Mappers You say which form and laboratory a QC request becomes, and which QC values go into which form fields.
3. Pull QC Requests SmartLIMS copies your SmartQC requests on a schedule, or when you click Pull now.
4. Seed A QC request's page You click Seed into LabRequest. SmartLIMS creates a request with one sample per QC sample.
5. Work Your request You work on the request as usual. Each status change is reported back to SmartQC.
6. Talk A QC request's page You exchange comments and PDF documents with the customer in SmartQC.

The QC Requests list is a read-only copy. You can't change a QC request in SmartLIMS. You change your own request, created from it.

The SmartQC connection doesn't go through the SmartLabSys platform. It uses its own access key, so you can connect to SmartQC even if your company isn't connected to the platform.

How to connect SmartQC

  1. In SmartQC, create an access key for your laboratory. SmartQC shows it once. Keys expire after a while (currently 90 days), so note when you need a new one.
  2. In SmartLIMS, open Settings › Integrations › Lab Integrations.
  3. Click New lab integration.
  4. Fill in:
    • Name: any name you will recognize, for example "SmartQC – main lab".
    • Type: SmartQC.
    • API URL: the SmartQC address, normally https://qc.smartlabsys.com/.
    • API token: the access key you created in step 1.
    • Active: leave it on.
  5. Click Save changes.

Once a connection exists, QC Requests appears in the sidebar under Lab work, and the QC Request Mappers tile appears in Settings › Integrations.

A company can have several connections, for example one per laboratory in SmartQC. SmartLIMS skips connections that aren't Active. You can't delete a connection once requests have been pulled through it: switch it off instead.

How to set up a mapper

A mapper tells SmartLIMS what a QC request becomes: which form, which laboratory, and which QC value goes into which form field.

  1. Open Settings › Integrations › QC Request Mappers and click New mapper.
  2. Enter a Name. It is only a label for the list and has no effect on which requests use the mapper.
  3. Choose the Form and the Laboratory. The laboratory must be one the form allows, and the form must have been saved at least once.
  4. Under Preview, pick a QC request that has already been pulled. SmartLIMS then suggests QC field names and shows what each mapping would produce for that example.
  5. Under General field mappings, link request-level form fields to QC fields. A QC field name is a path into the QC data, such as template.name or customer.email. Pick one from the suggestions.
  6. Under Item field mappings, link sample-level form fields to QC fields. SmartLIMS creates one sample for every QC sample.
  7. Set the Routing conditions (see below).
  8. Optionally change the Status push overrides (see Statuses).
  9. Click Save changes.

📷 Screenshot: the mapper page with a preview example selected, field mappings filled in and the "Matches selected example" badge

Routing conditions: which mapper is used

When you seed a QC request, SmartLIMS looks at all your company's mappers:

  1. It checks the mappers in Priority order, lowest number first.
  2. It uses the first mapper whose conditions all match the QC request.
  3. If none matches, it uses the mapper marked Default mapper. Your company can have one default mapper at most.
  4. If there is no default mapper either, the QC request can't be seeded yet. Its page shows "No mapper is configured for this request's template yet." with a link to Manage QC request mappers.

Click Add condition to add a condition. Each one compares a QC field with a value:

Operator Matches when the QC field…
Equals is exactly the value
Does not equal is anything except the value
Contains contains the value
Is empty has no value
Is not empty has any value
Is one of (comma-separated) equals one of the listed values

All conditions of a mapper must match. To say "this OR that", make two mappers.

SmartLIMS never picks a mapper by the QC template name on its own. If you want one mapper per SmartQC template, add a condition on template.name, like any other field.

While you edit a mapper with a preview example selected, the badge Matches selected example tells you whether that QC request would use this mapper.

How to pull and seed QC requests

  1. Open QC Requests in the sidebar. SmartLIMS refreshes this list automatically on a schedule. The figures at the top count the QC requests: Total, To seed (not in SmartLIMS yet), Seeded and Done in QC; click one to see just those. Search by QC id or template, or filter by lab status and by whether a request is seeded.
  2. To fetch the latest right away, click Pull now. A message shows how many QC requests were created, updated or failed.
  3. Click a QC request to open it. You see its Field values, Examinations, Samples, Comments, Documents and the original data (Raw payload).
  4. Click Seed into LabRequest.
  5. SmartLIMS creates a new request using the matching mapper. The QC request now shows Already seeded and a View LabRequest button.

📷 Screenshot: a QC request page with the Seed into LabRequest button and the Samples section

The new request:

  • starts in the Received status, like any request;
  • uses the latest version of the mapper's form and your company's default rulebooks;
  • gets one sample for each QC sample, named after it. A QC request without samples gives a request without samples;
  • leaves a form field empty when the QC request has no value for it.

A QC request can be seeded only once. In the list, Last pulled shows when SmartLIMS last fetched each QC request. An amber dot means it is older than the last scheduled pull.

How to exchange comments and documents

On a QC request's page:

  • Comments: write in the box ("Write a comment...") and click Post comment. The comment goes straight to SmartQC.
  • Documents: click Upload document to send a PDF to SmartQC. Only PDF files are accepted. Click Download to open a document from SmartQC. Downloaded documents aren't stored in SmartLIMS.

Statuses sent to SmartQC

When a request created from SmartQC changes status, SmartLIMS sends the matching status to SmartQC, so your customer sees the progress.

SmartLIMS request status Shown in SmartQC as
Received Accepted
Configuration Accepted
In progress In testing
Validated Requires documentation
Authorized Done

In a mapper, Status push overrides lets you send a different SmartQC status for requests created through that mapper. Leave a row on Default to use the table above.

  • Only requests created from SmartQC are reported. Your other requests stay private.
  • If reflex testing sends a request back to Configuration, SmartQC receives the Configuration status again.
  • If SmartQC can't be reached, the status change in SmartLIMS still goes through. SmartLIMS doesn't warn you about it, so check SmartQC if the customer reports an old status.

Messages you may see

Message What it means
SmartQC API URL/token are not configured for this lab integration. The connection is missing its address or access key. Edit it in Lab Integrations.
The request to SmartQC failed. SmartQC couldn't be reached, or the access key has expired. Create a new key in SmartQC and paste it into the connection.
This lab integration still has mirrored QC requests and cannot be deleted. Switch the connection off (Active) instead of deleting it.
The selected form has no version yet — configure and save it first. Save the form in Settings › Forms first.
The selected laboratory is not allowed by the selected form. Choose a laboratory the form allows, or allow it on the form.
A default mapper for your company already exists. Untick Default mapper on the other mapper first.
Only PDF documents can be uploaded to SmartQC. Convert the file to PDF.

Tips

  • Start with one Default mapper without conditions. Add more specific mappers with conditions later, when you see which QC requests need a different form.
  • Keep a note of when your SmartQC access key expires. When it does, pulling and status updates stop until you paste a new one.
  • The screen still uses the word "LabRequest" on the QC pages. It means a normal SmartLIMS request.
↑↓ to move ↵ to open esc to close