itsm-widget 1.0.1

package/ANGULAR-INSTALLATION.md

@@ -0,0 +1,372 @@
+# Hướng dẫn cài đặt ITSM Widget vào Angular Project
+
+## 📋 Các bước cài đặt
+
+### Cách 1: Cài đặt qua npm (Khuyến nghị)
+
+**Bước 1: Install package**
+
+```bash
+npm install itsm-widget
+```
+
+**Bước 2: Cập nhật `angular.json`**
+
+Thêm vào `scripts` và `styles`:
+
+```json
+{
+  "projects": {
+    "your-project-name": {
+      "architect": {
+        "build": {
+          "options": {
+            "scripts": [
+              "node_modules/itsm-widget/dist/itsm-widget.min.js"
+            ],
+            "styles": [
+              "src/styles.css",
+              "node_modules/itsm-widget/dist/itsm-widget.min.css"
+            ]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**Bước 3:** Xem tiếp phần "Khởi tạo widget" bên dưới.
+
+---
+
+### Cách 2: Copy files thủ công
+
+**Bước 1: Copy files vào project**
+
+Copy 2 files sau từ `dist/` của widget vào Angular project:
+
+```
+src/assets/
+  ├── itsm-widget.min.js
+  └── itsm-widget.min.css
+```
+
+**Cách copy:**
+- Copy `dist/itsm-widget.min.js` → `src/assets/itsm-widget.min.js`
+- Copy `dist/itsm-widget.min.css` → `src/assets/itsm-widget.min.css`
+
+**Bước 2: Cập nhật `angular.json`**
+
+Thêm scripts và styles vào `angular.json`:
+
+```json
+{
+  "projects": {
+    "your-project-name": {
+      "architect": {
+        "build": {
+          "options": {
+            "scripts": [
+              "src/assets/itsm-widget.min.js"
+            ],
+            "styles": [
+              "src/styles.css",
+              "src/assets/itsm-widget.min.css"
+            ]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**Lưu ý:** Thay `your-project-name` bằng tên project của bạn.
+
+---
+
+## ⚙️ Cấu hình (Áp dụng cho cả 2 cách)
+
+### Bước 3: Cấu hình environment (Khuyến nghị)
+
+Thêm config vào `src/environments/environment.ts`:
+
+```typescript
+export const environment = {
+  production: false,
+  // ... other config
+  itsm: {
+    apiBaseUrl: 'https://your-api-domain.com',
+    apiKey: 'your-api-key',
+    tenant: 'your-tenant-name',
+    site: 'Your Site Name'
+  }
+};
+```
+
+Và `src/environments/environment.prod.ts`:
+
+```typescript
+export const environment = {
+  production: true,
+  // ... other config
+  itsm: {
+    apiBaseUrl: 'https://your-api-domain.com',
+    apiKey: 'your-production-api-key',
+    tenant: 'your-tenant-name',
+    site: 'Your Site Name'
+  }
+};
+```
+
+## 🚀 Khởi tạo widget
+
+Có 2 cách để khởi tạo widget:
+
+#### Cách 1: Khởi tạo trong `app.component.ts` (Đơn giản)
+
+```typescript
+import { Component, OnInit, OnDestroy } from '@angular/core';
+import { environment } from '../environments/environment';
+
+declare var ITSMWidget: any;
+
+@Component({
+  selector: 'app-root',
+  templateUrl: './app.component.html',
+  styleUrls: ['./app.component.css']
+})
+export class AppComponent implements OnInit, OnDestroy {
+  title = 'your-app';
+  private itsmWidgetInstance: any;
+
+  ngOnInit() {
+    // Khởi tạo ITSM Widget
+    if (typeof ITSMWidget !== 'undefined') {
+      this.itsmWidgetInstance = new ITSMWidget({
+        apiBaseUrl: environment.itsm.apiBaseUrl,
+        apiKey: environment.itsm.apiKey,
+        tenant: environment.itsm.tenant,
+        position: 'bottom-right',
+        iconText: '📝',
+        iconColor: '#007bff',
+        title: 'Tạo phiếu yêu cầu ITSM',
+        requesterName: '', // Optional - có thể lấy từ service
+        site: environment.itsm.site,
+        onSuccess: (response: any) => {
+          console.log('ITSM Request submitted:', response);
+          // Hiển thị thông báo thành công
+          alert('Phiếu yêu cầu đã được gửi thành công!');
+        }
+      });
+
+      // Lưu instance vào window để có thể access từ nơi khác
+      (window as any).itsmWidgetInstance = this.itsmWidgetInstance;
+    }
+  }
+
+  ngOnDestroy() {
+    // Cleanup widget khi component bị destroy
+    if (this.itsmWidgetInstance) {
+      this.itsmWidgetInstance.destroy();
+    }
+  }
+}
+```
+
+#### Cách 2: Tạo Service riêng (Khuyến nghị cho project lớn)
+
+**1. Tạo service:** `src/app/services/itsm-widget.service.ts`
+
+```typescript
+import { Injectable, OnDestroy } from '@angular/core';
+import { environment } from '../../environments/environment';
+
+declare var ITSMWidget: any;
+
+@Injectable({
+  providedIn: 'root'
+})
+export class ItsmWidgetService implements OnDestroy {
+  private widgetInstance: any;
+
+  constructor() {
+    this.init();
+  }
+
+  private init(): void {
+    if (typeof ITSMWidget !== 'undefined' && !this.widgetInstance) {
+      this.widgetInstance = new ITSMWidget({
+        apiBaseUrl: environment.itsm.apiBaseUrl,
+        apiKey: environment.itsm.apiKey,
+        tenant: environment.itsm.tenant,
+        position: 'bottom-right',
+        iconText: '📝',
+        iconColor: '#007bff',
+        title: 'Tạo phiếu yêu cầu ITSM',
+        requesterName: this.getCurrentUser(), // Lấy từ auth service
+        site: environment.itsm.site,
+        onSuccess: (response: any) => {
+          console.log('ITSM Request submitted:', response);
+          // Có thể emit event hoặc hiển thị notification ở đây
+        }
+      });
+
+      (window as any).itsmWidgetInstance = this.widgetInstance;
+    }
+  }
+
+  private getCurrentUser(): string {
+    // Lấy tên user từ auth service, localStorage, hoặc sessionStorage
+    // Ví dụ:
+    // return this.authService.getCurrentUser()?.name || '';
+    // return localStorage.getItem('userName') || '';
+    return '';
+  }
+
+  ngOnDestroy(): void {
+    if (this.widgetInstance) {
+      this.widgetInstance.destroy();
+      this.widgetInstance = null;
+    }
+  }
+}
+```
+
+**2. Inject service vào `app.component.ts`:**
+
+```typescript
+import { Component, OnInit } from '@angular/core';
+import { ItsmWidgetService } from './services/itsm-widget.service';
+
+@Component({
+  selector: 'app-root',
+  templateUrl: './app.component.html',
+  styleUrls: ['./app.component.css']
+})
+export class AppComponent implements OnInit {
+  title = 'your-app';
+
+  constructor(private itsmWidgetService: ItsmWidgetService) {}
+
+  ngOnInit() {
+    // Service sẽ tự động khởi tạo widget
+  }
+}
+```
+
+### Bước 5: Build và test
+
+```bash
+# Development
+ng serve
+
+# Production build
+ng build --prod
+```
+
+## ⚙️ Cấu hình nâng cao
+
+### Lấy thông tin user từ Auth Service
+
+Nếu bạn có Auth Service, có thể lấy thông tin user:
+
+```typescript
+import { AuthService } from './services/auth.service';
+
+constructor(
+  private itsmWidgetService: ItsmWidgetService,
+  private authService: AuthService
+) {}
+
+ngOnInit() {
+  const user = this.authService.getCurrentUser();
+  
+  // Update widget với thông tin user
+  if ((window as any).itsmWidgetInstance && user) {
+    (window as any).itsmWidgetInstance.config.requesterName = user.name;
+    (window as any).itsmWidgetInstance.config.site = user.site || '';
+  }
+}
+```
+
+### Tích hợp với Notification Service
+
+Có thể tích hợp với notification service của Angular:
+
+```typescript
+import { NotificationService } from './services/notification.service';
+
+constructor(private notificationService: NotificationService) {}
+
+// Trong widget config:
+onSuccess: (response: any) => {
+  this.notificationService.showSuccess('Phiếu yêu cầu đã được gửi thành công!');
+}
+```
+
+### Custom UDF Fields
+
+Có thể thêm custom UDF fields:
+
+```typescript
+new ITSMWidget({
+  // ... other config
+  udf_fields: {
+    udf_pick_301: 'Value 1',
+    udf_pick_302: 'Value 2',
+    // ... other fields
+  }
+});
+```
+
+## 🐛 Troubleshooting
+
+### Widget không hiển thị
+
+1. Kiểm tra `angular.json` đã add scripts và styles chưa
+2. Kiểm tra files đã copy đúng vào `src/assets/` chưa
+3. Kiểm tra console có lỗi JavaScript không
+4. Đảm bảo đã build lại project: `ng serve` hoặc `ng build`
+
+### Lỗi TypeScript: Cannot find name 'ITSMWidget'
+
+Thêm declare vào đầu file:
+
+```typescript
+declare var ITSMWidget: any;
+```
+
+Hoặc tạo file `src/typings.d.ts`:
+
+```typescript
+declare var ITSMWidget: any;
+```
+
+### Widget không hoạt động sau khi build production
+
+Đảm bảo files đã được include trong `angular.json`:
+
+```json
+"assets": [
+  "src/favicon.ico",
+  "src/assets",
+  {
+    "glob": "**/*",
+    "input": "src/assets",
+    "output": "/assets"
+  }
+]
+```
+
+## 📝 Ví dụ hoàn chỉnh
+
+Xem file [example.html](../example.html) để tham khảo cách sử dụng cơ bản.
+
+## 📚 Tài liệu thêm
+
+- [README.md](../README.md) - Tài liệu tổng quan
+- [INSTALLATION.md](../INSTALLATION.md) - Hướng dẫn cho các platform khác
+- [API-SERVICE.md](../API-SERVICE.md) - Tài liệu API Service
+

package/API-SERVICE.md

@@ -0,0 +1,334 @@
+# ITSM API Service
+
+Service JavaScript để gọi các API của SDP ITSM theo tài liệu API v2 SDP ITSM SPC.
+
+## Tổng quan
+
+`ITSMAPIService` cung cấp các method để tương tác với ITSM API:
+- Tạo yêu cầu mới (ticket)
+- Upload file đính kèm
+- Lấy thông tin request
+- Helper methods để map và build data
+
+## Cài đặt
+
+### Import trong module:
+```javascript
+import ITSMAPIService from './itsm-api.service.js';
+```
+
+### Hoặc sử dụng global (sau khi load script):
+```javascript
+const ITSMAPIService = window.ITSMAPIService;
+```
+
+## Khởi tạo
+
+```javascript
+const apiService = new ITSMAPIService({
+  baseUrl: 'https://your-api-domain.com',
+  apiKey: 'your-api-key',
+  tenant: 'your-tenant-name'
+});
+```
+
+### Options
+
+| Option | Type | Default | Mô tả |
+|--------|------|---------|-------|
+| `baseUrl` | string | `''` | Base URL của API ITSM (bắt buộc) |
+| `apiKey` | string | `''` | API Key để xác thực (bắt buộc) |
+| `tenant` | string | `''` | Tenant name (pn header) (bắt buộc) |
+
+## Methods
+
+### 1. createRequest(requestData)
+
+Tạo yêu cầu mới (ticket).
+
+**Parameters:**
+- `requestData` (Object): Dữ liệu yêu cầu theo format API
+
+**Returns:** `Promise<Object>`
+
+**Ví dụ:**
+```javascript
+const requestData = {
+  requester: {
+    name: 'Lê Trường Tình'
+  },
+  category: {
+    name: 'A01A00 - Quản lý an toàn thông tin'
+  },
+  subcategory: {
+    name: 'A01A01 - Hệ thống'
+  },
+  priority: {
+    name: 'Trung bình'
+  },
+  subject: 'Test ITSM',
+  description: '<div>Test description</div>',
+  site: {
+    name: 'Your Site Name'
+  },
+  item: {
+    name: 'Danh sách chức năng'
+  },
+  template: {
+    name: 'A01A00 - Quản lý an toàn thông tin'
+  },
+  udf_fields: {
+    udf_pick_301: 'Value 1',
+    udf_pick_302: 'Value 2',
+    udf_pick_303: 'Value 3',
+    udf_pick_304: 'Value 4',
+    udf_pick_305: 'Value 5',
+    udf_pick_306: 'Value 6'
+  },
+  attachments: [],
+  assets: []
+};
+
+const response = await apiService.createRequest(requestData);
+console.log('Request ID:', response.request.id);
+```
+
+**Response:**
+```json
+{
+  "response_status": {
+    "status_code": 2000,
+    "status": "success"
+  },
+  "request": {
+    "id": "18391",
+    "ola_due_by_time": null,
+    "resolution": {
+      "resolution_attachments": [],
+      "content": null
+    },
+    "onhold_time": null,
+    "is_trashed": false
+  }
+}
+```
+
+### 2. uploadAttachment(requestId, files)
+
+Upload file đính kèm vào ticket đã tạo.
+
+**Parameters:**
+- `requestId` (string): ID của ticket
+- `files` (File | File[]): File hoặc mảng các file cần upload
+
+**Returns:** `Promise<Object>`
+
+**Ví dụ:**
+```javascript
+// Upload 1 file
+const fileInput = document.getElementById('file-input');
+const file = fileInput.files[0];
+const response = await apiService.uploadAttachment('18391', file);
+
+// Upload nhiều file
+const files = Array.from(fileInput.files);
+const response = await apiService.uploadAttachment('18391', files);
+```
+
+### 3. createRequestWithAttachments(requestData, files)
+
+Tạo request và upload file cùng lúc (all-in-one method).
+
+**Parameters:**
+- `requestData` (Object): Dữ liệu yêu cầu
+- `files` (File | File[]): File đính kèm (optional)
+
+**Returns:** `Promise<Object>`
+
+**Ví dụ:**
+```javascript
+const requestData = {
+  requester: { name: 'Nguyễn Văn A' },
+  category: { name: 'A01A00 - Quản lý an toàn thông tin' },
+  priority: { name: 'Trung bình' },
+  subject: 'Test with attachment',
+  description: 'Test description'
+};
+
+const files = Array.from(document.getElementById('file-input').files);
+const response = await apiService.createRequestWithAttachments(requestData, files);
+```
+
+### 4. getRequest(requestId)
+
+Lấy thông tin request theo ID.
+
+**Parameters:**
+- `requestId` (string): ID của request
+
+**Returns:** `Promise<Object>`
+
+**Ví dụ:**
+```javascript
+const requestInfo = await apiService.getRequest('18391');
+console.log(requestInfo);
+```
+
+### 5. mapPriority(priority)
+
+Helper method để map priority từ form widget sang format API.
+
+**Parameters:**
+- `priority` (string): 'low', 'medium', 'high', 'none'
+
+**Returns:** `string`
+
+**Ví dụ:**
+```javascript
+const priority = apiService.mapPriority('high'); // Trả về: 'Cao'
+```
+
+### 6. mapCategory(category)
+
+Helper method để map category từ form widget sang format API.
+
+**Parameters:**
+- `category` (string): Category từ form
+
+**Returns:** `string | null`
+
+**Ví dụ:**
+```javascript
+const category = apiService.mapCategory('hardware');
+// Trả về: 'A01A00 - Quản lý an toàn thông tin'
+```
+
+### 7. buildRequestData(formData, options)
+
+Build request data từ form data của widget sang format API.
+
+**Parameters:**
+- `formData` (Object): Dữ liệu từ form widget
+  - `title`: string
+  - `description`: string
+  - `category`: string
+  - `priority`: string
+  - `contact`: string
+- `options` (Object): Options bổ sung
+  - `requesterName`: string
+  - `site`: string
+  - `udf_fields`: object
+  - `zia_properties`: object
+  - `template`: string
+  - `item`: string
+  - `subcategory`: string
+
+**Returns:** `Object`
+
+**Ví dụ:**
+```javascript
+const formData = {
+  title: 'Test Request',
+  description: 'Test description',
+  category: 'hardware',
+  priority: 'none',
+  contact: 'test@example.com'
+};
+
+const requestData = apiService.buildRequestData(formData, {
+  requesterName: 'Người dùng',
+  site: 'Your Site Name',
+  udf_fields: {
+    udf_pick_301: 'Value 1'
+  }
+});
+```
+
+## Cấu trúc Request Data
+
+### Đầy đủ các trường:
+
+```javascript
+{
+  requester: {
+    name: string
+  },
+  assets: [],
+  category: {
+    name: string
+  } | null,
+  group: string | null,
+  subcategory: {
+    name: string
+  } | null,
+  technician: string | null,
+  item: {
+    name: string
+  } | null,
+  priority: {
+    name: string // 'Thấp', 'Trung bình', 'Cao', 'Khẩn cấp'
+  },
+  subject: string,
+  description: string, // HTML string
+  site: {
+    name: string
+  } | null,
+  attachments: [],
+  udf_fields: {
+    udf_pick_301: string,
+    udf_pick_302: string,
+    // ... các custom fields khác
+  },
+  template: {
+    name: string
+  } | null,
+  zia_properties: {}
+}
+```
+
+## Error Handling
+
+Tất cả các methods đều throw Error nếu có lỗi:
+
+```javascript
+try {
+  const response = await apiService.createRequest(requestData);
+} catch (error) {
+  console.error('Error:', error.message);
+  // error.message có thể là:
+  // - "API Key không hợp lệ."
+  // - "HTTP error! status: 400"
+  // - hoặc các thông báo lỗi khác
+}
+```
+
+## API Endpoints
+
+### 1. Tạo Request
+- **URL:** `POST {baseUrl}/{tenant}/send`
+- **Headers:**
+  - `authtoken`: API key
+  - `pn`: Tenant name
+  - `Content-Type`: `multipart/form-data` (auto)
+- **Body:** FormData với key `input_data` chứa JSON string
+
+### 2. Upload Attachment
+- **URL:** `PUT {baseUrl}/{tenant}/{id}/upload`
+- **Headers:**
+  - `authtoken`: API key
+  - `pn`: Tenant name
+  - `Content-Type`: `multipart/form-data` (auto)
+- **Body:** FormData với các file
+
+### 3. Get Request
+- **URL:** `GET {baseUrl}/{tenant}/{id}`
+- **Headers:**
+  - `authtoken`: API key
+  - `pn`: Tenant name
+  - `Accept`: `application/json`
+
+## Xem thêm
+
+- Xem tài liệu API đầy đủ tại: `src/assets/13082025 API v2 SDP ITSM SPC.doc`
+- Xem ví dụ sử dụng widget tại: [example.html](./example.html)
+