ServiceNow¶
ServiceNow 알림 대상은 Guance 알림을 POST JSON으로 ServiceNow 수신 엔드포인트에 전송합니다. 수신 프로세스는 알림을 파싱한 후 인스턴스의 비즈니스 규칙에 따라 Incident(장애 티켓)를 생성하거나 다른 처리 흐름을 트리거할 수 있습니다.
이 문서에서는 Scripted REST API를 사용합니다. 이는 ServiceNow 관리자가 생성하는 사용자 지정 HTTP 인터페이스입니다. 수신 스크립트는 알림 필드를 티켓 필드로 변환하고 티켓 생성, 중복 제거, 흐름 및 상태 유지를 제어합니다.
ServiceNow에서 수신 엔드포인트 구성¶
API와 리소스를 생성하려면 ServiceNow의 web_service_admin 또는 admin 역할이 필요합니다. 호출 계정은 수신 리소스의 인증 정책, ACL(액세스 제어 규칙) 및 대상 티켓 테이블의 권한 요구 사항도 충족해야 합니다.
- All > System Web Services > Scripted REST APIs로 이동하여 API를 생성하고 이름과 API ID를 입력합니다.
- Resources 관련 목록에서 New를 클릭하고 리소스를 생성한 뒤 POST를 선택하고 리소스 경로를 설정합니다. 예:
/notification. application/json요청 형식을 유지하거나 구성하고, Script에서request.body.data를 통해 알림 JSON을 읽고 티켓 필드 매핑을 완료합니다. 아래 수신 스크립트 예시를 참고할 수 있습니다.- 리소스의 Security에서 Requires authentication을 활성화합니다. 인터페이스 호출 권한을 제한해야 하는 경우 Requires ACL authorization을 활성화하고
REST_Endpoint유형의 ACL을 선택합니다. ACL 필드를 비워 두면 상위 API의 ACL을 사용합니다. 인터페이스 호출 권한과 대상 티켓 테이블 및 필드 권한은 각각 구성해야 합니다. - 인스턴스 정책에 따라 인증 자격 증명을 준비합니다. 최초 검증에는 인스턴스에서 허용하는 Basic 인증을 사용할 수 있으며, 호출 및 티켓 생성 권한이 있는 통합 계정과 비밀번호를 준비합니다. Bearer Token 또는 API Key를 사용할 수도 있습니다.
- 리소스를 저장하고 인스턴스 도메인, 네임스페이스, API ID 및 리소스 경로가 포함된 전체 HTTPS URL을 확보합니다.
URL 구조는 다음과 같으며, version은 해당 API가 버전을 사용하는 경우에만 입력하고 리소스에서 실제로 생성된 주소를 기준으로 합니다.
자세한 작업은 Scripted REST API, POST 리소스 생성, 리소스 ACL 구성 및 API 액세스 정책을 참고하세요. 메뉴와 인증 기능은 고객 인스턴스 버전에 따라 다를 수 있습니다.
수신 스크립트 예시¶
다음 예시는 각 알림을 하나의 Incident로 생성합니다. title은 요약에, message와 전체 알림 JSON은 설명에 기록하며 워크스페이스, 이벤트 컨텍스트 및 역링크를 유지합니다. 한 번의 집계 알림에 포함된 여러 이벤트는 동일한 티켓에 저장됩니다.
테스트 인스턴스에서 스크립트를 검증하고, 인스턴스의 필수 필드, 필드 길이, 애플리케이션 액세스 권한 및 비즈니스 규칙에 맞게 조정한 후 사용하세요. 집계 알림이 긴 경우 인스턴스 필드 용량에 따라 티켓 생성을 분할하거나 전체 내용을 별도 첨부 파일로 저장하는 방식을 선택하세요. 각 테스트 요청은 티켓 생성을 실행합니다.
(function process(request, response) {
var data = request.body.data;
if (!data || typeof data !== 'object' || Array.isArray(data)) {
response.setStatus(400);
response.setBody({ error: 'JSON object required' });
return;
}
var incident = new GlideRecordSecure('incident');
incident.initialize();
if (!incident.canCreate() || !incident.short_description.canWrite() ||
!incident.description.canWrite()) {
response.setStatus(403);
response.setBody({ error: 'Incident creation is not permitted' });
return;
}
incident.setValue('short_description', String(data.title || 'Monitoring notification'));
incident.setValue('description', String(data.message || '') +
'\n\n' + JSON.stringify(data, null, 2));
var sysId = incident.insert();
if (!sysId) {
response.setStatus(500);
response.setBody({ error: 'Incident creation failed' });
return;
}
response.setStatus(201);
response.setBody({ sys_id: String(sysId), number: incident.getValue('number') });
})(request, response);
이 예시는 GlideRecordSecure를 통해 현재 호출 사용자의 ACL에 따라 티켓 생성을 수행합니다. 수신 스크립트는 비즈니스 요구에 따라 events를 순회하며 각각 티켓을 생성하거나 이벤트 식별자에 따라 기존 레코드를 업데이트할 수도 있습니다.
스크립트 인터페이스는 ServiceNow Scripted REST 예시, 레코드 생성 권한 canCreate(), 필드 쓰기 권한 canWrite() 및 RESTAPIResponse를 참고하세요.
Guance에서 알림 대상 생성¶
모니터링 > 알림 대상 관리 > 알림 대상 생성으로 이동하여 ServiceNow를 선택합니다.
- 이름을 입력합니다. 목록과 알림 정책에서 알림 대상을 식별하는 데 사용됩니다. 이름은 현재 워크스페이스 내에서 고유하며 최대 200자입니다.
- Webhook 주소에 위 POST 리소스의 전체 HTTPS URL을 입력하고 최종 수신 주소를 사용합니다.
- 인증 방식에서 Basic을 선택하고 해당 엔드포인트에서 허용하는 사용자 이름과 비밀번호를 입력합니다. 또는 수신 측 구성에 따라 다른 인증 방식을 선택합니다.
- 필요에 따라 사용자 지정 요청 헤더를 활성화하고 수신 측에서 추가로 요구하는 키와 값을 입력합니다.
- 테스트 알림 전송을 클릭하여 미리 보고 전송을 확인합니다. ServiceNow에서 수신 요청, 스크립트 실행 및 생성된 티켓을 확인합니다.
- 작업 권한을 구성하고 저장을 확인합니다.
- 알림 정책에서 해당 알림 대상을 선택하고 전송할 이벤트 레벨과 범위를 구성합니다.
인증 방식 및 요청 헤더¶
수신 리소스의 API 액세스 정책은 선택한 인증 방식을 허용해야 합니다. 플랫폼은 제공된 자격 증명에 따라 요청을 전송하며, 토큰 획득과 갱신은 사용자가 관리합니다.
| 인증 방식 | 입력 내용 | 수신 측 준비 |
|---|---|---|
| Basic | 사용자 이름, 비밀번호 | 인스턴스에서 허용하는 통합 계정을 사용합니다. 사용자 이름은 비어 있지 않고 콜론을 포함하지 않아야 합니다. |
| Bearer Token | Token | 인스턴스 OAuth 구성에 따라 유효한 Access Token을 발급받아 원래 값을 입력합니다. 시스템이 Bearer 접두사를 추가합니다. 만료 또는 취소 후에는 즉시 갱신합니다. |
| API Key | 요청 헤더 이름, API Key | 아래 API Key 구성을 완료합니다. 요청 헤더 이름은 인스턴스 구성에 따라 입력합니다. 예: x-sn-apikey. 인스턴스에서 접두사를 요구하는 경우 접두사를 포함한 전체 Key 값을 입력합니다. |
| 무인증 | — | 수신 리소스의 실제 인증 요구 사항에 따라 사용자 지정 요청 헤더를 설정합니다. |
인스턴스에서 Basic Auth Restriction을 강제 적용하기 시작하면 통합 계정도 허용 조건을 충족해야 합니다. 예를 들어 Web Services Access Only(웹 서비스 액세스 전용) 계정으로 설정하거나 snc_basic_auth_api_access 역할을 보유해야 하며, 관리자가 인스턴스 정책에 따라 구성합니다.
API Key를 사용할 때 구성 담당자는 api_service_admin, adaptive_auth_policy_admin 역할이 필요합니다. 인스턴스에서 API Key and HMAC Authentication 플러그인(com.glide.tokenbased_auth)을 활성화하고 다음 구성을 완료해야 합니다.
- API Key의 인바운드 인증 프로필을 생성하고 인증 매개변수로 요청 헤더 방식을 선택합니다. 예:
x-sn-apikey: Auth Header. - REST API Key를 생성하고 호출 사용자를 연결한 뒤 생성된 Token을 복사합니다.
- API 액세스 정책을 생성하고 활성화하여 해당 인증 프로필을 대상 API의 POST 리소스 및 적용 버전에 연결합니다.
자세한 단계는 ServiceNow API Key 구성을 참고하고, Access Token 발급은 REST OAuth 예시를 참고하세요. Basic의 인스턴스 제한은 Basic authentication restriction을 참고하세요.
사용자 지정 요청 헤더 이름은 대소문자를 구분하지 않고 중복 제거됩니다. 선택한 인증 방식에서 생성된 요청 헤더는 동일한 이름의 사용자 지정 헤더보다 우선합니다. Content-Type은 application/json으로 고정되며 Accept의 기본값은 application/json입니다. API Key 요청 헤더 이름은 Content-Type 이외의 유효한 이름을 사용해야 합니다.
자격 증명 편집¶
동일한 주소, 인증 방식 및 ID에서 편집할 때 비밀번호, Token 또는 API Key를 비워 두면 원래 값이 유지되고 새 값을 입력하면 대체됩니다. 주소, 인증 방식, 사용자 이름 또는 API Key 요청 헤더 이름을 변경한 후에는 해당 자격 증명을 입력해야 합니다.
사용자 지정 요청 헤더 값은 암호화되어 저장됩니다. 위 구성이 동일하게 유지되는 경우 저장된 동일 이름의 요청 헤더 값을 비워 두면 유지되고 새 값을 입력하면 대체됩니다. 행을 삭제하면 해당 헤더가 제거됩니다. 요청 헤더를 추가하거나 이름을 변경한 경우, 그리고 위 구성을 변경한 후에는 전체 요청 헤더 값을 입력하세요.
테스트에는 현재 양식에 있는 유효한 구성이 사용됩니다. 저장 후 이후 알림에는 새 구성이 사용됩니다.
알림 내용 및 알림 집계¶
ServiceNow 알림 대상은 간단한 HTTP 요청의 알림 집계 형식을 따르며 일반, 규칙 집계 및 지능형 집계 알림을 지원합니다.
| 필드 | 의미 |
|---|---|
title, message, status |
현재 알림의 제목, 본문 및 상태입니다. |
events |
이벤트 목록입니다. 일반 알림에는 이벤트가 하나 포함됩니다. 집계 알림에는 해당하는 이벤트 그룹이 포함되며 이벤트 컨텍스트와 역링크를 유지합니다. |
workspace_uuid, workspace_name |
이벤트가 속한 워크스페이스의 ID와 이름입니다. |
monitor_checker_links |
규칙 집계 및 지능형 집계 알림의 모니터 이름과 이벤트 목록 링크입니다. |
알림 정책은 어떤 이벤트가 동일한 알림을 구성하는지 결정합니다. 알림 내용 구성이 완료되면 전송이 시작됩니다. 명시적 지연이 구성된 알림은 지정된 시간에 전송됩니다. 수신 스크립트는 위 알림 구조에 따라 필드 변환을 완료한 후 인스턴스의 티켓 처리 로직을 호출합니다.
테스트 및 문제 해결¶
테스트 알림의 필드는 수신 측에서 실제로 수신한 JSON을 기준으로 합니다. 엔드포인트와 인증 테스트를 완료한 후 실제 일반 및 집계 알림으로 필드 매핑과 events 처리 결과를 검증하세요.
수신 엔드포인트가 HTTP 2xx를 반환하는 것은 요청이 완료되었음을 의미할 뿐입니다. ServiceNow 수신 로그, 스크립트 실행 및 티켓 필드를 함께 확인하여 수신 프로세스가 예상 작업을 완료했는지 확인하세요.
| 증상 | 확인 방법 |
|---|---|
| 인증 실패 또는 액세스 권한 없음 | 계정, 토큰 또는 API Key의 유효성, 해당 POST 리소스의 액세스 정책 및 ACL을 확인합니다. |
| 요청은 완료되었으나 티켓이 생성되지 않음 | 수신 스크립트, 대상 테이블 권한, 인스턴스 필수 필드 및 비즈니스 규칙을 확인합니다. |
| 티켓 내용 누락 | request.body.data의 필드 매핑을 확인하고 실제 일반 및 집계 알림으로 각각 검증합니다. 집계 알림은 events 목록을 처리해야 합니다. |
| 전송 실패 | 최종 HTTPS 주소, 인증서 및 네트워크 연결성을 확인합니다. HTTP 3xx 리디렉션은 전송 실패로 처리됩니다. |