Integration Guide with ServiceNow

Welcome to the official implementation guide for the Hector + ServiceNow integration.

⚙️ Functional Overview

The integration operates in two distinct layers: Data Dictionary Synchronization (Makers, Hardware Models) and Asset/CI Synchronization (Hardware and Configuration Items).

🧠 How it Works

Sync Direction (Hector → ServiceNow): This integration is unidirectional. Hector is the source of truth and pushes data to ServiceNow. Changes made directly in ServiceNow are not pulled back into Hector.

To ensure data integrity, Hector syncs information to ServiceNow in a specific, dependency-based order, driven entirely by your category mappings:

1. Category Mapping (The Gatekeeper): Hector pulls in your ServiceNow Model Categories so you can map them to your Hector Categories. Only elements belonging to these mapped categories will be synchronized.
2. Makers (Manufacturers): For the mapped categories, Hector syncs its “Makers” (defined at the part level) to create or update corresponding Manufacturers/Companies in ServiceNow.
3. Hardware Models: Once Makers are established, Hector creates or updates the specific Hardware Models, linking them to the mapped Model Category.
4. Assets & CIs: Finally, the physical assets are created. Hector uses the mapped Categories to determine the correct Asset Class and CI Class for each.
5. User Assignment: During asset creation, if it is assigned to a user in Hector, the system looks up that user by email in ServiceNow and automatically populates the assigned_to field.

✅ Key Capabilities

The Hector-ServiceNow integration is a professional-grade bridge designed to maintain a single source of truth for your IT hardware and configuration items. Core features include:

• 🔄 Automated Lifecycle Sync: Keep your assets, models, and makers perfectly aligned across both platforms without double data entry.
• 🏗️ Intelligent Class Routing: Hector automatically routes assets and CIs into their proper ServiceNow tables based on the specific CI and Asset classes defined in your Category mapping.
• 👥 Automatic Identity Mapping: When an asset is assigned in Hector, the system looks up the user’s email address in ServiceNow and automatically updates the Assignment field.
• ✨ Advanced CI Enrichment: Overcome standard ServiceNow limitations by mapping specific Hector fields directly to distinct CI Class fields, ensuring your CMDB is always rich with accurate data.
• 📊 Incremental Sync: After the initial full synchronization, only assets modified since the last successful sync are processed, keeping sync cycles fast and efficient.

🛡️ Configuration: ServiceNow API Setup

Hector requires API access and specific roles in your ServiceNow instance to act as the secure bridge between systems. Follow the steps below to create a dedicated integration user and grant it the required access.

Step 1: Create an Integration User

We recommend creating a dedicated service account for the Hector integration rather than using a personal admin account.

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., hector_integration
   • First Name / Last Name: e.g., “Hector” / “Integration”
   • Password: Set a strong password and save it — you will need it for the Hector configuration.
4. Click Submit to create the user.

Step 2: Assign Roles

Open the newly created user record, then scroll down to the Roles related list and click Edit. Add the following roles:

• cmdb_read
• model_manager
• personalize_dictionary
• rest_api_explorer
• sn_cmdb_editor
• snc_required_script_writer_permission

Click Save to apply the roles.

Step 3: Configure ACLs (Access Control Lists)

Depending on your ServiceNow instance’s security configuration, you may need to ensure the integration user has the following record-level ACL permissions. Navigate to System Security > Access Control (ACL) to verify or create these rules:

Table	Operation	Type
alm_asset	write	record
alm_asset	create	record
cmdb_ci	write	record
cmdb_ci	create	record
core_company	write	record
core_company	create	record

🛠️ Configuration: Hector Integration Settings

Now that your ServiceNow instance is ready, you can configure the integration in Hector. Navigate to Settings > Integrations > Inventory > ServiceNow and click Add.

🔐 Step 1: Connect & Validate

On the Authentication tab, enter the credentials you prepared in the ServiceNow API Setup:

