# Set up ServiceNow CMDB

Setting up this connector is a guided sequence of seven steps. You can move
back at any point, and nothing is created until the last step.

Have your instance URL and a credential ready before you start — see
[what you need](./index.md#what-you-need-before-you-start).

> **note**
Steps 3 to 7 are all choices, and every one of them has a sensible default. If
you are setting this up for the first time, you can accept what is already
selected and change it later.

## Open the connector list

Select the settings icon in the top bar.

![The Mesh top bar, with the settings icon beside the search box](/img/connectors/servicenow-cmdb/cmdb-01-settings.png)

Choose **Connectors**.

![The Settings menu, with Connectors in the list](/img/connectors/servicenow-cmdb/cmdb-02-settings-menu.png)

Select **Add connector**.

![The Connectors page, with the Add connector button above the list](/img/connectors/servicenow-cmdb/cmdb-03-connectors.png)

Choose **ServiceNow CMDB** under **Guided setup**.

![The Add connector panel, with ServiceNow CMDB under Guided setup](/img/connectors/servicenow-cmdb/cmdb-04-add-connector.png)

> **note**
Guided setup is the only way to create this connector, and the same sequence
opens again when you edit it later. If the entry is greyed out, guided setup
has not been switched on for your tenant yet — contact Axiad.

## Step 1 — Identify

Name the connector and tell Mesh which instance to read.

| Field | Required | What to enter |
| --- | --- | --- |
| **Connector name** | Yes | A label of your choosing. It appears in the connector list and in reports, and you can change it later |
| **ServiceNow instance URL** | Yes | Your instance address, for example `https://acme.service-now.com` |

![Step 1, Identify, with the connector name and ServiceNow instance URL fields](/img/connectors/servicenow-cmdb/cmdb-05-step1-identify.png)

Rules for the instance URL:

| Rule | Allowed | Not allowed |
| --- | --- | --- |
| HTTPS only | `https://acme.service-now.com` | `http://acme.service-now.com` |
| A `service-now.com` address | `https://acme.service-now.com` | `https://cmdb.example.com` |
| The address only — no path or query | `https://acme.service-now.com` | `https://acme.service-now.com/nav_to.do` |
| No credentials in the URL | `https://acme.service-now.com` | `https://user:pass@acme.service-now.com` |

A trailing slash is accepted, and so is an explicit `:443`. Any other port is
not.

> **warning**
Every record Mesh collects is attributed to this instance. To read a second
instance, add a second connector rather than changing this one.

## Step 2 — Authenticate

Choose how Mesh signs in, then fill in only that method's fields.

| Method | What you enter | Use it when |
| --- | --- | --- |
| **api key** | API key | Your instance issues API keys for integrations |
| **bearer** | Bearer token | You already hold a token issued for this integration |
| **basic** | Username, password | A service account signs in directly |
| **oauth2 client credentials** | Client ID, client secret, token URL (optional) | An OAuth application integrates on its own behalf |
| **oauth2 password** | Client ID, client secret, username, password, token URL (optional) | An OAuth application integrates **as a named service account** |

![Step 2, Authenticate, with the api key method selected](/img/connectors/servicenow-cmdb/cmdb-06-step2-api-key.png)

Selecting a different method replaces the fields below the cards. The bearer
method asks for a single token:

![Step 2 with the bearer method selected, asking for a bearer token](/img/connectors/servicenow-cmdb/cmdb-07-step2-bearer.png)

Both OAuth methods ask for a client ID and a client secret:

![Step 2 with oauth2 client credentials selected, asking for a client ID, client secret and optional token URL](/img/connectors/servicenow-cmdb/cmdb-08-step2-oauth-client.png)

**oauth2 password** adds a username and password to those, so the OAuth
application acts as that account:

![Step 2 with oauth2 password selected, asking for client ID, client secret, username, password and optional token URL](/img/connectors/servicenow-cmdb/cmdb-09-step2-oauth-password.png)

### Which method to ask for

Start with whichever your ServiceNow administrator already provisions for
integrations. If you have a free choice, the two OAuth methods are preferable:
the credential can be revoked on its own without disturbing the account.

> **tip**
Instances are often provisioned for one OAuth grant and not the other. A
common pattern is that **basic** is refused and **oauth2 client credentials**
reports that the integration user is not configured for OAuth, while
**oauth2 password** works — because the OAuth application is registered
against a named account rather than on its own behalf. If an OAuth method
fails and your administrator confirms the client is active, try the other one
before assuming the credential is wrong.

### Things worth knowing

| | |
| --- | --- |
| **Fill in one method only** | Enter the credentials for the method you selected and leave the others empty. A configuration carrying credentials for more than one method is refused |
| **The token URL is optional** | Leave it empty and Mesh uses your instance's standard token endpoint. Set it only if your instance issues tokens somewhere else |
| **The client ID is not a secret** | It is a public identifier. It is shown back to you when you edit the connector. Never paste the client secret into this field |
| **Secrets are never shown again** | The client secret, password, API key and bearer token are stored encrypted. When you edit the connector later, leave a secret field empty to keep the stored value |

**Test connection** on this step checks the credential on its own, before you
choose any data. You can continue once it passes.

## Step 3 — Choose data

Choose which ServiceNow tables Mesh reads. Each one is a group of records
rather than a single field, and the panel header counts how many of the
eleven you have selected.

![Step 3, Choose data, listing the standard ServiceNow table groups with checkboxes](/img/connectors/servicenow-cmdb/cmdb-10-step3-choose-data.png)

| Table group | ServiceNow table | Becomes in Mesh | Selected by default |
| --- | --- | --- | --- |
| **Configuration items** | `cmdb_ci_computer` | Machine assets | Yes |
| **Installed software** | `cmdb_sam_sw_install` | Software assets | Yes |
| **People** | `sys_user` | User accounts | Yes |
| **Groups** | `sys_user_group` | Groups | Yes |
| **Group memberships** | `sys_user_grmember` | Who belongs to which group | Yes |
| **Organizations** | `cmn_department` | Organization context | Yes |
| **Locations** | `cmn_location` | Location records | Yes |
| **Certificates** | `cmdb_ci_certificate` | Certificate records | Yes |
| **Vulnerabilities** | `sn_vul_vulnerability` | Inventory records | No |
| **Containers** | `cmdb_ci_docker_container` | Software assets | No |
| **Software catalog** | `cmdb_sam_sw_discovery_model` | Software assets | No |

> **warning**
Correlations, risk scores and dashboards that draw on a group are incomplete
without it. The eight selected by default are the ones most of Mesh depends
on — clear one only when you have a reason.

> **note**
Mesh reads containers into your software inventory. **Software catalog** is
also software: it is the models that connect installations to licenses and
services, and two of the recommended relationships in Step 5 need it.

### Adding a table Mesh does not read by default

If your organization keeps asset data in a table that is not in the list,
choose **Add a custom ServiceNow table**.

![The Add a custom ServiceNow table form, with name, table path and information type](/img/connectors/servicenow-cmdb/cmdb-11-step3-custom-table.png)

| Field | What to enter |
| --- | --- |
| **What should Mesh call this table?** | A short name in lowercase letters, numbers and underscores, starting with a letter — for example `business_applications` |
| **ServiceNow table path** | The API path exactly as it appears in your instance, for example `/api/now/table/u_business_application` |
| **What kind of information is it?** | What these records represent in Mesh |

The information types are: machine, application, user, group, software
component, crypto asset, entitlement, location, organization, certificate and
ServiceNow software.

After you save the table, map its fields in Step 4. Three of them are
required: a **Record identity**, a **Display name**, and a date and time field
for **Last updated**.

> **tip**
Which table to read, and which of its fields mean what, depends on how your
CMDB is structured. Talk to Axiad before adding one — a table mapped to the
wrong information type produces records that look right but correlate badly.

## Step 4 — Understand fields

This step shows how ServiceNow fields become Mesh fields. For the standard
table groups the mapping is fixed — it is part of the connector, and the step
is there so you can see it rather than change it.

![Step 4, Understand fields, showing the locked mapping from ServiceNow fields to Mesh meanings](/img/connectors/servicenow-cmdb/cmdb-12-step4-fields.png)

Each group expands to a table with the ServiceNow field on the left and what
Mesh does with it on the right. **Configuration items**, for example, maps
thirteen fields:

| ServiceNow field | Mesh meaning |
| --- | --- |
| `sys_id` | Record identity |
| `name` | Display name |
| `manufacturer` | Supplier |
| `assigned_to` | Owner |
| `install_status` | Lifecycle state |
| `location` | Location |
| `department` | Organization |
| `install_date` | Install date |
| `serial_number` | Serial number |
| `os` | Operating system |
| `os_version` | OS version |
| `fqdn` | Fully qualified host name |
| `sys_updated_on` | Change tracking |

Use **Visual map** instead of **Table view** to see the same thing as a
diagram.

A **custom table** you added in Step 3 is the one case where you do set the
mapping, and you do it here, in plain language.

> **note**
Mesh reports what your CMDB holds. A machine with no manufacturer in
ServiceNow arrives with no supplier in Mesh rather than a guess.

## Step 5 — Connect related

Some of the most useful detail is not on the record itself — a computer's
manufacturer is a reference to another table, not a name. This step tells Mesh
which of those references to follow.

Everything here is optional. A connector with no relationships is a valid
connector.

![Step 5, Connect related, listing the recommended relationships](/img/connectors/servicenow-cmdb/cmdb-13-step5-recommended.png)

### Recommended relationships

| Relationship | What it adds | Reads from | Needs this group selected |
| --- | --- | --- | --- |
| **Computer → manufacturer** | The manufacturer name on each configuration item | Manufacturer company | Configuration items |
| **Software catalog → installed products** | Links software models to the products installed | Software product | Software catalog |
| **Software catalog → owner** | The company a software license is held by | License owner company | Software catalog |
| **Certificate → host** | Matches a certificate name to the host it runs on | Computer host | Certificates |
| **Group → members** | The people in each group, through the membership table | Group member | Groups |

Select **Use this** to add one.

> **warning**
The source has to be one of the table groups selected in Step 3, or the
relationship is refused when you check it. Two of the recommended
relationships read from **Software catalog**, which is **not** selected by
default — go back to Step 3 and select it first if you want them.

### Building your own

Choose **build one from the beginning** to describe a relationship yourself. A
relationship is one or more **hops**: at each hop you name a field on the
record you have, the table it points into, and the field in that table that
matches.

![The relationship builder, with the first hop's source field, lookup table and matching field](/img/connectors/servicenow-cmdb/cmdb-14-step5-hops.png)

| Setting | What it means |
| --- | --- |
| **Use a field on the source record** | The field that points at the other record |
| **Lookup table** | The table that field points into |
| **Matching field** | The field in that table the value matches, usually `Record ID` |
| **The source field is a ServiceNow reference** | Select this when the field is a ServiceNow reference rather than plain text |
| **+ Add another hop** | Follow a second step, when what you want is one table further out |
| **This relationship uses a many-to-many membership table** | Select this when the link is a membership table rather than a direct reference. You then name the field that points from the membership table to the related record |

Last, choose what to bring back: the field on the far record, and the Mesh
meaning to put it under.

![The relationship builder with the fields to bring back and the option to save it as custom](/img/connectors/servicenow-cmdb/cmdb-15-step5-custom.png)

Select **Check relationship setup** to validate everything before you
continue. Each saved relationship can be edited or removed from the list.

> **tip**
Opening a recommended relationship and adjusting it is easier than starting
with an empty builder — the hops are already filled in correctly. Saving
changes keeps it as your own copy.

## Step 6 — Tuning

How often Mesh reads, how fast it calls the API, and how much one run
collects. The defaults suit most instances.

![Step 6, Tuning, with the six pace and limit settings](/img/connectors/servicenow-cmdb/cmdb-16-step6-tuning.png)

| Setting | Default | Choices | What it changes |
| --- | --- | --- | --- |
| **How often Mesh reads** | Every hour | 15 minutes, 1 hour, 4 hours, 12 hours, 24 hours | How quickly a CMDB change reaches Mesh, against load on your instance |
| **Request rate** | Standard · 8 / sec | Gentle 4 / sec, Standard 8 / sec, Fast 16 / sec | How fast Mesh calls the API |
| **If ServiceNow stops responding** | Standard · 3 attempts | 2, 3 or 5 attempts | How long Mesh keeps trying before the run fails |
| **Rows per page (software installations)** | 10,000 rows | 500, 2,000, 5,000, 10,000, 20,000 | How many rows one response carries |
| **Records per run** | 50,000 records | 25,000 to 200,000 | How much one run collects before stopping |
| **Requests per run** | 100,000 requests | 50,000, 100,000, 200,000 | A ceiling on API calls per run |

> **tip**
If your instance is shared with other integrations, **Gentle** is the setting
that reduces pressure without making your data older. Reading less often has
a bigger effect on how current Mesh is.

> **note**
When a run reaches **Records per run** it stops and the next run carries on
from where it left off. A large CMDB loads over several runs rather than
failing.

## Step 7 — Review and create

Check the summary, then select **Test connection**.

![Step 7, Review and create, with the summary and the Test connection button](/img/connectors/servicenow-cmdb/cmdb-17-step7-review.png)

**Create connector** stays unavailable until the test passes.

![Step 7 after a successful test, with Create connector available](/img/connectors/servicenow-cmdb/cmdb-18-step7-tested.png)

A pass means ServiceNow accepted the credential and table access was
confirmed. If it fails, see [Troubleshooting](./troubleshooting.mdx).

Select **Create connector**. The connector appears in the list and the first
collection starts.

> **note**
Mesh reads your whole CMDB the first time. On a large estate this takes
several runs. You can use Mesh meanwhile, though data is incomplete until it
finishes.

## Check that it worked

1. Open **Settings › Connectors** and find your connector.
2. Watch **Sync status** go from **Starting** to **Good**.
3. For run-by-run detail, open the row menu and choose **Logs**, or open
   **Settings › Data source syncs**. See
   [Data source synchronizations](../../../admin-guide/audit-logging.md#data-source-synchronizations).

## Change a connector later

Open the row menu on the connector and choose **Edit**. The same seven steps
open again with your answers filled in.

Every answer can be changed, including the instance URL and the
authentication method. Leave a secret field empty to keep the credential
already stored, and the connection test has to pass again before you can save.

Changes to what is collected apply on the next run.

> **caution**
A stored secret is only ever reused with the instance and the method it was
saved for, so **changing the instance URL** or **changing the authentication
method** means entering the credentials again from scratch.

> **tip**
Every record Mesh has collected through this connector is attributed to the
instance it came from. Pointing an existing connector at another instance re-attributes that
history. Unless you are correcting a typo, add a second
connector instead.
