매핑

개요

매핑은 소스 메시지의 데이터를 타깃 메시지로 변환하는 규칙을 정의합니다. AnyLink에서는 외부 매핑, 내부 매핑, 임베디드 매핑의 3가지 유형을 제공합니다.

구분	외부 매핑	내부 패밍	임베디드 매핑
성격	독립된 리소스	플로우 액티비티	아웃바운드 룰 액티비티의 속성
생성 위치	리소스 트리 (거래/거래그룹 하위)	플로우 편집기 (노드 추가)	아웃바운드 룰 액티비티 프로퍼티 패널
재사용	여러 플로우에서 참조 가능	해당 플로우 전용	해당 액티비티 전용
적합한 상황	공통 매핑 규칙을 여러 곳에서 재사용하는 경우	특정 플로우에서만 사용하는 일회성 매핑인 경우	아웃바운드 룰 호출 시 요청/응답 메시지를 변환하는 경우

구분

외부 매핑

내부 패밍

임베디드 매핑

성격

독립된 리소스

플로우 액티비티

아웃바운드 룰 액티비티의 속성

생성 위치

리소스 트리 (거래/거래그룹 하위)

플로우 편집기 (노드 추가)

아웃바운드 룰 액티비티 프로퍼티 패널

재사용

여러 플로우에서 참조 가능

해당 플로우 전용

해당 액티비티 전용

적합한 상황

공통 매핑 규칙을 여러 곳에서 재사용하는 경우

특정 플로우에서만 사용하는 일회성 매핑인 경우

아웃바운드 룰 호출 시 요청/응답 메시지를 변환하는 경우

임베디드 매핑을 생성하는 방법은 플로우 생성 시 아웃바운드 룰 액티비티의 파라미터 설정에서 요청 메시지 및 응답 메시지의 매핑을 정의합니다. 자세한 내용은 파라미터 설정을 참고합니다.

외부 매핑과 내부 매핑의 생성 및 사용 방법은 각 절의 설명을 참고합니다.

매핑 타입

필드 매핑

필드 매핑(Field Mapping)은 소스 필드의 값을 타깃 필드로 직접 복사합니다.

필드 매핑 설정 구성 요소는 다음과 같습니다.

항목	설명
소스 변수	소스 메시지를 식별하는 변수명입니다.
소스 필드	소스 메시지의 필드 경로입니다.
타깃 변수	타깃 메시지를 식별하는 변수명입니다.
타깃 필드	타깃 메시지의 필드 경로입니다.

항목

설명

소스 변수

소스 메시지를 식별하는 변수명입니다.

소스 필드

소스 메시지의 필드 경로입니다.

타깃 변수

타깃 메시지를 식별하는 변수명입니다.

타깃 필드

타깃 메시지의 필드 경로입니다.

다음은 필드 매핑의 예시입니다.

소스: request.orderId → 타깃: response.transactionId
소스: request.customer.name → 타깃: response.customerName

표현식 매핑

표현식 매핑(Expression Mapping)은 지정한 고정값을 데이터 타입에 맞게 변환하여 타깃 필드에 설정합니다. 소스 필드를 참조하지 않고 상수값을 직접 입력할 때 사용합니다.

표현식 매핑 설정 구성 요소는 다음과 같습니다.

항목	설명
데이터 타입	값의 데이터 타입입니다. 입력값이 지정한 타입으로 변환됩니다.
표현식	타깃 필드에 설정할 고정값입니다.
타깃 변수	타깃 메시지를 식별하는 변수명입니다.
타깃 필드	타깃 메시지의 필드 경로입니다.

항목

설명

데이터 타입

값의 데이터 타입입니다. 입력값이 지정한 타입으로 변환됩니다.

표현식

타깃 필드에 설정할 고정값입니다.

타깃 변수

타깃 메시지를 식별하는 변수명입니다.

타깃 필드

타깃 메시지의 필드 경로입니다.

다음은 표현식 매핑의 예시입니다.

표현식 데이터 타입 결과

표현식	데이터 타입	결과
`ORDER_PREFIX`	STRING	`"ORDER_PREFIX"` (문자열은 따옴표로 감싸서 처리됩니다.)
`100`	INTEGER	`100` (정수)
`true`	BOOLEAN	`true` (불리언)
`3.14`	DOUBLE	`3.14` (실수)

