Xurrent (4me) Integration Guide

Overview

The Xurrent (4me) integration enables synchronization of Configuration Items (CIs) from KILLIT CMDB to Xurrent's ITSM platform. This integration uses Xurrent's GraphQL API to create, update, and manage CIs and their relationships.

Table of Contents

1. Configuration
2. What Gets Synced
3. When Does It Sync
4. Data Mapping
5. Architecture
6. Troubleshooting

Configuration

Prerequisites

1. Xurrent Account: You need an active Xurrent account with API access
2. API Token: Generate an API token from your Xurrent account with the following scopes:
   • configuration_items:read
   • configuration_items:write
   • products:read
   • teams:read
3. Account ID: Your Xurrent account identifier
4. Default Support Team: A valid Support Team ID in Xurrent
5. Product Mappings: CI Types must be mapped to Xurrent Product IDs

Configuration Steps

1. Navigate to Integration Settings

   • Go to CMDB → Integrations → Xurrent Configuration

2. Enter Connection Details

   Service URL: Select your Xurrent environment
   - Production - Global: https://graphql.xurrent.com
   - Production - Australia: https://graphql.au.xurrent.com
   - Production - UK: https://graphql.uk.xurrent.com
   - Production - Switzerland: https://graphql.ch.xurrent.com
   - Production - US: https://graphql.us.xurrent.com
   - QA - Global: https://graphql.xurrent.qa
   - Demo: https://graphql.xurrent-demo.com
   
   API Token: Your Xurrent API token
   Account ID: Your Xurrent account ID
   Source Identifier: KILLIT-DISCOVERY (default)
   Default Support Team ID: Required - the ID of your default support team
   Default Product ID: Optional - fallback product ID if no mapping exists

3. Test Connection

   • Click "Test Connection" to verify your credentials

4. Configure Product Mappings

   • Each CI Type must be mapped to a Xurrent Product ID
   • Use the Product Mapping section to:
     • Select a CI Type (e.g., Server, Network Device)
     • Enter or search for a Xurrent Product ID
     • Click "Add Mapping"
   • Product mappings are required for successful sync

5. Save Configuration

   • Click "Save Configuration" to store your settings

What Gets Synced

Configuration Items (CIs)

The following CI data is synchronized to Xurrent:

1. Basic CI Information

   • Name
   • Description
   • Status (mapped to Xurrent status values)
   • Serial Number (if available)
   • System ID (unique identifier as killit-{CI_ID})

2. Classification

   • Product (based on CI Type mapping)
   • Support Team
   • Source (KILLIT-DISCOVERY)

3. Custom Fields

   • All custom field values from KILLIT are synced
   • Fields are mapped by field ID

4. Relationships

   • CI relationships are synced with appropriate relationship types:
     • Depends On → software_dependency
     • Runs On → parent
     • Used By → child
     • Uses → parent
     • Consists Of → child
     • Component Of → parent
     • Connected To → network_connection
     • Installed On → parent

Supported CI Types

Any CI Type can be synced, but must have a product mapping configured. Common types include:

• Servers (Physical and Virtual)
• Network Devices
• Software Instances
• Storage Systems
• Databases

When Does It Sync

Manual Sync

Currently, the integration operates on a manual sync basis:

1. Export via UI

   • Navigate to CMDB → Integrations → Xurrent Export
   • Select CI Type to export (or "All")
   • Choose batch size (default: 50)
   • Click "Export to Xurrent"

2. Sync Triggers

   • No automatic sync is currently implemented
   • CIs are marked with needsXurrentSync flag when changes occur
   • Manual export processes all flagged CIs

Sync Process

1. Marking for Sync

   • CIs are automatically flagged for sync when:
     • Created
     • Updated
     • Relationships change

2. Export Process

   • Queries all CIs with needsXurrentSync = true
   • Processes in batches (configurable, default 50)
   • For each CI:
     • Checks if CI exists in Xurrent (by name)
     • Creates new CI or updates existing
     • Syncs relationships after CI is created/updated
     • Marks CI as synced (needsXurrentSync = false)

Data Mapping

Status Mapping

KILLIT Status → Xurrent Status:

active → in_production
inactive → archived
maintenance → undergoing_maintenance
standby → standby_for_continuity
removed → removed
(default) → in_production

Field Mapping

