Skip to main content

🔌 Connecting via the Automation API

This guide describes how to implement and test a server that works with LabXpert Automation using the Automation API specification.

🧩 Overview​

LabXpert Automation connects to external systems via HTTP using a well-defined API. To enable this connection, external systems must implement endpoints as defined in the Automation API (Swagger) spec — either in full or selectively, depending on the system’s role.

✅ Requirements for Your Server​

Must:​

  • Be accessible via HTTP (locally or over a network)

  • Implement one or more of the following endpoints:

    • GET /tests
    • GET /requests
    • POST /machines
    • POST /results

  • Follow the schemas in the provided OpenAPI document

  • Support Basic Authentication

🏗️ Step 1: Understand the Endpoints​

EndpointPurposeRequired?
GET /testsReturns list of available tests to match machine results✅ for systems doing test mapping
GET /requestsReturns pending test requests (worklist)✅ for systems pushing work to Automation
POST /resultsReceives results from Automation✅ for systems receiving test results
POST /machinesReceives machine metadataOptional, used for inventory sync

Each endpoint must follow the structure defined in the OpenAPI schemas (see /docs).

🧪 Step 2: Test Your API with Swagger UI​

  1. Open the Swagger API Client using Swagger UI

  2. Use the "Try it out" feature to test:

    • Authentication
    • Schema validation
    • Expected responses

⚙️ Step 3: Implement the Endpoints (Any Language)​

You can use any backend language or framework. Here's how it might look conceptually:

Example: GET /requests​

  • Accepts optional query parameters: testIds, sampleId
  • Returns a JSON array of test request objects
[
  {
    "id": "req-001",
    "date": "2024-05-04T12:00:00Z",
    "status": "pending",
    "sampleId": "sample-001",
    "testId": "hb",
    "patient": {
      "name": { "givenName": "John", "familyName": "Doe" },
      "dob": "2000-01-01T00:00:00Z",
      "sex": "M"
    }
  }
]

Example: POST /results​

  • Receives an array of result objects
  • Responds with array of SyncedItem confirmations
[
  {
    "status": "success",
    "localId": "result-001",
    "remoteId": "server-789"
  }
]

Refer to the /components/schemas in the Swagger spec for detailed structure.

🔐 Step 4: Add Basic Authentication​

All requests from Automation use HTTP Basic Auth. Your server should reject requests that do not provide valid credentials.

Example header:

Authorization: Basic YWRtaW46cGFzc3dvcmQ=

Decoded, this is:

username: admin
password: password

🔗 Step 5: Configure Automation to Use Your API​

On the Automation app, configure a System to point to your server:

  • Base URL: e.g., http://192.168.1.10:8080
  • Authentication: Basic auth credentials
  • Automation will automatically use /tests, /requests, and /results as needed

🎯 Tips for a Smooth Integration​

  • Stick to the spec: The JSON payloads must match exactly (field names, types, structure).
  • Log all incoming requests for troubleshooting
  • Use ISO 8601 timestamps (e.g., "2024-05-04T12:00:00Z")
  • Return clear errors for bad requests (status 400+) and document what went wrong