Instance URL: Your full ServiceNow instance URL (e.g., https://YOURINSTANCE.service-now.com).

Username: The User ID of the integration service account you created.

Password: The password for the integration service account. This value is stored encrypted in Hector.

Click Validate. During validation, Hector tests API access to every required ServiceNow table (categories, companies, models, users, locations, assets, and CI fields). If any table is unreachable — due to incorrect credentials, missing roles, or network issues — validation will fail with a specific error message.

Once validation succeeds, the Inventory tab becomes available, unlocking the mapping configuration.

🗂️ Step 2: Category & Class Mapping

Switch to the Inventory tab, then open the Categories sub-tab. This is where you establish the mapping that drives the entire synchronization. Only elements belonging to mapped categories will be synchronized.

Click Add to create a new mapping row. For each row, select:

• Hector Category (left dropdown): One of your existing Hector Categories. Each Hector Category can only be mapped once.
• ServiceNow Model Category (right dropdown): The corresponding ServiceNow Model Category. This dropdown only lists categories with an asset_class of alm_hardware. Each category carries its own asset_class (determines the target asset table) and cmdb_ci_class (determines the CI type for enrichment).

Repeat for each category you want to synchronize. You can remove a mapping at any time by clicking the delete button on the row. Click Save when you are done.

🎛️ Step 3: Advanced CI Field Mapping (Optional)

Once you have saved at least one category mapping, the CI Fields sub-tab becomes available. This step is optional but recommended if you want to push additional Hector data into ServiceNow Configuration Items beyond the base asset fields.

By default, when ServiceNow generates a CI from a new asset, it only copies over basic information. This feature lets you go further by mapping specific Hector asset columns directly to CI fields.

How it works:

• Aggregated Field Discovery: Hector dynamically reviews all the CI Classes associated with your mapped categories and gathers every distinct CI field available across them. Only fields with supported data types (string, integer, boolean, date/time, duration, IP address, domain path, field name) are included. If multiple CI classes share the same field (e.g., “CPU” or “MAC Address”), it appears only once.
• Mapping: For each discovered CI field, you can optionally select a Hector asset column to map to it.
• Smart Execution: During the sync, Hector checks if the specific CI being updated actually supports that field. If the field belongs to that CI’s class, the mapped value is pushed. Date/time values are automatically converted to UTC format.

🔄 Usage & Synchronization

Once the initial connection is established, the integration manages the lifecycle of your hardware dictionary and individual assets for all mapped categories.

🕒 Sync Frequency

• Scheduled Job: The synchronization runs as a scheduled job on a configured interval. It can also be triggered manually from the integration settings.
• Incremental by Default: After the initial sync, only assets modified since the last successful sync are included. This keeps sync cycles efficient.
• Full Sync Option: A full sync can be forced when needed, which re-processes all active assets in the mapped categories regardless of their modification date.

🔍 The “Lookup, Link, or Create” Logic

For every entity synced to ServiceNow (Makers, Models, and Assets), Hector follows a strict validation process to prevent duplicates:

1. Lookup: Hector searches ServiceNow for an existing record based on predefined matching fields.
2. Link & Update: If a match is found, Hector links its internal ID to the ServiceNow sys_id. For all future syncs, it will simply update this existing record.
3. Create: If no match is found during the initial lookup, Hector creates a brand-new record in ServiceNow and establishes the link for future updates.

---

📥 1. Dictionary Synchronization (Hector → ServiceNow)

Before syncing individual assets, Hector ensures ServiceNow has the correct foundational data for your mapped categories.

A. Makers (Manufacturers)

Hector checks the core_company table in ServiceNow for makers tied to mapped categories.

• Matching Field: Name (case-insensitive)

🔁 Sync Behavior:

• If found: Hector links to the existing company. If the company is not already marked as a manufacturer, it updates the manufacturer flag to true.
• If not found: Hector creates a new company with the manufacturer flag set to true and a note indicating it was auto-created via Hector Sync.

Hector Part Field	ServiceNow Field	Notes
Maker	name	Used to find matching manufacturers.
–	manufacturer	Set to true to identify the company as a manufacturer.
–	notes	Set to “Auto-created via Hector Sync” on creation only.

B. Hardware Models

Hector checks the cmdb_hardware_product_model table in ServiceNow for models tied to mapped categories.

• Matching Fields: Name + Manufacturer

🔁 Sync Behavior:

• If a mapping already exists: Hector updates the existing product model in ServiceNow with the latest data from Hector.
• If no mapping exists: Hector creates a new product model and saves the link (Hector Part ID → ServiceNow sys_id) for future syncs.

Hector Part Field	ServiceNow Field	Notes
Model	name	The model name.
Maker	manufacturer	Linked to the company synced in Step A.
Category	cmdb_model_category	Linked to the ServiceNow Model Category defined in your integration mapping.
Description	short_description	Populated directly from the Hector part.
Vendor SKU	model_number	Populated directly from the Hector part.
Price	cost	Populated directly from the Hector part.

---

📥 2. Asset & CI Synchronization (Hector → ServiceNow)

Once the structural data is in place, Hector syncs the physical assets and configuration items that belong to your mapped categories using a specialized enrichment process.

Assets & Configuration Items

Hector checks the appropriate asset table (determined by the category’s asset_class, typically alm_hardware) in ServiceNow.

• Matching Fields: Serial Number OR Asset Tag (via existing mapping link)

🔁 Sync Behavior & Creation Logic:

1. Lookup: Hector checks if it already has a mapping (Hector Asset ID → ServiceNow sys_id). If a mapping exists, it updates the record. If the mapped record no longer exists in ServiceNow (e.g., it was deleted), Hector falls back to creating a new one.
2. Table Routing: The target ServiceNow table is determined by the asset’s category. The Part → Model → Category → asset_class chain determines the exact table (e.g., alm_hardware). If the chain cannot be resolved, it falls back to alm_asset.
3. User Assignment: If the asset is assigned to a user in Hector, the system looks up that user’s email address in ServiceNow’s sys_user table. If a match is found, the assigned_to field is populated. If no match is found, the field is left empty.
4. ✨ Two-Step CI Enrichment:
   • Step 1 – Standard Creation: Hector creates the Asset, triggering ServiceNow to generate the baseline Configuration Item (CI).
   • Step 2 – Targeted CI Update: Immediately after, Hector reads the CI reference from the newly created asset. Using the CI class determined by the category’s cmdb_ci_class, Hector pushes mapped field values into the CI record. This enrichment also runs on updates to existing assets.

🧱 Base Asset Field Mapping

Hector Asset Field	ServiceNow Field	Notes
Asset Tag	asset_tag	The asset’s unique tag identifier.
Serial Number	serial_number	Populated from the asset’s serial number attribute.
Model	model	Linked to the Hardware Product Model synced in Step 1B (reference by sys_id).
Model Category	model_category	Inherited from the model’s cmdb_model_category.
Manufacturer	manufacturer	Inherited from the model’s manufacturer (reference by sys_id).
Assignment (if user only)	assigned_to	Populated automatically if the user is found in ServiceNow by email. Left empty otherwise.
Acquired Date	purchase_date	Formatted as yyyy-MM-dd.
Price	cost	Populated directly from your Hector asset.
Currency	currency	Populated directly from your Hector asset.
[Custom Mapped Fields]	[Distinct CI Fields]	Pushed to the CI record during Step 2 of enrichment, provided the field exists on the CI’s specific class.

🚫 Integration Constraints

• Unidirectional Sync: This integration pushes data from Hector to ServiceNow only. Changes made directly in ServiceNow (field updates, status changes, deletions) are not reflected back in Hector.
• No Deletion Propagation: When records are deleted or inactivated in Hector (assets, categories, parts, manufacturers, etc.), they are not removed from ServiceNow. Cleanup in ServiceNow must be performed manually.
• Skip Sync Flag: Individual assets can be excluded from synchronization by enabling the Skip Sync flag on the asset in Hector.
• Category-Gated: Only assets belonging to categories that have been explicitly mapped in the integration settings will be synchronized. Unmapped categories are completely ignored.
• User Matching by Email Only: The assigned_to field is populated by matching the Hector user’s email address against ServiceNow’s sys_user table. If the email does not exist in ServiceNow, the field is left empty — no error is raised.
• Hardware Only: This integration is designed exclusively for hardware. The category mapping dropdown only displays ServiceNow Model Categories with an asset_class of alm_hardware, and product models are synced exclusively to the cmdb_hardware_product_model table. Other ServiceNow model types (e.g., software models, consumable models) and non-hardware asset classes are not supported.
• CI Class Fallback: If a mapped ServiceNow category does not have a cmdb_ci_class defined, CI enrichment will target the generic cmdb_ci base table. For best results with CI field mapping, ensure your ServiceNow categories have a specific CI class assigned (e.g., cmdb_ci_computer, cmdb_ci_server).

---

📤 3. Incident Synchronization (ServiceNow → Hector) — Coming Soon

A future update will introduce inbound synchronization for ServiceNow incidents and tickets. When a ticket in ServiceNow is associated with a Configuration Item that has been synced to a Hector asset, the integration will automatically pull basic ticket information back into Hector.

Planned capabilities:

• Automatic Ticket Discovery: Hector will detect incidents linked to synced CIs and display them on the corresponding asset record.
• Basic Ticket Info: Key fields such as the ticket number, short description, state, priority, and assignment group will be visible directly in Hector.
• Direct Link to ServiceNow: Each ticket will include a clickable link that opens the full incident record in your ServiceNow instance, allowing users to consult details without leaving Hector.

We hope this guide was helpful and best of luck on your Hector journey!