ORDER_PREFIX

STRING

"ORDER_PREFIX" (문자열은 따옴표로 감싸서 처리됩니다.)

100

INTEGER

100 (정수)

true

BOOLEAN

true (불리언)

3.14

DOUBLE

3.14 (실수)

null 처리

소스와 타깃의 데이터 타입이 동일하다는 전제 하에 매핑이 진행됩니다.

null 값은 다음과 같이 처리합니다.

상황	동작
소스 값이 null인 경우	타깃 필드에 null 값을 설정합니다.
소스 필드가 존재하지 않는 경우	타깃 필드에 null 값을 설정합니다.
타깃 필드가 null을 허용하지 않는 경우	null 대신 기본값(예: 0, false 등)으로 설정됩니다.

상황

동작

소스 값이 null인 경우

타깃 필드에 null 값을 설정합니다.

소스 필드가 존재하지 않는 경우

타깃 필드에 null 값을 설정합니다.

타깃 필드가 null을 허용하지 않는 경우

null 대신 기본값(예: 0, false 등)으로 설정됩니다.

외부 매핑

외부 매핑은 독립적인 리소스로서 거래 또는 거래그룹 하위에서 생성할 수 있습니다. 공통되는 매핑 로직을 한 곳에서 관리하고 여러 플로우에서 재사용할 수 있습니다.

외부 매핑의 특징은 다음과 같습니다.

소스 메시지에서 타깃 메시지로 데이터를 변환합니다.
필드 대 필드의 직접 매핑을 지원합니다.
고정값 설정을 지원합니다.
여러 플로우에서 재사용이 가능합니다.

외부 매핑 생성

리소스 트리에서 원하는 거래 또는 거래그룹의 컨텍스트 메뉴를 열고 [리소스 생성] > [매핑 생성]을 선택합니다.

매핑 생성 화면이 표시되면 설정 옵션을 입력하고 [생성] 버튼을 클릭합니다.

다음은 설정 항목에 대한 설명입니다. (*: 필수 설정 항목)

항목	설명
매핑 아이디 *	외부 매핑을 식별하기 위한 고유 ID입니다. 영문, 숫자 및 언더스코어(_)를 사용할 수 있으며, 2~32자 이내로 입력해야 합니다.
매핑 이름	외부 매핑의 표시 이름입니다. 2~32자 이내로 입력해야 하며, 영문, 숫자 및 다음 특수문자를 사용할 수 있습니다. 언더스코어(_), 하이픈(-), 대괄호([]), 중괄호({}), 괄호(()), 쉼표(,), 콜론(:)
설명	외부 매핑에 대한 설명을 작성합니다.

항목

설명

매핑 아이디 *

외부 매핑을 식별하기 위한 고유 ID입니다. 영문, 숫자 및 언더스코어(_)를 사용할 수 있으며, 2~32자 이내로 입력해야 합니다.

매핑 이름

외부 매핑의 표시 이름입니다. 2~32자 이내로 입력해야 하며, 영문, 숫자 및 다음 특수문자를 사용할 수 있습니다.

언더스코어(_), 하이픈(-), 대괄호([]), 중괄호({}), 괄호(()), 쉼표(,), 콜론(:)

설명

외부 매핑에 대한 설명을 작성합니다.

소스/타깃 메시지 설정

소스 메시지는 매핑의 데이터 원본이 되는 메시지입니다. Source 영역에서 [메시지 추가] 버튼을 클릭하여 메시지를 선택하거나, 리소스 트리에서 메시지를 드래그하여 소스 영역에 놓습니다.

타깃 메시지는 매핑의 결과가 저장되는 메시지입니다. Target 영역에서 [메시지 추가] 버튼을 클릭하여 메시지를 선택하거나, 리소스 트리에서 메시지를 드래그하여 타깃 영역에 놓습니다.

하나의 매핑 정의에서 여러 소스 메시지와 타깃 메시지를 설정할 수 있습니다.

소스 메시지:
├── request (OrderRequest)
└── context (ContextData)

타깃 메시지:
├── response (OrderResponse)
└── log (LogData)

