SMILEconnect API

A REST API proxy and abstraction layer for BMC HELIX ITSM (IT Service Management).

Overview

SMILEconnect serves as a middleware/API gateway between external systems and BMC Remedy ITSM. It enables rapid interface creation and management for ITSM departments through a configuration-driven approach with minimal customization to the underlying ITSM system.

Version: 1.72.3

Key Features

• Ticket Management - Full CRUD operations for Incidents, Changes, Problems, and Work Orders
• Task Management - Create and manage tasks linked to parent tickets
• CMDB Integration - Query, create, and update Configuration Items/Assets
• Organizational Data - Manage persons, support groups, and organizations
• Custom Scripts - Execute custom business logic via sandboxed JavaScript (vm2)
• Multi-Tenant - Support for multiple clients with isolated configurations
• Template Management - Store and retrieve templates for various ticket types
• Work Logs & Attachments - Attach work logs and files to tickets

Technology Stack

| Component | Technology | |-----------|------------| | Runtime | Node.js 21+ | | Framework | Express.js 4.17.1 | | Authentication | Passport.js with JWT | | Logging | Bunyan + @manyos/logger | | HTTP Client | request-promise-native, node-fetch | | Caching | node-cache | | Script Execution | vm2 (sandboxed JS) | | Testing | Mocha, Chai |

Project Structure

itsmproxy/
├── app.js                    # Main entry point (Express server)
├── package.json              # Dependencies and metadata
├── Dockerfile                # Docker configuration (Node.js 21)
│
├── controller/               # Business logic layer (12 controllers)
│   ├── ticketController.js       # Incidents, Changes, Problems, WorkOrders
│   ├── taskController.js         # Task management
│   ├── cmdbobjectController.js   # CMDB/Asset operations
│   ├── scriptController.js       # Custom script execution
│   └── ...
│
├── routes/                   # Express route handlers (14 route files)
│   ├── ticketRoutes.js
│   ├── cmdbObjectRoutes.js
│   ├── personRoutes.js
│   └── ...
│
├── util/                     # Utilities and services
│   ├── config.js             # Client configuration loading
│   ├── arquery.js            # BMC AR Query abstraction
│   ├── mappingUtil.js        # Field mapping utilities
│   ├── cache.service.js      # In-memory caching
│   └── ...
│
├── conf/                     # Configuration files
│   ├── clients.json          # Client configurations (multi-tenant)
│   ├── mapping.json          # Field mappings
│   ├── customFormMapping.json
│   ├── adapterConfig.js      # Adapter configuration
│   └── scripts/              # Custom business logic scripts (27+)
│
├── test/                     # Test suite (Mocha/Chai)
└── docs/                     # Documentation

API Endpoints

| Endpoint | Description | |----------|-------------| | GET /v1/health | Health check | | GET/POST /v1/incidents | Incident management | | GET/POST /v1/changes | Change management | | GET/POST /v1/problems | Problem management | | GET/POST /v1/workorders | Work order management | | GET/POST /v1/cmdbobjects | CMDB/Asset management | | GET /v1/persons | Person queries | | GET /v1/supportgroups | Support group queries | | GET /v1/organisations | Organization queries | | POST /v1/scriptEndpoints/:name | Execute custom script | | GET /v1/openapi/:clientId | OpenAPI specification |

Authentication

• JWT Bearer Token via Authorization header
• SSO Integration (Keycloak/OAuth2)
• Client-based Authorization - Each client has isolated configuration
• Admin Authorization via ADMIN_USERS environment variable
• Master Client - Can impersonate other clients
• Rate Limiting - 10,000 requests per 15 minutes (configurable)

Data Flow

Client Request (JWT Token)
    ↓
Express Middleware (Auth, Rate Limit, CORS)
    ↓
Route Handler → Controller
    ↓
Pre-Mapping Scripts (optional)
    ↓
Field Mapping (API → Remedy)
    ↓
Post-Mapping Scripts (optional)
    ↓
AR Query (BMC Remedy REST API)
    ↓
Response Processing & Reverse Mapping
    ↓
JSON Response

Configuration

Environment Variables

Authentication:

• SSO_PUBLIC_KEY - JWT Public Key
• SSO_ISSUER - JWT Issuer
• SSO_AUDIENCE - JWT Audience
• SSO_CLIENTNAME_ATTRIBUTE - JWT claim for client ID (default: "azp")
• SSO_USERNAME_ATTRIBUTE - JWT claim for username (default: "preferred_username")

Remedy Connection:

• AR_SERVER - BMC Remedy AR Server host
• AR_PORT - AR Server port
• AR_USER - AR Server user
• AR_PASSWORD - AR Server password
• BASEURL - Remedy API base URL

Application:

• RATE_LIMIT - Rate limit per 15 minutes (default: 10000)
• MAX_FILESIZE - Max upload size in MB (default: 5)
• MAX_HTTP_SOCKETS - Maximum HTTP connections (default: 10)
• LOGLEVEL - Log level (debug/info/warn/error)
• LOG_REQUEST - Enable request logging (boolean)

Cache TTL (in seconds):

• CACHETTL_CMDB, CACHETTL_TICKETS, CACHETTL_TASK
• CACHETTL_CHANGE, CACHETTL_PEOPLE, CACHETTL_ORGDATA
• CACHETTL_TEMPLATE, CACHETTL_CONFIG (default: 3600)

Authorization:

• ADMIN_USERS - Comma-separated list of admin usernames
• MASTER_CLIENTS - Comma-separated list of master client IDs

Quick Start

Prerequisites

• Node.js 21+
• Access to BMC Remedy ITSM
• SSO/Keycloak configuration

Installation

npm install

Running

# Development
npm start

# Docker
docker build -t smileconnect-api .
docker run -p 3000:3000 smileconnect-api

Testing

npm test

Documentation

Full documentation is available at: https://smileconnect.manyosdocs.de

• Architecture
• Adapter Documentation
• Script System
• Getting Started
• How-To Guides
• Configuration

Author

Robert Hannemann

License

ISC