액션 웹훅의 실행과 실패 처리

Data Connection 웹훅은 Salesforce, SAP나 설정한 HTTP 서버 등 외부 시스템에 요청을 보냅니다. 액션(Action)에 연결하면 사용자의 결정과 입력을 외부 시스템에 반영할 수 있습니다.

Writeback과 Side effect

Writeback은 한 액션에 하나만 구성합니다. 외부 요청이 실패하면 다른 규칙의 변경을 적용하지 않습니다. 반대로 외부 요청이 성공한 뒤 온톨로지 편집에 실패할 수 있으므로 두 시스템의 원자적 트랜잭션으로 보지 않습니다.

Side effect는 여러 개를 둘 수 있고 실행 순서를 보장하지 않습니다. 입력에 payload 목록을 제공하면 항목 수만큼 호출하며 그 순서도 보장하지 않습니다. 최선형 알림이나 여러 외부 시스템 반영에 사용할 수 있습니다.

입력 매핑

웹훅의 필수 입력을 모두 채워야 합니다. 액션 매개변수(Parameter)에서 매핑할 때에는 자료형이 맞는 입력, 고정값 또는 객체 참조 입력의 속성을 선택합니다.

함수로 만들 때에는 필수 입력의 이름과 자료형에 맞는 사용자 지정 반환형을 사용합니다. 맞지 않으면 OntologyMetadata:ActionWebhookInputsDoNotHaveExpectedType 오류가 발생합니다. 함수는 연결된 객체를 조회하고 그 값을 조합할 수도 있습니다.

단일 payload 함수

다음은 웹훅 입력 ID가 name, industry와 country이고 모두 문자열인 예입니다. Company 유형의 같은 API 이름 속성도 문자열이라고 가정합니다.

functions-typescript/src/companyWebhook.ts에 다음 코드를 둡니다. 해당 Company 유형을 Resource imports에 가져옵니다.

import { Function, UserFacingError } from "@foundry/functions-api";
import { Company } from "@foundry/ontology-api";

export interface MyWebhookInput {
    name: string;
    industry: string;
    country: string;
}

export class MyWebhookFunctions {
    @Function()
    public returnWebhookInput(company: Company): MyWebhookInput {
        if (!company.name || !company.industry || !company.country) {
            throw new UserFacingError("Some required fields are not set.");
        }
        return {
            name: company.name,
            industry: company.industry,
            country: company.country,
        };
    }
}

게시한 함수를 웹훅 입력 생성기로 선택하고 함수가 요구하는 Company 입력을 액션 입력에 연결합니다.

payload 목록으로 두 번 호출

다음 예는 입력 ID가 arg1과 arg2인 별도 웹훅입니다. arg1에는 Company.name, arg2에는 Company.country를 연결하고 Company 두 개에서 두 payload를 만듭니다. Side effect 방식에서 이 목록은 별도 외부 요청 두 번이 됩니다.

functions-typescript/src/twoCompanyWebhook.ts에 작성합니다.

import { Function, UserFacingError } from "@foundry/functions-api";
import { Company } from "@foundry/ontology-api";

export interface TwoCompanyWebhookInput {
    arg1: string;
    arg2: string;
}

export class MyTwoCompanyWebhookFunctions {
    private payload(company: Company): TwoCompanyWebhookInput {
        if (!company.name || !company.country) {
            throw new UserFacingError("Some required fields are not set.");
        }
        return { arg1: company.name, arg2: company.country };
    }

    @Function()
    public createWebhookRequest(company1: Company, company2: Company): TwoCompanyWebhookInput[] {
        return [this.payload(company1), this.payload(company2)];
    }
}

두 예제를 같은 저장소에서 게시한다면 functions-typescript/src/index.ts에서 클래스를 내보냅니다.

export { MyWebhookFunctions } from "./companyWebhook";
export { MyTwoCompanyWebhookFunctions } from "./twoCompanyWebhook";

입력 형식이 다른 두 웹훅의 예제이므로 실제 대상 웹훅에 맞는 함수를 선택합니다. 함수는 payload를 만들고 외부 요청은 설정한 웹훅이 수행합니다.

Writeback 출력 사용

Writeback 웹훅의 출력은 뒤의 온톨로지 규칙, 알림이나 Side effect 웹훅에 사용할 수 있습니다. 규칙의 값 원천에서 Writeback response를 선택한 뒤 필요한 출력을 고릅니다.

입출력의 정의와 추출 조건은 Data Connection 웹훅 참조를 따릅니다.

OAuth와 실행 재시도

REST API 소스가 외부 연결 애플리케이션(Outbound application)의 OAuth 2.0을 사용한다면 Foundry가 사용자를 대신해 승인 흐름과 토큰 취득 및 갱신을 관리하고 호출에 토큰을 전달합니다. 액션 코드에 별도 토큰 갱신 로직을 넣을 필요는 없습니다.

외부 호출의 반복은 외부 상태를 중복 변경할 수 있습니다. 액션 재시도 설정과 대상 시스템의 멱등성을 함께 검토합니다. 웹훅은 시험 실행에서도 종류와 필요한 계산에 따라 실제 호출될 수 있습니다.