# ServiceNow Catalog Integration

Connect AirHub® Portal to ServiceNow's Service Catalog for two-way work order sync, without requiring Field Service Management (FSM). Users submit a Drone Flight Request through the Service Catalog with a drawn map polygon; on submission, a Work Order is automatically created in AirHub® Portal. Status changes in AirHub® flow back to the originating ServiceNow Request Item (RITM) as state updates, work notes, deliverable URLs, and auto-closure of related catalog tasks.

#### Who this is for

This integration is for ServiceNow customers without Field Service Management (FSM) licensed. If your ServiceNow instance has FSM, see the [ServiceNow Work Order (FSM) Integration guide ](/integrations-setup-and-customizations/servicenow-work-order-fsm-integration.md)instead, which uses the standard Work Order table and is installed directly from the ServiceNow Store.

#### License

Requires Team License or higher.

#### Prerequisites

Collect the following before starting. Installation cannot be completed without these.

**From Airspace Link (contact** [**helpdesk@airspacelink.com**](mailto:helpdesk@airspacelink.com)**)**

* Webhook ID. A GUID that identifies your AirHub® organization.
* AirHub® API base URL. Sandbox or production endpoint.
* Confirmation that your ServiceNow instance base URL has been registered in AirHub®.

**From your side**

* ServiceNow admin credentials.
* An ArcGIS Online API key, obtained from Esri. Airspace Link does not provide this.
* The latitude and longitude of your primary service area, for setting the default map center.
* A Service Portal where end users will submit requests 

**Provide to Airspace Link before going live**

