Skip to main content

JSON HTTP Connectivity Guide

Adapter script required — JSON HTTP will not collect data without one

Saving a JSON HTTP machine in MachineMetrics does not collect data by itself. You must add a Transform Adapter Script that maps JSON paths from the endpoint response to MachineMetrics data items (execution, part count, program, alarms, etc.). Without a script, the connection will show as configured but no production data will appear.

An adapter script is mandatory before you will see data. See Examples on this page for ready-to-use scripts. Contact MachineMetrics Support if you need more help.

Overview​

The JSON HTTP connector lets MachineMetrics collect data from any device or service that serves machine data as JSON over HTTP or HTTPS. The Edge device polls an API endpoint on a set interval, pulls out the values you choose, and turns them into MachineMetrics data items such as execution, part count, program and alarms.

When to use JSON HTTP​

Use JSON HTTP when:

  • The machine or controller has a built-in web server or REST API that returns JSON.
  • The machine builder or integrator can expose machine status through a JSON endpoint (for example, a controller with a status screen that already shows the data you need).
  • A small service on the machine PC, or an Edge service, reads machine files or logs and serves the results as JSON.
  • You need a fast route to a custom connection without building a dedicated adapter.

JSON HTTP is a polling connection. MachineMetrics requests the endpoint, reads the response, and repeats. It does not receive pushed data. If the machine publishes data instead of serving it, look at the MQTT Connectivity Guide.


Prerequisites​

Machine or data source

  • An HTTP or HTTPS endpoint that returns valid JSON for a GET request.
  • The endpoint must not require a login, API key or token. See Limitations.
  • The endpoint should respond quickly. Responses that take longer than 10 seconds are treated as failed.

Network

  • A MachineMetrics Edge device on a network that can reach the endpoint.
  • The endpoint's IP address (static or a reserved DHCP address is strongly recommended) and port.
  • Any firewall on the machine PC or network must allow inbound traffic from the Edge device on that port.
Quick check before you start

From a PC on the same network as the Edge device, open the endpoint URL in a browser or run curl http://<ip>:<port>/<path>. You should see JSON text. If you see an HTML page, a login screen or nothing at all, fix that first.


Adding the Machine in MachineMetrics​

Step 1: Add a data collection method​

Under Assets > Machines, select the machine and add a data collection method. Choose JSON HTTP as the Integration Type.

Step 2: Enter the Connection Address​

Enter the full URL of the endpoint, including the protocol and, if it is not the default, the port.

http://192.168.100.132:8080
  • If every value you need comes from the same endpoint, include the full path in the address, for example http://192.168.100.132/path/to/endpoint.
  • If the endpoint is a file, include the file name and extension, for example http://192.168.100.132/state.json.
  • If values come from more than one endpoint on the same server, enter only the base address here and set a route for each value in the adapter script (see Longhand syntax).
  • Use https:// if the device only serves HTTPS.

Step 3: Add the adapter script​

The connection address only tells the Edge where to look. You must add an adapter script in the Configure your adapter field that defines which values to read from the JSON response and which data items to send to MachineMetrics. Without a script, no data is collected.

Step 4: Save and verify​

Save the data collection method, then check the machine's diagnostics to confirm the data items are reporting values rather than UNAVAILABLE.

Step 5: Map the data items​

Map the data items in the machine's data item mapping (for example, execution, part count and program), the same way you would for any other connection type.


Adapter Script Reference​

A JSON HTTP adapter script uses the standard adapter script structure:

  • Input: props defines which values to read from the JSON response.
  • Transform: variables (optional) converts raw values into the states MachineMetrics expects.
  • Output: data-items and conditions define what is sent to MachineMetrics.

For the general adapter script language (variables, expressions, conditions), see the Adapter Scripts guide. This page covers what is specific to JSON HTTP.

props​

props is where every value read from the endpoint is defined. Each prop has a name (used in the rest of the script) and a path to the value in the JSON response. There are two ways to write props.

Shorthand syntax (single endpoint)​

Use shorthand when everything comes from the one endpoint in the Connection Address. Each prop is a name and a path.

props:
key: path.to.attribute

Longhand syntax (multiple routes)​

Use longhand when values come from different endpoints on the same server. The request URL is the Connection Address with the prop's route added to the end.

props:
key:
path: path.to.attribute
route: /some/api/route

Optional settings​

These go at the top level of the script.

SettingDefaultDescription
scan-interval1Seconds to wait between each poll of the endpoint. Increase this for slow devices or data that changes rarely.
insecurefalseSet to true to connect to an HTTPS endpoint whose certificate cannot be validated, such as a self-signed certificate.
version: 2
scan-interval: 3
insecure: true
props:
test: a.b
data-items:
- test

JSON Path Syntax​

