REST API 레퍼런스

인스턴스 시작·업무 목록·작업 완료·위임·반송·변수·되돌리기를 HTTP로 호출하는 방법입니다. 표의 「확인」 칸에 ✅가 있는 호출은 이 튜토리얼의 스택에서 실제로 호출해 결과를 확인했습니다.

무엇을 · 왜#

uEngine6의 화면이 하는 일은 모두 REST API로도 할 수 있습니다. 다른 시스템에서 프로세스를 시작하거나 자체 화면에서 작업을 완료할 때, 운영 도구에서 인스턴스를 수정할 때 씁니다(Camunda의 REST API와 같은 역할을 합니다).

인증#

• 토큰: Keycloak realm uengine의 클라이언트 uengine에서 비밀번호 방식(password grant)으로 받습니다. 요청마다 Authorization: Bearer <access_token>을 붙입니다.
• 게이트웨이(:8288)는 로그인 세션 쿠키가 없어도 Bearer만으로 인증할 수 있습니다. 토큰도 쿠키도 없으면 302로 Keycloak 로그인으로 이동합니다.
• 사용자 ID = preferred_username(hong, choi). process-service는 토큰의 preferred_username → email → sub 순으로 사용자를 정합니다(SecurityAwareServletFilter). 그래서 roleMappings·위임의 endpoint에는 이메일이 아니라 사용자 이름을 씁니다.
• 권한: 작업을 바꾸는 API(완료·위임·반송·SKIP)는 「지금 그 작업의 담당자인가」를 확인합니다. 담당자가 아니면 403입니다. 인스턴스 시작은 역할이 없는 사용자(choi)로도 가능했습니다. 레인에 그룹·역할 규칙이 있으면 작업은 해당 그룹·역할의 사용자에게만 배정됩니다.

TOKEN=$(curl -s http://localhost:8280/realms/uengine/protocol/openid-connect/token \
  -d client_id=uengine -d grant_type=password -d username=hong -d password=1234 | jq -r .access_token)

따라 하기 — 위임 API#

영상에서는 홍길동이 시작한 작업을 API로 최구매에게 넘깁니다. 화면에는 위임 버튼이 보이지 않아(이 브랜치의 결함) 위임은 API로만 합니다. 정의는 첫 프로세스의 「구매 요청 → 결재」 사본 튜토리얼/API/구매결재입니다.

1. 홍길동이 시작합니다. POST /instance로 시작하면 첫 작업 「구매 요청」이 홍길동에게 배정됩니다. GET /instance/<번호>/worklists로 해당 인스턴스의 작업을 확인합니다. 영상에서는 인스턴스 423, 작업 722(NEW, hong)였고, 홍길동의 업무 목록에도 「TaskId : 722」 카드가 있습니다.

   curl -s -X POST http://localhost:8288/instance -H "Authorization: Bearer $TOKEN" \
     -H 'Content-Type: application/json;charset=UTF-8' \
     -d '{"processDefinitionId":"튜토리얼/API/구매결재"}' | jq '{instanceId, name, status}'
   curl -s http://localhost:8288/instance/<번호>/worklists -H "Authorization: Bearer $TOKEN" \
     | jq -c '.[] | {taskId, title, status, endpoint}'
   

   

2. 담당자가 아니면 위임할 수 없습니다. 윤팀장(yoon)의 토큰으로 홍길동의 작업을 위임하면 403과 No permission to delegate this task. currentOwner=hong, userId=yoon이 반환됩니다.
3. 홍길동이 최구매에게 위임합니다. 본문 {"targetType":"USER","endpoint":"choi","resourceName":"choi"}로 호출하면 응답에 최구매에게 새로 배정된 작업(723, NEW)이 포함됩니다. 원래 작업 722는 DELEGATED가 되고 담당자 칸도 choi로 바뀝니다.

   curl -s -X POST http://localhost:8288/work-item/<작업 번호>/delegate -H "Authorization: Bearer $TOKEN" \
     -H 'Content-Type: application/json;charset=UTF-8' \
     -d '{"targetType":"USER","endpoint":"choi","resourceName":"choi"}' | jq '.worklist | {taskId, title, status, endpoint}'
   

   

4. 업무 목록이 바뀝니다. 홍길동의 업무 목록에서 722 카드가 사라지고, 최구매의 업무 목록에 「구매 요청」이 723으로 나타납니다(DELEGATED인 722는 화면에 보이지 않습니다). 업무 목록은 자동으로 갱신되지 않으므로 다시 열거나 새로고침 아이콘을 누릅니다.

   

설정 레퍼런스#

표의 경로는 게이트웨이(http://localhost:8288) 기준입니다. 본문은 모두 Content-Type: application/json;charset=UTF-8입니다.

인스턴스#

ProcessExecutionCommand의 필드:

작업#

정의#

변수 읽기·쓰기 예#

# 쓰기: 값은 JSON 으로 해석됩니다. 문자열은 따옴표까지 보냅니다.
curl -s -X POST http://localhost:8288/instance/317/variable/%EB%A9%94%EB%AA%A8 \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json;charset=UTF-8' -d '"급하게 필요합니다"'
# 읽기: 한글 이름·값은 /variables 로. 프로세스 변수는 키 앞에 ':' 가 붙습니다.
curl -s http://localhost:8288/instance/317/variables -H "Authorization: Bearer $TOKEN" \
  | jq '{memo: .[":memo"], 메모: .[":메모"]}'

확인한 결과(인스턴스 317): {":memo": "urgent", ":메모": "급하게 필요합니다"}. 같은 값을 GET /instance/317/variable/메모로 읽으면 ??? ?????가 반환됩니다. 영문 이름 memo는 단건으로도 urgent가 반환됩니다.

작업을 완료하며 보낸 parameterValues(아규먼트 값)는 매핑하지 않으면 프로세스 변수가 되지 않습니다. 프로세스 변수에 값을 넣으려면 작업 입력값과 데이터 매핑을 보세요.

되돌리기(backToHere) 예#

curl -s -X POST http://localhost:8288/instance/317/activity/UserTask_1/backToHere -H "Authorization: Bearer $TOKEN"

확인한 결과: 완료된 「구매 요청」(515)과 진행 중이던 「결재」(516)가 COMPENSATED가 되고, 「구매 요청」이 새 작업(517)으로 다시 생성되었습니다. 화면에서 되돌리는 방법은 되돌리기와 실패한 작업 다루기에 있습니다.

알려진 제약#

확인 문제#