> 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-integrations/jd-edwards-integration-setup/running-the-agent.md).

# Running the agent

Run modes, what one extraction cycle does, verification, updates and write-back

### Running modes <a href="#running-modes" id="running-modes"></a>

The same binary supports several run modes:

| Flag                                        | Mode                                                                      |
| ------------------------------------------- | ------------------------------------------------------------------------- |
| *(none, in a terminal)*                     | Opens the dashboard TUI. Non-interactive → headless service               |
| `--tui`                                     | Dashboard TUI: status, test, run, reconfigure, live log pane              |
| `--configure`                               | Setup form on its own. Verifies the connection before it saves            |
| `--test-connection`                         | Probe the JD Edwards connection and exit                                  |
| `--dry-run --output <dir>`                  | Extract to CSVs locally; upload nothing                                   |
| `--headless`                                | Run the heartbeat loop in the foreground. This is what the service starts |
| `--check-ais`                               | Probe the AIS server and print the write-back readiness table             |
| `--plan`                                    | Run one dry-run write-back cycle and print what would be sent             |
| `--check-update`                            | Report whether a newer release exists, then exit                          |
| `--install-service` / `--uninstall-service` | Register / remove the operating-system service                            |
| `--config <path>`                           | Use a specific configuration file                                         |
| `--version`                                 | Print the version and exit                                                |

The one-shot diagnostics (`--test-connection`, `--dry-run`, `--check-ais`, `--plan`, `--check-update`) write nothing to JD Edwards and upload nothing to BalkanID.

***

### I. Using the TUI (Terminal User Interface) <a href="#using-the-tui-terminal-user-interface" id="using-the-tui-terminal-user-interface"></a>

**Launch it:**

```sh
balkanid-jde-agent --tui
```

```powershell
& "C:\Program Files\BalkanID\jde-agent\balkanid-jde-agent.exe" --tui
```

The dashboard shows connection status for the selected instance, a live log pane, and a menu: **Test connection**, **Run extraction now** (a full extraction into its own staging directory), **Dry run to a directory**, **Reconfigure** and **Quit**.

**Keys:** arrow keys or `j` / `k` to move, `Enter` to select, `Tab` to switch which JD Edwards instance the actions target, `q` or `Ctrl+C` to quit.

Nothing in the TUI uploads to BalkanID, and the TUI does not check for or apply updates. To make a delivery happen now, restart the service. The first cycle runs immediately on start.

The TUI runs as your interactive account. If the instance uses `auth_mode: windows`, a successful connection test here says nothing about the service, which runs as the service account. Test both.

***

### II. Running as a service (headless) <a href="#running-as-a-service-headless" id="running-as-a-service-headless"></a>

**Linux:**

```sh
sudo systemctl enable --now balkanid-jde-agent
systemctl status balkanid-jde-agent
journalctl -u balkanid-jde-agent -f
```

**Windows:**

```powershell
Start-Service BalkanIDJDEAgent
Get-Service BalkanIDJDEAgent
Get-Content "C:\ProgramData\BalkanID\jde-agent\logs\<today>.log" -Tail 50 -Wait
```

**Service behaviour:**

* Runs headless with no UI, and starts on boot.
* Extracts and uploads every 2 hours (`server.extraction_interval`). The first cycle runs immediately on start.
* Writes to journald or the Windows Event Log, plus per-day files (`YYYY-MM-DD.log`) under `/var/log/balkanid/` or `C:\ProgramData\BalkanID\jde-agent\logs\`.
* On Linux, runs as the unprivileged `balkanid` user under a hardened systemd unit.
* A cycle that produces zero entities is not uploaded.
* If the previous cycle is still running when the next interval elapses, that tick is skipped rather than queued.
* Each cycle carries a deadline of 80% of the interval. A cycle that hits it is abandoned and the next tick starts fresh.
* With `server.heartbeat_mode: false` the process idles instead of exiting, and logs `heartbeat mode is disabled, skipping this cycle` on every tick.

**Each cycle:**

Every step is started by the agent. The database and BalkanID only answer.

```mermaid
sequenceDiagram
  participant A as Agent
  participant J as JD Edwards database
  participant B as BalkanID
  Note over A,B: Every message runs on a connection the agent opened.<br/>Nothing connects to the agent.
  Note over A: A tick is skipped while the<br/>previous cycle is still running
  A->>J: Connect, read the catalog for the schema owners
  J-->>A: Owners
  A->>J: Read the required tables, then the optional ones
  J-->>A: Rows
  A->>A: Resolve effective access, then insights and SoD
  A->>A: Write entities.csv and entity_relations.csv
  Note over A,B: Zero entities: nothing is uploaded<br/>and the cycle ends here
  A->>B: Request an upload URL
  B-->>A: Presigned URL
  A->>B: PUT the zipped bundle
  Note over A: Sleep until the next interval
