> For the complete documentation index, see [llms.txt](https://docs.balkan.id/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.balkan.id/getting-started/setting-up-your-tenant/application-integrations/direct-application-integration/oracle-e-business-suite-integration-setup/installation-and-configuration.md).

# Installation & Configuration

### Requirements

* **Oracle E-Business Suite R12.2** (works across R12.x; reads via `APPS` editioning views).
* Network reachability from the agent host to the EBS DB listener (default TCP `1521`, or `2484` for TCPS) and outbound HTTPS (`443`).
* A read-only Oracle account (see below).
* BalkanID tenant credentials (`tenant_key`, `tenant_secret`) and an installed `oracle-ebs` integration on the tenant.
* A Linux (systemd) or Windows host.

***

#### Required database privileges

Create a dedicated, read-only account.

```sql
CREATE USER balkanid_ro IDENTIFIED BY "<strong-password>";
GRANT CREATE SESSION TO balkanid_ro;

-- Required:
GRANT SELECT ON apps.fnd_user                      TO balkanid_ro;
GRANT SELECT ON apps.fnd_responsibility_vl         TO balkanid_ro;
GRANT SELECT ON apps.fnd_application_vl            TO balkanid_ro;
GRANT SELECT ON apps.fnd_user_resp_groups_direct   TO balkanid_ro;
GRANT SELECT ON apps.fnd_user_resp_groups_indirect TO balkanid_ro;

-- Recommended (reliable last-login; falls back to FND_USER.LAST_LOGON_DATE):
GRANT SELECT ON apps.fnd_logins                    TO balkanid_ro;

-- Recommended (FND_INIT_SQL session-SQL insight; skipped if not granted):
GRANT SELECT ON apps.fnd_profile_options           TO balkanid_ro;
GRANT SELECT ON apps.fnd_profile_option_values     TO balkanid_ro;

-- Optional (enriches users with full name / employee number; degrades gracefully):
GRANT SELECT ON apps.per_all_people_f              TO balkanid_ro;
```

If your read account uses a schema other than `APPS`, set `schema:` in the config accordingly; the value is validated against `^[A-Za-z0-9_$#]{1,30}$` before use.

Verify from the agent host: `balkanid-ebs-agent --test-connection` pings the database, runs `SELECT 1 FROM DUAL`, and reports the visible `FND_USER` count.

### Installation

You can install the EBS Agent by using the following steps:

#### Linux (systemd)

```sh
curl -fsSL https://d3g543zyzzpcxb.cloudfront.net/files/balkanid/ebs-agent/latest/install.sh | sudo sh
sudo balkanid-ebs-agent --configure      # enter tenant keys + DB connection
sudo systemctl enable --now balkanid-ebs-agent
```

The installer creates a dedicated `balkanid` service user, drops the static binary in `/usr/local/bin`, and registers + starts the hardened systemd unit.

| Path   | Location                                                                                         |
| ------ | ------------------------------------------------------------------------------------------------ |
| Binary | `/usr/local/bin/balkanid-ebs-agent`                                                              |
| Config | `/etc/balkanid/ebs-agent/config.yaml`                                                            |
| Output | `/var/lib/balkanid/ebs-agent/`                                                                   |
| Logs   | journald (`journalctl -u balkanid-ebs-agent`) + per-day files `/var/log/balkanid/YYYY-MM-DD.log` |

#### Windows (service)

From an **elevated PowerShell**:

```powershell
Invoke-WebRequest -Uri "https://d3g543zyzzpcxb.cloudfront.net/files/balkanid/ebs-agent/latest/install.ps1" -OutFile "C:\temp\install.ps1"
.\install.ps1
& "C:\Program Files\BalkanID\ebs-agent\balkanid-ebs-agent.exe" --configure
Get-Service BalkanIDEBSAgent
```

| Path    | Location                                                              |
| ------- | --------------------------------------------------------------------- |
| Binary  | `C:\Program Files\BalkanID\ebs-agent\balkanid-ebs-agent.exe`          |
| Config  | `C:\ProgramData\BalkanID\ebs-agent\config.yaml`                       |
| Logs    | per-day files `C:\ProgramData\BalkanID\ebs-agent\logs\YYYY-MM-DD.log` |
| Service | `BalkanIDEBSAgent` (auto-start, LocalSystem)                          |

### Configuration

The agent resolves its config path in this order: the `BALKAN_CONFIG_PATH` environment variable; then by platform — Linux root `/etc/balkanid/ebs-agent/config.yaml`, Linux non-root `~/.config/balkan-cli/config.yaml`, Windows `C:\ProgramData\BalkanID\ebs-agent\config.yaml`. Override with `--config <path>`.

The easiest way to configure is the **wizard** (`--configure`), which prompts for the EBS connection and BalkanID credentials, runs a live **Test Connection**, and writes `config.yaml` only on success. Get the tenant ID/key/secret and integration ID from your BalkanID administrator (Integrations → Add Integration → Oracle E-Business Suite).

A complete `config.yaml`:

```yaml
server:
  heartbeat_mode: true          # run the periodic extract-and-upload loop
  provisioning_enabled: false

ebs:
  instances:
    - name: prod-ebs            # logical name; becomes the source system on rows
      host: ebs-db.internal.example.com
      port: 1521                # 1521 for TCP, 2484 for TCPS
      service_name: VIS         # Oracle SERVICE_NAME (or set `sid:` instead)
      db_username: BALKANID_RO  # dedicated read-only account
      db_password: "CHANGE_ME"
      schema: APPS              # owner of the FND_* views (default APPS)
      version: "12.2"           # target EBS release
      # use_tls: true           # connect over Oracle TCPS (encrypted)
      # wallet_path: ""         # Oracle wallet dir with the TLS trust anchors
    # Add more instances here; each is extracted and merged into one upload.

auth:
  tenant_id: "01xxx"
  tenant_key: ""                # from the BalkanID platform
  tenant_secret: ""             # from the BalkanID platform
  integration_id: ""            # optional; resolved automatically if empty
```

**Connecting over TLS (optional).** For an encrypted DB connection (Oracle TCPS), set `use_tls: true` and point `wallet_path` at an Oracle wallet directory holding the trust anchors. Server-certificate verification stays on. Most on-prem EBS deployments use plain TCP on `1521`, in which case leave both unset.

***

### Running the agent

The same binary supports several run modes:

| Flag                                        | Mode                                                             |
| ------------------------------------------- | ---------------------------------------------------------------- |
| *(none, in a TTY)*                          | Opens the dashboard TUI. Non-interactive → headless service.     |
| `--configure`                               | Interactive setup form with a live Test Connection, then saves.  |
| `--tui`                                     | Dashboard TUI (status, configure, test, run, live logs).         |
| `--headless`                                | Run the heartbeat loop in the foreground (used by the services). |
| `--test-connection`                         | Verify the EBS connection and exit (prints visible user count).  |
| `--dry-run --output <dir>`                  | Extract to CSVs locally; do **not** upload.                      |
| `--install-service` / `--uninstall-service` | Register / remove the OS service.                                |
| `--config <path>`                           | Use a specific config file.                                      |
| `--version`                                 | Print version and exit.                                          |

In service mode the agent runs **headless**: no UI, starts on boot, extracts every 2 hours, and writes **per-day log files** (`YYYY-MM-DD.log`). The first cycle runs immediately on start.

**Verify without uploading.** `balkanid-ebs-agent --dry-run --output ./out` writes `entities.csv` and `entity_relations.csv` locally and uploads nothing — useful for inspection or CI.

A healthy cycle logs the fetched and emitted counts and `heartbeat cycle complete`:

```
level=info msg="instance \"<your-instance>\": fetched 4213 users, 612 responsibilities, 9871 assignments"
level=info msg="instance \"<your-instance>\": emitted 4836 entities (11 insights), 10128 relations"
level=info msg="uploaded entities+relations bundle"
level=info msg="heartbeat cycle complete"
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.balkan.id/getting-started/setting-up-your-tenant/application-integrations/direct-application-integration/oracle-e-business-suite-integration-setup/installation-and-configuration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.