Loading…
Loading…
Maps customer-facing terms to their precise technical counterparts within the S2R platform, including code locations and caveats, for consistent
This document serves as a canonical reference for mapping natural-language terms used by API consumers to their precise technical counterparts within the S2R platform's codebase and schema. Its primary purpose is to ensure consistent communication and accurate technical implementation by providing a single source of truth for terminology. (source: docs/customer-terminology.md)
Key Capabilities:
When to Use This Document:
API publishers and agents must consult this file whenever a project brief or customer requirement quotes customer language. It is essential for translating requirements into technical specifications, code, SQL, and Data Transfer Object (DTO) fields. (source: docs/customer-terminology.md)
When to Seek Clarification:
If a term is ambiguous, not found in this document, or appears to point to a different technical target than expected, the Product Manager (PM) is responsible for seeking clarification from the customer and recording the resolution here. Agents are strictly prohibited from coining their own translations. (source: docs/customer-terminology.md)
The following step-by-step process outlines how agents must use this terminology mapping document to ensure accuracy and consistency: (source: docs/customer-terminology.md)
Caveat explaining the discrepancy.Terms are grouped by domain to facilitate easier lookup. Each entry includes the customer's natural-language term, its canonical technical counterpart, where it is implemented or stored, and any important caveats regarding its usage or history. (source: docs/customer-terminology.md)
This section defines terms related to the discovery and management of F5 load balancer configurations. (source: docs/customer-terminology.md)
| Customer term | Technical term | Where it lives | Caveat |
|---|---|---|---|
| Discovery Ingest VM | discovery-ingest VM (relay VM) | GCE instance (live: s2r-f5r-0c4059fc in me-west1-b until it migrates on recreate to the s2r-discovery-ingest-* / s2r-di-* pattern); columns relayVmInstanceName, relayVmTarget, relayVmIpAddress on the F5 instance sync state; logForwardingEnabled / relayEnabled flags on the F5 instance record. | UI label history: Relay Health → F5 Log Ingestion VM (commit 600d3ce) → Discovery Ingest VM (discovery-ingest Wave B, #914). data-tab="relay-health" kept stable for deep-links. The ingest Cloud Run service is s2r-discovery-ingest (was s2r-f5-ingest); provisioning classes are DiscoveryIngestVmService / DiscoveryIngestHealthService (were F5RelayVmService / F5RelayHealthService). The F5 gateway domain (F5 instances, virtual servers, F5 discovery) keeps its F5* names — F5 is a real supported vendor. |
| F5 instance | A configured F5 load balancer connection | s2r_f5_instance table; f5_instance_id (uuid) foreign key across s2r_master_discovery, s2r_master_discovery_consumer, s2r_f5_virtual_server_catalog, s2r_f5_sync_state. | Not the F5 hardware unit — it's the per-management-endpoint record this app keeps. One configured entry per F5 box or HA pair. |
| Virtual Server / VS | F5 Virtual Server | s2r_f5_virtual_server_catalog rows; frontVirtualServers[] / backendVirtualServers[] in catalog snapshot. | Frontend VS = external-facing; Backend VS = pool target. Identified by name + partition + (ip:port or pool). |
| Frontend VS | Frontend-role Virtual Server | frontendVirtualServers[] in the F5 catalog snapshot payload. | — |
| Backend VS | Backend-role Virtual Server | backendVirtualServers[] in the F5 catalog snapshot payload. | — |
| Pool | F5 Pool | .pool field on each VS row; s2r_f5_pool_catalog if persisted. | Pool members = the actual backend IPs the pool balances over. |
| Pool Members | F5 Pool Members (IP:port targets) | poolMembers[] on each VS row. | Rendered as monospace chips in the Admin UI. |
| Matched Services | REST/SOAP services whose backend matches the VS's host:port | matchedServices field on each catalog VS entry (renamed from matchedConfiguredServices during Epic O; the legacy alias was dropped from the wire in Epic P #13 once the UI had stabilised). Source data: s2r_master_discovery.back_pool_members joined by host+port. | Customer originally said "based on s2r_master_discovery_consumer table" — the service URI actually lives on the parent s2r_master_discovery row; the consumer table only holds consumer IPs. |
| Instances (as a tab label) | F5 instances CRUD panel | settings.html#panelF5 iframed into F5 Discovery's Instances tab via ?tab=f5&hideChrome=1. | Tab label is literally Instances, not F5 Instances — the page is already F5 Discovery so the prefix is redundant. |
| F5 catalog | Last snapshot of F5 configuration discovered by the scanner | s2r_f5_sync_state.last_catalog_snapshot JSONB column. | Populated by F5DiscoveryService, not by live API calls. |
| Full scan / light scan | F5 discovery scan modes | F5DiscoveryService scan runs; "full" = exhaustive inventory, "light" = incremental health/metric refresh. | Surfaced in F5 Instance card as full ok @ <timestamp> / light failed @ <timestamp>. |
This section defines terms related to the discovery and management of IBM DataPower appliance configurations. (source: docs/customer-terminology.md)
| Customer term | Technical term | Where it lives | Caveat |
|---|---|---|---|
| DataPower instance / Gateway | A configured IBM DataPower appliance | s2r_datapower_instance table. | — |
| Cluster | Set of DataPower gateways serving the same domain | Implicit via shared domain_name; rendered under DataPower-GW-1, -GW-2 etc. | — |
| Service Mapping | DataPower service → F5/runtime backend mapping | s2r_datapower_service_mapping table; the DataPower Discovery Service Mapping tab. | Reason column was removed in commit 57bee5e; backend still emits inactiveReason (computed live in DataPowerController.java:768-785) — backlog item to drop. |
| Cluster Drift | Rows where value-groups disagree across gateways OR a gateway is missing | renderClusterDrift in datapower-discovery.html; drill-down modal #dpDriftDetailModal (commit afe97c8). | Rows where every group agrees AND nothing is missing are now hidden — matches the tab name. |
| Gateway Value Groups | Per-gateway Frontend / Backend / WSDL / Route records | diff.items[].valueGroups[] in the drift API response. | Used to be a wide multi-line column; replaced in commit afe97c8 with a compact Gateways chip cell + a row-click modal with field-by-field diff highlighting. |
| Missing Gateways | Gateways in the cluster that don't carry this object at all | diff.items[].missingInstances[]. | Rendered as .pill.pill-err chips in the summary table. |
This section covers general terms related to service discovery across different sources. (source: docs/customer-terminology.md)
| Customer term | Technical term | Where it lives | Caveat |
|---|---|---|---|
| Main Discovery | Cross-source correlated service inventory view | discovery.html — tabs Service Inventory / Active Services / Consumers / Correlation / WSDL Probe / Incomplete / Onboarding. | — |
| Service URI | Canonical REST path of a discovered service | service_uri_canonical column on s2r_master_discovery. | Also called uri_name in some older code paths; canonical name is service_uri_canonical. |
| Service Backend | Upstream SOAP endpoint the REST route proxies to | back_pool_members[] / backendUrl / backend_host:backend_port. | — |
| Consumer | An IP / client that has been observed calling a service | s2r_master_discovery_consumer rows — per (master_discovery_id, consumer_ip). Optional human-readable label stored in consumer_alias (wire field consumerAlias), editable inline on both the Consumers and Correlation tabs of discovery.html. | Consumer table carries traffic volume counters (hits_24h..hits_1y), NOT service URIs. Alias is per-IP across the whole F5 instance (not per-master-row). |
This section defines terms related to monitoring and observing platform behavior, including traffic and error conditions. (source: docs/customer-terminology.md)
| Customer term | Technical term | Where it lives | Caveat |
|---|---|---|---|
| Live Traffic | Last-15m runtime invocation log | s2r_runtime_log; Services Live Traffic tab on observability.html. | — |
| F5 Live Traffic Log | Raw F5 ingest event feed | s2r_f5_traffic_event; fed from the relay VM's /ingest/v1/f5/traffic endpoint. | — |
| Correlation ID | Per-request trace id | correlation_id column on runtime logs, debug traces, audit events. | — |
| System error | Transport / infrastructure failure | Detection surface: curator shouldStoreLearnedExample in F5TrafficLearningService; also s2r_runtime_log.result_code. Signals: HTTP 4xx/5xx, result_code IN ('failed','backend_failure','blocked','error','timeout'), non-empty error_message, SOAP Fault envelope (any namespace prefix) in response body, or string "Internal (System )?Error". | Always disqualifies a row from being a Good Example. |
| Logical error / business error | HTTP 200 response whose payload conveys a business-rule failure | Detection is payload-content only (no status signal). Markers are frequently Hebrew UTF-8. Note Hebrew is gendered — both masculine לא קיים and feminine לא קיימת (the feminine variant is used with feminine nouns like תעודת זהות) must be on the list. Common markers: תעודת זהות לא קיימת ("ID does not exist"), לא קיים, לא קיימת, לא נמצא, שגיאה, כשל, תקלה — or English equivalents, or structured XML/JSON fields (<errorCode>, <errorMessage>, <errorDescription>, resultCode != 0/success). | Customer requirement (2026-04-19): curator must filter these the same way as system errors when deciding Good Examples. Marker list is runtime-configurable via S2R_LEARNED_EXAMPLE_ERROR_MARKERS (Epic X #6); superseded in Epic X #9 by the s2r_learned_example_error_marker table editable from Settings UI. Be conservative — prefer false negatives over false positives. |
| Error marker / logical-error pattern | Configurable substring pattern that classifies a response payload as a business error | s2r_learned_example_error_marker table (Epic X #9, Flyway). Global markers (service_id IS NULL) apply everywhere; per-service markers add to the global set. Managed from Settings UI ("Error Markers" panel) and from the service drill-down ("Error Markers" accordion). Worker loads markers with 60s TTL cache; changes take effect without redeploy. | Customer phrasing (2026-04-19): "pattern" / "patterns you can add in the settings". v1 supports SUBSTRING only (regex deferred — typos cause real successes to be classified as errors). |
This section defines terms that apply broadly across the user interface and the application. (source: docs/customer-terminology.md)
| Customer term | Technical term | Where it lives | Caveat |
|---|---|---|---|
| Main object / main object on the page | The primary data-bearing element (usually a table) | Case-by-case. | Customer uses this phrase to mean "the thing the page exists to show — give it the viewport, drop everything else". UI/UX standards §0 rule 2 captures the same idea. |
| Top-level tab vs grouped tab | Flat tab vs nested sub-tab | .tab-bar + .tab-btn (flat); .subtab-strip + .subtab-panel (nested). | House pattern is FLAT tabs with count-badges across the whole app (see Observability, Settings, Main Discovery). Nested sub-tabs are discouraged — Epic O flattened them on F5 Discovery. |
| Admin UI / the app | The Node.js-served frontend at https://s2r.mot.gov.il/ | services/admin-ui/ (current). Future target: React + TS. | Always validated through https://s2r.mot.gov.il/ — never a raw Cloud Run URL. |
| Onboarding | The onboarding wizard page | Route /onboarding → services/admin-ui/public/onboarding.html; top-nav label Onboarding. | Label replaced WSDL Onboarding to accommodate the dual-flow rework (Epic P) — the route stays at /onboarding.html. |
| Publish SOAP as REST | direction=PUBLISH onboarding flow | state.direction = 'PUBLISH' in onboarding.html; s2r_service.direction = 'PUBLISH'; left-hand card on the onboarding landing picker. | Existing WSDL-driven wizard. Operator picks this card before Step 1 runs (Epic P #7a). |
| Consume REST as SOAP | direction=CONSUME onboarding flow | state.direction = 'CONSUME' in onboarding.html; s2r_service.direction = 'CONSUME'; right-hand card on the onboarding landing picker. | 5-step wizard reuses Publish markup (Epic P #7b), with per-direction labels + a step-5 curl hint and inbound-WSDL download row. |
| Inbound WSDL | WSDL the platform serves to SOAP clients in the Consume flow | s2r_wsdl_artifact.wsdl_xml (migration V82); download endpoint GET /admin/v1/services/{id}/versions/{vid}/inbound-wsdl; step 5 of the Consume wizard exposes a download button. | Uploaded as-is on Consume step C2; served back verbatim (no auto-emission / synthesis — that's RFC E5). |
| OpenAPI import | Parsed + persisted OpenAPI 3 spec uploaded for a Consume service | s2r_openapi_import table (migration V83); endpoints POST /admin/v1/openapi/import (multipart) + POST /admin/v1/openapi/import-url + GET /admin/v1/openapi/imports/{id}. Consume wizard step 3a (#step-openapi in onboarding.html) drives the upload and PATCHes the association onto s2r_service_version.openapi_import_id via PATCH /admin/v1/services/{id}/versions/{vid} (Epic P #17, migration V87). | RFC E4a / Epic P #15 + E4c / #17. OpenAPI 3 only (Swagger 2 rejected). JSON or YAML accepted; YAML is normalised to JSON in parsed_spec. Dedup is by SHA-256 of the raw bytes — re-uploading the same spec returns the existing importId. The wizard step pre-fills the REST Backend URL on step 4 from servers[0].url, shows a collapsed table of parsed operations, and the Publish button is disabled (hover text: "Upload an OpenAPI spec (Step 3) before publishing") until an association is set. |
| URL direction segment / direction segment | Leading URL path prefix that encodes the product mode | Runtime path shape /{publish|consume}/{environment}/{serviceKey}/{operationPath...} (see docs/lld/naming-and-standards.md §4 + §4.1). Lowercase rendering of s2r_service.direction / s2r_runtime_route.direction (V80 + V81). | Segment is REQUIRED; runtime rejects any path without a valid leading publish / consume with HTTP 400 S2R-RUN-0405. No synonyms (pub, sub, inbound, outbound, in, out) accepted. |
| SOAP Request / SOAP Response | The stored backend-format payload (XML envelope) for a learned example | s2r_f5_learned_example.request_payload / .response_payload (V79). Per-operation Onboarding Routes table (Epic X #17) renders "SOAP Request" / "SOAP Response" buttons that open the payload modal with the stored XML verbatim via GET /admin/v1/operations/{id}/examples?kind=<request|response> (for request-side source=learned) — deterministic, no format heuristic. | Customer phrasing (2026-04-19): "SOAP Request" / "SOAP Response" mean the raw stored XML on F5-learned examples. The per-operation API currently only projects request_payload — SOAP Response button is disabled with a tooltip until a future pass extends /operations/{id}/examples to mirror Epic X #2's loadGoodExamplesForServiceUri projection. |
| REST Request / REST Response | JSON preview computed via POST /admin/v1/soap-to-json/preview from the stored SOAP XML | Same Onboarding Routes table as above. REST buttons send the stored XML through the SOAP-to-JSON preview endpoint and render the JSON side of {format, fault, json} in the payload modal. Empty-JSON handling mirrors Epic X #1 — shows "// (empty — the SOAP Body had no extractable payload root)" rather than a blank pane. | Customer phrasing (2026-04-19): "REST" = the JSON projection operators see in the admin UI; "SOAP" = the XML envelope on the wire. The distinction is the core of Epic X #17 — it replaced two ambiguous "Request" / "Response" buttons whose output flipped between XML (learned) and JSON (WSDL-derived fallback) depending on whether F5 traffic had been ingested yet. |
This section outlines terms related to specific gateway connectors supported by the platform. (source: docs/customer-terminology.md)
| Customer term | Technical term | Where it lives | Caveat |
|---|---|---|---|
| Oracle API Gateway / Oracle OAG / OAG | gateway_type = 'oracle-oag' | V184__oracle_oag_connector.sql seeds the vendor-enable row; OracleOagClient / OracleOagDiscoveryService / OracleOagSyslogConfigService in services/admin-api; parser services/generic-ingest/internal/parser/oracleOag.go; UI sections in connector-instances.html + connectors.html. | Refers to the legacy on-premises Oracle API Gateway product (pre-Oracle APIM), not Oracle API Platform Cloud Service / Oracle APIM. v1 connector shipped 2026-05-24 per customer decision (issue #567). Field-shape validation pending first real OAG appliance (open-item D-18). |
This section details terms specific to configuring the backend for services operating in the "Consume" direction. (source: docs/customer-terminology.md)
| Customer term | Technical term | Where it lives | Caveat |
|---|---|---|---|
| REST Backend | The HTTPS REST service called from the SOAP-facing ingress when a SOAP client posts to /consume/{env}/{serviceKey}/... | s2r_backend_profile.endpoint_url on a CONSUME-direction service; Step 4 "REST Backend" card on the onboarding wizard. | Only the CONSUME direction uses this framing. For PUBLISH the same column carries the SOAP backend URL. |
| Extra Headers | Static headers stacked onto every outbound REST call after the Authorization header | s2r_backend_profile.extra_headers (jsonb, array of {name, value}); Step 4 REST form table. | Epic Q #2 removed the per-header secretRef slot. Secret-bearing headers belong inside s2r_backend_profile.credentials.extraHeaders alongside the other auth material. api_key_header auth mode relies on Extra Headers — the key travels as an operator-defined header like X-API-Key. |
| Client Certificate | PEM cert+key bundle used for mutual TLS on outbound REST calls | s2r_backend_profile.mtls_enabled (boolean) + s2r_backend_profile.credentials.mtls.{certPem,keyPem} (inside the pgcrypto envelope); Step 4 REST form mTLS section. | Epic Q #2 made mTLS orthogonal to identity — the operator can tick mTLS on alongside any auth_type (including oauth2_client_credentials). Missing or unparseable cert material raises S2R-RUN-0420. |
| OAuth2 client credentials | Bearer-token prefetch via the OAuth2 client_credentials grant (RFC 6749 §4.4) for service-to-service outbound REST calls | s2r_backend_profile.oauth2_token_endpoint / oauth2_client_id / oauth2_scope / oauth2_extra_params plus the client_secret inside credentials.oauth2ClientSecret (Epic Q #2); runtime OAuth2TokenService; Step 4 REST form OAuth2 section, visible only when Auth Mode = oauth2_client_credentials. | Token cache is keyed by (token_endpoint, client_id, scope, extra_params) — different services sharing a client share the cached token. Refresh is automatic near expiry (60 s safety margin) and on 401 from the REST backend. When mTLS is also enabled (Epic Q #2a) the same SSLContext is presented on both the token-endpoint fetch AND the REST API call (RFC 8705). password / authorization_code / refresh_token grants are out of scope. |
This section covers terms related to the process of gathering and using evidence for mapping SOAP and REST fields in the "Consume" direction. (source: docs/customer-terminology.md)
| Customer term | Technical term | Where it lives | Caveat |
|---|---|---|---|
| Mapping evidence / Payload example | A persisted SOAP ↔ REST request/response pair that grounds bidirectional mapping synthesis | s2r_mapping_evidence table (migration V86); endpoints POST/GET/DELETE /admin/v1/services/{id}/versions/{vid}/mapping-evidence (+ /{id}). | RFC §E6 / Epic P #23, amendment #9. The source column takes one of two values: f5_traffic (auto-suggested from F5 ingestion — item #24) or manual_upload (operator upload via the multipart or JSON endpoint). Per-row size cap 2 MB (HTTP 413 S2R-VAL-0407). |
| Grounding inputs / four grounding inputs | The four artefacts the Consume flow needs to synthesise a correct mapping: old WSDL + REST OpenAPI + REST backend auth + payload examples (mapping evidence) | WSDL: s2r_wsdl_artifact. OpenAPI: s2r_openapi_import. Auth: s2r_backend_profile. Examples: s2r_mapping_evidence. | RFC §0 amendment #9 locks this set. The Consume wizard (item #26) enforces all four before publish; readiness gate requires ≥1 evidence row per operation. |
| F5 auto-suggest | Operator-reviewed list of candidate SOAP/REST payload pairs drawn from recent F5 traffic for a service version, ranked by match confidence (soap_action 0.9 → vs_match 0.7 → url_match 0.5 → namespace 0.3); confirmation persists picks as source='f5_traffic' mapping-evidence rows. | GET /admin/v1/services/{id}/versions/{vid}/mapping-evidence/f5-candidates (preview) + POST …/f5-candidates:confirm (persist). Sources s2r_f5_request_log; writes s2r_mapping_evidence. | RFC §E6 / Epic P #24, amendment #9. Confirmation is idempotent — re-confirming the same F5 event id silently skips. Out-of-range perOperationLimit / sinceHours return S2R-VAL-0409; a candidate that doesn't match the target service returns S2R-VAL-0408. |
| Mapping synthesis | `Deterministic example-grounded alignment |