JSON HTTP Connectivity Guide
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
GETrequest. - 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.
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
routefor 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:
propsdefines which values to read from the JSON response. - Transform:
variables(optional) converts raw values into the states MachineMetrics expects. - Output:
data-itemsandconditionsdefine 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.
| Setting | Default | Description |
|---|---|---|
scan-interval | 1 | Seconds to wait between each poll of the endpoint. Increase this for slow devices or data that changes rarely. |
insecure | false | Set 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.statereadsstateinsidesysteminsidemachine. - Find in array:
machines[id=102].locationsearches themachinesarray for the object whereidequals102, then reads itslocation. - Array index:
0.r.sreads 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
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
GETrequests. 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. Increasingscan-intervalreduces 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_faultfield that only appears when there is a fault), that prop reportsUNAVAILABLEuntil 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-intervalthat suits how quickly the data changes.
Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
All data items show UNAVAILABLE | The Edge cannot reach the endpoint, or every request is failing | Check 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 UNAVAILABLE | The service on the machine stopped, the port changed, a firewall was turned on, or the device switched from HTTP to HTTPS | Restart 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 UNAVAILABLE | The endpoint is responding close to, or over, the 10 second timeout | Test 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 fine | The path does not match the response, or the key is missing from the response | Compare 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 nothing | The 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 error | Self-signed or untrusted certificate | Add 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.