> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Oomnitza

> Connect Serval to your Oomnitza instance with a dedicated service account to automate IT asset management workflows across assets, software, SaaS, people, locations, and contracts.

## About Oomnitza

[Oomnitza](https://www.oomnitza.com) 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

| Capability                        | Description                                                                                                                                                                 |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Asset management                  | List, search, create, create-or-update, edit, and delete hardware assets; read each asset's installed software, change history, and saved searches.                         |
| Accessories and kits              | Full create, read, update, and delete for accessories and kits, plus search, change history, and saved searches.                                                            |
| Software and license tracking     | Create, list, search, edit, and delete software titles; see which assets have each title installed, and read change history and saved searches.                             |
| SaaS and SaaS user management     | Manage SaaS records, SaaS roles and role members, and the users assigned to each SaaS, including activating or deactivating SaaS users.                                     |
| People and user records           | Create, list, search, edit, and delete Oomnitza user records; read a user's assets, SaaS and software assignments, profile settings, change history, and saved searches.    |
| Locations and stockrooms          | Full create, read, update, and delete for locations and stockrooms, plus search, change history, and saved searches.                                                        |
| Contracts and subscriptions       | Create, search, edit, and delete contracts; read each contract's licenses, change history, and saved searches; and full create, read, update, and delete for subscriptions. |
| Custom objects                    | Define custom objects and create, search, create-or-update, edit, and delete their records, including change history.                                                       |
| Activity feed and bulk operations | Read the user activity feed with filters, run bulk edit and bulk delete jobs with status polling, activate Oomnitza workflows, and read connector run logs.                 |

Anything defined in the [Oomnitza API](https://oomnitza.zendesk.com/hc/en-us/articles/17200339347991-Oomnitza-REST-APIs) 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](https://oomnitza.zendesk.com/hc/en-us/articles/17200339347991-Oomnitza-REST-APIs) for background on API access.

<Note>
  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.
</Note>

<Tabs>
  <Tab title="API token (recommended)">
    <Steps>
      <Step title="Log in to your Oomnitza instance">
        Sign in at your organization's URL, for example [https://company.oomnitza.com](https://company.oomnitza.com).
      </Step>

      <Step title="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**.
      </Step>

      <Step title="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.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Username and password">
    <Steps>
      <Step title="Log in to your Oomnitza instance">
        Sign in at your organization's URL, for example [https://company.oomnitza.com](https://company.oomnitza.com).
      </Step>

      <Step title="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**.
      </Step>

      <Step title="Record the credentials">
        Note the username and password - you will enter them in the Serval connect form along with your domain.
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Warning>
  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.
</Warning>

<Note>
  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.
</Note>

## Connect in Serval

<Steps>
  <Step title="Open the Oomnitza connect form">
    In Serval, open the Oomnitza integration and start a new connection.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Save the connection">
    Save, then verify the connection using the health checks below.
  </Step>
</Steps>

<Note>
  **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.
</Note>

## 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.

| Health check            | What it verifies                                          | Success message                                          |
| ----------------------- | --------------------------------------------------------- | -------------------------------------------------------- |
| List Oomnitza Users     | The stored credentials authenticate against your instance | "Successfully connected to Oomnitza and retrieved users" |
| List Oomnitza Assets    | The service account can read asset records                | "Successfully retrieved assets from Oomnitza"            |
| List Oomnitza Locations | The service account can read location records             | "Successfully retrieved locations from Oomnitza"         |

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."

<Tip>
  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.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="My domain keeps getting rejected">
    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)".
  </Accordion>

  <Accordion title="Which authentication method should I use?">
    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.
  </Accordion>

  <Accordion title="Health checks mention an API key, but I connected a different way">
    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).
  </Accordion>

  <Accordion title="I changed the username, but the connection still uses the old one">
    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.
  </Accordion>

  <Accordion title="Some Oomnitza calls fail with authentication errors">
    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.
  </Accordion>

  <Accordion title="Notes for workflow builders">
    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.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Oomnitza integration.