매핑 규칙 관리

다음은 매핑 규칙 편집 화면입니다.

규칙 추가

필드 매핑 규칙을 추가하려면, 소스 필드와 타깃 필드를 각각 선택한 뒤 매핑 추가 버튼()을 클릭합니다.

표현식 매핑 규칙은 타깃 필드를 선택한 뒤 표현식 추가 버튼()을 클릭하여 추가합니다.
규칙 수정

필드 매핑 규칙을 수정하려면, 매핑 연결선 또는 규칙 목록에서 규칙을 클릭하면 하단의 상세 패널에 소스/타깃 정보가 표시됩니다.

표현식 매핑의 경우 표현식 편집기에서 값을 수정할 수 있습니다.
규칙 삭제

매핑 규칙을 삭제하려면, 매핑 연결선 또는 규칙을 선택한 뒤 매핑 삭제 버튼()을 클릭합니다.

플로우에서 외부 매핑 사용하기

다음은 플로우에서 리소스로 등록된 외부 매핑을 사용하는 방법입니다.

플로우 편집기에서 팔레트의 액티비티 노드를 캔버스에 드래그합니다.
노드를 클릭하여 노드 편집 도구 모음에서 노드 타입을 '외부 매핑'으로 선택합니다.
프로퍼티 패널의 기본 정보 영역에서 플로우의 이름과 설명을 입력합니다.
서비스 호출 다이얼로그에서 외부 매핑을 선택합니다. 리소스 트리에서 외부 매핑을 선택하여 서비스 호출 필드에 끌어다 놓을 수도 있습니다.
파라미터 설정 영역에서 소스/타깃 변수 바인딩을 설정합니다.

파라미터 설정 시 소스/타깃 변수는 외부 매핑에 정의된 메시지와 동일한 타입의 메시지 변수만 바인딩할 수 있습니다.

사용 예시

다음은 주문 요청(OrderRequest)을 처리 요청(ProcessRequest)으로 변환하는 시나리오의 설정 예시입니다.

다음은 소스 메시지입니다.

{
  "orderId": "ORD20250115001",
  "customer": {
    "name": "홍길동",
    "email": "hong@example.com",
    "address": {
      "city": "서울",
      "zipCode": "12345"
    }
  },
  "items": [
    {"productId": "P001", "quantity": 2, "price": 10000},
    {"productId": "P002", "quantity": 1, "price": 25000}
  ],
  "totalAmount": 45000
}

다음은 소스 메시지를 타깃 메시지로 변환하기 위한 매핑 설정입니다.

타입	소스	타깃	설명
필드	request.orderId	processRequest.transactionId	주문 ID → 거래 ID
필드	request.customer.name	processRequest.customerName	고객명 직접 매핑
필드	request.customer.address.zipCode	processRequest.deliveryZone	우편번호 → 배송 구역
필드	request.totalAmount	processRequest.amount	총액 직접 매핑
필드	request.items.productId	processRequest.primaryProductId	첫 번째 상품 ID
표현식	ORDER (STRING)	processRequest.channelCode	고정값 설정

타입

소스

타깃

설명

필드

request.orderId

processRequest.transactionId

주문 ID → 거래 ID

필드

request.customer.name

processRequest.customerName

고객명 직접 매핑

필드

request.customer.address.zipCode

processRequest.deliveryZone

우편번호 → 배송 구역

필드

request.totalAmount

processRequest.amount

총액 직접 매핑

필드

request.items.productId

processRequest.primaryProductId

첫 번째 상품 ID

표현식

ORDER (STRING)

processRequest.channelCode

고정값 설정

위 매핑 설정을 적용하면 다음과 같은 타깃 메시지가 생성됩니다.

{
  "transactionId": "ORD20250115001",
  "customerName": "홍길동",
  "deliveryZone": "12345",
  "amount": 45000,
  "primaryProductId": "P001",
  "channelCode": "ORDER"
}

내부 매핑

내부 매핑은 플로우 액티비티로 존재하는 매핑입니다. 별도의 리소스를 생성하지 않고 플로우 내에서 바로 매핑 규칙을 정의합니다.

내부 매핑의 특징은 다음과 같습니다.

