# GUI automation

The GUI automation API consist of a set of JavaScript functions which enables programmatic access to some features normally controlled by a user in the GUI. These functions are grouped in a global `window.Exivity` object.

## `session`

Control the current user session.

### `.login`

`function(string username, string password): void`\
Attempts to login given the username and password.

### `.logout`

`function(): void`\
Logs out the current user, and cleans up local storage used by the current session.

### `.refreshToken`

`function(string token): void`\
Attempts to use the given token to login (always refreshes the given token).

### `.apiRoot`

`function(string root): void`\
Set the domain (e.g. `https://example.com:8002`) for the Exivity API.

## `navigate`

Navigate the GUI.

### `.home`

`function(): void`\
Navigate to the root URL of the Exivity instance, which is the Dashboard if a user is currently logged in, or the login page otherwise.

### `.to`

`function(string path): void`\
Navigates to the given URL fragment.

## `report`

Control the report filters and more.

### `.byId`

`function(int id): void`\
Select a report definition.

### `.depth`

`function(int depth): void`\
Select a reporting depth.

### `.daterangeStart`

`function(string start): void`\
Select a the reporting start date, in *YYYYMMDD* format.

### `.daterangeEnd`

`function(string end): void`\
Select a the reporting end date, in *YYYYMMDD* format.

### `.filterAccount`

`function(int id): void`\
Filter the report by showing only this account.

### `.showSingleAccount`

`function(bool show = true): void`\
On the summary report, show only the single account set with [`filterAccount`](/3.5.4/advanced/integrate/gui-automation.md#filteraccount).

### `.showAllSummaries`

`function(bool show = true): void`\
Show all summaries if on the `/reports/summary` page.

### `.showConsolidatedSummaries`

`function(bool show = true): void`\
Show consolidated summary on the `/reports/summary` page.

### `.showSummaryAccounts`

`function(bool show = true): void`\
Show accounts on summary report.

### `.showSummaryServices`

`function(bool show = true): void`\
Show services on summary report.

### `.showSummaryInstances`

`function(bool show = true): void`\
Show instances on summary report.

### `.summaryGroupInstanceBy`

`function(string key): void`\
Group the instances on the summary report by this key. The `key` argument should be one of: `instances`, `services`.

## `wait`

Functions returning a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises) to make it easier to determine the state of the GUI.

### `.ms`

`function(int|float ms): Promise`\
Wait for *ms* and then resolve the returned promise.

### `.networkIdle`

`function(int waitBefore = 100, int waitAfter = 100, int timeout = 60000): Promise`\
Wait for the network stack to become idle, optionally specifying:

* A timeout before starting to detect network traffic
* A timeout after detecting that the network became idle
* A timeout after which the promise will reject. Set to `0` to disable.

### `.syncComplete`

`function(): Promise`\
Wait for data synchronisation to complete.


---

# Agent Instructions: 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:

```
GET https://olddocs.exivity.io/3.5.4/advanced/integrate/gui-automation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.