Set up the Odoo integration

The Odoo integration connects octoja to the Helpdesk module of your Odoo instance, so that monitoring alarms turn into tickets your team already works in. Setting it up takes three things: the connection itself, the ticket settings, and an alert rule that routes alarms to Odoo.

What the integration does

Once connected and configured, the integration does two separate jobs:

• Creates a ticket from an alarm — when a monitoring check raises an alarm and an alert rule routes it to the Odoo channel, octoja opens a Helpdesk ticket on the matched Odoo customer.
• Handles the recovery — when the check recovers, octoja always adds an internal note to that ticket, and moves the ticket to a closing stage when nobody has picked it up yet.

Everything runs outbound, from octoja to Odoo. octoja only ever touches the tickets it created itself, it never pulls existing Odoo tickets into octoja, and it never deletes anything in Odoo. There is no background synchronisation of any kind, and no manual sync control anywhere on the page.

Connecting on its own creates nothing. A connected integration with every setting filled in still produces zero tickets until an alert rule points at the Odoo channel. That routing step is Step 5 below, and it is the one people most often miss.

Prerequisites

• The Integration Management permission in octoja. Permissions are assigned under Administration → Groups.
• The Customer Management permission as well, if you also want to import customers from Odoo.
• An Odoo instance reachable over HTTPS with API access. octoja automatically detects the JSON-2 API on Odoo 19+ or the legacy RPC API on Odoo 18 and older. Plain http:// addresses are rejected. For a firewall or IP allowlist in front of your Odoo API, see IP addresses and firewall rules.
• The Odoo Helpdesk module installed. octoja reads Helpdesk teams and stages and writes Helpdesk tickets; without the module none of those exist.
• The name of the Odoo database you want octoja to work against. octoja sends it with every request.
• An Odoo API key. The setup dialog in octoja points at Settings → Users → API Keys in Odoo; where API keys live differs between Odoo versions, so follow Odoo's own documentation if you do not find them there. The key inherits the rights of the Odoo user it belongs to, and that user needs to read contacts, Helpdesk teams and Helpdesk stages, and to create, read, update and comment on Helpdesk tickets.
• A monitoring check that already runs, so there is an alarm to turn into a ticket.

Step 1 — Gather your Odoo connection details

Collect the base URL of your Odoo instance, the database name, and an API key. On Odoo 18 and older, also obtain the Odoo username the key belongs to.

The base URL is the address you open Odoo at, for example https://mycompany.odoo.com. It must be a complete https:// address. On Odoo 19 and newer, the API key is sufficient; on older instances it replaces the password, not the username.

Step 2 — Connect octoja to Odoo

1. In octoja, go to Administration → Integrations and find the Odoo card.
2. Click Set up. The Set up Odoo dialog opens.
3. Fill in the connection fields:

4. Click Test connection. A successful result names the detected API. If it fails, check the URL, database, key and, on older instances, username.
5. Click Connect. octoja stores the connection and opens the Odoo integration page on its Configuration tab.

Connect becomes available only after a successful test. Test again after changing credentials. octoja also checks the connection when saving and rejects invalid credentials.

Step 3 — Match customers to Odoo customers

Matching tells octoja which Odoo customer each of your octoja customers is, so tickets land on the right contact.

1. On the Configuration tab, find the Customer mapping section.
2. Click Match customers, pair each octoja customer with its Odoo customer, then click Save matches.
3. Click Match sites to map each customer's octoja sites to Odoo locations — a location being a child contact of that customer in Odoo that is filed as an address, so a delivery, invoice or other address. This button stays disabled until at least one customer is matched, so do the customer matching first.

In the site dialog, … → Auto-match by name fills unambiguous name matches within each customer. Existing mappings are preserved and ambiguous matches stay open. Review the suggestions and save the dialog.

An unmatched customer does not stop a ticket. If the device's customer has no Odoo counterpart, octoja still creates the ticket, only without a customer on it. Nothing is skipped and nothing fails, so a forgotten match shows up as Helpdesk tickets with no customer rather than as missing tickets.

When a device belongs to a site that is matched as well, the site's Odoo location wins over the customer's own contact, so the ticket lands at the more specific address.

The customer picker lists every company contact in Odoo, suppliers included, because octoja deliberately avoids filtering on fields that only exist once Odoo's Sales or Accounting modules are installed. On a large Odoo instance, use the search box rather than scrolling. The table's … menu inside the dialog holds two shortcuts: Auto-match by name pairs up every customer whose name lines up with an Odoo one and leaves the ambiguous cases for you to settle by hand, and Show only unmatched hides the rows you have already done. Each octoja customer can be matched to exactly one Odoo customer, and the other way round.

Step 4 — Choose the team, priorities and stages

The Ticket mapping section decides what a ticket looks like. Every setting here is optional and falls back to a sensible default, so none of them can stop a ticket from being created.

The two priority dropdowns offer Low, Medium, High and Urgent — Odoo's own four levels. Warning alarms use the first setting, everything more severe uses the second.

