## Overview

The Assembled ServiceNow integration brings operational data from your ServiceNow instance into Assembled so you can monitor performance, build forecasts, and track adherence.

After you connect ServiceNow, Assembled ingests two main categories of data:

1. **Agent state data** — powers real-time adherence and intraday monitoring.
2. **Work item (ticket/task) data** — powers staffing analysis, historical reporting, forecasting, scheduling context, and queue configuration.

The integration is **read-only**. Assembled does not write data back to ServiceNow.

**Who can set up the integration:** Only Assembled **admins** can connect and manage the ServiceNow integration from **Settings → Integrations**.

**To connect your instance:** Follow the step-by-step instructions in [How to Connect ServiceNow](https://support.assembled.com/hc/en-us/articles/45353222209933-How-to-Connect-ServiceNow).

* * *

## What data Assembled syncs

### Agent state data

**Purpose:** Real-time adherence, agent state timelines, and intraday views.

| Detail | Behavior |
| --- | --- |
| Source | ServiceNow Advanced Work Assignment (AWA) presence history (`awa_agent_presence_history`) |
| Sync frequency | Approximately every **30 seconds** (near real-time) |
| Historical backfill | **Not supported.** Agent state data is available only from the time the integration is enabled forward. |
| Requirement | Your ServiceNow instance must actively record agent presence. If presence data is not populated, adherence based on agent states will not work until your ServiceNow configuration is updated or an alternative approach is agreed with Assembled. |

When ServiceNow reports an **Offline** presence state, Assembled maps it to Assembled's internal offline state for consistency across products.

### Work items (tickets / tasks)

**Purpose:** Volume, handle times, queue mapping, forecasting, staffing analysis, and performance reporting.

| Detail | Behavior |
| --- | --- |
| Supported objects | Configurable per customer. Common sources include **task-based tables** (for example, tasks, interactions, and customer-specific case tables). Additional table types (such as incidents or service requests) may require a schema review with your ServiceNow admin and Assembled before go-live. |
| Sync mechanism | Incremental polling based on `sys_updated_on` |
| Sync frequency | Approximately every **5 minutes** |
| Lookback window | **30 minutes** on each sync to reduce the risk of missed updates due to ServiceNow processing delays |
| Historical backfill | **Supported** for work item data, as long as records exist in ServiceNow and your OAuth credentials can read the configured tables |

Assembled maps common ServiceNow fields into tickets, including created/updated timestamps, status, assignee, channel (from contact type where available), assignment group, and related metadata used for **Queues and exclusions** keyword mapping.

**Queue mapping keywords** available for ServiceNow include:

- Assignment group
- Category
- Service
- Product

### Time worked (when enabled)

For some customers, Assembled also syncs **time worked** records from a ServiceNow time-tracking table. This data can supplement adherence and handle-time reporting when presence alone is not sufficient.

Time worked sync runs on a frequent schedule (approximately every **30 seconds**, with overlapping jobs for consistency). Whether this applies to your account depends on your ServiceNow schema and is configured by Assembled during implementation — not in the standard connection form.

* * *

## How syncing works

```auto
flowchart LR
    SN[ServiceNow instance]
    SN -->|Agent presence history| A[Agent states sync ~15s]
    SN -->|Work items by sys_updated_on| B[Ticket sync ~5 min]
    SN -->|Time worked optional| C[Handle times sync ~30s]
    A --> ASB[Assembled]
    B --> ASB
    C --> ASB
```

**Agent states:** Incremental updates from presence history. No backfill.

**Work items:** Incremental updates using `sys_updated_on`, with a 30-minute lookback on routine syncs. Historical backfill is available for tickets and time worked (when configured).

**Users:** Assembled discovers agents from ServiceNow user records (matched by email) based on the **group types** and **group IDs** you provide at connection time. Users without an email in ServiceNow may not map correctly to Assembled people.

* * *

## Authentication and permissions

### Authentication method

- **OAuth (server-to-server)** using a ServiceNow **Client ID** and **Client Secret**
- Credentials are stored securely and used by Assembled for all API requests

### Permission scope

Your OAuth application should have **read-only** access, scoped to only the tables required for your integration. Typical tables include:

| Table / data | Purpose |
| --- | --- |
| Users | Agent discovery and platform association |
| Presence / agent state | `awa_agent_presence_history` (and related presence metadata) |
| Work item tables | Tasks, cases, or other configured ticket/task tables |
| Time worked (if used) | Equivalent time-tracking table in your instance |

**No write access** is required.

* * *

## Configuration and adaptability

ServiceNow deployments vary widely. The integration is designed to adapt to your instance, but some configuration is done **with Assembled** rather than entirely self-serve:

| Setting | Where it is configured |
| --- | --- |
| Instance URL, API URL, OAuth domain, Client ID/Secret, group types, group IDs | **Connection form** in Assembled (see [How to Connect ServiceNow](https://support.assembled.com/hc/en-us/articles/45353222209933-How-to-Connect-ServiceNow)) |
| **Which ServiceNow tables** to sync for work items | **Assembled configuration** (per customer) |
| **Field mappings** and queue keyword behavior | **Queues and exclusions** in Assembled, using ServiceNow keyword types |
| **Time worked** table (if applicable) | **Assembled configuration** during implementation |

### Before you go live

We recommend a short **schema review** with your ServiceNow administrator and Assembled before production setup to:

- Confirm required fields exist on your chosen tables
- Identify any data gaps (especially for presence/adherence)
- Validate that adherence tracking is feasible with your current ServiceNow setup

Most ServiceNow task-style tables share similar core fields, which often reduces customization effort — but instance-specific validation is still important.

* * *

## Where to use ServiceNow data in Assembled

| Assembled area | ServiceNow data used |
| --- | --- |
| **Realtime → Agent analysis** | Agent states and adherence |
| **Queues and exclusions** | Incoming work items; map channels and queues via keywords |
| **Forecasting & staffing** | Historical ticket/work item volume |
| **Reports & metrics** | Handle time, volume, and performance (where configured) |
| **People / agent mapping** | ServiceNow user IDs associated with Assembled agents |

* * *

## Limitations and considerations

- **No historical agent state backfill.** Plan accordingly if you need adherence history before the integration was enabled.
- **Real-time adherence depends on presence data.** You need active presence tracking in ServiceNow (or a validated alternative, such as reliable time-worked data, where enabled).
- **Instance-specific behavior.** Custom tables, fields, and workflows may require iteration with Assembled support.
- **Table selection is not fully self-serve.** After connecting OAuth, tell your Assembled contact which tables and use cases you need so work item sync can be configured.
- **Email required for user matching.** ServiceNow users without email addresses may not appear as mappable agents in Assembled.
- **Read-only integration.** Assembled never modifies records in ServiceNow.

* * *

## Verifying the integration

After connecting, confirm data is flowing:

1. **Realtime → Agent analysis** — agent states and adherence should update for mapped agents.
2. **Queues and exclusions** — set the time range to **Last hour** and confirm expected volume appears in the relevant channel tiles.

If either view shows zero or unexpected results, contact [support@assembled.com](mailto:support@assembled.com) or your Deployment Strategist.

For connection troubleshooting, see [How to Connect ServiceNow](https://support.assembled.com/hc/en-us/articles/45353222209933-How-to-Connect-ServiceNow).

* * *

## Getting help

- **Setup and connection:** [How to Connect ServiceNow](https://support.assembled.com/hc/en-us/articles/45353222209933-How-to-Connect-ServiceNow)
- **Schema review, table configuration, or adherence feasibility:** Contact your Assembled Deployment Strategist or [support@assembled.com](mailto:support@assembled.com)