Paths tell the connector where a value sits in the JSON response. The connector supports regular dot paths, plus an extended "find" notation for arrays.

  • Regular path: machine.system.state reads state inside system inside machine.
  • Find in array: machines[id=102].location searches the machines array for the object where id equals 102, then reads its location.
  • Array index: 0.r.s reads from the first object (index 0) of an array.

Basic path​

props:
test: a.b.c

Response:

{
"a": {
"b": {
"c": "test"
}
}
}

test reads the value "test".

Path with a dedicated route​

props:
test-dedicated-route:
path: d.e.f
route: /other-route

Response from /other-route:

{
"d": {
"e": {
"f": "test-dedicated-route"
}
}
}

Search within an array​

props:
test-search-array: g.h[i=j].k

Response:

{
"g": {
"h": [
{
"i": "j",
"k": "test-search-array"
}
]
}
}

The connector searches the g.h array for the object where i equals j, then reads its k value.

Search within a root array, with a dedicated route​

When the response itself is an array, start the path with the search. Wrap the path in quotes because it starts with [.

props:
test-search-array-root:
path: "[l=m].n[o=p].q"
route: /array

Response from /array:

[
{
"l": "m",
"n": [
{
"o": "p",
"q": "test-search-array-root"
}
]
}
]

Array index, with a dedicated route​

props:
test-index-array:
path: 0.r.s
route: /array

Response from /array:

[
{
"r": {
"s": "test-index-array"
}
}
]

Examples​

Example 1: Machine status endpoint​

Endpoint response:

{
"machine_state": "Running",
"unit_count": 1312,
"program": "O1234",
"server_time": "2026-03-10T15:47:45"
}

Adapter script:

version: 2
scan-interval: 5
props:
machine_state: machine_state
part_count: unit_count
program: program

variables:
execution:
- state:
- ACTIVE: machine_state == "Running"
- READY: true

data-items:
- execution
- part_count
- program
note

Only list what you need in props. Values that are read but not listed in data-items are not sent to MachineMetrics.

Example 2: Reading a text file through the SMB Reader Edge service​

JSON HTTP can also read machine files when paired with the SMB Reader Edge service, which reads a file from a shared folder on the machine PC and serves its contents as JSON. This is used, for example, to read DPRNT program headers from a Mazak print.txt file.

Connection Address:

http://smb-reader:8080?host=<machine-ip>&share=print&filename=print.txt

Adapter script (extracts the program name from a MMPHDR* line in the file):

version: 2
scan-interval: 10
props:
content: content
variables:
operation_name:
- source: content
- pattern-match:
pattern: /MMPHDR[*]([^\r\n]+)/
group: 1
data-items:
- operation_name

The SMB Reader must be added and configured on the Edge device first. Contact support@machinemetrics.com if you need help setting it up.


Limitations​

  • No authentication. The connector sends plain GET requests. Endpoints that need a username and password, an API key or a bearer token are not supported.
  • 10 second timeout. Each request times out after 10 seconds. If the device regularly takes longer, values will drop to UNAVAILABLE. Increasing scan-interval reduces load on the device but does not extend the timeout.
  • Missing keys report as unavailable. If a key is not present in the response (for example, a latest_fault field that only appears when there is a fault), that prop reports UNAVAILABLE until the key appears. This is expected.
  • Polling, not streaming. Very short-lived events that start and finish between polls can be missed. Pick a scan-interval that suits how quickly the data changes.

Troubleshooting​

SymptomLikely causeWhat to do
All data items show UNAVAILABLEThe Edge cannot reach the endpoint, or every request is failingCheck the Connection Address (protocol, IP, port, path). Confirm the endpoint loads from another PC on the same network. Check for a firewall on the machine PC blocking the port.
Worked before, now all UNAVAILABLEThe service on the machine stopped, the port changed, a firewall was turned on, or the device switched from HTTP to HTTPSRestart the service on the machine. Re-test the URL from another PC. Check whether the device now only answers on https:// and update the address, adding insecure: true if the certificate is self-signed.
Data flickers between values and UNAVAILABLEThe endpoint is responding close to, or over, the 10 second timeoutTest how long the URL takes to load. If it is slow, the fix is on the data source side (faster response or caching). A longer scan-interval can reduce load on the device.
One or two data items UNAVAILABLE, others fineThe path does not match the response, or the key is missing from the responseCompare the path in the script with the actual JSON. Paths are case sensitive. If the key only appears sometimes, this is expected.
Endpoint loads in a browser but MachineMetrics gets nothingThe response is not JSON (for example an HTML page or a login screen)Check the raw response is JSON. Ask the device vendor or integrator to correct the output, or contact support.
HTTPS endpoint fails with a certificate errorSelf-signed or untrusted certificateAdd insecure: true to the top of the script.

If you are still stuck, contact support@machinemetrics.com with the machine name, the Connection Address, a copy of the endpoint's JSON response and your adapter script.


Additional Resources​