Oracle E-Business Suite R12

Status

This connector is installed together with GoRoute and your DBA. It has been on GoRoute's production and test services since 8 November 2026, and on GoRoute's services in Oman since 10 November 2026, with Retry now, Skip and Never send for its documents. The ORDS package has passed its acceptance checks on Oracle Database XE; the connector has not yet been accepted on a real R12.2 instance: see Not proven yet for what that acceptance must show.

The GoRoute connector for Oracle E-Business Suite has two parts, both installed on the client's side:

• The goroute.ebs ORDS package: an integration schema (XXGOROUTE), a PL/SQL package and an Oracle REST Data Services module. It reads completed Receivables transactions and records what happened to each one in a table of its own, XX_GOROUTE_AR_CLEARANCE. It never changes an EBS base table. Its one write into EBS is optional: received supplier invoices go into the Payables open interface, for Payables Open Interface Import.
• The GoRoute EBS agent: a small program on a host the DBA approves. It reads the ORDS module, sends each document to GoRoute as an e-invoice, and writes the outcome back to EBS. It connects out over HTTPS, to ORDS and to GoRoute. Nothing listens on the host, no inbound port is opened, and no VPN is needed.

EBS (Receivables)  ──►  goroute.ebs ORDS  ◄──  GoRoute EBS agent  ──►  GoRoute  ──►  Peppol / tax authority
   XX_GOROUTE_AR_CLEARANCE  ◄── status, reason, transaction id and UUID ──┘

Sites that do not allow ORDS can use Integrated SOA Gateway (ISG) instead. That path is designed but not built. Ask GoRoute before you plan for it.

What the DBA prepares

#	Prerequisite	Why
1	Oracle Database 12.2 or later (19c is the usual one for R12.2)	The package uses JSON_OBJECT and JSON_OBJECT_T
2	ORDS 19.4 or later, reachable from the agent's host over HTTPS	The agent reads EBS only through ORDS
3	A host for the agent: Linux (RHEL/Oracle Linux 8+, Ubuntu 22.04+, Python 3.9+) or Windows Server 2019+	It must reach ORDS and GoRoute over HTTPS (outbound 443)
4	The schema XXGOROUTE (script 00) and the grants (script 01, as APPS)	Read-only on the Receivables, TCA, E-Business Tax and Payables objects the views read
5	Optional: INSERT on AP_INVOICES_INTERFACE and AP_INVOICE_LINES_INTERFACE (the last block of script 01)	The supplier-invoice lane. Leave it out to run Receivables only
6	A Payables Source lookup value GOROUTE (Payables → Setup → Lookups → Source)	Payables Open Interface Import picks up rows by source
7	The customer's Peppol ID in a descriptive flexfield on HZ_CUST_ACCOUNTS, and the supplier's on AP_SUPPLIERS (the column is set in 20_views_r12.sql)	Stock EBS has nowhere to keep it. For Oman it is 0248:OM plus the VAT number
8	One row per operating unit in XX_GOROUTE_SELLER: legal name, VAT number, Peppol ID, address	The seller on each invoice

Install the ORDS package

GoRoute provides the scripts (version 2.0.0). Every script can be run again safely. The table changes only add things: an existing XX_GOROUTE_AR_CLEARANCE keeps its rows and gains columns and status values.

1. As a DBA: 00_dba_create_user.sql (edit the password first).
2. As APPS: 01_apps_grants_r12.sql.
3. Edit the two DEFINEs at the top of 20_views_r12.sql (the flexfield columns for the Peppol IDs) and the alias in 40_ords_module.sql (default goroute_ebs).
4. As XXGOROUTE, from the folder that holds the scripts (they call each other by relative path): install_r12.sql. It runs 02 (synonyms), 10 (tables), 20 (adapter views), 30 (package), 40 (ORDS module) and then 99_verify.sql, which prints one line per check and a last RESULT line. Every line must read OK and the last one RESULT all checks OK. SQL*Plus reports a compilation error only as a Warning and carries on, so read the RESULT line rather than the end of the run.
5. Fill XX_GOROUTE_SELLER, then run 41_ords_client.sql. It creates the agent's OAuth client and prints its id and secret once. ORDS 23.3 and later mark the OAUTH package deprecated in favour of ORDS_SECURITY.register_client and grant_client_role, but it still works: the script ran unchanged on ORDS 26.3 (see the acceptance below).

The module answers at https://<ords-host>/ords/goroute_ebs/goroute/ebs/, and every handler is protected by the privilege goroute.ebs.agent.

