Integrations and your ERP¶

An integration connects Colleag to a system you already run, so agents answer from live data instead of memory. Ask how many of this article did we sell this year and the Sales agent reads the actual customer orders.

Setting this up is an admin job. Go to Settings → Integrations.

Modules

Some parts of Colleag are modules that an organisation has or does not have: Monitor ERP, CRA monitoring, Silicon Advisor and UPS shipping. A module your organisation does not have does not appear anywhere — not under Integrations, not in the chat's + menu, not in the documents panel. Ask your Colleag contact to switch one on.

What can be connected¶

Every integration is a card with the same parts: name, a short description, a status badge, and the same buttons in the same place. Some are set up once for the whole organisation by an admin (ERP, shipping, Microsoft Teams); some are connected by each person for themselves (Microsoft 365).

Microsoft Teams

ask @Colleag in a channel. Opens its own page for channels and people. See Asking Colleag from Microsoft Teams.
Microsoft 365

your own Outlook, so mail drafts from the chat land in your Drafts folder. Per person.
ERP Systems

your business system: articles, stock, orders, suppliers, prices.
Shipping

carrier accounts for rates and labels.

Badge	Meaning
Connected	Turned on, with credentials saved (or, for a personal connection, your account is linked)
Saved (off)	Credentials are stored but the integration is switched off. Use Configure → Save & Enable to reconnect
Not connected	Not set up yet
Unavailable	This deployment is not configured for it (an operator step, not a Settings step)

Enabled does not mean reachable

Enabled only means an admin turned it on and saved credentials. It does not prove that Colleag can actually talk to the system. Always click Test Connection afterwards to confirm a live handshake.

Connect an integration¶

Click Configure on the card. The button reads Update Config when it is already enabled, or Reconnect when credentials are stored but the integration is off.
Fill in the fields. Required ones are marked with a red asterisk, and each field explains what it expects.
Save.
Click Test Connection and confirm it succeeds.

Rotating a password

Stored secrets come back masked. Leave the field exactly as it is to keep the saved value, or type a new one to rotate it.

Connecting Monitor ERP¶

Monitor has an extra choice, because most installations sit behind a firewall. Open Configure on the Monitor card and pick a Connection method.

Secure connector (recommended)Direct URL

A small outbound agent runs on your own network next to Monitor and dials out to Colleag. Nothing needs to be opened inbound through your firewall.

You do not enter an instance URL with this method — the agent is told where Monitor lives through its own MONITOR_URL setting.

Colleag calls your Monitor hostname directly. This only works when that host is reachable from Colleag, which in practice means a local or on-network deployment. Hosted Colleag cannot reach private hostnames inside your network.

Step by step: Monitor with the secure connector¶

Allow half an hour. Step 1 happens in Monitor, steps 2–4 in Colleag and on a machine on your network, step 5 together.

You need: an administrator in Colleag, someone who may create users in Monitor, and a machine on the network with Docker that can reach Monitor.

Step 1 — Create a Monitor user of its own¶

Create a separate Monitor user for Colleag, with read access. Do not use a personal login: this is the user that shows up in Monitor's own logs, and it has to be possible to switch off without taking someone's access away with it.

Note four things down; they are needed in step 4:

Detail	Example	Where you see it
Company number	`001.1`	On Monitor's sign-in dialog
Language code	`sv`	Same place
Username	`colleag`	The user you just created
Password	—	Make it long and unique

If API access has to be enabled in your Monitor licence, this is where you check that too. Colleag uses Monitor's own REST API on port 8001.

Step 2 — Get the connector token in Colleag¶

Go to Settings → Integrations and find the Monitor card.
Click Configure and choose Secure connector.
Find the Secure connector row and click Set up.
The panel gives you an install command and a connector token. Copy both. The token has the form connector-id:secret and is shown once.

The panel also lists the hub address, the container image and the port your connector has been assigned.

Step 3 — Run the connector on your network¶

Run it on a machine that can reach Monitor. The command in the panel already carries your token; it looks like this:

docker run -d --name colleag-connector --restart unless-stopped \
  -e COLLEAG_TOKEN='<connector-id:secret>' \
  -e MONITOR_URL='https://monitor.internal.example:8001' \
  ghcr.io/colleag-ai/erp-connector:stable

MONITOR_URL is the address as seen from inside your network. It pins what the tunnel can reach; the agent cannot be talked into reaching anything else.
The firewall needs to allow outbound HTTPS to connector.colleag.ai. No inbound rule, no port forward, no VPN.
Check that it started: docker logs colleag-connector should show the tunnel is up.

Does IT have to approve it first?

Send them Connector security. It covers traffic direction, what the tunnel can reach, where credentials live and how you revoke access.

Step 4 — Enter the Monitor credentials in Colleag¶

Back in Configure on the Monitor card: fill in company number, language, username and password from step 1, plus the company currency for reporting. Save.

The credentials are encrypted before they are stored and are never sent to the connector agent — it only moves traffic.

Step 5 — Verify¶

The connector's badge should show online in green, with the time it was last seen.
Click Test Connection on the Monitor card and confirm it succeeds. Remember: Enabled only means somebody switched it on, not that the system can be reached.
Ask a real question in the chat, for example what is the stock level for article 230010-A?. The agent shows which lookup it made.

If something does not work

Symptom	Likely cause	What to do
The badge shows Not set up	The agent has never run	Run the command from step 3
The badge went from online to stale	Machine switched off, or lost the network	Check Last seen, restart the container
Test Connection fails with a sign-in error	Wrong company number, language or password	Check against step 1. The company number is often `001.1`, not `001`
Test Connection fails with a timeout	`MONITOR_URL` points somewhere else, or the machine cannot reach Monitor	Test from that same machine: `curl -k https://<monitor>:8001`
The agent finds no articles	The user lacks read access to the module	Check the rights in Monitor
Everything works but the answers are empty	The integration is off for that discipline	Check Access by domain

