> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuro-tech.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Reports JavaScript methods

> Use GetReports, GetReportParameters, and ExecuteReport and understand their return values.

The JavaScript files served by a Neuron expose three Reports methods.
They resolve the report target, build concentrator requests, and, for execution, assemble asynchronous progress into a result object.

For a shared credential integration, use the [backend quickstart](/reports/quickstart).
The browser helpers keep the Agent API session in browser storage; use them only where an individual user's browser session is appropriate.
Do not embed your shared client account's password or JWT in a public page.

## Endpoints used by the browser helpers

The helpers send requests to `https://<NEURON_HOST>`. These are the endpoints you should see in the browser's network inspector:

| Helper or action                | Network request                         | Purpose                                                                 |
| ------------------------------- | --------------------------------------- | ----------------------------------------------------------------------- |
| `Account.Login()`               | `POST /Agent/Account/Login`             | Sign in and retain the returned JWT for later calls.                    |
| Resolve a bare Reports JID      | `POST /Agent/Xmpp/PresenceProbe`        | Find the target's current full JID before a report query.               |
| `Reports.GetReports()`          | `POST /Agent/Xmpp/InformationQuery`     | Send `getAllNodes` with source `Reports`.                               |
| `Reports.GetReportParameters()` | `POST /Agent/Xmpp/InformationQuery`     | Send `getCommandParameters` with the report ID and command `Execute`.   |
| Register report progress        | `POST /Agent/Xmpp/RegisterEventHandler` | Register `queryProgress` delivery to the browser tab before execution.  |
| `Reports.ExecuteReport()`       | `POST /Agent/Xmpp/InformationQuery`     | Send `executeNodeQuery` with submitted fields and a generated query ID. |
| Receive completion              | `wss://<NEURON_HOST>/ClientEventsWS`    | Deliver asynchronous progress to `Events.js` on an HTTPS page.          |
| `Account.Logout()`              | `POST /Agent/Account/Logout`            | End the session.                                                        |

`ExecuteReport()` manages registration and result assembly. Its event registration uses this JSON body, with the actual tab ID supplied by `Events.js`:

```json theme={null}
{
  "localName": "queryProgress",
  "namespace": "urn:nf:iot:concentrator:1.0",
  "type": "",
  "function": "AgentAPI.Things.Concentrator.QueryProgress.OnQueryProgress",
  "tabId": "<EVENTS_TAB_ID>"
}
```

The helper makes this request for you. Loading the scripts alone does not establish an authenticated session or prove that progress is arriving.
An accepted execution request followed by a completed result confirms the full flow.
Use the [HTTP execution guide](/reports/execute-over-http) for backend polling with `PopMessages`; matching browser handlers divert progress from that queue.

## Load the Neuron libraries

Read the JavaScript source served by the lab Neuron:

