i3X setup walkthrough

Connect to an i3X 1.0 API, browse its elements, and create read-only tags for selected current values. Start with polling and one element so you can verify the API address, authentication and data type before adding a larger model.

Build availability: these steps require a SparkStudio build whose New Connection menu includes i3X source. The published Windows v0.2.0-preview.12 and Docker 0.2.0-preview.11-docker.1 do not include this source feature. This is a development-build guide, reviewed October 2, 2026.

Where do I create the tags?

The recommended route is in the connection: browse elements, select values, then Preview point and tag import → Apply reviewed import. Apply saves the selected source points and creates their gateway tags together. You do not need to recreate them in Tags.

Alternatively, save point definitions in the connection and create tags later in Tags. Add point and Import / edit JSON change the point-map draft only; they require Save connection and do not create tags. Both routes bind a tag to a stable saved point, rather than treating a displayed element name as its identity.

Before you start

Have an engineering session signed in as a gateway administrator and obtain the following from the i3X service owner:

• The complete i3X 1.0 API base URL, for example https://i3x.example.com/v1.
• The required username/password, bearer token or API key, including its header name.
• A known element you are permitted to browse and read, its expected value/type, and any supported subscription transport.
• Certificate references for a private CA or mutual TLS, if required.

The API must be reachable from the gateway machine or container. Outside loopback, SparkStudio requires HTTPS and configured authentication for i3X. Plain HTTP with None authentication is permitted only for a local loopback service. A browser reaching the service does not establish gateway connectivity; 127.0.0.1 refers to the gateway's own host or container.

1. Create and test the connection

1. Open Gateway Settings → Configuration → Connections → New Connection → i3X source.
2. Give it a recognizable name, such as Line 1 i3X, and leave it enabled.
3. Set Base URL to the service's full API root. Include /v1 if it is part of that root; do not enter an individual element or current-value URL.
4. Set Authentication mode to the service's mode: Username and password, Bearer token, or API key. Fill the displayed credential fields. For an API key, set API-key header to the service's required header; its default is X-API-Key.
5. Leave Acquisition at Polling and Poll / sync interval (ms) at 1000 for the initial check. The supported interval is 1,000–60,000 ms.
6. Leave Client identity blank to generate and retain an identity on first save. Keep Prefer advertised SSE, with sync fallback checked and Reconcile current state every (seconds) at 30 for later subscription use.
7. Choose Save connection → Test connection. Test is unavailable while the connection has unsaved changes or is disabled.

Expect a successful API connectivity result. This does not yet prove that your selected element returns usable data. The following read check establishes that.

For certificate settings, expand Certificates and server identity and enter existing gateway certificate reference names. These fields do not accept certificate contents or local file paths. A saved credential placeholder retains its secret when left unchanged; Clear password or Clear token removes it.

Connection field reference

These settings identify the API and control one shared acquisition session. They do not create tags. Start with polling, then browse and import one known value before choosing subscriptions.

Credential values are limited to 8,192 characters and cannot contain carriage returns, newlines or NUL characters. Use a token/key in its dedicated field rather than pasting an entire HTTP header.

The following optional fields appear under Certificates and server identity. Ask the gateway administrator for an existing certificate reference name; do not paste PEM contents, a private key or an absolute file path.

Certificate reference names are at most 128 characters, start with a letter or digit, and otherwise use letters/digits/underscore/dot/hyphen. They cannot contain ... Certificates and keys must already be provisioned in the gateway's certificate store before a connection can use them.

2. Browse an element and import its tag

1. Under Browse source, choose Browse / refresh.
2. Navigate the model using Browse children. Use Load next page when offered; a folder is a navigation entry, not automatically a value tag.
3. Set Import root to an unused tag folder such as [default]I3XDemo before selecting points.
4. Select one readable value's checkbox. Inspect its raw element ID and any selector. In the selected-points table, confirm the data type and edit the Tag path to a useful name, such as [default]I3XDemo/Running for a Boolean value.
5. Choose Preview point and tag import. Review the proposed rows and total tag count, then choose Apply reviewed import.

Apply commits the selected point definitions and tags together; no follow-up Save connection is needed for this import. If configuration changes invalidate the preview, preview again. Each transaction permits at most 1,000 selected points. Unsupported or non-value entries can remain browse-only.

Keep element IDs and selectors separate

