Connectors

A connector is how Liberty Next reaches a data source. Every screen, chart, dashboard, action, job step and assistant answer names the connector and the query — or the endpoint — it uses.

Type	Reaches	Holds
SQL	A database, through a pool.	Named queries, in four kinds: tables, queries, sequences, lookups.
API	A web API (REST, JSON).	Named endpoints: method, path, headers, body, response mapping.

A connector that has a menu is an app — see Apps.

---

At a glance

---

Liberty Next → Build → Connectors

The left list has two groups: Apps (connectors with a menu) and Data sources (the others). ＋ Connector creates one (name, type SQL or API); the right pane edits the selected connector. Save writes connectors.toml and applies the change without a restart; Discard drops the pending changes. The connector's own buttons — Clone (with its dictionary scope, screens, menu, charts and dashboards), Rename (every reference rewritten), Delete (with everything that belongs to it) — are on its settings view.

Pools

A pool is a database connection, defined in Liberty Next → Administer → Pools and shared by the connectors that use it:

Field	Effect
Url	The connection URL (postgresql+asyncpg://user@host:5432/db, oracle+oracledb://user@host:1521/?service_name=…). Picking a Dialect first fills a template. ${VARIABLE} accepted.
Password	Kept out of the URL; encrypted when saved.
Dialect	postgresql, oracle, sqlite, mysql, mssql… — derived from the URL when empty; chooses a query's per-dialect variant.
Schemas, DB Links	The values of the #SCHEMA.<NAME># and #DBLINK.<NAME># tokens — see below.
Pool size, Max overflow, Pool pre ping, Pool recycle	Connections kept open, extra connections under load, liveness check, recycling.
Max rows	Default row limit of the pool's reads (1 000 when empty).
Arraysize	Oracle: rows fetched per round trip; raise it (500–1 000) for large reads.
Trim strings	Removes the trailing spaces of fixed-length text (Oracle CHAR, JD Edwards).
Coalesce nulls	On writes, replaces empty values with a space or 0 (Oracle NOT NULL text columns).
Debug sql	Logs every statement run on the pool.

---

SQL connector

The mode bar of a SQL connector has five views: Settings…, Tables, Queries, Sequences, Lookups. The four query views are described on Queries — overview.

Settings

The Settings mode of a SQL connector (the Settings button of the connector page) holds its connection settings.

Field	Effect
Pool	The pool the queries run on — a dropdown of the pools defined in Liberty Next → Administer → Pools. The connector takes the pool's address, credentials and dialect.
Pools	Extra pools the same queries may run on — see Multi-pool connectors.
Show In Switcher	Shows the connector as an application in the switcher at the top of the sidebar — together with a menu, see Make a connector an app.
Home	The menu entry opened when the application is picked.
Max Rows	Default row limit of a read; otherwise the pool's, then 1 000. A screen's or a request's limit wins.
Dd Prefix	Length of the table prefix in column names (JD Edwards: 2, so ABCO, MCCO and SDCO all carry the dictionary item CO). Used by a role's data scope. 0: column names are the items.

Query editor

Clicking ＋ Add query or an existing query opens the query editor:

Field	Effect
Name	Identifier of the query — used in the URL (/api/sql/billing/<name>) and the permission (sql:billing:<name>).
SQL	The statement, with :name parameters and {{TOKEN}} server values. One text, or one variant per database — see Per-dialect SQL.
Writable	Off: only a SELECT is accepted. On: INSERT / UPDATE / DELETE / CALL / MERGE.
Params	The declared parameters (name, label, default) — see Parameter binding.
Label, Description (Advanced)	Shown in the pickers, and read by the AI assistant to choose its queries.

The SQL editor highlights the syntax, completes table and column names from the pool, and has a Token menu ({{LOGIN}}, {{SYSDATE}}…) and a Pool schemas menu. The editor's buttons — Find usages, Rename, Change type, Move, Clone, Delete — are described on Create a custom query.

Schema and DB-link tokens

A SQL query can carry two placeholder tokens that let the same text run against any pool — local or remote — without maintaining a per-environment variant of the query:

Token	Resolves to	Where it's configured
#SCHEMA.<NAME>#	The pool's mapping for schema <NAME> (e.g. SY920.). Empty when the pool has no entry — the token drops out and the table name is written bare.	Pool settings — the Schemas map on each pool.
#DBLINK.<NAME>#	The pool's DB-link suffix for schema <NAME> (e.g. @ORCLPROD). Appended after the table name, so a #SCHEMA.SY#F0092#DBLINK.SY# resolves to SY920.F0092@ORCLPROD. Empty when no entry — nothing is appended, and the query stays local.	Pool settings — the DB links map on each pool (dblinks = { SY = "@ORCLPROD", … }).

The two are position-independent: #SCHEMA.…# prefixes the table, #DBLINK.…# suffixes it. The same query works locally (both mappings empty), against a remote schema without a link (schema mapped, dblink empty) or via a database link (both mapped) — the pool decides which shape to emit.

A non-empty DB-link value must be a bare @link reference (starts with @, letters, digits, _, $, # and . only). Anything else makes the query fail when it runs — a guard against a DB-link value that would try to smuggle SQL into the statement.

Oracle thick mode

The Oracle driver runs in thin mode by default: no Oracle client needed, every call on the server's event loop. Two cases need the thick mode, which goes through the Oracle Instant Client:

• Native Network Encryption (NNE) required by the database — thin mode fails with DPY-3001;
• reading a LOB across a database link — thin mode fails with ORA-22992 / ORA-03149.

Tick Oracle thick mode in Liberty Next → Administer → App (section App) and restart the server: every Oracle pool then runs in thick mode — the setting applies to the whole server, not to one pool. PostgreSQL pools are not affected. The Instant Client is included in the Docker image (amd64 and arm64); a Python install needs it on the host.

---

Multi-pool connectors

One SQL connector can serve several pools — several database or JDE instances — without cloning the connector or duplicating its screens. Alongside the default Pool, list the extra ones in Pools (both are dropdowns of configured pools in the connector's Settings mode); the same named queries and the same screens then run against any pool in the set.

The pool is chosen at runtime:

• In the app — when the current app spans a multi-pool connector, a Pool picker appears in the sidebar, under the application picker (Default is the connector's own pool). Picking a pool re-runs that app's screens against the chosen instance. The choice is kept per app in the browser, and it applies only to the connectors that declare that pool — an app's other (single-pool) connectors keep their default rather than erroring.
• In jobs — a sql_copy step takes pool in its source or target block, a sql_query step takes pool, to target a specific instance without a new connector (steps). These keys are set in jobs.toml; the step editor does not show them.

The reachable set is the default pool plus pools; a request or a job can never reach a pool outside it, and only pool names reach the picker — never a URL or credentials. A connector with just a pool behaves exactly as before.

An API connector called from those screens — AIS, for JD Edwards — can follow the same environments: see One server per environment.

---

API connector

An API connector calls a web API. Its editor has six tabs:

Tab	Content
Connection	Base URL (https://api.example.com, ${VARIABLE} accepted), Default headers, Timeout, SSL Verify (true, false, or a variable such as ${JDE_AIS_VERIFY_SSL:-true}, kept as written), Show in switcher, Home.
Authentication	Auth type: None, Basic (user and password), Bearer (static token), API Key (header name and key), OAuth2 / JWT (token endpoint, request body and headers, token field, token lifetime). Secrets are encrypted when saved.
Environments	One server per environment, for a connector used with several JDE environments — see One server per environment.
Endpoints	The named endpoints — see below.
Webhooks	Not available yet: external systems cannot push events into Liberty Next.
Test	Test connection checks the authentication; Run calls an endpoint with parameter values and shows the response. Nothing is saved.

An endpoint has:

Field	Effect
Name	Used in the URL (/api/http/<connector>/<name>) and the permission (api:<connector>:<name>).
Method, URL path	GET, POST, PUT, PATCH, DELETE…; the path is appended to the base URL (an absolute URL bypasses it).
Headers, Query params	Added to the connector's; values accept {{placeholders}}.
Body template, Body Content-Type	The request body, with {{placeholders}}.
Response field, Response mappings	A dot path into the JSON response (data.0.id), or several named paths; blank returns the whole response.
Parameters	The declared {{placeholders}}, with label and default.
Label, Description	Shown in the pickers and to the AI assistant.

Endpoints are called by screen actions (call_api), menu entries (type endpoint), notification rules (action channel), plugins (connectors.api(…).call(…)) and — when allowed — the AI assistant. A Nomaflow http step calls a URL directly, without a connector.

One server per environment

When the screens run on a multi-pool connector — several JD Edwards environments — each environment usually has its own AIS server. The Environments tab gives the API connector one server per environment; the endpoints stay defined once.

Field	Effect
Environment (pool)	The environment (pool) of the connector's own server — its Base URL and credentials. Required as soon as there is another environment.
Other environments	One entry per other pool: Base URL, Username, Password, Token, SSL Verify. A blank field takes the connector's value. Passwords and tokens are encrypted when saved.

Nobody chooses the server. A call follows the environment the screen runs on — the Pool picked in the sidebar, or the default — and a job step's pool (any step type). That covers screen actions (call_api), plugins, /api/http and the AI assistant.

A call made for one of the connector's environments with no server is refused ("no target for pool …"); it is never sent to the connector's own server, which is another environment — often production. The environments are the connector's pool plus every pool of the SQL connectors running on it, so a JDE environment added on the SQL side and forgotten here is refused too. The tab lists those environments without a server, and so does Settings → Integrity.

[connectors.ais_connection]
base_url = "${JDE_AIS_URL}"
pool = "jdedwards"                          # the environment of base_url

[connectors.ais_connection.targets.jdedwards_dev]
base_url = "https://ais-dev.example.com:7077/jderest/v2"
auth_password = "ENC:…"                     # only what differs

To name the environment before a sensitive call, use #POOL# in a confirm message: Reset the password of {INPUT.user} on #POOL#?. An upgrade of the licensed apps keeps an install's pool and targets.

---

Schema discovery and column hints

A query has no declared column list: the columns are those the database returns when it runs. How a column looks on a screen is decided, in this order, by:

1. the column settings of the screen (Columns tab) — label, format, width, rule, conditions;
2. the dictionary entry whose key is the column's name, or the one named in the column's dd field — label per language, format, rule (Boolean, enum, lookup…);
3. otherwise the column's name and the default display for its type.

A column does not need a setting of its own: a dictionary entry with its name is enough. See Dictionary and Screens → Columns.

---

Permissions

Each query and each endpoint has its own permission:

Permission	Allows
sql:<connector>:<query>	Running the query — read or write alike.
api:<connector>:<endpoint>	Calling the endpoint.

They are granted through roles: allowing a menu entry grants what it opens, and Beyond the menus grants a query, an endpoint or a whole connector — patterns such as sql:billing:report_* are accepted. See Roles & permissions.

---

Tips

• Name queries after the entity — invoices_get, invoices_by_status_get — the lists read themselves.
• Describe the queries the AI assistant should use: label and description (Advanced tab).
• Prefer the dictionary to per-screen labels: one entry serves every screen.
• Keep secrets out of the files with ${VARIABLE} references when a secrets manager is used — see Encryption & secrets.

---

Under the hood

Connectors and pools are stored in connectors.toml, in the apps configuration folder. The Liberty Next pages are the normal way to edit them; the same configuration is reachable through the REST API under /admin/config/connectors — see REST API.

---

What's next

• Queries — overview — the four kinds of queries and their editors.
• Dictionary — labels, formats and lists of values of the columns.
• Parameter binding — parameters, built-ins and tokens.
• Screens — grids and dialogs on the queries.