Appearance
Calling other systems: HTTP, webhooks and e-mail
A gateway script can call a REST API (an ERP, an MES, a ticketing system, a chat webhook) and send e-mail, and an alarm pipeline's Webhook node can call a URL when an alarm trips. All of these go through one sender on the gateway. That sender decides which hosts may be called, caps how long and how large a call may be, and puts stored secrets such as API tokens into a request without the script ever seeing them.
The script sandbox still blocks Python's own network modules (urllib, http, smtplib, socket). Use raylux.net and raylux.mail instead.
Where a gateway may call
Set this in ConfigHub under System > Outbound HTTP. A save applies at once; Nexus does not restart.
By default:
- Allowed: the plant LAN (10/8, 172.16/12, 192.168/16, 100.64/10 and IPv6
fc00::/7) and the internet. - Blocked: the gateway itself (127.0.0.0/8 and
::1), link-local addresses (169.254.0.0/16 andfe80::/10), the cloud metadata addresses (169.254.169.254, 100.100.100.200, Azure's 168.63.129.16 andfd00:ec2::254), multicast,0.0.0.0and::, and reserved ranges. An IPv6 address that carries an IPv4 address (::ffff:127.0.0.1, NAT64, 6to4) is judged by the IPv4 address.
You can change that with:
| Setting | What it does |
|---|---|
| Allow | Hosts (erp.plant.local, *.corp.example), addresses or CIDRs (10.20.0.0/16) that may be called. A blocked address such as 127.0.0.1 can be allowed only by listing the address; listing a host name never unblocks the gateway's own address. |
| Deny | The same forms. A deny entry always wins over an allow entry. |
| Block private LAN ranges too | Private ranges are refused unless an allow entry matches. |
| Only call destinations on the allow list | Nothing else may be called. |
| Limits | Default timeout (a script may ask for its own, up to 60 s), the largest request and response, how many redirects are followed, and how many calls may be in flight at once (16 by default; one more is refused with BUSY, not queued). |
The check is made on the address the gateway actually connects to, after the name is looked up, and again on every redirect. A name that looks harmless but resolves to the gateway itself is refused. Credentials in a URL (https://user:pass@host) and proxies are not used. Authorization and Cookie headers are dropped when a redirect goes to another host.
Secrets
Add a secret under Secrets on the same page: a name, the hosts it may be sent to (* for any host the rules allow) and its value. The value is kept in the gateway's secret store, not in the project file, and never comes back to the browser. Renaming a secret on the page keeps its value; a new secret must be given its value when it is added.
A script uses raylux.net.secret("erp_token") and a Webhook node uses {secret.erp_token}. Both are placeholders. The gateway puts the value in when it sends the request, only when the host is one the secret allows. The value never reaches the script, never appears in a log line and is replaced with *** if the server echoes it back.
From a script: raylux.net
python
import raylux
token = raylux.net.secret("erp_token")
r = raylux.net.post("https://erp.plant.local/api/batches",
json={"line": "L1", "count": raylux.read_tag("[DEFAULT]L1/Count")},
headers={"Authorization": "Bearer " + token},
timeout=10)
if r.ok:
raylux.log_info("ERP took batch " + str(r.json()["id"]))
else:
raylux.log_error("ERP answered " + str(r.status))| Call | Returns |
|---|---|
raylux.net.request(method, url, *, headers=None, params=None, body=None, json=None, timeout=None, verify=True, auth=None) | An HttpResponse. method is GET, POST, PUT, PATCH, DELETE or HEAD. |
raylux.net.get(url, ...), .post, .put, .patch, .delete | The same, with the method set. |
raylux.net.secret(name) | The placeholder for a secret. Use it in a header, the body, json= or params=. |
headersis a dict of text to text.paramsis a dict added to the query string. Sendbody=(text or bytes) orjson=(a dict or list), not both.timeoutis in seconds, at most 60; the default comes from the gateway setting.verify=Falseskips the TLS certificate check for a server with a self-signed certificate. Prefer a proper certificate.auth=(user, password)sends HTTP Basic credentials. Either part may be a secret:auth=("svc", raylux.net.secret("erp_password")). The gateway encodes them after it puts the secret in, and a server that echoes them back is answered with***. Do not also send anAuthorizationheader.
An HttpResponse has .status, .ok (2xx), .is_client_error (4xx), .is_server_error (5xx), .headers (a dict with lower-case names), .content (bytes), .text, .json(), .redirects, .elapsed_ms and .raise_for_status().
Any HTTP status comes back as a response. A call that cannot be made raises raylux.net.HttpError, whose .code says why:
| Code | Meaning |
|---|---|
BLOCKED | The host or the address it resolves to is not allowed. .message names the address and the rule. |
TIMEOUT | No complete answer in time. |
TOO_LARGE | The request or the response is over its limit. |
SECRET | The secret is not defined, has no value, or may not go to this host. |
TLS | The certificate check failed. |
NETWORK | The name did not resolve or the connection failed. |
TOO_MANY_REDIRECTS | More redirects than the setting allows. |
INVALID | A malformed call: a bad URL, method or argument. |
BUSY | As many calls as the Calls at once limit are already in flight, or half the gateway's script threads are already waiting on the network, a mail server or Iris. Try again later. |
STOPPING | The gateway is shutting down; calls in flight are ended within about a second. |
DISABLED | The settings saved on the gateway are invalid, or the sender is not running. |
CONTEXT | Called outside a script run: from a strict-sandbox tool, or from a thread the script started itself. |
From a script: raylux.mail
python
raylux.mail.send(["[email protected]"], "Shift report", "<b>All lines running</b>", html=True)raylux.mail.send(to, subject, body, *, html=False) sends through the mail server set under System > Mail Server (SMTP). to is one address or a list of up to 50. It raises raylux.mail.MailError with .code NOT_CONFIGURED (no mail server set), INVALID, SEND_FAILED, BUSY (too many scripts are waiting already) or DISABLED.
Where these calls may run
Everywhere a script runs:
- gateway scripts of every type: Startup, Scheduled, Tag Change and Shutdown;
- component event scripts and message handlers (a button can call a webhook);
- transforms and script bindings;
- report data sources;
- alarm-pipeline Script nodes;
- project scripts called from any of these.
Each call is audited as the script that made it: a gateway script by name, and anything a person triggered (a button, a binding on their screen, a report they ran) under that person, for example component event script for 'operator'.
The gateway stays safe with limits, not refusals:
- every call has its timeout (at most 60 seconds);
- Calls at once caps calls in flight across the gateway, and at most half the gateway's script threads may be waiting on the network, a mail server or Iris at once; one more call gets
BUSYinstead of queuing; - the time a call waits does not count against the script's own time limit, so a transform or a pipeline node with a 5-second limit is not cut off by a slow server, and its 5 seconds still apply once the call returns;
- on shutdown, Shutdown scripts run first, while the sender, mail and Iris are still up. They get 30 seconds; then the sender stops and ends any call still waiting. From the moment Shutdown scripts start, no other script runs: timers, tag changes, bindings and buttons are refused with "the gateway is stopping". That includes a Tag Change script that a Shutdown script's own tag write would trigger. This is deliberate: nothing new starts while the gateway shuts down.
A call blocks the script that makes it. A binding that calls a slow server updates only as fast as the server answers, so for a value many screens show, fetch it in a Scheduled script and write it to a tag instead.
When a gateway script is still busy
A gateway script never runs twice at once, and a busy one never holds more than one script thread:
- Tag Change scripts run once per change of their tag, in order. While a run waits on a slow call, up to 5 further changes wait for it. When a sixth arrives, the oldest waiting change is dropped, and the next run sees
missed_eventsset toTrue(it isFalseotherwise). This matches Ignition'smissedEvents. A script that must not lose a change should keep its slow call out of the Tag Change script, for example by writing a tag a Scheduled script reads. - Scheduled scripts that run longer than their interval do not pile up: at most one tick waits, and it runs as soon as the current run ends.
- Project scripts (
raylux.custom) are plain Python modules, as in Ignition: a function may call back into its own script or into one that called it, and two scripts may call the same function at the same time. A recursion that never ends stops with Python'sRecursionErrorin the script; the gateway keeps running.
Webhook node
In Studio's Alarm Pipeline workspace, a Webhook node has:
| Field | |
|---|---|
| Method | POST, GET, PUT, PATCH or DELETE. |
| URL | {alarm.field} placeholders are allowed and are URL-encoded. |
| Headers | One Name: value per line, for example Authorization: Bearer {secret.hook_token}. |
| Body format | JSON or Text. |
| Body | Empty sends the alarm as a JSON object (the same fields a script node gets). In a JSON body, write placeholders inside quotes, {"text": "{alarm.name}: {alarm.message}"}, and their values are escaped for you. |
The node does not hold up the pipeline: the call is queued and made in the background. A failed call (blocked, refused, timed out, or answered with 4xx or 5xx) is written to the Nexus log and the audit log and never stops the pipeline.
What is recorded
Every call writes one line to the Nexus log and one row to the audit log (action OUTBOUND_HTTP, or SCRIPT_MAIL for e-mail) with the caller (the script, or the pipeline and node), the method, the host and the result. The full URL is not recorded, because a query string can carry a token.