인터페이스 액션 유형 제약
인터페이스 액션 유형 제약(Interface action type constraint)은 여러 객체 유형(Object type)이 공통으로 제공해야 할 액션(Action) 기능의 이름과 입력 형태를 정의합니다. 각 구현 유형은 그 기능을 자신의 구체 액션 유형(Action type)에 매핑합니다.
가상의 Ticket 인터페이스에 Create ticket 제약을 두면 Bug는 Create bug, Feature request는 Create feature request 액션으로 구현할 수 있습니다. 공통 기능의 의미는 같아도 각 액션의 실제 로직은 해당 유형에 맞게 작성합니다.
이 기능은 베타이며 추가 검증 기능을 개발 중입니다. 기능이 확장되어도 기존 정의와 매핑 및 지원 워크플로는 유지하지만 설정 UI는 바뀔 수 있습니다.
제약이 정하는 범위
제약은 실행 로직, 제출 조건(Submission criteria), 부수 효과(Side effect)나 입력 폼 배치를 정의하지 않습니다. 이 동작은 실제 액션에 설정합니다.
제약 모델이 모든 업무 의미를 검증하지는 않으므로 Description에 예상 편집, 부수 효과, 제출 동작 등 구현자가 지켜야 할 의미를 설명합니다. 인터페이스 객체를 대상으로 실행하는 액션 규칙과 공통 액션을 매핑하는 이 제약은 서로 구분합니다.
액션 수준의 설정
| 항목 | 용도 |
|---|---|
| Display name | 사용자가 보는 기능 이름 |
| Description | 구현 액션이 수행해야 할 동작 설명 |
| API name | 코드와 플랫폼 구성에서 제약을 참조할 이름 |
| Parameter constraints | 구현 액션이 노출해야 하는 매개변수(Parameter)의 형태 |
| Required | 모든 구현 유형이 이 기능을 제공해야 하는지 여부 |
필수 액션 제약은 모든 구현 유형에서 실제 액션을 선택해야 합니다. 선택 제약은 해당 유형이 기능을 제공할 때 매핑하고 그렇지 않으면 생략할 수 있습니다.
매개변수 제약
각 매개변수 제약에는 자료형, 단일 값 또는 목록 여부, 표시 이름, API 이름과 매핑 필수 여부가 있습니다. 자료형 예로 문자열, timestamp, 객체 참조, 인터페이스 참조, 객체 집합(Object set), 첨부파일(Attachment), 미디어 참조(Media reference)와 구조체(Struct)가 있습니다.
새 매개변수를 직접 정의하거나 기존 인터페이스 속성(Property)에서 추가할 수 있습니다. 속성에서 만들면 표시 이름, 자료형과 필수 상태를 가져오고 표시 이름을 바탕으로 매개변수 API 이름을 생성합니다. API 이름은 수정할 수 있습니다.
필수 매개변수 제약은 구체 액션의 호환되는 필수 매개변수에 매핑해야 합니다. 같은 액션 매개변수를 같은 액션 제약 안의 여러 매개변수 제약에 중복 매핑할 수 없습니다.
객체 참조, 인터페이스 참조, 객체 집합과 구조체 제약은 일반적인 매개변수 종류를 정의합니다. 예를 들어 객체 참조 제약 자체가 하나의 구체 객체 유형에 고정되는 것은 아닙니다. 실제 액션의 호환되는 입력을 선택합니다.
구현과 저장 검증
객체 유형에 인터페이스를 구현한 뒤 Interfaces의 Actions 하위 탭에서 필수 제약마다 실제 액션을 선택합니다. 선택 제약은 생략하거나 연결합니다.
매핑한 제약의 설정 아이콘으로 Configure parameters를 엽니다. 필수 매개변수를 호환되는 필수 액션 입력에 연결합니다. 앱이 값을 전달하거나 미리 채울 필요가 있다면 선택 매개변수도 연결합니다.
다음 경우에는 Ontology Manager가 저장을 허용하지 않습니다.
- 구현 객체 유형에 필수 액션 제약의 매핑이 없습니다.
- 필수 매개변수 제약이 매핑되지 않았습니다.
- 매핑한 매개변수의 자료형이 호환되지 않습니다.
- 같은 구체 액션 매개변수를 여러 제약에 중복 매핑했습니다.
- 매핑이 가리키는 액션 제약이나 매개변수 제약이 삭제되어 존재하지 않습니다.
상속과 필수 여부
인터페이스 확장은 액션 제약도 상속합니다. 자식 인터페이스를 구현하는 유형은 상속한 필수 제약과 자식이 직접 정의한 필수 제약을 모두 만족해야 합니다. 여러 인터페이스에 공통인 기능은 상위에 두고 자식에만 필요한 기능은 자식에 추가합니다.
모든 구현 유형이 제공해야 앱이 동작하는 기능은 required로 지정합니다. 일부 유형에만 의미가 있거나 기능을 점진적으로 도입할 때에는 optional을 선택할 수 있습니다.
매개변수도 모든 구현 액션이 필수 입력으로 노출해야 할 때에만 required로 지정합니다. 구현에서 내부 계산하거나 기본값을 쓰거나 필요하지 않은 값은 선택 조건으로 두어 불필요하게 구현을 막지 않습니다.
사용 환경과 제한
| 환경 | 지원과 사용 방식 |
|---|---|
| Ontology Manager | 제약 정의와 액션 및 매개변수 매핑을 지원하고 저장 시 모든 구현의 필수 조건을 검증합니다. 소비 앱이 제약을 직접 노출하지 않아도 공통 기능 계약을 관리할 수 있습니다. |
| Marketplace | 액션 제약을 포함한 인터페이스를 패키징하고 설치합니다. |
| TypeScript OSDK | 구현 객체 유형에서 제약을 만족하는 실제 액션을 찾아 그 액션을 호출할 수 있습니다. 제약 자체를 직접 호출하지는 못합니다. |
| Workshop | 최종 사용자에게 이 제약을 직접 노출하지 않습니다. TypeScript OSDK로 실제 액션을 찾아 호출하는 사용자 정의 위젯을 사용하면 이 경로를 구성할 수 있습니다. |
| Pipeline Builder | 구현 과정에서 액션 제약을 매핑할 수 없습니다. 필수 제약이 있으면 Ontology Manager에서 구현과 매핑을 합니다. |
일반적인 인터페이스 지원이 액션 제약 지원까지 포함한다는 뜻은 아닙니다. 매핑한 액션의 규칙, 제출 조건, 권한과 부수 효과가 제약 설명의 업무 의미에 맞는지도 직접 검토합니다.