Reports JavaScript methods

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. 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:

{
  "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 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 — HTTP requests, authentication, and session handling.
Agent.Things.js — concentrator queries, parameter submission, and asynchronous result assembly.
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:

<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:

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

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.

["Client Reports\\Monthly usage.rpx"]

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 normalizes both shapes.

Fetch a parameter form

Use a report ID from discovery:

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.

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. This example continues with the fetched form and an illustrative Month parameter:

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.

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, which can contain repeated <value> elements.

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 for the returned fields.

Method signatures

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.

Build an application

Verified identity

Sign-in and signatures

Contracts and agreements

Tokens and digital assets

Wallets and payments

Other application tasks

Reports

Endpoints used by the browser helpers

Load the Neuron libraries

List report IDs

Fetch a parameter form

Submit values and await completion

Method signatures

​Endpoints used by the browser helpers

​Load the Neuron libraries

​List report IDs

​Fetch a parameter form

​Submit values and await completion

​Method signatures

Endpoints used by the browser helpers

Load the Neuron libraries

List report IDs

Fetch a parameter form

Submit values and await completion

Method signatures