Handler	What it does
GET meta	Package version, instance id, counts by status, whether the AP interface is granted
GET ar/pending[?since=]	Documents waiting to be sent. since is in the database's own clock
GET ar/inflight	Documents GoRoute has accepted whose outcome is still to come
GET ar/held	Failed, skipped and never-send documents, with their reasons
GET ar/lookup?trx_number=	A transaction number, resolved to its id and status
GET ar/invoice/:id	One document as nested JSON: header, seller, customer, lines, tax lines, the original invoice of a credit memo
POST ar/clearance/:id	Writes SUBMITTED, CLEARED or FAILED, with the reason, GoRoute transaction id and UUID
POST ar/reset/:id	Retry: FAILED or SKIPPED back to PENDING
POST ar/mark/:id	SKIPPED or NEVER, with a reason that cannot be empty
POST ap/invoices	Puts a received supplier invoice into the Payables open interface
GET ap/invoices/:id	How that went, including the import's outcome
GET ap/needs-supplier	Received invoices waiting for a supplier record

Install and enrol the agent

GoRoute creates the enrolment code with you; there is no portal screen for it. The code is valid for 15 minutes and works once. Developers can create it with POST /api/v1/connectors/{id}/agent/enrolment-codes, which accepts an Oracle EBS connector on the services named in the status note at the top of this page. GoRoute provides the installer. Then:

• Linux: sudo sh packaging/linux/install.sh from the agent package. Then run the enrol command the script prints, giving it the code, the GoRoute API address, the ORDS module URL and the OAuth client id (it asks for the secret). Then run systemctl enable --now goroute-ebs-agent.
• Windows: run GoRouteEbsAgent-Setup.exe as an administrator. The Connect to GoRoute page asks for the same details. The agent runs as SYSTEM from a scheduled task at start-up. Its folder, %ProgramData%\GoRoute\EBS Agent, is readable by SYSTEM and Administrators only.

Enrolment gives the agent a key that belongs to this connector. The key can send and read invoices and transactions, and nothing else: no settings and no connector management. The key is stored in secrets.json, apart from the configuration. No log line ever shows a key, a token or a secret.

With its first heartbeat the agent sends a readiness report. The report gives the EBS release, the ORDS package version and whether ORDS answers. It gives the number of documents waiting and whether the AP interface is granted. It names any operating unit with no seller row. It also checks up to five documents that are waiting against GoRoute's validation, and sends none of them. Read the report before the first real cycle: it is readiness_report (with the time it arrived, readiness_report_at) on GET /api/v1/connectors/{connector_id}, which needs connectors:read or connectors:manage. Or ask GoRoute, who installs the agent with you.

What happens to each document

Every 2 minutes the agent reads the documents waiting, oldest change first. It sends each one to GoRoute as an invoice, credit note or debit note. It then writes the outcome to XX_GOROUTE_AR_CLEARANCE, and the table's history records every change of status with who made it and why.

Status	Meaning	What brings it back
PENDING	Not sent yet (also: no row at all)	—
SUBMITTED	GoRoute accepted it; delivery is under way (the transaction id is recorded)	The agent asks GoRoute each cycle and writes the outcome
CLEARED	Delivered, or issued, or cleared by the tax authority. Transaction id and UUID recorded	Final
FAILED	Refused or not delivered. The reason is GoRoute's own words, with a code and whether it is the customer's to fix in EBS (customer) or GoRoute's (platform)	Edit the transaction in EBS and it is waiting again by itself; or Retry
SKIPPED	A person chose not to send it, with a reason	Edit the transaction in EBS, or Retry
NEVER	Handled outside GoRoute: it will never be sent and never be waiting again	A DBA clears the mark

The agent sends the same invoice only once. Each document goes under the key ebs-<instance id>-<invoice|credit_note|debit_note>-<transaction number>. After a Retry the key gains -g2, -g3 and so on, so that a corrected document is not refused as a reused key. GoRoute's own same-document check still stops a second issue. If the agent stops between sending a document and writing its outcome, the next cycle sends the same request again, and GoRoute answers with the first transaction.

A document the agent cannot turn into an invoice is written back FAILED before anything is sent, with a sentence that says what to fix. For example: a tax rate code not in the mapping table, a unit of measure that is not a UN/ECE code, no seller row for the operating unit, or a line with no tax line. An Omani credit memo whose invoice has not been cleared yet is not failed. It waits on the agent's held list until that invoice has its UUID, and is then sent.

