Integrations
The integrations store: connecting ticket and documentation systems, the setup assistant, mappings, company import, history, the log of a connection, what a connection sends, and which rights and tenant limits apply.
Integrations
Settings → Integrations at /settings/integrations connects NetLock RMM to other products. Every entry is a tile with its category and its state on this instance. Tiles fall into three groups:
- Connectors connect to a product of another vendor, for example a ticket system. They have a setup assistant and, once connected, a page of their own.
- Signed webhooks is a built-in NetLock feature. The tile opens
Settings → Integrations → Signed webhooks. - Custom integration is for tools that fetch data themselves. It creates an ordinary API token with suggested read scopes, see A.14.8.
The store offers a search, a filter per category and the switch Connected only. A product can appear in more than one category.
E-mail, Microsoft Teams, Telegram, ntfy and the NetLock app are notification channels and are not part of the store. They are configured under Settings → Notifications.
A.14.1 Requirements
Connectors read NetLock data through the public API, on a local port of the server, with a token that belongs to the connection. The public API therefore has to be on. While it is off, the store and every connection page show a banner, and connections do not run. An account with settings_api_tokens_manage sees the button Switch on public API in that banner.
The web console and the server need the same Security:Local_Encryption_Key, because the console stores the credentials and the server reads them. If the keys differ, a connection stops with the note that the stored credentials cannot be read.
The server listens for this traffic on 127.0.0.1:7480. Integrations:Loopback_Port in the appsettings.json of the server changes the port; 0 switches the listener off, and connectors then do not work. The port accepts only /v1 and is not meant to be published. In a container it stays inside the container, so nothing has to be added to a compose file. If the port is taken, the server starts anyway and the connection shows that the local listener cannot be reached.
A.14.2 Connecting
Connect in the detail of a tile opens the assistant.
- Credentials. The name of the connection and the fields of the product. A secret field is write-only: it is stored encrypted and never shown again.
- Test. NetLock makes a read-only call to the vendor. The step cannot be skipped, and nothing is stored until the test has passed. The connection is created with exactly the values that were tested, and it gets its token, bound to your account.
- Options. The settings of the product, the alert filter, what an all-clear does to a ticket, and the language of the ticket frame, see A.14.4.
- Mappings. Which tenant belongs to which company, and which severity to which priority, see A.14.5.
- Activate. The connection starts to work. Alerts that were already open are not sent: a connection only handles alerts from the moment it is activated.
If you leave the assistant after step 2, the connection stays in the state Setup open. Continue setup on the page of the connection resumes at the options.
Note: Alert texts, device names and tenant names go to the vendor. Check that this matches your data processing agreements before you activate a connection.
Target addresses follow the rules of the instance. On a cloud instance only public addresses can be reached. A self-hosted instance can also reach private addresses, but never loopback, link-local or cloud metadata addresses. The test reports a refused address.
A.14.3 The page of a connection
/settings/integrations/<id> has these tabs.
| Tab | Content |
|---|---|
Overview | State and its reason, the account the connection runs under, mapped tenants, last success and last error. Pause, Resume, Synchronize now and Switch to my account. |
Settings | Name and options, see A.14.4. |
Mappings | Tables per kind of mapping, Auto mapping, Import companies, see A.14.5. |
Billing | Only for connectors that can write quantities: contract items per tenant, plan, preview and transfer, see A.14.10. For accounting connectors: positions, tax case per tenant, preview and documents, see A.14.11. |
History | Every job with its result, filter, export, the redacted request and response, Send again, see A.14.6. |
Danger zone | Replace credentials, Disconnect, Delete connection. |
A connection is in one of these states.
| State | Meaning |
|---|---|
Setup open | The assistant was not finished. Nothing runs. |
Connected | The connection works. The chip Setup incomplete next to it says that a required mapping is missing, so some alerts end as skipped. |
Paused | Paused by a person, or by NetLock after 20 failures in a row. Jobs wait. Resume runs them. |
Error | The vendor rejected the credentials, or the token no longer works. Jobs wait. Replacing the credentials or Resume ends the state. |
Disconnected | Credentials and token are gone, the mappings stay. Connect again under Danger zone asks for the credentials and starts from that moment. |
The account of a connection
There is no service account. The token of a connection is bound to the account that connected it, and it always has the current rights of that account. The overview shows that account, the tenants it does not cover and the scopes it can no longer grant. A disabled or removed account stops the connection.
Switch to my account moves the connection to your account with a new token. That only works if your account covers every mapped tenant and every scope of the connection; otherwise nothing changes and the page names what is missing, so a connection never loses tenants without notice.
The token appears under Settings → API tokens with the chip Integration: <name> and cannot be changed there. NetLock replaces it every 30 days. It is valid only on the local port and from the server itself; the public port rejects it with 401.
If you leave a secret empty in Replace credentials, the stored secret is kept, but only for the address it was stored for. If the address changes, or Allow unencrypted http is switched, every secret has to be entered again; otherwise the test and saving are refused. The audit log names the old and the new address.
A.14.4 Settings
- Alert filter. The minimum severity and the sources that create tickets. Empty sources mean every source.
- After an all-clear.
Add a note only,Close if nobody is assigned(default) orAlways close. If the ticket was changed at the vendor in the meantime, only the note is added. - When a one-shot alert is acknowledged. The same choice for alerts that have no all-clear, such as an antivirus finding. They end when the event is read or hidden. Like every open alert, they also end when no new event arrives for the number of days set on the retention page (30 by default).
- Language of the ticket frame. Title, field names and notes of a ticket; the text of the alert stays as it is. Defaults to the language of the instance.
Tickets link back to the web console through the public console URL. Without that setting a ticket has no link.
A.14.5 Mappings
Only mapped tenants are included. An alert of a tenant without a mapping is not lost: it appears in the history as skipped, with the reason.
A mapping connects a local object with its counterpart at the vendor: tenants and locations with companies and sites, severities with priorities, device classes with types. A product decides which of them it offers and which are required. A mapping can be switched off without removing it.
Auto mapping compares the tenants without a mapping with the companies of the vendor by name. A company whose name matches the tenant's, ignoring case and spaces, is selected. Less certain matches stay open as candidates: names that differ in an accent or in punctuation, a tenant with several candidates, and a company that matches two tenants. Müller and Muller can be two different customers, so a person has to choose. Existing mappings stay as they are, and one company cannot be chosen for two tenants.
Import companies lists the companies without a mapping. Each one can become a new tenant, which needs the permission to add tenants, or be mapped to an existing tenant without a mapping. A new tenant is added to the tenants of your account. The import never replaces a mapping; a line it cannot apply stays in the dialog with the reason.
A.14.6 History
The history lists what a connection did, newest first. A job is Waiting, Running, Done, Failed or Skipped. Failed attempts are repeated after 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours and 24 hours; a limit of the vendor (429) does not count as a failure, and a refused request (4xx) is not repeated.
The full text of a vendor error is shown only on the job of its tenant. The overview of a connection and jobs without a tenant, which every reader sees, show only the kind of error.
The detail of a job shows the request and the response. Credentials and tokens are redacted before they are stored. Send again queues a failed or skipped job once more. NetLock does not create a second ticket for an alert it already reported, and it never deletes anything at the vendor. The connector pages name the cases where a repeated job cannot rule out a second ticket.
Finished jobs are removed after the time set on the retention page.
A.14.6a Log
The tab Log on the page of a connection shows what happened and why something failed. It exists for every connector. The history lists jobs; the log also shows events that no job records: failed connection tests, status changes, a pause and its end, the replacement of the token, a local listener that cannot be reached, and what the scheduler decided, such as a report left out or the first status pull. A line that belongs to a job links to it. Notification channels and signed webhooks keep their own delivery logs and do not appear here.
Each line has a time, a level (Error, Warning, Info, Debug), an area and a message in your language. You can filter by level, area and time, and the search also covers the messages of the vendor. Export data writes the lines you see. The detail of an error or a warning says what to do, and shows the request it came from: method, host, path without the query, status and duration. The same explanation appears in the setup assistant when a test fails.
Repeats of the same error within an hour are combined into one line with a counter and the time of the last occurrence, so a failing connection does not fill the log. Runs that find nothing new leave no line.
| Message | What to do |
|---|---|
The vendor rejected the credentials (401) | Check them at the vendor and replace them under Danger zone. The connection stays stopped until then. |
| The address is not allowed on this instance | Use the public https address of the vendor. Private addresses and plain http are refused, and the name has to resolve on the server. |
| Mapping missing | Add it under Mappings, then use Send again on the job in the history. |
| The key or token has expired | Create a new one at the vendor and replace it under Danger zone. |
| The token of the connection is refused | The token belongs to NetLock. Reconnect, or switch the account on the overview. |
The vendor limits the requests (429) | Nothing for now: the work waits as long as the vendor asks. If it stays, reduce other use of its API. |
Debug logging
Debug for 60 minutes is for a support case. For that time the log also keeps every request with a summary of the request and the answer, and the runs that found nothing. It ends automatically; Stop debug ends it early. The button needs settings_integrations_manage, and switching it on or off is recorded in the audit log.
Credentials are removed before anything is stored, at this level too, and vendor lists such as all companies or all tickets never reach the log. Requests for work that covers all tenants, such as the asset sync, show the response only when they fail. A very busy connection records up to 120 requests per minute and server process; a line says how many were left out.
Entries are removed after 14 days, counted from their last occurrence. The period can be changed on the retention page. Deleting a connection removes its log.
A.14.7 Rights and tenant limits
settings_integrations_enabled opens the store and shows connections, mappings, history and log. settings_integrations_manage allows everything else. Both are described in X.2.17.
An account limited to some tenants can still connect, configure, pause and disconnect, because a connection belongs to the instance. Anything that touches the data of a tenant is limited to the account's own tenants:
| Action | Limit |
|---|---|
| Connect, test, replace credentials, settings, pause, resume, synchronize, disconnect, delete | None. The confirmation of Disconnect and Delete names how many tenants the connection serves. |
| Lists of the vendor, such as companies or queues | None. They are not NetLock data, but they need settings_integrations_manage: reading them uses the stored credentials. An account that only reads sees stored values as text. |
| Mappings of tenants and their locations | Outside the account's tenants a row stays visible, locked and without names. |
Auto mapping, Import companies | Only tenants of the account. A new tenant additionally needs the permission to add tenants. |
| Contract items, preview, transfer | Only tenants of the account. Other rows stay visible, locked and without names or numbers. Preview and transfer need settings_integrations_manage. A planned transfer covers every mapped item. |
| History | Jobs of other tenants are hidden. Jobs without a tenant are visible. Send again only for visible jobs. |
| Log | Lines of other tenants are hidden. Lines without a tenant are visible with their message and error class, without the text of the vendor, the path and the summary of the request. Switching debug logging on needs settings_integrations_manage. |
| Token of the connection | Only mapped tenants, and only those the bound account covers. |
A connection set up by an account with few tenants can therefore serve only those tenants. The overview shows when mapped tenants are out of reach.
A.14.8 Custom integration
The tile Custom integration suggests read scopes for tools that fetch data themselves. Create token opens the usual token dialog with these scopes ticked; account, tenants and expiry are chosen there. It needs settings_api_tokens_manage. The token is shown once and then behaves like any other token, see X.9. For push instead of pull, see X.10 — Webhook signatures.
A.14.9 Connectors
Setup, the data that goes to the vendor and the known limits of each connector:
- Zammad
- Jira Service Management
- Freshservice
- Freshdesk
- Odoo Helpdesk
- ITFlow
- TOPdesk
- DocBee
- TANSS
- NEXOWARE / c-entron
- HaloPSA
- Autotask PSA
- IT Glue
- Hudu
- Bitdefender GravityZone
- Acronis Cyber Protect Cloud
- Zendesk
- Zoho Desk
- ServiceDesk Plus
- ServiceNow
- Lexware Office
- sevdesk
- NetBox
- Snipe-IT
- Wazuh
- Docusnap365
NetBox and Snipe-IT are usually a customer's source of truth. NetLock therefore only adds its own fields to objects that already exist there and skips a device without a match, with the reason in the History tab.
Docusnap365 runs its own scans, so NetLock only links a device to its scanned object by serial number and writes nothing.
Status connectors such as GravityZone, Acronis and Wazuh query the vendor every five minutes and report through POST /v1/alerts/ingest, so the same rules apply to their alerts as to any external report. Their first pull only records the current state, so connecting an account does not open hundreds of old problems.
A ticket that cannot be closed keeps its note and stays open, and the History tab gives the reason: assigned, changed, no_transition or close_refused.
A.14.9a External systems of a device
As soon as a connection exists, the device details show the tab External systems. It lists the objects of the device in the connected systems: the asset of the device sync, the endpoint a status connector matched, what such a connector reports as open, the tickets of the alerts of the device, and references set through the public API. Each row names the system, the connection, the state and the last change, and links to the object where the vendor provides an address.
Like the rest of the device details, the tab requires the device tab permission General and access to the tenant of the device. Nothing can be changed in it.
A.14.10 Contract quantities
Connectors that support it write the device count of a tenant for a period to a contract item at the vendor. The Billing tab holds one row per tenant and item. A tenant needs its company mapping first.
Each row has its own counting rule. The rules apply together; all three are on by default.
| Rule | Effect |
|---|---|
Only authorized devices | A device counts on a day it was authorized. |
Leave out blocked devices | A device does not count on a day it was blocked. |
Online at least once in the period | A device counts only if it checked in on at least one day of the period. |
Platforms, Device classes | Only the chosen ones. Empty means all. |
Value of the period decides what goes to the vendor: the Maximum of the daily counts (default), their Average, rounded, or the Last day. The counts come from a snapshot NetLock takes every night, starting with the first snapshot. Days without a snapshot are not included. They match the usage endpoints of the public API.
Required coverage sets the share of days in a period for which the tenant needs counts. The default is 100 percent, every day. A month that is not fully covered, such as a month with a long server outage, is then not written until you lower the value for that item. A contract item holds one count, so two tenants or two counts cannot write to the same item.
Preview shows what a transfer would do for a month: the quantity at the vendor against the new one, how each rule changes the count, for example All devices 52 → Only authorized 50 → Without blocked 49 → Online in the period 47, the three period values, how many days have numbers, and which devices a rule removes. A device that passes a rule on some days stays in the list and only lowers the count of those days.
Transfer now sends the rows that would change. Planned transfer sends the previous month on a day of your choice, once the snapshot of its last day exists. If a plan or a row is switched on after that day, it starts with the next month, because nobody has seen a preview for the month that is due.
When in doubt, NetLock writes nothing and says why, in the preview, in the Billing tab and in the history.
- A transfer asks the vendor what is booked and writes only the difference. A second transfer of a period books nothing twice.
- A period that has not ended is not written, not even by hand. If the vendor bills a quarter, the quantity is sent once the quarter is over.
- A period below the required coverage is not written.
- A tenant without any numbers for the period writes nothing; in particular, it does not write zero.
- A planned transfer never sets an item to zero. A manual transfer can, and the preview warns about it.
- An item the vendor blocks or no longer lists is skipped.
- A refused quantity fails its job but does not count as a failure of the connection.
- A write that ends without an answer, such as after a timeout, is resolved on the next attempt based on what the vendor holds. If that is not possible, the row shows
Check at the vendorand nothing else goes out for this item. Look at the quantity at the vendor and useSend againon the job in theHistorytab. Send againruns a transfer under your account.- A plan that skipped a month, for example while the connection was paused, does not catch up. The row shows
A period was missed. - Every transfer is recorded in the audit log with the old and the new quantity and the coverage. A planned one has the user
system.
Check the rules in the preview before you plan a transfer: these numbers end up on invoices.
A.14.11 Invoice drafts
This is meant for MSPs without a PSA. Accounting connectors create one invoice draft per tenant and month, with one line per position. A person checks the draft and finishes it in the accounting product. NetLock never finishes or sends a document: a finished invoice can only be undone by a cancellation.
The connectors are Lexware Office and sevdesk. Their pages describe the differences, most of which concern Lexware Office.
Positions. A tenant needs its contact mapped first. A position in the Billing tab names an article of the accounting product, what it counts, and the rule of A.14.10: the three rules, the filters, the value of the period and the required coverage. Price per unit is optional and overrides the price of the article, because prices often differ per customer. A tenant can have several positions, for example Servers and Workstations through the platform and class filters. They all end up on one document.
Preview and creating. Create drafts shows, for a month and per tenant, each position with the effect of the rules, the article, the price and the amount, the total, the tax case, and whether a document of that month exists. Create drafts in the dialog then creates drafts for the tenants that can get one. The dialog applies the same checks as the planned job.
Plan. Planned drafts is off by default. When switched on, it creates the drafts for the previous month on a day of your choice, once the snapshot of its last day exists. A tenant with a position switched on after that day starts with the next month, because nobody has seen a preview for this one.
All or nothing. If one position cannot be written, the whole document is stopped and the history names the reason: a period that has not ended, too little coverage, no numbers for the tenant, an article that is gone, a position without a price. A planned run never reduces a position from a quantity to zero. A position that counts 0 is left out; if all of them count 0, no document is created.
Tax. NetLock does not decide tax questions or calculate tax. The rate comes from the article, and the tax case is set per tenant. For a contact in Germany, no choice is needed. For a contact in another country or with an unknown country, no document is created until a tax case is chosen, even on a small-business account. If the vendor refuses the tax, no document is created either. The mapping of the tax cases to the vendor's terms follows the vendor's names. It is not tax advice; have it checked by your tax adviser.
Documents. The list of documents shows one row per tenant and month. The rows are kept permanently, even after the jobs have been removed and the connection is deleted, because they prevent a period from being invoiced twice. A document belongs to the account at the vendor, not to a connection: a second connection to the same account, or one set up again, sees the same rows and creates no second document. Before a document is created, NetLock also searches the vendor for its reference. If the vendor does not identify the account, no document is created.
NetLock reads the current state of the documents when an account with the manage permission opens the tab, when you click Check at the vendor, and once a day.
| State | Meaning | What happens next |
|---|---|---|
Draft | The vendor holds the draft. | No second document. If the count differs from it, the row shows old and new, and you correct the draft at the vendor. |
Finished | A person finished the document. | The same. A correction is a cancellation or credit note in the accounting product. |
Deleted at the vendor | The draft is gone. | Nothing by itself. Create again makes a new one. |
Check at the vendor | A call ended without an answer, and the vendor does not show the document. A run left in progress ends here as well. | Nothing by itself. Check at the vendor, then use Checked, try again in the list of documents. NetLock looks once more and creates a document only if there is none. Your confirmation allows one attempt. |
Send again in the history repeats a job, but does not allow a new attempt for a document in Check at the vendor or Deleted at the vendor. For those, use Checked, try again or Create again in the list of documents.
The vendor key has access to the entire accounting. Use it only for this connection. Every draft is recorded in the audit log as invoice_draft_created, with tenant, month, lines and amount. A planned one has the user system. A failure of one tenant never pauses the connection.
Related
- X.5 — Integration endpoints — outbound connections and the firewall.
- X.9 — Public API — alerts, external references, usage, managed tokens.
- A.8 — Notifications deep dive — the notification channels.
Endpoint protection
Endpoint protection: devices installed with a trust anchor execute only definitions a registered phone signed and remote actions a registered phone approved. Setup in the NetLock app, the anchor as installation parameter, protection levels, signing definitions, approving actions and work sessions, screen control from the Relay App and the NetLock app, what happens when the server cannot check a device, device states, the public API, the operating rules, and Android devices.
Zammad
Connect NetLock RMM to Zammad: alerts become tickets in a group, the all-clear adds an internal note and closes the ticket, organizations can be imported as tenants.