해당 플로우에서만 사용 가능하며 재사용할 수 없습니다.
플로우 변수를 직접 소스/타깃으로 사용합니다.
별도의 리소스 생성 없이 플로우 내에서 바로 정의합니다.

내부 매핑 생성

다음은 내부 매핑을 생성하는 방법입니다.

플로우 편집기에서 팔레트의 액티비티 노드를 캔버스에 드래그합니다.
노드를 클릭하여 노드 편집 도구 모음에서 노드 타입을 '내부 매핑'으로 선택합니다.

프로퍼티 패널에서 기본 정보를 설정합니다.

항목	설명
아이디	내부 매핑 노드의 고유 식별자입니다.
이름 *	내부 매핑의 표시 이름을 입력합니다.
설명	내부 매핑에 대한 설명을 작성합니다.

항목

설명

아이디

내부 매핑 노드의 고유 식별자입니다.

이름 *

내부 매핑의 표시 이름을 입력합니다.

설명

내부 매핑에 대한 설명을 작성합니다.

프로퍼티 패널에서 파라미터 정보를 설정합니다.

플로우 변수 중 소스로 사용할 변수를 추가합니다.

항목	설명
SOURCE *	플로우 변수 중 소스로 사용할 변수명이 표시됩니다. 드롭다운 목록에서 변수를 선택한 후 [+ 추가] 버튼을 클릭해 추가합니다.

항목

설명

SOURCE *

플로우 변수 중 소스로 사용할 변수명이 표시됩니다. 드롭다운 목록에서 변수를 선택한 후 [+ 추가] 버튼을 클릭해 추가합니다.

플로우 변수 중 타깃으로 사용할 변수를 추가합니다.

항목	설명
TARGET *	플로우 변수 중 타깃으로 사용할 변수명이 표시됩니다. 드롭다운 목록에서 변수를 선택한 후 [+ 추가] 버튼을 클릭해 추가합니다.

항목

설명

TARGET *

플로우 변수 중 타깃으로 사용할 변수명이 표시됩니다. 드롭다운 목록에서 변수를 선택한 후 [+ 추가] 버튼을 클릭해 추가합니다.

타깃 파라미터가 없으면 매핑 규칙을 정의할 수 없습니다. 반드시 하나 이상의 타깃 파라미터를 추가해야 합니다.

매핑 규칙 정의

파라미터 설정 후 매핑 버튼()을 클릭하면 매핑 다이얼로그가 표시됩니다.

매핑 다이얼로그는 다음 3개 영역으로 구성됩니다.

영역	설명
소스 메시지 트리	소스 파라미터에 설정된 메시지 변수와 해당 메시지의 필드를 트리 형태로 표시합니다.
매핑 연결선	소스 필드와 타깃 필드 간의 매핑 관계를 시각적으로 표시합니다.
타깃 메시지 트리	타깃 파라미터에 설정된 메시지 변수와 해당 메시지의 필드를 트리 형태로 표시합니다.

영역

설명

소스 메시지 트리

소스 파라미터에 설정된 메시지 변수와 해당 메시지의 필드를 트리 형태로 표시합니다.

매핑 연결선

소스 필드와 타깃 필드 간의 매핑 관계를 시각적으로 표시합니다.

타깃 메시지 트리

타깃 파라미터에 설정된 메시지 변수와 해당 메시지의 필드를 트리 형태로 표시합니다.

필드 매핑 정의

다음은 필드 매핑을 수행하는 방법입니다.

소스 메시지 트리에서 필드를 클릭합니다.
타깃 메시지 트리에서 필드를 클릭합니다.
매핑 추가 버튼()을 클릭하면 소스 필드와 타깃 필드 사이에 연결선이 생성됩니다.

표현식 매핑 정의

다음은 표현식 매핑을 수행하는 방법입니다.

타깃 메시지 트리에서 필드를 클릭합니다.
표현식 추가 버튼()을 클릭합니다.
하단의 표현식 편집기에서 고정값을 입력합니다.

매핑 규칙 삭제

생성한 매핑 규칙을 삭제하려면 매핑 연결선 또는 규칙을 클릭하여 선택한 뒤 매핑 삭제 버튼()을 클릭합니다.