* Your ServiceNow instance base URL (e.g., <https://customer.service-now.com>).
* The inbound webhook URL generated during installation. The URL pattern is https\://\[instance].service-now\.com/api/x\_airli\_asl\_dr/airhub\_inbound/workorder.
* The API Key token generated during inbound authentication setup. Transmit via secure channel (password manager share or encrypted transfer), not plain email or chat.
* The header name AirHub® must use to transmit the token: x-sn-apikey.

#### Installation

Time required: about 30 minutes.

Technical level: ServiceNow admin. No development required.

This method installs the entire integration (all scripts, variables, widget, business rules, REST messages, and cross-scope privileges) in a single step using a ServiceNow Update Set XML file. If your instance does not permit Update Set imports, contact <helpdesk@airspacelink.com> for manual installation guidance.

**Step 1. Obtain the Update Set XML**

Request the file AirspaceLink\_Catalog\_Integration\_v1.1.xml from your Airspace Link implementation contact at <helpdesk@airspacelink.com>.

**Step 2. Import the Update Set**

1. Navigate to **All** → search Retrieved Update Sets → select **System Update Sets → Retrieved Update Sets**.
2. Click **Import Update Set from XML** in the Related Links section.
3. Click **Choose File**, select AirspaceLink\_Catalog\_Integration\_v1.1.xml, and click **Upload**.
4. The imported Update Set appears in the list as AirspaceLink Catalog Integration v1.1.
5. Click the Update Set name to open it.
6. Click **Preview Update Set**. ServiceNow will check for conflicts.
7. Review any warnings in the **Update Set Preview Problems** related list. For a fresh instance, there should be none. If there are conflicts, contact <helpdesk@airspacelink.com> before proceeding.
8. Click **Commit Update Set**.
9. Wait for the commit to complete. This typically takes 30 to 60 seconds.

**Step 3. Verify cross-scope privileges**

The Update Set includes all required cross-scope privileges, but ServiceNow occasionally imports them with **Status: Requested** instead of **Allowed**. This will cause the integration to fail silently.

1. Navigate to **System Applications → Application Cross-Scope Privileges**.
2. Filter where **Source Scope contains** AirspaceLink.
3. For each of the following records, confirm **Status is Allowed**. If any show Requested, open the record and change Status to **Allowed**.

| Target Name          | Operation   |
| -------------------- | ----------- |
| ScopedGlideElement   | Execute API |
| GlideAPI: properties | Execute API |
| sc\_req\_item        | Write       |
| RESTMessageV2        | Execute API |
| GlideDateTime        | Execute API |

**Step 4. Configure system property values**

{% hint style="info" %}
Do not skip this section. The Update Set creates the five required system properties. Four of them ship with empty values and must be filled in before testing. If workorder.webhookid is left empty, outbound calls will fail. If it is set to anything other than your own organization's Webhook ID, your Work Orders will route to the wrong AirHub® organization.
{% endhint %}

Navigate to **All** → type sys\_properties.list → press Enter. Search for x\_airli\_asl\_dr to filter to the integration's properties. Set the **Value** field on each:

| Property name                         | Ships with | Must change to                                                                                     |
| ------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------- |
| x\_airli\_asl\_dr.workorder.webhookid | empty      | Webhook ID GUID provided by Airspace Link for your organization                                    |
| x\_airli\_asl\_dr.api.base\_url       | empty      | AirHub® API base URL provided by Airspace Link (sandbox or production)                             |
| x\_airli\_asl\_dr.arcgis.api.key      | empty      | Your ArcGIS Online API key                                                                         |
| x\_airli\_asl\_dr.center.coordinates  | empty      | \[longitude, latitude] of your primary service area (e.g., \[-83.0493, 42.3449] for Detroit)       |
| x\_airli\_asl\_dr.api.timeout.ms      | 100        | No change needed in most cases. Increase only if AirHub® calls are timing out in your environment. |

After setting all values, re-run the property list query and verify each row shows a non-empty Value field. The api.timeout.ms row should still read 100 unless you intentionally changed it.

**Step 5. Make the Catalog Item visible**

The Drone Flight Request catalog item is imported but may not be visible in your Service Portal depending on your catalog structure.

1. Navigate to **Service Catalog → Catalog Definitions → Maintain Items**.
2. Open **Drone Flight Request**.
3. Confirm the **Catalogs** field includes your primary catalog (e.g., Service Catalog).
4. Confirm the **Category** is appropriate for your portal layout.
5. Confirm **Active** is checked.

**Step 6. Configure the Business Rule filter**

The Business Rule is configured to trigger on the catalog item from the source instance. On a new instance, the catalog item has a different sys\_id and the filter may not resolve correctly.

1. Navigate to **System Definition → Business Rules**.
2. Search for **AirHub - Catalog Operation Trigger**.
3. Open the record and go to the **When to run** tab.
4. In Filter Conditions, verify the Item field reads Drone Flight Request. If the Item field shows as empty or unresolved, click the magnifying glass and re-select **Drone Flight Request**.
5. Click **Update**.

**Step 7. Register your instance with Airspace Link**

Email <helpdesk@airspacelink.com> with:

* Your ServiceNow instance base URL.
* Confirmation that installation is complete and testing is ready to begin.

Airspace Link will confirm the instance is registered as an active source in AirHub® Portal.

### Inbound Authentication Setup

If you need bi-directional sync (AirHub® status updates flowing back to ServiceNow), complete the steps in the **Inbound Authentication Setup** section below before testing. Skip this section if outbound-only is sufficient.

**Step 1. Create the integration service account**

Navigate to **User Administration → Users**. Click **New** and configure:

* **User ID:** airhub.integration
* **First name / Last name:** AirHub / Integration
* **Web service access only:** checked
* **Internal Integration User:** checked
* **Active:** checked

Submit, then reopen the record. In the **Roles** related list, add:

| Role                                              | Purpose                                          |
| ------------------------------------------------- | ------------------------------------------------ |
| web\_service\_admin                               | Allows the user to invoke Scripted REST APIs     |
| x\_airli\_asl\_dr.user (if defined by your scope) | Grants scope-level access for the inbound script |

{% hint style="info" %}
Do not assign admin or any broad ITIL role. The service account should be limited to exactly what the inbound script needs to do (write to sc\_req\_item, close sc\_task).
{% endhint %}

**Step 2. Verify the Auth Parameter**

The Auth Parameter defines the HTTP header name AirHub® will use to transmit the API Key. ServiceNow ships a built-in Auth Parameter (Header for API Key) in Global scope that uses x-sn-apikey as the header name. This integration reuses that built-in record — no new Auth Parameter needs to be created.

To verify the built-in record exists and matches the expected values:

1. Navigate to **System Web Services → API Access Policies → Auth Parameters** (or sys\_auth\_profile\_api\_key\_parameter.list).
2. Open **Header for API Key**.
3. Confirm:
   * **Type:** Auth Header
   * **Parameter Name:** x-sn-apikey
   * **Application:** Global

Do not edit this record. It is shared by all ServiceNow APIs that use API Key authentication.

**Step 3. Verify the HTTP Authentication Profile**

The Update Set installs the Authentication Profile that binds the Auth Parameter to the API Key authentication mechanism. Verify it imported correctly.

1. Navigate to **System Web Services → API Access Policies → Authentication Profiles**.
2. Open **ASL Profile API Key**.
3. Confirm:
   * **Auth Parameter:** Header for API Key
   * **Application:** AirspaceLink Drone Flight Request (Catalog)

If this record is missing or shows a different Auth Parameter, the Update Set did not commit fully. Re-import or contact <helpdesk@airspacelink.com>.

**Step 4. Create the REST API Key**

This is the actual token AirHub® will use to authenticate inbound calls. The key is bound to the service account from Step 1 and to the application scope.

Before creating the key, confirm you are in the correct application scope: click the globe icon (top right) → **Developer → Application → AirspaceLink Drone Flight Request (Catalog)**. The Source field on the key will auto-populate from your current scope, so being in the wrong scope here is the most common cause of silent authentication failures later.

Navigate to **System Web Services → API Access Policies → REST API Key**. Click **New** and configure:

* **Name:** ASL API Key
* **Description:** API Key for AirspaceLink integration
* **User:** airhub.integration (the service account from Step 1)
* **Active:** checked
* **Source:** must read x\_airli\_asl\_dr. If it shows any other value, cancel and verify your developer scope before retrying.
* **Expiry:** Set per your security policy. A blank value means no expiration; for production, set a renewal date and add a calendar reminder.

Submit. ServiceNow generates the token and displays it once on the form (e.g., now\_J2ZUzh3mpcnqfW3a6Ustz...).

{% hint style="info" %}
Capture the token immediately. ServiceNow will obscure the token after navigation. If lost, the key must be regenerated.
{% endhint %}

**Step 5. Verify the API Access Policy**

The Update Set installs the API Access Policy that binds the Authentication Profile to the Scripted REST API. Verify it imported correctly.

1. Navigate to **System Web Services → API Access Policies**.
2. Open **ASL API Access Policy**.
3. Confirm:
   * **Active:** checked
   * **REST API:** AirHub Inbound
   * **Apply to all methods / resources / versions:** all checked
   * **REST API PATH:** x\_airli\_asl\_dr/airhub\_inbound
   * **Application:** AirspaceLink Drone Flight Request (Catalog)
4. In the **Authentication Profiles** related list, confirm **ASL Profile API Key** is present.

If the REST API PATH shows a different scope prefix (for example, x\_airli\_asl\_dfr/airhub\_inbound), the policy was bound to the wrong endpoint and inbound calls will not authenticate. Contact <helpdesk@airspacelink.com>.

**Step 6. Verify the Scripted REST API Security tab**

1. Navigate to **System Web Services → Scripted REST APIs**.
2. Open **AirHub Inbound**.
3. On the **Security** tab, confirm Requires authentication is checked.
4. Leave the legacy **Authentication Profiles** related list empty - the API Access Policy from Step 5 now controls authentication for this endpoint.

**Step 7. Transmit credentials to Airspace Link**

Send Airspace Link the following via a secure channel:

| Item                  | Value                                                                                          |
| --------------------- | ---------------------------------------------------------------------------------------------- |
| Inbound URL           | https\://\[customer-instance].service-now\.com/api/x\_airli\_asl\_dr/airhub\_inbound/workorder |
| Authentication method | API Key                                                                                        |
| Header name           | x-sn-apikey                                                                                    |
| Token                 | The value generated in Step 4                                                                  |
| Token expiry          | The date set in Step 4, or "none"                                                              |

Airspace Link confirms storage and registration before testing begins.

### Testing

**Test outbound sync**

1. Navigate to your Service Portal (e.g., /sp).
2. Find and open **Drone Flight Request**.
3. Confirm the map renders. The loading spinner should clear within a few seconds, leaving an interactive map.
4. Fill in all required fields and **draw a polygon** on the map using the polygon or rectangle tool.
5. Click **Order Now**.

**Verify in ServiceNow:** Open the resulting RITM (sc\_req\_item.list) and check the Activity stream. Within a few seconds you should see the work note:

*AirHub Sync Successful. Work Order created in AirHub Portal.*

**Verify in AirHub® Portal:** Navigate to **Manage → Work Orders**. The new Work Order should appear with the polygon rendered at the exact location where you drew it on the map.

**Test inbound sync**

Skip this section if you configured outbound-only sync. Coordinate with Airspace Link before running.

1. Submit a fresh request from the Service Portal to generate a Work Order in AirHub® Portal.
2. In AirHub® Portal, update the Work Order status: schedule it, mark it in progress, then complete it.
3. Watch the corresponding RITM in ServiceNow. Each status change should add a work note and update the RITM state accordingly.
4. On completion in AirHub® Portal, any related catalog tasks should auto-close.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://support.airspacelink.com/integrations-setup-and-customizations/servicenow-catalog-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.