Telematik

ordyn-telematik is the service client used for Telematik card terminal endpoints.

It connects through an assigned edge service, so the Ordyn server does not need direct network access to card terminals. Ordyn sends Telematik work to the selected service client, the service client talks to the terminal from its local network, and the result is reported back to Ordyn.

• create and edit Telematik card terminal endpoints
• collect card terminal system status
• probe card terminal API reachability
• expose terminal network interfaces for endpoint views and switch-port matching
• reboot card terminals
• run Telematik card terminal work from endpoint jobs

Supported terminals

Ordyn currently supports:

• Cherry ST-1506
• Worldline ORGA 6141 online

Reachability, system status, and reboot are supported. Broader vendor remote-management functions are currently not exposed.

Installation

Checkout the Telematik deployment folder from the Ordyn compose repository:

if [ ! -d /opt/ordyn-compose/.git ]; then
  git clone --filter=blob:none --sparse https://github.com/ordyn-project/compose.git /opt/ordyn-compose
fi
cd /opt/ordyn-compose
git sparse-checkout add telematik

Create the environment file:

cd /opt/ordyn-compose/telematik
cp .env.example .env

Set these values in .env:

ORDYN_TELEMATIK_EDGE_HOST=ordyn-edge.example.com
ORDYN_TELEMATIK_SERVICE_CLIENT_ID=<service-client-id>
ORDYN_LOG_LEVEL=info

Start the service:

docker compose pull
python3 /opt/cosign-docker-verify/verify.py

Continue with docker compose up -d only when the Telematik image verifies successfully and no failed verification message appears.

docker compose up -d

Issue a service-client enrollment token for the Telematik service client in Ordyn. Enroll the service once:

printf '%s' '<enrollment-token>' | docker compose exec -T telematik node dist/index.js enroll --token-stdin

Use the same enrollment command when renewing or recovering the Telematik service-client certificate. See service-client certificate lifetime and renewal.

Telematik does not need public HTTPS ingress. It connects outbound to the assigned Edge service and must be able to reach the card terminal management addresses from its local network.

Credential profiles

Telematik card terminal credential profiles are tenant-scoped and can be assigned to card terminals from the same tenant.

Profiles contain:

• username
• password
• TLS verification behavior

Secret fields are stored encrypted in Ordyn and are only sent to the assigned Telematik service client for terminal operations. The username is required by the Ordyn profile even when a terminal installation mostly treats authentication as password-based. For Cherry ST-1506 terminals, use the Webadmin username configured on the device, commonly admin.

A credential profile cannot be deleted while it is assigned to one or more card terminals.

Card terminal endpoints

Create card terminals manually with:

• endpoint kind Telematik card terminal
• hostname or management IP in the normal endpoint hostname field
• assigned Telematik service client
• assigned Telematik credential profile
• terminal type

The hostname is the terminal management address used by ordyn-telematik.

Card terminal endpoints appear in the endpoint tree and endpoint table like regular agent endpoints.

Connected and active state

Telematik card terminal endpoints use different connection semantics than agent endpoints.

Connected, Active, and Online in endpoint views mean Ordyn has a recent successful card terminal API reachability probe.

The assigned Telematik service client's own websocket state is shown separately as service connection state in the card terminal overview.

Reachability freshness is controlled by the Telematik Card Terminal Reachability Probe Freshness setting and defaults to 300 seconds. Ordyn automatically requests reachability probes through connected Telematik service clients. The probe interval is controlled by the Telematik Card Terminal Reachability Probe Interval setting and defaults to 60 seconds.

If the assigned service client is disconnected, the terminal cannot be probed and the endpoint becomes inactive after the freshness window expires.

System status collection

System status collection gathers operational facts from the terminal and stores them on the endpoint's Telematik card terminal configuration.

Ordyn stores:

• last request timestamp
• last successful or failed collection timestamp
• last collection status and error
• normalized facts used by the UI
• raw vendor payload for diagnostics

Ordyn automatically requests system status after terminal configuration changes and then refreshes it in the background. The automatic interval is controlled by the Telematik Card Terminal System Status Interval setting and defaults to 3600 seconds. The freshness window is controlled by the Telematik Card Terminal System Status Freshness setting and defaults to 7200 seconds.

The Collect card terminal system status job step can request the same collection on demand.

Network interfaces and switch matching

Card terminal network interfaces are stored as endpoint network interfaces.

Ordyn marks the vendor-reported active interface as link-up so the active terminal interface is visible immediately. MAC addresses are stored on the endpoint interfaces. This allows switch-port matching to link a card terminal interface to a switch port when SNMP switch inventory learns the same MAC address.

Card terminal interfaces can also store manually configured IP and MAC data. Interface IP addresses are used by IPAM and can be probed through the endpoint's effective net node. Use Net node routing from the card terminal endpoint action menu to set a direct endpoint net-node assignment, or rely on folder or tenant inheritance.

Each interface can be configured for:

• IPAM inclusion or ignore
• ICMP probing
• common protocol probing

The endpoint overview shows probe results and service metadata when the assigned net node reports them.

Vendor-specific network configuration such as DNS, gateway, netmask, DHCP mode, and NTP server is available from the interface details.

Reboot

Card terminal reboot is available from card terminal endpoint actions and from jobs that target Telematik card terminal endpoints.

Cherry ST-1506 reboot uses the COBRA RebootRequest with an empty payload. Ordyn must never send the optional adminPassword field for reboot, because Cherry documents that including a matching adminPassword causes a factory reset during reboot.

Worldline ORGA 6141 reboot uses authenticated RMI System.reboot with the active session id.

Reboot results are reported back through the Telematik service client and keep the job target and task context when reboot is executed from a job.

Job steps

Telematik job steps are documented in Available Job Tasks.

The current Telematik-specific task is:

• Collect card terminal system status

The regular Reboot endpoint task can also target Telematik card terminal endpoints.

Logging

The Telematik service client supports a dedicated log level setting. The default in .env.example is info. Use a more verbose level temporarily when diagnosing vendor payloads, reachability probes, or remote-management API failures.

System status and reboot diagnostics include normalized result data and selected raw vendor payload data in service logs so support bundles can show what the terminal actually returned.