i3X element IDs are opaque. Copy the exact ID returned by the service, including characters such as #; do not turn it into a tag folder path or append a member selector to it.

For a structured element, a point might use:

For a scalar element, leave the selector empty. Prefer the browsed selector when available; its spelling follows the service's actual structured value.

Point and tag import field reference

An element ID identifies the service value; a Point ID identifies its saved binding in SparkStudio; a Tag path is your gateway name for that binding. These are different fields. For example, an element named urn:line1:machine#state might return {"running":true,"temperature":24.5,"axes":[{"position":10.2}]}. One saved point can select /running as Boolean and another can select /temperature as Double while retaining the same raw element ID.

The saved map is limited to 10,000 points and 768 KiB of serialized point definitions. Removing or changing the type of a point referenced by a tag or UDT is blocked until those bindings are updated. In Tags, choose Device / industrial source point → Device / source connection → Saved point; its saved identity, type and read-only status supply the binding. Do not paste the raw element ID into the Saved point field. Opening Browse or saving a point map does not create tags automatically.

3. Verify current values

1. Under Saved source points, choose Read beside the imported point, or Read first 256 points for a small map.
2. Confirm the expected value, Good quality, Source timestamp and Receipt timestamp. A healthy i3X reading requires a valid UTC source timestamp ending in Z; a missing or invalid timestamp produces Bad_DecodingError. Receipt describes gateway arrival and does not replace an invalid source time.
3. Open Tags, find the path you created, and inspect its current value and quality.
4. If possible, have the service owner change a known test value. Confirm the next polling result reaches the tag.

Open Diagnostics for acquisition, per-element failures, reconnection and resource-limit details. A reachable information endpoint or a connected transport does not prove that every selected element is healthy. Large Int64 values retain their exact decimal digits and can appear as decimal strings in the browser; avoid converting them to rounded floating-point display values.

Add a tag later from the Tags tab

1. If the desired point is not saved yet, choose Add point in the connection. Enter a stable Point ID, Point name, exact Raw address, optional separate Selector, and Data type. Choose Apply point to draft → Save connection. A manually entered address still needs a successful read to confirm it matches the service.
2. Open Tags → New Tag → Device point tag and enter the Tag path.
3. Confirm Value source is Device / industrial source point, choose Device / source connection, then Saved point.
4. Leave the tag enabled and choose Save. The saved point supplies its type and read-only status.

Acquisition belongs to the connection. Tag scan-group settings do not create independent polling or subscription sessions. For reusable equipment structures, see tag models.

Optional subscriptions

After polling works, change Acquisition to Subscription / stream, retain Prefer advertised SSE, with sync fallback, and choose Save connection → Test connection. The connector uses advertised server-sent events when available. It uses subscription synchronization when SSE is not advertised, the preference is unchecked, or the stream endpoint returns HTTP 501 Not Implemented. Other stream failures remain visible as recovery or faulted acquisition; they do not silently force sync. The Poll / sync interval (ms) controls the delay between completed sync requests and does not throttle pushed SSE updates.

Keep Reconcile current state every (seconds) at 30, or choose a value from 5 to 300 appropriate to your service. Reconciliation repairs current-state drift even while a subscription remains connected. Check Diagnostics after enabling the mode and verify a changing value again. Subscriptions are best effort and current-state updates can coalesce; this is not a lossless event journal.

Advanced limits and timeouts

These 12 fields appear under Effective limits and timeouts for i3X. Leave the defaults for an initial connection. They are ceilings and deadlines, not requests for faster polling. Smaller ceilings can reject valid large responses/models; Diagnostics identifies the rejected limit. Per-connection settings also share the gateway's global resource budgets.

For i3X, Decode working bytes must be at least eight times HTTP / XML document bytes to admit even one decode. With the maximum 32 MiB decode ceiling, a document ceiling above 4 MiB cannot be admitted, even though the shared document field individually accepts up to 8 MiB. For example, a 2 MiB document limit needs at least 16 MiB decode working bytes. The default 1 MiB/32 MiB pair leaves room for four concurrent decode reservations.

Troubleshooting

The resulting tags are read-only and cannot be used as equipment command targets. Once values have acceptable quality, add a display in Designer and use fx → Tag to bind its property; see property bindings. Save and explicitly publish the project for operators. Saving gateway connections or tags does not publish a project.

For other source setup paths, see MQTT and MTConnect.