Set up the Codemeta OS integration

Set up the Codemeta OS integration

Codemeta OS is a service-desk and CRM platform. When you connect it to octoja, octoja can raise Codemeta OS tickets from check alerts, keep your device inventory in sync, and import customers from Codemeta OS so tickets land on the right customer. The connection is built in two halves: you create an API key and read your Workspace ID inside Codemeta OS, then enter both in octoja and configure the mapping.

Prerequisites

• The Integration Management permission in octoja. Administrators assign permissions to groups under Administration → Groups.
• A Codemeta OS account with administrator access — enough to create an API key in the API console and to read your Workspace ID.
• For a self-hosted Codemeta OS instance: the API base URL of that instance, as an absolute HTTPS address. The cloud service at https://os.codemeta.de/api/v1 is the default and needs no override.

For a self-hosted instance, the firewall in front of your Codemeta OS API must allow requests from octoja. For the appropriate source IPs, see IP addresses and firewall rules.

Step 1 — Create an API key in Codemeta OS

1. In Codemeta OS, open the API-Konsole and click Neuen Schlüssel erstellen.

2. Give the key a name (for example octoja RMM) so you can recognise it later.
3. Choose the Live environment for production use.
4. Enable the GET, POST, and PATCH HTTP methods. octoja reads and writes data, so read-only (GET) alone is not enough. Those three are the only methods octoja sends, so PUT and DELETE can stay off.
5. Select the permissions the integration needs. octoja works with six Codemeta OS resources: customers (parties), locations, assets, ticket types, tickets, and messages — the last one carries the internal note octoja posts when a check recovers. Grant the scopes that cover those and leave the rest unticked.
6. Click Schlüssel erstellen.

7. Codemeta OS shows the token once. Click Token kopieren and paste it somewhere safe — a password manager or secret store. You will paste it into octoja in Step 3. If you lose it, you cannot view it again; create a new key instead.

Step 2 — Find your Tenant ID (Workspace ID)

octoja identifies your Codemeta OS tenant by its Workspace ID.

1. Open the user menu in the bottom-left corner of Codemeta OS and click Profil.

2. In Einstellungen, open the Workspaces tab. Each workspace card shows a Workspace-ID. Copy the ID of the active workspace — this is the Tenant ID you will enter in octoja.

Step 3 — Connect in octoja

1. In octoja, go to Administration → Integrations and open Codemeta OS.
2. In the Set up Codemeta OS dialog, fill in:

3. Click Test connection to verify the credentials, then Connect to save the connection.

Step 4 — Configure the integration

After connecting, the Configuration tab opens. Work through the three sections and then save.

The site dialog also offers … → Auto-match by name to fill unambiguous name matches within each customer. Existing mappings are preserved and ambiguous matches stay open. Review the suggestions and save the dialog.

• Customer mapping — map your octoja customers and sites to their Codemeta OS counterparts. Use Match customers and Match sites. Inside the Match customers dialog, the … menu offers Auto-match by name, which pairs the customers whose names line up. Start here: Codemeta OS needs a customer on every ticket, so an alert on a device whose customer is unmapped raises no ticket at all.
• Ticket mapping — pick the Ticket type Codemeta OS tickets use, then set Priority for Warning and Priority for Critical. Both offer LOW, NORMAL, HIGH and CRITICAL; octoja starts on HIGH for warnings and CRITICAL for critical alerts.
• Device sync — under Device types, every octoja device type is listed, from Windows Server and macOS through to Switch, Firewall, NAS and IP Camera. Each maps to one of four Codemeta OS asset types: Server, PC, Laptop or Virtual machine. The five operating-system types arrive pre-filled; any type you leave unset is skipped by the sync. octoja matches devices by hostname per customer/location, creates the ones that are missing, and leaves existing devices untouched. Turn on Automatically sync devices hourly for an hourly sync.

Click Save settings to apply the configuration.

Track activity

The History tab lists everything octoja sends to Codemeta OS under Recent deliveries — Create ticket, Recovery and Device sync attempts alike. Expand a row to read the Request payload and the Response Codemeta OS returned, so you can confirm deliveries and track down failures.

What you can do now

• Import customers from Codemeta OS into octoja — open the Customers page, use the actions menu and choose Import from ticketing system. The addresses of each imported customer become octoja sites, and the customer mapping is created for you.
• Raise Codemeta OS tickets automatically from octoja check alerts.
• Create devices in Codemeta OS from octoja.

Tips

• Restrict the API key to the permissions listed above — no more.
• To rotate the token, create the new key in the Codemeta OS API console first. Then open the Codemeta OS integration in octoja, use Disconnect Codemeta OS in the Danger Zone and connect again with the new token — octoja turns down a second Connect while a token is stored. Your customer matches and configuration survive the disconnect.
• The device sync matches on hostname per customer/location. Make sure your customer mapping is correct first, or devices may be created under the wrong customer.
• Existing Codemeta OS devices are never overwritten — the sync only fills in the ones that are missing.