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

# ServiceNow

> Integration details and setup guide for the ServiceNow connector in Alloy Automation.

## Pre-Built Tooling

| Category                            | Details                                               |
| ----------------------------------- | ----------------------------------------------------- |
| **Authentication**                  | Basic Authentication (Username & Password with Token) |
| **Two-Way Sync**                    | Yes                                                   |
| **Events Supported**                | Yes                                                   |
| **Realtime**                        | Yes (via Business Rules and Script Actions)           |
| **Supports Rate Limiting**          | Yes                                                   |
| **Authentication Scopes Supported** | N/A (Permission-based via roles)                      |

***

## Objects Supported

Alloy Automation supports syncing the following objects from **ServiceNow**:

* **Incidents**
* **Cases**
* **Change Requests**
* **Problems**
* **Service Catalog Items**
* **Users**
* **Configuration Items (CIs)**
* **Knowledge Articles**

***

## Set Up Guide

### Trial Access

| Question                                           | Answer                                                                                                                                    |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Offers free trial?**                             | Yes. ServiceNow offers a Personal Developer Instance (PDI) for free, forever. [Request free PDI](https://developer.servicenow.com/dev.do) |
| **Requires paid sandbox**                          | No. The PDI provides full functionality for development and testing.                                                                      |
| **Requires partnership to obtain authentication?** | No. Anyone can create a developer instance and obtain credentials.                                                                        |

***

### Authentication (Basic Auth + Token)

ServiceNow uses Basic Authentication with username, password, and an authentication token appended to the password.

<step>
  ## Step 1: Request a Personal Developer Instance

  1. Visit **ServiceNow Developer Portal** ([https://developer.servicenow.com/](https://developer.servicenow.com/))
  2. Click **Sign Up and Start Building**
  3. Create an account or log in with existing credentials
  4. Navigate to **Manage** > **Instance**
  5. Click **Request Instance**
  6. Select the latest ServiceNow release
  7. Wait a few minutes for your instance to provision
  8. Your instance URL will be in the format: `https://devXXXXXX.service-now.com`
</step>

<step>
  ## Step 2: Log Into Your Instance

  1. Use the instance URL provided (e.g., `https://dev123456.service-now.com`)
  2. Log in with the admin credentials:
     * **Username**: `admin`
     * **Password**: The password provided during instance creation (check your email)
  3. You now have full administrator access to your ServiceNow instance
</step>

<step>
  ## Step 3: Create an Integration User (Recommended)

  1. In ServiceNow, navigate to **User Administration** > **Users**
  2. Click **New** to create a new user
  3. Fill in the required fields:
     * **User ID**: e.g., `integration_user`
     * **First Name**: Integration
     * **Last Name**: User
     * **Email**: Your email address
  4. Set a strong password
  5. Assign necessary roles:
     * **rest\_api\_explorer** (for API access)
     * **itil** (for Incident, Case, Problem access)
     * Additional roles based on your integration needs
  6. Click **Submit**
</step>

<step>
  ## Step 4: Generate an Authentication Token (Optional but Recommended)

  1. Log in as the integration user
  2. Navigate to **System Security** > **User Authentication Tokens**
  3. Click **New**
  4. Select the user for whom to create the token
  5. Copy the generated token
  6. When authenticating with Alloy Automation, append the token to the password:
     * Format: `password<token>`
     * Example: If password is `MyPass123` and token is `xyz789`, use `MyPass123xyz789`
</step>

<step>
  ## Step 5: Configure Alloy Automation

  1. In Alloy Automation, configure your ServiceNow connector
  2. Provide:
     * **Instance Name**: Your ServiceNow instance subdomain (e.g., `dev123456`)
     * **Username**: Your integration user username
     * **Password**: Your password with token appended (e.g., `MyPass123xyz789`)
  3. Test the connection by retrieving incidents or cases
</step>

***

## Use Cases

### 1) Automated incident creation

Automatically create ServiceNow incidents from monitoring tools, error tracking systems, or customer support platforms when issues are detected, ensuring rapid response and proper tracking.

### 2) IT service management integration

Sync ServiceNow change requests, problems, and incidents with project management tools, development platforms, and communication tools to keep IT teams aligned.

### 3) Asset and configuration management

Integrate ServiceNow CMDB with discovery tools, cloud platforms, and inventory systems to maintain an accurate, real-time view of IT infrastructure and assets.

### 4) Knowledge base automation

Automatically create or update knowledge articles in ServiceNow based on resolved incidents, support tickets, or documentation from external systems.

### 5) Self-service portal integration

Connect ServiceNow's service catalog with internal portals, allowing employees to request services, track approvals, and receive updates through integrated workflows.

***

## API Gotchas

* **Authentication Token Required for Production:** For production ServiceNow instances, authentication tokens are mandatory for API access. Append the token to the password when making API calls: `password<token>`.

* **Table API vs. Aggregate API:** ServiceNow offers multiple APIs. The Table API is most common for CRUD operations, but consider the Import Set API for bulk imports or the Aggregate API for reporting queries. Choose the right API for your use case.

* **sysparm\_fields and sysparm\_query:** ServiceNow APIs support query parameters to filter results and select specific fields. Use `sysparm_fields` to reduce payload size and `sysparm_query` to filter records with encoded query strings.

* **Display Values vs. Actual Values:** By default, ServiceNow returns sys\_ids and reference field IDs. Use `sysparm_display_value=true` to get human-readable values, or `sysparm_display_value=all` to get both sys\_id and display value.

* **Rate Limiting and Throttling:** ServiceNow implements rate limiting to prevent abuse. Limits vary by instance type and configuration. Monitor for 429 status codes and implement exponential backoff. Consider using batch APIs for high-volume operations.

* **Scoped Applications:** ServiceNow uses scoped applications for modularity. Custom tables and fields may be scoped (e.g., `x_custom_app_table`). Ensure your integration user has access to the correct scopes and applications.

> For questions or troubleshooting, contact **[support@runalloy.com](mailto:support@runalloy.com)**.