> For the complete documentation index, see [llms.txt](https://docs.labatlas.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.labatlas.com/integrations/softmouse.md).

# SoftMouse

Linking SoftMouse colony records to your projects, studies, and assays

Lab Atlas can connect to [SoftMouse](https://softmouse.net), the mouse colony management system. Once connected, you can link SoftMouse mice, cages, studies, and protocols to Lab Atlas projects, studies, and assays. The animals behind a piece of work then sit next to everything else about it, and searching for a mouse or cage finds the work it's linked to.

SoftMouse is an **organization integration**: an Organization Admin connects it once with a single SoftMouse account, and everyone in the organization uses that connection. See [Third-Party Connectors](https://docs.labatlas.com/managing-your-organization/third-party-connectors.md) for how organization and personal integrations differ.

{% hint style="info" %}
The SoftMouse integration is in **beta**. It works as described here, but its behavior may change as it develops.
{% endhint %}

## What Lab Atlas does with it

* Looks up SoftMouse records by their identifier, so you can link them to a project, study, or assay.
* Shows linked records on the record's **ELN** tab, with a link back to SoftMouse for mice and cages.
* Makes linked records searchable. Searching Lab Atlas for a mouse's or cage's ID returns the work it's linked to. See [Search](https://docs.labatlas.com/using-lab-atlas/search.md).

SoftMouse isn't an electronic lab notebook. Lab Atlas doesn't create anything in SoftMouse, and it doesn't create notebook folders or entries for it.

## What you can link

| Entity type         | Look it up by                         | Opens in SoftMouse |
| ------------------- | ------------------------------------- | ------------------ |
| **Mouse**           | Mouse SID                             | Yes                |
| **SoftMouse Study** | Study code                            | No                 |
| **Cage**            | Cage SID, as printed on the cage card | Yes                |
| **Protocol**        | Protocol number, such as `P101`       | No                 |

A SoftMouse study is a SoftMouse cohort. It isn't the same thing as a Lab Atlas study, which is why Lab Atlas labels it **SoftMouse Study**.

Each linked record is labelled with the details that identify it at the bench:

* A mouse shows its SID, plus its ear tag and genotype when SoftMouse records them.
* A cage shows its SID, plus its tag, strain, and how many animals are in it.
* A SoftMouse study shows its code, plus its project and how many groups it has.
* A protocol shows its number, plus its title and principal investigator.

## Before you start

You need a SoftMouse account for Lab Atlas to use. SoftMouse doesn't issue API keys, so Lab Atlas signs in with a username and password.

* **Use a dedicated service account** rather than a person's own login where you can. The whole organization shares this connection, and a login tied to one person stops working when they leave.
* **The account must have API access enabled by SoftMouse.** An ordinary SoftMouse login can't be used by Lab Atlas until API access is switched on for it.
* **Lab Atlas sees what the account sees.** It can only look up mice, cages, studies, and protocols that the account can reach in SoftMouse.

## Connecting in Lab Atlas

{% stepper %}
{% step %}

### Open the Integrations page

Click **Integrations** in the sidebar. Find **SoftMouse** under **Available** and click **Connect**.
{% endstep %}

{% step %}

### Fill in the connection details

The **Add Integration** dialog asks for:

* **Name** — a display name for the connection. It defaults to *SoftMouse*.
* **Username** — the SoftMouse account Lab Atlas will use.
* **Password** — that account's password.

There is nothing else to configure. Lab Atlas always connects to softmouse.net.
{% endstep %}

{% step %}

### Save

Click **Save**. Lab Atlas signs in to SoftMouse to check both the password and that API access is switched on.
{% endstep %}
{% endstepper %}

When the check succeeds, SoftMouse moves to **Connected** with an **Active** badge. If it fails, the integration shows **Authentication Failed**, and the reason appears under **Last Error** on its details page. Check the username, the password, and that SoftMouse has enabled API access for the account.

{% hint style="info" %}
The password is stored encrypted and is never shown again. If you edit the integration, you'll be asked to re-enter the password.
{% endhint %}

## Managing the connection

Click **Manage** on the SoftMouse card to open its details page. The **Actions** menu offers:

* **Test & Sync** — signs in to SoftMouse again to confirm the credentials still work. Use it after the account's password changes, or if lookups start failing.
* **Edit** — change the name, username, or password.
* **Disable** / **Re-enable** — turn the connection off without removing it.
* **Archive** — remove the connection. An archived integration can't be re-enabled.

## Linking SoftMouse records

{% stepper %}
{% step %}

### Open the ELN tab

Open the project, study, or assay and click its **ELN** tab.
{% endstep %}

{% step %}

### Start a search

Click **Add**, then **Search All**. The **Link Entity** dialog opens.
{% endstep %}

{% step %}

### Choose SoftMouse and a type

Under **ELN Integration**, choose your SoftMouse connection. Under **Entity Type**, choose **Mouse**, **Softmouse Study**, **Cage**, or **Protocol**.
{% endstep %}

{% step %}

### Enter the identifier

In the **Search** box, type the exact identifier from the table above and press Enter. Click **(open)** next to a mouse or cage to check it in SoftMouse.
{% endstep %}

{% step %}

### Link it

Tick the result and click **Link 1 Item**.
{% endstep %}
{% endstepper %}

The record appears in the **Electronic Lab Notebook** card on the **ELN** tab. To unlink it, click the **⋯** menu on its row and choose **Remove**. Nothing is changed in SoftMouse.

See [Linked records](https://docs.labatlas.com/using-lab-atlas/search.md#linked-records) for who can link records and when.

## Limitations

* **Lookups are by exact identifier, not by name.** SoftMouse doesn't offer a name or free-text search, so the **Search** box (which suggests *Search by name…*) only finds a record when you type its exact SID, study code, or protocol number. A typo returns no results rather than a near match.
* **You link one record at a time.** Each lookup returns at most one match.
* **Samples aren't supported.** You can't link SoftMouse samples yet.
* **SoftMouse studies and protocols don't link back.** SoftMouse doesn't give Lab Atlas the internal address it needs, so these rows have no **Open in ELN** option. Mice and cages do.
* **Linked records are a snapshot.** Lab Atlas stores the name and ID at the moment you link a record. If the mouse's tag or genotype changes in SoftMouse later, the linked row keeps the old label.

## For administrators

* Only Organization Admins and Account Admins can connect, edit, sync, disable, or archive the SoftMouse integration. Other members see it on the **Integrations** page without these controls.
* Anyone who can edit a project, study, or assay can link and unlink SoftMouse records on it.
* Every lookup is made as the SoftMouse account you connected. Keep its password current in Lab Atlas whenever it changes in SoftMouse, then run **Test & Sync**.