When GoRoute does not answer, the agent stops for that cycle and tries again in the next one. It writes nothing to EBS while it waits. The agent's place in the list moves only past documents that reached a status. Once an hour the agent reads the whole list of documents waiting.

Retry, Skip and Never send

The agent reports its held documents, each with its reason, with every heartbeat: they are agent_status.parked on GET /api/v1/connectors/{connector_id}. Every action needs connectors:manage, travels to the agent with its next heartbeat (normally within a minute), and writes an audit log entry with who did it and why.

• Retry: if GoRoute accepted the document and its delivery failed, the agent asks GoRoute to deliver the same document again, with no second issue. Otherwise (GoRoute refused it, it never got there, or it was skipped) the row goes back to PENDING and the document is sent again at once from what EBS holds now.
• Skip: a reason is required. If the transaction is edited in EBS later, the skip ends and the document is waiting again.
• Never send: a reason is required. Use it for documents handled outside GoRoute.

Through the API, the same routes as every other connector's held documents, with the transaction number as the key (URL-encoded):

Call	Body
POST /api/v1/connectors/{id}/held-invoices/{number}/retry	none
POST /api/v1/connectors/{id}/held-invoices/{number}/skip	{"reason": "…"} (required)
POST /api/v1/connectors/{id}/held-invoices/{number}/never-send	{"reason": "…"} (required)

Add ?document_id=<customer_trx_id> when the same number exists in more than one operating unit. The answer is state: queued with the agent's command. Its status (pending, delivered, done, failed) and detail show how it went. GET /api/v1/connectors/{connector_id} shows them too: unfinished commands in pending_commands and the last 20 finished ones in recent_commands. Or ask GoRoute, who installs the agent with you. 409 AGENT_NOT_ENROLLED before an agent has enrolled. The agent's own command channel, POST /api/v1/connectors/{id}/agent/commands, does not take these three. It answers 400 USE_HELD_INVOICES_ROUTE.

Supplier invoices into Payables

GoRoute receives supplier e-invoices over Peppol. When the AP lane is on ("ap": {"enabled": true, "org_id": <operating unit>} in agent.json, and the interface is granted), the agent puts each one into the Payables open interface. It matches the supplier by Peppol ID, then by VAT number. The interface tables get standard columns only. The GoRoute transaction id and UUID go into two descriptive flexfield attributes, ATTRIBUTE14 and ATTRIBUTE15 by default (set them with AP_TXN_ATTRIBUTE and AP_UUID_ATTRIBUTE in XX_GOROUTE_CONFIG).

Intake status	Meaning
MATCHED	In the interface, waiting for Payables Open Interface Import. GoRoute shows it as draft created
IMPORTED	The import created the invoice. GoRoute shows it as posted, with the Payables invoice id
REJECTED	The import rejected it. The rejection codes are shown on the document in GoRoute
NEEDS_SUPPLIER	No supplier has that Peppol ID or VAT number. Nothing is put in the interface. Create the supplier, and the invoice goes in on the next cycle
NEEDS_PO	The invoice names a purchase order that is not open for that supplier

Tax is calculated during import by default (AP_CALC_TAX_DURING_IMPORT = Y). Set it to N to send the invoice's own tax amount as a TAX line instead.

What is proven, and what acceptance on a real R12.2 must show

Proven, on 7 November 2026:

• The agent's test suite runs against an in-memory copy of the ORDS module and the demo data. A test holds that copy to the SQL scripts: the state machine, the routes, the columns and the JSON keys.
• The platform's own validation and its Oman renderer accept the agent's mapped documents.
• The real agent ran against a GoRoute API started locally on Postgres. It enrolled with a code, checked 5 of 5 documents through the validation endpoint, and sent six documents through POST /invoices. It wrote CLEARED and FAILED with GoRoute's reason. It ran a Retry through GoRoute's retry endpoint. Its held list reached the connector's stored status.

Proven on Oracle XE, 7 November 2026: the SQL itself, on a real database and a real ORDS. See the next section for what it covered and what it did not.

Not proven yet. Acceptance on a real R12.2 instance must show the following:

1. install_demo.sql on Oracle XE 21c with ORDS, and the agent against it: done, see below.
2. On a real R12.2 instance, every join in 20_views_r12.sql against the instance: the bill-to address path, the tax registration source (ZX_PARTY_TAX_PROFILE or JGZZ_FISCAL_CODE), the due date from AR_PAYMENT_SCHEDULES_ALL, one ZX_LINES row per taxed line, the transaction classes, and the flexfield column of the Peppol ID.
3. The site's tax rate codes mapped in agent.json (mapping.tax_categories) and its units of measure (mapping.uom). The readiness report's samples must pass.
4. LAST_UPDATE_DATE behaviour on the instance. A completed transaction that is incompleted, changed and completed again must show up again, and an AutoInvoice batch must be picked up whole (the look-back is 2 hours by default, and an hourly full pass reads everything).
5. The AP lane: a received invoice put in the interface with source GOROUTE, imported by Payables Open Interface Import, and reported posted. A rejection must show its codes.
6. The OAuth client on the site's ORDS version, a token renewal, and the agent running for 24 hours as a service.