Monitor credentials¶

Whichever method you choose, you provide the Monitor credentials Colleag should use — company, language, username and password, and the company currency for reporting. Use a dedicated Monitor user with read access. Colleag only reads from your ERP; it never writes back.

Where your ERP data ends up¶

A fair question before connecting the ERP: what of this ends up at Colleag, and where does it show?

Most of it is not stored. A lookup happens when an agent needs it to answer something. The answer travels back, is used in the answer, and is not kept as a copy of your ERP. There is no scheduled export and no nightly sync.

Three things are kept anyway, on purpose:

What	Why	What it holds
The article register (the search mirror)	So product search can find an article by name without asking the ERP on every keystroke	Article number, description, unit, lifecycle status, type. Not prices, stock, orders, customers or suppliers
The article number on a product	So the product's structure can be fetched from the ERP	One number per product
Whatever an answer said	A conversation is saved, like every other piece of text in the system	The figures the agent happened to mention

When an agent writes a report — a supplier assessment, a monthly report — it becomes a document like any other: stored, versioned and searchable. The figures in it are then part of that document.

Where it shows in the interface: in the chat's answers, in the ERP assemblies section on a product (read live on every load), in the product picker's article list, and in reports somebody asked for. The article list fills itself the first time someone searches, and is refreshed once a day; the explicit Import the article list link remains for an admin who wants it now.
Who can see it: your own users, according to their role. Data is separated per organisation in every database query, and your connector is bound to your organisation and its own port — it cannot be reached from any other account. For the whole picture, including what Colleag's operations staff can and cannot reach, see Deployment options and data security.
What goes to the language model: what you ask, and the extracts needed to answer it — which can include figures from your ERP. Your data is not used to train models.
Disconnecting: stop the connector and the tunnel dies immediately. You can also revoke it from inside Colleag. The article mirror is emptied when the integration is disconnected.

Using ERP data day to day¶

Once connected, ask the relevant agent in plain language:

How many of article 230010-A have we sold this year, and to whom? — Sales
What have we paid this supplier over the last twelve months? — Procurement
What is the stock and lead time on this part? — Supply Chain

The agent shows the lookup it made, so you can see which figures came from your ERP rather than from the conversation.

Ask for what you want

Ask how many and you get quantities. Ask about revenue or value and you get money. The agents keep the two apart on purpose, so a quantity question is not answered with a pile of financial figures you did not ask for.

ERP assemblies¶

When the organisation has an ERP connector, the document workspace shows an ERP assemblies section at the bottom of the product's documents. It has one job: to show the exact structure your ERP holds for the linked article — article numbers, quantity per parent (×2), routing operations (OP3; hover to list them), stock on hand and supplier. It is read live from the ERP on every load. Nothing is cached and nothing is written back.

Without an ERP connector the section does not exist.

Every symbol explains itself on hover, and a legend under the tree lists the types that occur:

Symbol	Type
■	Top-level article (the product as sold)
○	PCBA — printed circuit board assembly
△	Mechanical part
—	Cable / harness
»	Firmware
«	Software
▪	Module / subassembly
◇	Purchased part

Hover a name for its article number. Beside the name, a small tag says what the ERP calls the article — purchased, manufactured, fictitious, subcontract or service — on every row, the top one included. The symbol is Colleag's kind of node; the tag is the ERP's, and it is the tag that decides who owns the article and which documents it needs (see What the workspace is for).

Documents never sit here

Documents about an assembly live under Engineering documents, in the assemblies/{id}/ folder. The ERP section is reference only.

Link the product to an ERP article¶

The ⤓ Import structure from ERP action on the section header links the product to an ERP article and writes the structure into the product's product.yml. That is what creates the assembly folders under Engineering documents.

Click ⤓ Import structure from ERP on the ERP assemblies header.
Type the article number of the finished product, for example 230010-A.
Click Import.

Re-importing later does not touch the documents under assemblies/. And as everywhere else, nothing is written back to your ERP — the import only reads.

You can also just ask an agent: import the BOM structure for 232011.

What the badge means¶

Header badge	Section body	What to do
ERP in green	The live tree	Nothing — the structure is being read from the ERP.
No badge	Not linked to an ERP article yet	Use ⤓ Import structure from ERP.
ERP? in yellow	Article … was not found in the ERP	Re-import with the correct number.
ERP! in orange	The ERP could not be reached	No tree is shown. Check Test Connection under Settings → Integrations.

Troubleshooting¶

Problem	What to do
There is no ERP assemblies section at all	No ERP connector is configured for the organisation. Set one up under Settings → Integrations.
ERP assemblies says Not linked to an ERP article yet	The product is not linked to an ERP article. Use ⤓ Import structure from ERP on the section header.
The ERP assemblies header shows ERP? in yellow	The article was not found in the ERP. Re-import with the correct number.
The ERP assemblies header shows ERP! in orange	The ERP could not be reached, so no tree is shown. Check Test Connection.
The agent says the lookup failed	Open Settings → Integrations and click Test Connection. If the connector is used, check that its badge is online.
The connector badge says Not set up	Nobody has run the connector agent yet. Open the panel and follow the steps.
The connector went from online to stale	The machine running it is off or lost its network. Check Last seen and restart the connector.
Direct URL cannot reach your server	Expected on hosted Colleag. Switch to the secure connector.
The agent gives a plausible number with no lookup	The integration is off or was never tested. Check the badge and click Test.

Next: Settings & Admin →