KILLIT Field	Xurrent Field	Notes
name	name	Required
name	label	Defaults to name
description	remarks	Optional
customFields.serial_number	serialNr	If available
_id	systemID	As killit-{ID}
status	status	Mapped values
type → productMapping	productId	Required mapping
(configured)	supportTeamId	From config
relationships	ciRelations	Mapped types

Product Mapping Requirements

Each CI Type must be mapped to a Xurrent Product:

1. Server → Xurrent Server Product ID
2. Network Device → Xurrent Network Product ID
3. Software → Xurrent Software Product ID

Without a product mapping, CIs cannot be exported.

Architecture

Components

1. Backend Service (xurrentService.js)

   • Handles GraphQL API communication
   • Manages configuration
   • Processes CI exports
   • Maps data between systems

2. Controller (xurrentController.js)

   • REST API endpoints
   • Request validation
   • Response formatting

3. Frontend Components

   • XurrentIntegrationConfig.tsx: Configuration UI
   • XurrentIntegrationExport.tsx: Export management UI
   • BasicProductMapping.tsx: Product mapping interface

4. Data Model (xurrentConfig.js)

   • Stores integration configuration
   • Product mappings
   • Sync status

API Endpoints

GET  /api/integrations/xurrent/config         - Get configuration
POST /api/integrations/xurrent/config         - Save configuration
POST /api/integrations/xurrent/test-connection - Test connection
POST /api/integrations/xurrent/export         - Export CIs
GET  /api/integrations/xurrent/export-status/:jobId - Check export status
POST /api/integrations/xurrent/product-details - Get product info

GraphQL Operations

1. Find CI

   query FindCI($nameval: String!) {
     configurationItems(filter: { name: { values: [$nameval] } }) {
       nodes { id, name, sourceID, status }
     }
   }

2. Create CI

   mutation CreateConfigurationItem($input: ConfigurationItemCreateInput!) {
     configurationItemCreate(input: $input) {
       configurationItem { id, name, status }
       errors { path, message }
     }
   }

3. Update CI

   mutation UpdateConfigurationItem($input: ConfigurationItemUpdateInput!) {
     configurationItemUpdate(input: $input) {
       configurationItem { id, name, status }
       errors { path, message }
     }
   }

Troubleshooting

Common Issues

1. "Missing required field productId"

   • Cause: No product mapping for CI Type
   • Solution: Configure product mapping in integration settings

2. "Missing required field supportTeamId"

   • Cause: No default support team configured
   • Solution: Set Default Support Team ID in configuration

3. "Missing required scope"

   • Cause: API token lacks necessary permissions
   • Solution: Generate new token with required scopes

4. "GraphQL errors: "message":"Not Found""

   • Cause: Invalid Product ID or Support Team ID
   • Solution: Verify IDs exist in Xurrent

Debug Mode

Enable debug logging:

// Set environment variables
MOCK_XURRENT=true  // Enable mock mode for testing
DEBUG=true         // Enable detailed logging

Verification Steps

1. Check Configuration

   // In backend console
   const config = await xurrentService.getConfig();
   console.log(config);

2. Test Single CI Export

   // Export with dry run
   const result = await xurrentService.exportCIs({
     batchSize: 1,
     dryRun: true,
     ciType: 'Server'
   });

3. Verify Product Mappings

   • Ensure all CI Types have valid Xurrent Product IDs
   • Test product lookup in Xurrent to verify IDs

Logs

Check logs for detailed information:

• Backend logs: backend/logs/combined.log
• Look for entries with "Xurrent" or "GraphQL"

Best Practices

1. Start Small

   • Test with a few CIs first
   • Use dry run mode to preview changes

2. Product Mapping

   • Map all CI Types before bulk export
   • Verify Product IDs in Xurrent first

3. Batch Processing

   • Use appropriate batch sizes (10-50)
   • Monitor API rate limits

4. Relationship Sync

   • Ensure related CIs exist in Xurrent first
   • Relationships require both source and target to exist

5. Regular Sync

   • Schedule regular manual exports
   • Monitor for CIs pending sync

Future Enhancements

1. Automatic Sync

   • Webhook-based real-time sync
   • Scheduled sync jobs

2. Bi-directional Sync

   • Import CIs from Xurrent
   • Sync changes from Xurrent back to KILLIT

3. Advanced Mappings

   • Custom field mappings
   • Conditional logic for field values

4. Sync History

   • Track sync operations
   • Audit trail for changes

Support

For issues or questions:

1. Check the troubleshooting section
2. Review backend logs
3. Contact system administrator
4. Refer to Xurrent API documentation: https://developer.xurrent.com/