Acceptance on Oracle XE, 7 Nov 2026

One throwaway test machine, run for this acceptance and then removed.

What ran: Oracle Database XE 21c (gvenzl/oracle-xe:21-slim) and ORDS 26.3.1 in standalone mode, installed into XEPDB1 with ords install (non-interactive). Then the package exactly as this guide gives it: 00_dba_create_user.sql as SYSTEM, install_demo.sql as XXGOROUTE, 41_ords_client.sql. GoRoute's acceptance harness, run on the machine, then called every route with the agent's own ORDS client over HTTP and ran the real agent against it, with the agent's test double standing in for GoRoute.

Result: 51 checks, all passed (after the four fixes below). In short:

• 99_verify.sql: every line OK. install_demo.sql run a second time on the installed schema: still all OK, so the scripts are safe to re-run.
• OAuth: no token gives 401; a client-credentials token opens every route.
• meta, ar/pending (paged, the draft left out, since=), ar/invoice/:id (the same JSON keys as the agent's fixture, the credit memo's PREVIOUS, 404 for an unknown id), ar/lookup, ar/inflight, ar/held.
• Every transition of the state machine and every refusal: PENDING → SUBMITTED → CLEARED; FAILED with its reason; reset FAILED → PENDING (generation 2); SKIPPED with and without a reason (400); NEVER; reset of NEVER and SUBMITTED-without-force refused (409); CLEARED → FAILED refused with the current status; the 1.x PUT. A FAILED document whose LAST_UPDATE_DATE moves afterwards is pending again with generation 2. The history trigger records each step.
• AP: ap/invoices matches a known supplier and open PO (MATCHED), lands the same document once, answers NEEDS_SUPPLIER and NEEDS_PO; ap/needs-supplier lists them; after the demo's stand-in for the import, ap/invoices/:id reads IMPORTED.
• The agent: one cycle sent four documents (two refused at validation never left), wrote CLEARED (credit memo included, with its original's UUID) and FAILED (a validation refusal and a failed delivery), and reported the three in its heartbeat. A second cycle sent nothing. Then retry_document (reset, sent again under a new idempotency key …-g2, CLEARED), skip_document (SKIPPED, kept in the held list so it can be un-skipped) and never_send_document (NEVER, gone from the list) all ended done, and neither document was sent again. A received supplier invoice was landed, imported and reported posted.
• 20_views_r12.sql parses: all six adapter views compile (FORCE) in a scratch schema, each failing only because the EBS tables are not there.

Fixed on the way, in the scripts and in this guide:

1. 10_tables.sql: the history trigger used CASE WHEN INSERTING inside its INSERT. INSERTING exists only in PL/SQL, so the trigger did not compile (ORA-00920) and no history would have been written.
2. 30_package.sql: a TYPE was declared after the first function bodies; PL/SQL needs every declaration first (PLS-00103), so the package did not compile at all.
3. 99_verify.sql stopped at its first line when the package was invalid, so it named one problem out of several. It now lists every invalid object, keeps going, and ends with a RESULT line; both install scripts point at that line instead of saying "installed" whatever happened (step 4 above).
4. 00_dba_create_user.sql echoed the new schema's password (SQL*Plus VERIFY); it sets VERIFY OFF now.

What XE cannot show (so read the result as no more than this): the demo tables carry R12's names and the columns the views read, but they are not EBS. Nothing here exercised the joins of 20_views_r12.sql against real data (bill-to path, tax registration source, AR_PAYMENT_SCHEDULES_ALL, ZX_LINES, transaction classes, the flexfield), the grants of 01_apps_grants_r12.sql and the synonyms of 02 (there is no APPS schema), EBS's own LAST_UPDATE_DATE behaviour on incomplete/complete and AutoInvoice, the real Payables Open Interface Import and its rejection codes (the demo procedure only imitates it), an EBS multi-org context, ORDS over HTTPS behind the site's proxy, a token renewal after an hour, a real GoRoute, or 24 hours as a service. Items 2 to 6 of the list above stand.