```

1. Connects to each instance read-only and resolves the schema owners from the database catalog.
2. Reads the required tables, `F0092` users and roles and `F95921` role assignments, then the optional ones: the Security Workbench, environments and environment grants, the object catalogue and the enrichment tables.
3. Resolves effective access through the user → role → `*PUBLIC` chain, then derives the [insights and the Segregation of Duties matrix](/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/jd-edwards-integration-setup.md#insights-and-segregation-of-duties).
4. Writes `entities.csv` and `entity_relations.csv` to the output directory.
5. Requests an upload URL from BalkanID.
6. Uploads the zipped bundle to that URL, and logs `heartbeat cycle complete`.
7. Sleeps until the next interval.

***

### Verifying without uploading <a href="#verifying-without-uploading" id="verifying-without-uploading"></a>

```sh
balkanid-jde-agent --test-connection
```

Prints the resolved schema owners, the EnterpriseOne release read from `F00942`, visible row counts (`F0092` users and roles, `F0094` environments, `F00950` security records), and any optional table the database account cannot read. `F00950` returning 0 rows is reported explicitly. Confirm the `SELECT` grant before accepting it.

```sh
balkanid-jde-agent --dry-run --output ./out
```

```powershell
& "C:\Program Files\BalkanID\jde-agent\balkanid-jde-agent.exe" --dry-run --output .\out
```

Runs the whole pipeline and writes `entities.csv` and `entity_relations.csv` to the directory. Nothing is uploaded. Exclude the correlation id and timestamp columns before comparing two runs.

***

### Automatic updates <a href="#automatic-updates" id="automatic-updates"></a>

| Mode                   | Checks                       | Applies                       |
| ---------------------- | ---------------------------- | ----------------------------- |
| **Service / headless** | On start, then every 2 hours | Windows **yes**, Linux **no** |
| **Dashboard TUI**      | No                           | Never                         |
| **`--check-update`**   | Once                         | Never                         |

On Windows the agent downloads the new binary, verifies its `sha256`, swaps it in and relaunches in the same run mode. A `.old` file may briefly remain beside the executable and is cleaned up on the next start.

On Linux the agent reports that a release is available and installs nothing. Re-run the installer to update; configuration, state and logs are untouched:

```sh
curl -fsSL https://cdn.balkanid.app/files/balkanid/jd-edwards-agent/releases/latest/install.sh | sudo sh
balkanid-jde-agent --version && sudo systemctl status balkanid-jde-agent
```

***

### Provisioning (write-back) <a href="#provisioning-write-back" id="provisioning-write-back"></a>

Provisioning applies approved BalkanID access changes back into EnterpriseOne. It is **disabled by default**.

* Changes go through **AIS (Application Interface Services) and Orchestrator**. The agent never writes to the JD Edwards database.
* **You author the orchestrations** in Orchestrator Studio and name them in `config.yaml`, along with their input names and date format. The agent ships none.
* The EnterpriseOne service account needs Security Workbench authorization to the applications the orchestration drives. Orchestrator runs as that user.
* The supported operations are `grant_role`, `grant_environment` and `revoke_environment`. Any other operation is refused.
* **Removing a role from a user is not supported.** The request is closed as requiring manual application: expire the assignment in P95921, then re-extract.

All three of these settings must change before any request can be sent:

```yaml
server:
  provisioning_enabled: false   # off
  provisioning:
    mode: dry-run               # dry-run | enforce; anything else resolves to dry-run
    allowed_operations: []      # empty permits nothing
```

Every attempt, including refusals, no-ops and dry runs, appends one line to `provisioning-audit.jsonl` in the agent's state directory (`/var/lib/balkanid/jde-agent/` on Linux, `C:\ProgramData\BalkanID\jde-agent\` on Windows).

**Check readiness before enabling anything:**

```sh
balkanid-jde-agent --check-ais
balkanid-jde-agent --plan
```

`--check-ais` prints endpoint reachability, transport, the session, the orchestrations it could confirm and their declared inputs, plus the mode, the effective allowlist and anything still missing. It exits non-zero while any check is unresolved. `--plan` runs one dry-run write-back cycle and prints the exact request body that would have been sent. Neither sends anything.


---

# 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-integrations/jd-edwards-integration-setup/running-the-agent.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.