Skip to main content

​
About Oomnitza

Oomnitza is an IT asset management (ITAM) platform that tracks your hardware, software, SaaS applications, and the people and places they belong to. The Serval integration connects to your company’s own Oomnitza instance (for example, company.oomnitza.com) using a dedicated service account, and gives your workflows fully typed access to the Oomnitza REST API: assets, accessories, kits, software, SaaS applications and users, people, locations, stockrooms, contracts, subscriptions, custom objects, request portal requests, activity feeds, saved searches, and bulk operations. Authentication: Choose one of two methods when you connect. An Oomnitza API token (recommended for Oomnitza API v3) or Basic authentication with a service account username and password. You enter your choice along with your Oomnitza domain. Data sync: On-demand only. Serval calls Oomnitza when a workflow runs and when you run the connection’s health checks - there is no background sync, entity ingestion, or webhook subscription.

​
What the Oomnitza integration enables

Anything defined in the Oomnitza API can be accessed through Serval.

​
Get your credentials

Serval authenticates with either an Oomnitza API token or a service account username and password. Either way, create a dedicated account rather than using a personal login - a dedicated account survives staff changes, makes the credential easier to audit and rotate, and its role can be scoped to exactly what your workflows need. See the Oomnitza REST API documentation for background on API access.
Oomnitza’s help center requires signing in with your Oomnitza account, so the documentation links on this page may prompt you to log in first.
1

Log in to your Oomnitza instance

Sign in at your organization’s URL, for example https://company.oomnitza.com.
2

Create a service account

Go to Configuration > User Management and create a new user with a role that has API access. Use a descriptive name such as Serval Integration Service.
3

Generate an API token

Go to Configuration > Security > API tokens and generate a token for the service account. The token is displayed only once, so copy it before you leave the page - it cannot be recovered afterward. You will enter it in the Serval connect form along with your domain.
Whichever method you use, the service account’s role needs at least read permission on Users, Assets, and Locations. Serval’s connection health checks probe all three modules, so a role missing any of them will show a failing connection even when your workflows only touch other objects.
Menu names can vary between Oomnitza versions. If you do not see Configuration > User Management or Configuration > Security > API tokens, check Oomnitza’s documentation for where user roles, accounts, and API tokens are managed in your instance.

​
Connect in Serval

1

Open the Oomnitza connect form

In Serval, open the Oomnitza integration and start a new connection.
2

Enter your Oomnitza Domain (required)

Type the bare hostname of your instance, for example company.oomnitza.com - the placeholder and helper text (“Your Oomnitza domain (e.g., company.oomnitza.com)”) show the expected shape. An https:// prefix, a trailing slash, a path, bare oomnitza.com, or a nested subdomain is rejected with “Please enter a valid Oomnitza domain (e.g., company.oomnitza.com)”. Leaving it blank flags “This field is required”. This domain also becomes the connection’s display name in Serval.
3

Choose an Authentication Method

Pick API token or Basic authentication. The form defaults to API token and shows only the credential fields for the method you select.
4

Enter the credential for your chosen method

For API token, enter the token you generated in Oomnitza (helper text: “Your Oomnitza API token from Configuration > Security > API tokens”). For Basic authentication, enter your service account Username and Password. After saving, Serval only ever displays the token or password obfuscated - bullet characters followed by its last 4 characters.
5

Save the connection

Save, then verify the connection using the health checks below.
When editing an existing connection: the domain appears in plain text, and the stored secret (the API token, or the username and password for Basic auth) appears obfuscated with a Replace button. Leave the secret untouched and the stored credentials are kept as-is. For Basic auth, the username and password are stored as a pair, so to change either one, click Replace and enter both. Leaving the domain blank keeps the previously saved domain. After you save changes, Serval automatically re-runs the connection’s health checks.

​
Verifying the connection

The integration ships three health checks, each fetching a single record from your instance. Run them from the connection’s page in Serval; they also run automatically after you save changes to the connection. On failure you will see, respectively: “Unable to list Oomnitza users. Please verify your API key is valid.”, “Unable to list Oomnitza assets. Please verify your API key has the required permissions.”, and “Unable to list Oomnitza locations. Please verify your API key has the required permissions.”
If “List Oomnitza Users” passes but the assets or locations checks fail, your credentials are fine - the service account’s role is missing read permission on the Assets or Locations module. Grant the role read access in Oomnitza, then run the checks again.

​
Gotchas and troubleshooting

The Oomnitza Domain field accepts exactly one subdomain of oomnitza.com - enter company.oomnitza.com and nothing else. An https:// prefix, a trailing slash, any path, bare oomnitza.com, a nested subdomain (like a.b.oomnitza.com), or a non-oomnitza.com host all fail with “Please enter a valid Oomnitza domain (e.g., company.oomnitza.com)”.
API token is recommended for Oomnitza API v3 and is the form’s default - generate one under Configuration > Security > API tokens. Use Basic authentication (service account username and password) only if your Oomnitza tenant requires it. Serval shows only the credential fields for the method you select, so set the Authentication Method selector before entering credentials.
Serval stores your token (or your username and password) as a single API-key-style credential, so failure messages reference “your API key”. Read them as: the token or username/password is wrong, or the account’s role lacks read permission on the module that check probes (Users, Assets, or Locations).
For Basic authentication, the username and password are stored and updated as a pair, and the pair is only replaced when both fields are submitted with real values. If you edit the username but leave the password untouched (still showing its obfuscated value), the previous username and password stay in place. To change either one, click Replace on the password field and enter the password along with the username.
Serval injects credentials only for requests to version 3 of the Oomnitza REST API on your oomnitza.com domain. Calls to other Oomnitza paths or older API versions receive no credentials and will fail to authenticate.
Three things to know when using the Oomnitza API action in workflows. First, use curly-brace placeholders (such as {ident}) with path parameters - colon-style placeholders are not substituted. Second, list endpoints paginate with skip and limit query parameters and return a plain JSON array: keep paging until a page returns fewer items than the limit. Third, updating non-system edit-only fields on create and edit calls requires the optional Oomnitza-Ignore-Meta-Restriction header (values 0 or 1) set to 1.
Need help? Contact support@serval.com for assistance with your Oomnitza integration.