> For the complete documentation index, see [llms.txt](https://calctree.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://calctree.gitbook.io/docs/desktop-app/connections.md).

# Connections

Connect your workspace to the engineering software on your computer, then let CalcTree AI and connection nodes pull data from it and push data to it.

Connections let CalcTree work with the engineering software running on your computer. Once a connection is on for your workspace, there are two ways to use it:

* **CalcTree AI works with the software directly.** It can look inside the files you have open, make changes to them when you ask, and build calculations from what it finds.
* **Connection nodes bring the software into your calculation.** A connection node is a pre-configured block on a page that pulls values from the software into page variables, and pushes page values back. You can add one yourself, or have CalcTree AI set it up.

Because connection nodes live on the page, you can build them into scripts and [templates](#build-templates-that-use-your-software), so the same calculation and report can be run against the next model or workbook.

Connections need the [desktop app](/docs/desktop-app.md).

## Supported software

* [ETABS](/docs/desktop-app/connections/etabs.md)
* [Excel](/docs/desktop-app/connections/excel.md)

### Coming soon

* More CSI software: SAP2000, SAFE and CSiBridge
* SPACE GASS
* Bentley software: STAAD.Pro, RAM Concept and PLAXIS

Use something else, or want early access to one of these? Email <contact@calctree.com>.

## 1. Turn on a connection for your workspace

A workspace admin chooses which software the workspace can connect to.

1. Go to **Settings > Connections**.
2. Under **Available**, switch on the software you use.

When a connection is on, it can be used in pages and by CalcTree AI. When it is off, it can't be used by either. ETABS and Excel are on by default.

## 2. Open your software

Open the model or workbook in its software, on the same computer as the CalcTree desktop app. The desktop app looks for open files when it starts and then every 30 seconds. The status bar at the bottom of the app shows which software it has detected.

## 3. Work with CalcTree AI

In the desktop app, CalcTree AI knows which connected software you have open. Ask it in the AI chat to work with that software, and it can:

* **Inspect your open files.** The AI writes a short, read-only Python script to see what is in the file, such as sheet names, tables or model information, so it knows what to build.
* **Change your open files.** When you ask for a change, the AI writes a script that modifies the open file.
* **Add a connection node** to your page with the reads and writes it needs.
* **Set up an existing connection node.** Click **Configure with AI** on a connection node and the AI fills in its reads and writes.

The AI never runs a script against your software without asking. Each script is shown to you first, with **Approve & run** (or **Approve & modify** for a change) and **Deny**. Read the script before you approve it, and check any connection node the AI sets up before you rely on it.

## 4. Use connection nodes

A connection node is a block on your page that is tied to one open file. It has:

* **Target file.** The model or workbook it talks to.
* **Mappings.** A list of reads and writes. A **read** takes a location in the software (for example a table or a cell) and stores it in a page variable. A **write** takes a page variable and puts it in a location in the software.
* **Script.** An optional block of Python for anything the mappings can't do.

Page variables created by a connection node work like any other variable: use them in calculations, checks, charts and reports.

### Add a connection node

1. On your page, open **Nodes** in the left sidebar, click **+** and choose **Connection**.
2. The node lists the software that is on for your workspace and the files it found open. Click **Connect** next to the file you want. If your file isn't listed, check it is open and click **Scan**.

The connection appears as a tab in the bar at the bottom of the page, named after the file. Click the tab to open or close it.

### Add reads and writes

Under **Mappings**:

* Click **+ Add read**, choose where to read from in the software, and type a name for the page variable that will hold it.
* Click **+ Add write**, choose a page variable, and choose where in the software it should go.

Or click **Configure with AI** and describe what you need.

The node shows how many reads and writes the next sync will run, for example *Run will write 2 / read 3*. Use the **All**, **Read** and **Write** tabs to filter the list.

### Run a sync

Click **Run sync**. A sync runs every write first, then every read, so your page ends up showing what the software returned. The status line shows **Syncing...**, then **Connected · synced just now**, and every calculation that uses a read value updates.

If a read fails, the page keeps the last values it read successfully, so your calculations don't break. The node tells you how many variables could not be read.

{% hint style="info" %}
Syncs never happen on their own. Changing an input on the page, or editing the model, does nothing to the other side until you click **Run sync** again.
{% endhint %}

### Use a script

The **Script** section lets you write Python that talks to the software directly, for example to pick one value out of a large table. Click **Run** in the script section to run it. **Run sync** does not run the script.

Variables your script creates are listed under **Exports** and become page variables. Two exports can't share a name.

Scripts run in a restricted environment. You can import Python's standard maths, text, date and data-structure modules (`math`, `statistics`, `datetime`, `re`, `json`, `itertools`, `collections` and similar). Reading or writing files on your computer is not allowed. Each software page lists what its scripts can reach: [ETABS](/docs/desktop-app/connections/etabs.md#use-a-script), [Excel](/docs/desktop-app/connections/excel.md#use-a-script).

## Build templates that use your software

A connection node is part of the page, so it is saved with the page and copied with it. Set up a page once with its connection nodes, scripts, calculations and report layout, then save it as a template. Each time the template is used:

1. Open the new model or workbook.
2. In each connection node, click **Bind to open file** and choose it. If a file with the same name is already open, the node reconnects by itself, or offers **Reconnect**.
3. Click **Run sync**.

The calculations and report update from the new file.

## Reopening a connected page

When you reopen a page and its files are open, its connection nodes reconnect by themselves. If a node can't find its file, it shows the values from the last sync as read-only and offers **Reconnect** or **Bind to open file**. You can still edit the script while disconnected; changes save automatically.

To switch a connected node to another open file of the same type, use the **Target file** dropdown.

## In the web app

In the browser, connection nodes show the values from their last sync, read-only. Anyone in the workspace can read and review the page. Only the desktop app can sync, change mappings or run scripts, and CalcTree AI can only reach your software from the desktop app.