eapim-admin/WebContent/guide/error-handling-setting-guide.md

EAPIM 오류 변환 조건 등록 가이드

1. 메시지 키 등록 방법

1.1 메뉴 접근 경로

• 경로: 환경정보 > 어댑터 관리 > 메시지 키 관리

1.2 등록 화면 입력 항목

항목	설명	입력 예시
어댑터명	대상 어댑터 선택	L_TST_OU_RST_SyCj REST Outbound Adapter For Test
메시지유형	JSON/XML 메시지 타입 선택	[JSN] JSON 또는 [XML] XML
추출기능구분	고정값 지정	O (고정)
업무필드명	추출할 필드명 지정 (아래 '1. 필드 추출 패턴' 참고)	- 일반: status - JSON Path: $.response.status - XPath: //response/status
정상값	비교할 값 지정 (아래 '2. 비교 패턴' 참고)	- 일반: 0000 - 예약어: @eq:0000 - 다중값: @contains:0000,2000

1.2 등록 화면 예시

등록 화면 구성:

1. 어댑터명: L_TST_OU_RST_SyC] REST Outbound Adapter For Test 선택
2. 메시지유형: [JSN] JSON 선택
3. 추출기능구분: [O] 응답메시지구분값 추출 선택
4. 업무필드 목록:

   구분	업무필드명	필드시작위치	필드길이	정상값
   1	messageCode	0	0	900

참고: 위 예시는 'messageCode' 필드의 값이 900일 때 정상 응답으로 처리하는 설정입니다.

2. 필드 추출 패턴

필드명 정의 시 사용할 수 있는 패턴과 동작 방식을 설명합니다.

2.1 JSON 필드 추출

패턴	설명	예시	검색 방식
일반 필드명	단순 필드 접근	status	전체 깊이 재귀 검색하여 첫번째 발견된 값 반환
$.	JSONPath 처리	$.response.status	명시적 경로로 검색

일반 필드명 검색 특징:

• 재귀적 깊이 우선 검색
• 첫 번째 발견된 값 반환
• JSONObject와 JSONArray 모두 검색
• 대소문자 구분

예시) 필드명을 "status"로 검색하고 필드값을 "0000"으로 설정했을 때:

{
   "status": "0000",             // 이 값이 먼저 발견되어 반환
   "data": {
      "status": "1111"           // 무시됨
   },
   "items": [
      {
         "status": "2222"        // 무시됨
      }
   ]
}

JSONPath 패턴 예시:

$.orders[0].status           // 배열 첫 요소 접근
$.items[?(@.type=='book')]   // 조건부 필터링
$.prices[?(@>100)]           // 수치 기반 필터링
$..status                    // 모든 status 필드 검색

2.2 XML 필드 추출

패턴	설명	예시	검색 방식
일반 태그명	단순 태그 검색	status	첫 번째 일치 태그 값 추출
//	XPath 처리	//order/status	전체 경로 기반 검색

일반 태그명 검색 특징:

• 단순 문자열 매칭으로 검색
• 첫 번째 발견된 태그만 처리
• 대소문자 구분
• 태그 속성 처리 불가
• 중첩 태그 내부 검색 불가

예시) 필드명을 "status"로 검색하고 필드값을 "0000"으로 설정했을 때:

<response>
   <status>0000</status>          <!-- 이 값이 반환됨 -->
   <data>
      <status>1111</status>       <!-- 무시됨 -->
   </data>
</response>

XPath 패턴 예시:

//order[@id='123']/status     <!-- 속성으로 필터링 -->
//items/item[1]/name          <!-- 인덱스로 접근 -->
//order[price>100]/status     <!-- 조건부 필터링 -->
//items//name                 <!-- 모든 하위 요소 검색 -->

3. 비교 패턴

3.1 일반 비교 (예약어 '@' 미사용)

• 예약어 없이 값을 직접 입력하는 경우 equals 비교를 수행