The closing-stage dropdown lists folded stages only. Odoo marks a stage as folded when it should collapse in the Helpdesk kanban view, which is how closing stages are normally set up. If the stage you want is missing from that list, it is not folded in Odoo — mark it folded there, then reopen the page.

Settings are not saved automatically. Every dropdown you change stays local until you click Save settings in the page header, or press Ctrl+S.

The team and stage dropdowns are read live from Odoo every time the page opens. If they are empty, suspect the connection rather than Odoo: check that the API key is still valid and that its user may read Helpdesk teams and stages.

Step 5 — Route alerts to the Odoo channel

This is the step that makes tickets appear. Everything so far only prepared octoja; no alarm reaches Odoo until an alert rule sends it there.

1. Open the config package that contains the check you want tickets for, go to its Checks tab and open the check.
2. Switch to the check's Alert tab and pick or create an alert configuration.
3. In that configuration, add the channel Odoo ticket.
4. Set the rule for the channel — the share of recent results and the minimum severity that has to be reached — and save the check.

Odoo is a single, tenant-wide channel: once you pick Odoo ticket there is nothing else to select, no target and no team to choose again. The channel only appears in the picker once Odoo is connected — if Odoo ticket is missing from the list, finish Step 2 first. Pausing is the real trap: a paused integration keeps the channel selectable, so a rule saved against it looks perfectly fine and quietly does nothing. When tickets fail to appear, check the integration status as well as the rule.

For the full walkthrough of alert configurations, rules and schedules, see Set up alerts for a check.

A ticket octoja opens is titled octoja: <check> – <device>. Its description names the check, the device, the reported status and how many of the last runs failed, followed by the customer name, the check's own output, and a link back to the device in octoja.

What happens when a check recovers

Recovery is handled in two parts, and only the first is unconditional.

The recovery note is an internal log note in Odoo rather than a customer-visible message, so nothing is emailed to the contact on the ticket. It is always written in English, whatever you picked under Ticket language — that setting covers only the ticket octoja creates.

Only tickets octoja created for that alarm are touched. If the original ticket never came into existence — because the integration was disconnected at the time, for instance — there is nothing to comment on, and the recovery passes without a trace in Odoo.

Import customers from Odoo

If your customers do not exist in octoja yet, you can seed them from your Odoo customers. This lives on the Customers page, not on the integration page.

1. Open Customers and choose Import from ticketing system.
2. Select the Odoo customers you want and confirm the import.

Each selected Odoo customer becomes an octoja customer, its Odoo locations become octoja sites, and both the customer match and the site matches are created for you — so an imported customer needs no manual matching in Step 3. Customers that are already matched are counted as skipped and left alone.

The menu item opens the first connected ticketing system in a fixed order: DocBee, HaloPSA, Inserve, Autotask, Codemeta OS, Odoo, Jira, TOPdesk, TANSS, c-entron Service-Board, Freshservice, Zammad. Odoo sits sixth, so if any of the five ahead of it is connected as well, that system's import dialog opens instead and there is no way to pick Odoo.

When tickets stop arriving

The History tab lists recent Create ticket and Recovery attempts with their outcome and response, and is the place to look whenever a ticket you expected is missing. There is no replay button: a delivery is retried on its own schedule or not at all.

• A delivery failed. octoja retries a failed ticket create or recovery after 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours and 24 hours. Errors Odoo reports as a client mistake are not retried, because repeating them would not change the answer.
• The card shows the status Paused. After 20 consecutive delivery failures octoja stops sending, so a broken connection does not keep hammering Odoo. To resume, use Disconnect Odoo and connect again with the same values. Your matches and settings survive the round trip, so nothing has to be set up twice.
• It is hard to tell that it is paused. The integration page shows no failure counter and no banner. The two signals are the status badge on the Odoo card under Administration → Integrations, which flips from Active to Paused, and the failed rows on the History tab that stopped being retried.
• The team and stage dropdowns are empty. The stored API key is no longer valid, or its Odoo user may not read Helpdesk teams and stages. Disconnect and connect again with a working key.
• Tickets arrive without a customer. That customer has no Odoo match — go back to Step 3 and pair it up.
• No tickets at all. Confirm that an alert configuration on the check really includes the Odoo ticket channel, and that the integration is connected and not paused.

Disconnect Odoo

To remove the connection, open the Odoo integration page, scroll to the Danger Zone and click Disconnect Odoo, then confirm with Disconnect.

Only the API key is removed. Your customer and site matches, all ticket settings and the delivery history stay exactly as they were, and every ticket already created remains in Odoo. To reconnect, enter and test the connection details again.

Tips

• Click Save settings after every change — a dropdown you changed but did not save has no effect on the next alarm.
• Set Stage when closing on recovery if you want recovered tickets closed. Leave it unset if your team prefers to close tickets by hand; recoveries are noted on the ticket either way.
• If the stage you want to close into does not appear in that dropdown, mark it as folded in Odoo first.
• Match every customer even though tickets are created without a match — a ticket with no customer on it is easy to lose in Odoo.
• Use Test connection before Connect and after changing credentials in the dialog.
• Leave Helpdesk team unset if Odoo's own routing rules already put tickets where you want them.