@manyos/smileconnect-api 1.72.3 → 1.72.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude/settings.local.json +9 -0
- package/README.md +202 -1
- package/docs/releases.md +3 -0
- package/package.json +1 -1
- package/todo.md +137 -0
package/README.md
CHANGED
|
@@ -1 +1,202 @@
|
|
|
1
|
-
|
|
1
|
+
# SMILEconnect API
|
|
2
|
+
|
|
3
|
+
A REST API proxy and abstraction layer for BMC HELIX ITSM (IT Service Management).
|
|
4
|
+
|
|
5
|
+
## Overview
|
|
6
|
+
|
|
7
|
+
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.
|
|
8
|
+
|
|
9
|
+
**Version:** 1.72.3
|
|
10
|
+
|
|
11
|
+
## Key Features
|
|
12
|
+
|
|
13
|
+
- **Ticket Management** - Full CRUD operations for Incidents, Changes, Problems, and Work Orders
|
|
14
|
+
- **Task Management** - Create and manage tasks linked to parent tickets
|
|
15
|
+
- **CMDB Integration** - Query, create, and update Configuration Items/Assets
|
|
16
|
+
- **Organizational Data** - Manage persons, support groups, and organizations
|
|
17
|
+
- **Custom Scripts** - Execute custom business logic via sandboxed JavaScript (vm2)
|
|
18
|
+
- **Multi-Tenant** - Support for multiple clients with isolated configurations
|
|
19
|
+
- **Template Management** - Store and retrieve templates for various ticket types
|
|
20
|
+
- **Work Logs & Attachments** - Attach work logs and files to tickets
|
|
21
|
+
|
|
22
|
+
## Technology Stack
|
|
23
|
+
|
|
24
|
+
| Component | Technology |
|
|
25
|
+
|-----------|------------|
|
|
26
|
+
| Runtime | Node.js 21+ |
|
|
27
|
+
| Framework | Express.js 4.17.1 |
|
|
28
|
+
| Authentication | Passport.js with JWT |
|
|
29
|
+
| Logging | Bunyan + @manyos/logger |
|
|
30
|
+
| HTTP Client | request-promise-native, node-fetch |
|
|
31
|
+
| Caching | node-cache |
|
|
32
|
+
| Script Execution | vm2 (sandboxed JS) |
|
|
33
|
+
| Testing | Mocha, Chai |
|
|
34
|
+
|
|
35
|
+
## Project Structure
|
|
36
|
+
|
|
37
|
+
```
|
|
38
|
+
itsmproxy/
|
|
39
|
+
├── app.js # Main entry point (Express server)
|
|
40
|
+
├── package.json # Dependencies and metadata
|
|
41
|
+
├── Dockerfile # Docker configuration (Node.js 21)
|
|
42
|
+
│
|
|
43
|
+
├── controller/ # Business logic layer (12 controllers)
|
|
44
|
+
│ ├── ticketController.js # Incidents, Changes, Problems, WorkOrders
|
|
45
|
+
│ ├── taskController.js # Task management
|
|
46
|
+
│ ├── cmdbobjectController.js # CMDB/Asset operations
|
|
47
|
+
│ ├── scriptController.js # Custom script execution
|
|
48
|
+
│ └── ...
|
|
49
|
+
│
|
|
50
|
+
├── routes/ # Express route handlers (14 route files)
|
|
51
|
+
│ ├── ticketRoutes.js
|
|
52
|
+
│ ├── cmdbObjectRoutes.js
|
|
53
|
+
│ ├── personRoutes.js
|
|
54
|
+
│ └── ...
|
|
55
|
+
│
|
|
56
|
+
├── util/ # Utilities and services
|
|
57
|
+
│ ├── config.js # Client configuration loading
|
|
58
|
+
│ ├── arquery.js # BMC AR Query abstraction
|
|
59
|
+
│ ├── mappingUtil.js # Field mapping utilities
|
|
60
|
+
│ ├── cache.service.js # In-memory caching
|
|
61
|
+
│ └── ...
|
|
62
|
+
│
|
|
63
|
+
├── conf/ # Configuration files
|
|
64
|
+
│ ├── clients.json # Client configurations (multi-tenant)
|
|
65
|
+
│ ├── mapping.json # Field mappings
|
|
66
|
+
│ ├── customFormMapping.json
|
|
67
|
+
│ ├── adapterConfig.js # Adapter configuration
|
|
68
|
+
│ └── scripts/ # Custom business logic scripts (27+)
|
|
69
|
+
│
|
|
70
|
+
├── test/ # Test suite (Mocha/Chai)
|
|
71
|
+
└── docs/ # Documentation
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## API Endpoints
|
|
75
|
+
|
|
76
|
+
| Endpoint | Description |
|
|
77
|
+
|----------|-------------|
|
|
78
|
+
| `GET /v1/health` | Health check |
|
|
79
|
+
| `GET/POST /v1/incidents` | Incident management |
|
|
80
|
+
| `GET/POST /v1/changes` | Change management |
|
|
81
|
+
| `GET/POST /v1/problems` | Problem management |
|
|
82
|
+
| `GET/POST /v1/workorders` | Work order management |
|
|
83
|
+
| `GET/POST /v1/cmdbobjects` | CMDB/Asset management |
|
|
84
|
+
| `GET /v1/persons` | Person queries |
|
|
85
|
+
| `GET /v1/supportgroups` | Support group queries |
|
|
86
|
+
| `GET /v1/organisations` | Organization queries |
|
|
87
|
+
| `POST /v1/scriptEndpoints/:name` | Execute custom script |
|
|
88
|
+
| `GET /v1/openapi/:clientId` | OpenAPI specification |
|
|
89
|
+
|
|
90
|
+
## Authentication
|
|
91
|
+
|
|
92
|
+
- **JWT Bearer Token** via Authorization header
|
|
93
|
+
- **SSO Integration** (Keycloak/OAuth2)
|
|
94
|
+
- **Client-based Authorization** - Each client has isolated configuration
|
|
95
|
+
- **Admin Authorization** via `ADMIN_USERS` environment variable
|
|
96
|
+
- **Master Client** - Can impersonate other clients
|
|
97
|
+
- **Rate Limiting** - 10,000 requests per 15 minutes (configurable)
|
|
98
|
+
|
|
99
|
+
## Data Flow
|
|
100
|
+
|
|
101
|
+
```
|
|
102
|
+
Client Request (JWT Token)
|
|
103
|
+
↓
|
|
104
|
+
Express Middleware (Auth, Rate Limit, CORS)
|
|
105
|
+
↓
|
|
106
|
+
Route Handler → Controller
|
|
107
|
+
↓
|
|
108
|
+
Pre-Mapping Scripts (optional)
|
|
109
|
+
↓
|
|
110
|
+
Field Mapping (API → Remedy)
|
|
111
|
+
↓
|
|
112
|
+
Post-Mapping Scripts (optional)
|
|
113
|
+
↓
|
|
114
|
+
AR Query (BMC Remedy REST API)
|
|
115
|
+
↓
|
|
116
|
+
Response Processing & Reverse Mapping
|
|
117
|
+
↓
|
|
118
|
+
JSON Response
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## Configuration
|
|
122
|
+
|
|
123
|
+
### Environment Variables
|
|
124
|
+
|
|
125
|
+
**Authentication:**
|
|
126
|
+
- `SSO_PUBLIC_KEY` - JWT Public Key
|
|
127
|
+
- `SSO_ISSUER` - JWT Issuer
|
|
128
|
+
- `SSO_AUDIENCE` - JWT Audience
|
|
129
|
+
- `SSO_CLIENTNAME_ATTRIBUTE` - JWT claim for client ID (default: "azp")
|
|
130
|
+
- `SSO_USERNAME_ATTRIBUTE` - JWT claim for username (default: "preferred_username")
|
|
131
|
+
|
|
132
|
+
**Remedy Connection:**
|
|
133
|
+
- `AR_SERVER` - BMC Remedy AR Server host
|
|
134
|
+
- `AR_PORT` - AR Server port
|
|
135
|
+
- `AR_USER` - AR Server user
|
|
136
|
+
- `AR_PASSWORD` - AR Server password
|
|
137
|
+
- `BASEURL` - Remedy API base URL
|
|
138
|
+
|
|
139
|
+
**Application:**
|
|
140
|
+
- `RATE_LIMIT` - Rate limit per 15 minutes (default: 10000)
|
|
141
|
+
- `MAX_FILESIZE` - Max upload size in MB (default: 5)
|
|
142
|
+
- `MAX_HTTP_SOCKETS` - Maximum HTTP connections (default: 10)
|
|
143
|
+
- `LOGLEVEL` - Log level (debug/info/warn/error)
|
|
144
|
+
- `LOG_REQUEST` - Enable request logging (boolean)
|
|
145
|
+
|
|
146
|
+
**Cache TTL (in seconds):**
|
|
147
|
+
- `CACHETTL_CMDB`, `CACHETTL_TICKETS`, `CACHETTL_TASK`
|
|
148
|
+
- `CACHETTL_CHANGE`, `CACHETTL_PEOPLE`, `CACHETTL_ORGDATA`
|
|
149
|
+
- `CACHETTL_TEMPLATE`, `CACHETTL_CONFIG` (default: 3600)
|
|
150
|
+
|
|
151
|
+
**Authorization:**
|
|
152
|
+
- `ADMIN_USERS` - Comma-separated list of admin usernames
|
|
153
|
+
- `MASTER_CLIENTS` - Comma-separated list of master client IDs
|
|
154
|
+
|
|
155
|
+
## Quick Start
|
|
156
|
+
|
|
157
|
+
### Prerequisites
|
|
158
|
+
- Node.js 21+
|
|
159
|
+
- Access to BMC Remedy ITSM
|
|
160
|
+
- SSO/Keycloak configuration
|
|
161
|
+
|
|
162
|
+
### Installation
|
|
163
|
+
|
|
164
|
+
```bash
|
|
165
|
+
npm install
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
### Running
|
|
169
|
+
|
|
170
|
+
```bash
|
|
171
|
+
# Development
|
|
172
|
+
npm start
|
|
173
|
+
|
|
174
|
+
# Docker
|
|
175
|
+
docker build -t smileconnect-api .
|
|
176
|
+
docker run -p 3000:3000 smileconnect-api
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
### Testing
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
npm test
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
## Documentation
|
|
186
|
+
|
|
187
|
+
Full documentation is available at: <https://smileconnect.manyosdocs.de>
|
|
188
|
+
|
|
189
|
+
- [Architecture](docs/architecture.md)
|
|
190
|
+
- [Adapter Documentation](docs/adapter.md)
|
|
191
|
+
- [Script System](docs/scripts.md)
|
|
192
|
+
- [Getting Started](docs/getting-started/)
|
|
193
|
+
- [How-To Guides](docs/howto/)
|
|
194
|
+
- [Configuration](docs/configuration/)
|
|
195
|
+
|
|
196
|
+
## Author
|
|
197
|
+
|
|
198
|
+
Robert Hannemann
|
|
199
|
+
|
|
200
|
+
## License
|
|
201
|
+
|
|
202
|
+
ISC
|
package/docs/releases.md
CHANGED
package/package.json
CHANGED
package/todo.md
ADDED
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
# SMILEconnect API - TODO
|
|
2
|
+
|
|
3
|
+
## Phase 1: Stabilität (Kritisch)
|
|
4
|
+
|
|
5
|
+
### 1.1 Deprecated Dependencies ersetzen
|
|
6
|
+
- [ ] `request` / `request-promise-native` durch `axios` ersetzen
|
|
7
|
+
- Dateien: `util/arquery.js`, `controller/scriptController.js`
|
|
8
|
+
- [ ] `vm2` durch `isolated-vm` ersetzen (Sicherheitslücken)
|
|
9
|
+
- Dateien: `controller/scriptController.js`
|
|
10
|
+
- [ ] `uuid@3` auf `uuid@9` upgraden
|
|
11
|
+
- [ ] `mongoose@5` auf `mongoose@8` upgraden
|
|
12
|
+
- [ ] `socket.io@2` auf `socket.io@4` upgraden
|
|
13
|
+
|
|
14
|
+
### 1.2 Security Headers
|
|
15
|
+
- [ ] `helmet.js` integrieren für Security Headers
|
|
16
|
+
- Content-Security-Policy
|
|
17
|
+
- X-Content-Type-Options
|
|
18
|
+
- Strict-Transport-Security
|
|
19
|
+
- X-Frame-Options
|
|
20
|
+
|
|
21
|
+
### 1.3 Offene TODOs im Code
|
|
22
|
+
- [ ] `app.js:142-143` - Config error abfangen, AdminScope implementieren
|
|
23
|
+
- [ ] `ticketController.js:130, 327` - Code-Cleanup
|
|
24
|
+
- [ ] `taskController.js:189` - Phase handling für Records ohne Phases
|
|
25
|
+
- [ ] `taskController.js:273` - Attachment handling hinzufügen
|
|
26
|
+
- [ ] `taskController.js:421` - Scripts aktivieren
|
|
27
|
+
- [ ] `ticketCIRelationController.js:181, 221` - Impersonate implementieren
|
|
28
|
+
- [ ] `scriptController.js:76` - Script nur einmal hinzufügen
|
|
29
|
+
- [ ] `scriptController.js:119` - Timeout hinzufügen
|
|
30
|
+
- [ ] `ticketWorkLogController.js:52` - Ticket-Existenz prüfen
|
|
31
|
+
- [ ] `arquery.js:185` - Impersonate hinzufügen
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## Phase 2: Performance
|
|
36
|
+
|
|
37
|
+
### 2.1 Distributed Caching
|
|
38
|
+
- [ ] Redis-Integration für verteiltes Caching
|
|
39
|
+
- [ ] Fallback auf in-memory wenn Redis nicht verfügbar
|
|
40
|
+
- [ ] Cache-Invalidierung über Pub/Sub
|
|
41
|
+
|
|
42
|
+
### 2.2 Rate Limiting pro Client
|
|
43
|
+
- [ ] Rate Limit basierend auf JWT clientId statt nur IP
|
|
44
|
+
- [ ] Konfigurierbare Limits pro Client in `clients.json`
|
|
45
|
+
|
|
46
|
+
### 2.3 Connection Pooling
|
|
47
|
+
- [ ] Separate Pools für verschiedene Backend-Services
|
|
48
|
+
- [ ] Keep-Alive Connections optimieren
|
|
49
|
+
- [ ] HTTP/2 Support für Remedy-Backend evaluieren
|
|
50
|
+
|
|
51
|
+
### 2.4 Health Check erweitern
|
|
52
|
+
- [ ] Dependency-Status hinzufügen (Remedy, MongoDB, Redis)
|
|
53
|
+
- [ ] Latenz-Metriken
|
|
54
|
+
- [ ] Version und Uptime
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## Phase 3: Developer Experience
|
|
59
|
+
|
|
60
|
+
### 3.1 Strukturierte Error Responses
|
|
61
|
+
- [ ] RFC 7807 Problem Details Format implementieren
|
|
62
|
+
- [ ] Einheitliche Error-Struktur über alle Endpoints
|
|
63
|
+
- [ ] Datei: `util/responsehandler.js`
|
|
64
|
+
|
|
65
|
+
### 3.2 Test Coverage
|
|
66
|
+
- [ ] Jest für Unit Tests einführen
|
|
67
|
+
- [ ] Coverage Report (Ziel: 80%)
|
|
68
|
+
- [ ] Testcontainers für Integration Tests
|
|
69
|
+
|
|
70
|
+
### 3.3 OpenAPI Auto-Generation
|
|
71
|
+
- [ ] swagger-jsdoc integrieren
|
|
72
|
+
- [ ] OpenAPI 3.1 Upgrade
|
|
73
|
+
- [ ] Validierung gegen Schema
|
|
74
|
+
|
|
75
|
+
### 3.4 Prometheus Metrics
|
|
76
|
+
- [ ] `prom-client` integrieren
|
|
77
|
+
- [ ] Request Duration Histogram
|
|
78
|
+
- [ ] Request Counter (by endpoint, status)
|
|
79
|
+
- [ ] Cache Hit/Miss Rate
|
|
80
|
+
- [ ] Endpoint: `GET /metrics`
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
## Phase 4: Neue Features
|
|
85
|
+
|
|
86
|
+
### 4.1 Webhook/Event System
|
|
87
|
+
- [ ] Webhook-Registrierung pro Client
|
|
88
|
+
- [ ] Events: ticket.created, ticket.updated, ticket.resolved
|
|
89
|
+
- [ ] Retry-Logik mit exponential backoff
|
|
90
|
+
- [ ] Signature Verification
|
|
91
|
+
|
|
92
|
+
### 4.2 Batch-Operationen
|
|
93
|
+
- [ ] `POST /v1/incidents/batch` Endpoint
|
|
94
|
+
- [ ] Bulk-Create und Bulk-Update
|
|
95
|
+
- [ ] Transaktionale Verarbeitung
|
|
96
|
+
|
|
97
|
+
### 4.3 API Key Authentifizierung
|
|
98
|
+
- [ ] API Keys als Alternative zu JWT
|
|
99
|
+
- [ ] Key Rotation
|
|
100
|
+
- [ ] Scope-basierte Berechtigungen
|
|
101
|
+
|
|
102
|
+
### 4.4 Audit Trail
|
|
103
|
+
- [ ] Alle Änderungen in Audit-Log speichern
|
|
104
|
+
- [ ] `GET /v1/{type}/{id}/history` Endpoint
|
|
105
|
+
- [ ] Wer hat wann was geändert
|
|
106
|
+
|
|
107
|
+
---
|
|
108
|
+
|
|
109
|
+
## Phase 5: Strategisch
|
|
110
|
+
|
|
111
|
+
### 5.1 TypeScript Migration
|
|
112
|
+
- [ ] TypeScript-Konfiguration aufsetzen
|
|
113
|
+
- [ ] Schrittweise Migration (util/ zuerst)
|
|
114
|
+
- [ ] Type Definitions für alle Entities
|
|
115
|
+
|
|
116
|
+
### 5.2 GraphQL API (Optional)
|
|
117
|
+
- [ ] Apollo Server evaluieren
|
|
118
|
+
- [ ] Schema Design
|
|
119
|
+
- [ ] Parallel zu REST API
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
## Notizen
|
|
124
|
+
|
|
125
|
+
**Priorität:** Phase 1 > Phase 2 > Phase 3 > Phase 4 > Phase 5
|
|
126
|
+
|
|
127
|
+
**Kritische Sicherheitsprobleme:**
|
|
128
|
+
- `vm2` hat bekannte Sandbox-Escape-Vulnerabilities
|
|
129
|
+
- `request` ist deprecated und erhält keine Security-Updates mehr
|
|
130
|
+
|
|
131
|
+
**Deprecated Dependencies in package-lock.json:**
|
|
132
|
+
- debug (ReDos vulnerability)
|
|
133
|
+
- glob (versions prior to v9)
|
|
134
|
+
- mkdirp (legacy versions)
|
|
135
|
+
- rimraf (versions prior to v4)
|
|
136
|
+
- superagent (upgrade recommended)
|
|
137
|
+
- uuid (Math.random() issue in v3)
|