* [Agent.js](https://lab.tagroot.io/Agent.js) — HTTP requests, authentication, and session handling.
* [Agent.Things.js](https://lab.tagroot.io/Agent.Things.js) — concentrator queries, parameter submission, and asynchronous result assembly.
* [Agent.Reports.js](https://lab.tagroot.io/Agent.Reports.js) — the `GetReports`, `GetReportParameters`, and `ExecuteReport` methods.

These links provide reference implementations from `lab.tagroot.io`. For your application, use the files served by your provider's Neuron so they match its build.

In a browser integration, load these files from the same Neuron build:

```html theme={null}
<meta name="NEURON" content="neuron.example.com" />
<script src="https://neuron.example.com/Agent.js"></script>
<script src="https://neuron.example.com/Agent.Things.js"></script>
<script src="https://neuron.example.com/Agent.Reports.js"></script>
<script src="https://neuron.example.com/Events.js"></script>
```

After the scripts load, set the host and sign in with credentials entered by the individual user:

```javascript theme={null}
AgentAPI.IO.SetHost("neuron.example.com", true);
await AgentAPI.Account.Login(userName, password, 3600);
```

`userName` and `password` are runtime inputs from your sign-in form. Clear the password input after login.
The helper generates the nonce and signature, calls `/Agent/Account/Login`, and stores the returned session JWT for subsequent calls.
The `NEURON` metadata tells `Events.js` where to receive events when your page uses another origin.
Your provider must allow your application's origin for Agent API and Events access.
Use a browser referrer policy that sends the application origin so Agent API requests include the required `Referer` header.
An HTTPS page needs HTTPS scripts/API requests and WSS Events; `Events.js` selects `ws://` when the page itself uses HTTP.

`Events.js` is needed for the execution helper to receive progress and settle its promise.
Discovery and parameter retrieval do not require asynchronous events.

## List report IDs

```javascript theme={null}
const jid = "reports@neuron.example.com";
const language = "en";
const reportIds = await AgentAPI.Reports.GetReports(jid, language);
```

Returns a string array containing visible executable leaf report IDs. It filters out nodes without a parent, nodes without commands, and nodes with children.
It does not return report contents or execute a report.

```json theme={null}
["Client Reports\\Monthly usage.rpx"]
```

<Note>
  The current helper expects the underlying node list to be an array. If the server returns a single node object,
  the helper can return an empty list. The [backend discovery sample](/reports/quickstart) normalizes both shapes.
</Note>

## Fetch a parameter form

Use a report ID from discovery:

```javascript theme={null}
const reportId = "Client Reports\\Monthly usage.rpx";
const form = await AgentAPI.Reports.GetReportParameters(jid, language, reportId);
```

Returns the form from `Stanza.x`, or `[]` when no `x` element is returned.
Check for a valid form before execution. Normalize a single `field` object to an array when using the current execution helper.
See [parameter forms](/reports/responses#parameter-forms).

## Submit values and await completion

Each `ExecuteReport` call starts report execution. For dashboards, use a shared backend job and cached results rather than calling it on every page load.
See [dashboard refresh policies](/reports/dashboard-integration#choose-a-refresh-policy).

This example continues with the fetched form and an illustrative `Month` parameter:

```javascript theme={null}
if (!form || Array.isArray(form) || form.__name !== "x") {
  throw new Error("The report did not return a parameter form.");
}
const parameters = structuredClone(form);
parameters.field = parameters.field == null
  ? []
  : Array.isArray(parameters.field) ? parameters.field : [parameters.field];
const month = parameters.field.find(field => field.var === "Month");
if (!month) throw new Error("This report does not define a Month parameter.");
month.value = { value: "2026-08" };

const result = await AgentAPI.Reports.ExecuteReport(
  jid, language, reportId, parameters
);
if (!result.Done || result.HasErrors || result.Errors.length > 0) {
  throw new Error("The report did not complete successfully.");
}
for (const table of Object.values(result.Tables)) {
  console.log(table.Name, table.Columns, table.Records);
}
```

Replace the field name and value with those defined by your report. Preserve hidden fields and defaults unless you intend to change them.
Treat report messages as part of result validation as well; the helper's `HasErrors` does not classify every message level.

<Note>
  The current helper serializes one nested string value per field (`field.value.value`).
  Use strings such as `"0"` and `"false"`, not JavaScript numbers or booleans.
  Multi-value fields require the [HTTP submit form](/reports/execute-over-http#submit-the-report), which can contain repeated `<value>` elements.
</Note>

The promise resolves after `queryDone` or `queryAborted`; an abort can resolve with `HasErrors: true` instead of rejecting.
Transport or command errors can reject the promise. Add an application deadline because missing events can leave it pending.
A local deadline does not cancel execution on the server.

See [assembled results](/reports/responses#assembled-javascript-results) for the returned fields.

## Method signatures

```javascript theme={null}
AgentAPI.Reports.GetReports(JID, Language, DeviceToken, ServiceToken, UserToken)
AgentAPI.Reports.GetReportParameters(JID, Language, Report, DeviceToken, ServiceToken, UserToken)
AgentAPI.Reports.ExecuteReport(JID, Language, Report, Parameters, DeviceToken, ServiceToken, UserToken)
```

The last three arguments are optional device, service, and user tokens for deployments that require them.
They are separate from the JWT used to authenticate HTTP requests. Leave them omitted unless your provider supplies them.

You can resolve a bare target once with `AgentAPI.Things.XmppHelper.GetFullJid(jid, false)` and use the full JID for subsequent calls.
Resolve it again if the target reconnects. The helpers otherwise probe bare JIDs when needed.

When the user signs out, call `await AgentAPI.Account.Logout()` to end the session.