패턴	설명	예시	비교 결과
(예약어 없음)	일치	0000	값이 "0000"과 정확히 일치

3.2 예약어 비교 패턴

모든 예약어는 @ 접두어로 시작합니다.

3.2.1 기본 비교

패턴	설명	예시	비교 결과
@eq:	일치	@eq:0000	값이 "0000"과 정확히 일치
@ne:	불일치	@ne:E001	값이 "E001"이 아님
@null	null 체크	@null	값이 null 또는 빈 문자열
@!null	not null 체크	@!null	값이 존재하고 비어있지 않음

3.2.2 문자열 패턴

패턴	설명	예시	비교 결과
@contains:	포함	@contains:0000,2000	나열된 값 중 하나와 일치
@!contains:	미포함	@!contains:ERROR	"ERROR" 문자열 미포함
@starts:	시작값	@starts:P	"P"로 시작
@ends:	종료값	@ends:OK	"OK"로 종료

3.2.3 숫자 비교

패턴	설명	예시	비교 결과
@gt:	초과	@gt:100	값이 100 초과
@lt:	미만	@lt:100	값이 100 미만
@ge:	이상	@ge:100	값이 100 이상
@le:	이하	@le:100	값이 100 이하

4. 통합 사용 예시

4.1 JSON 메시지 처리

// 일반 필드명으로 상태 검색 - equals 비교
messageKeyVO.setBwkColNm("status");
messageKeyVO.setBwkColDef("SUCCESS");     // 단순 일치 비교

// 일반 필드명으로 상태 검색 - 예약어 비교
messageKeyVO.setBwkColNm("status");
messageKeyVO.setBwkColDef("@contains:SUCCESS,OK");

// JSONPath로 명시적 경로 검색
messageKeyVO.setBwkColNm("$.response.status");
messageKeyVO.setBwkColDef("@lt:500");

4.2 XML 메시지 처리

// 일반 태그명으로 상태 코드 추출 - equals 비교
messageKeyVO.setBwkColNm("status");
messageKeyVO.setBwkColDef("0000");       // 단순 일치 비교

// 일반 태그명으로 상태 코드 추출 - 예약어 비교
messageKeyVO.setBwkColNm("status");
messageKeyVO.setBwkColDef("@eq:0000");   // 예약어 사용 일치 비교

// XPath로 특정 조건의 상태 코드 추출
messageKeyVO.setBwkColNm("//response/data[@type='main']/status");
messageKeyVO.setBwkColDef("@contains:0000,2000");

// 에러 메시지 null 체크
messageKeyVO.setBwkColNm("errorMessage");
messageKeyVO.setBwkColDef("@null");

5. 주의사항

5.1 필드 추출 시

1. JSON 검색

   • 일반 필드명은 전체 깊이 검색으로 성능 고려 필요
   • 명확한 경로를 알 경우 JSONPath 사용 권장
   • 동일 키가 여러 곳에 있는 경우 JSONPath로 명시적 지정

2. XML 검색

   • 일반 태그명 사용 시 첫 번째 일치 태그만 처리
   • 태그 속성이 있는 경우 XPath 사용 권장
   • 중첩 구조에서는 XPath 사용 권장

5.2 비교 패턴 사용 시

• 예약어가 없는 경우 단순 equals 비교 수행
• 모든 예약어는 @로 시작
• 숫자 비교 시 숫자 형식이 아닌 경우 false 반환
• @contains:는 콤마로 구분된 여러 값 비교 가능

6. 예외 처리

상황	처리 방식
잘못된 XML 태그	빈 문자열 반환
잘못된 XPath	빈 문자열 반환
잘못된 JSONPath	빈 문자열 반환
존재하지 않는 필드	빈 문자열 반환
null 값	빈 문자열 반환
숫자가 아닌 값의 숫자 비교	false 반환
인식할 수 없는 예약어	false 반환