API로 같은 일 하기

첫 프로세스에서 화면으로 한 일을 curl로 합니다. 토큰을 받고, 인스턴스를 시작하고, 내 할 일에서 작업을 찾아 완료하고, 변수를 쓰고 읽은 뒤, 관리자 화면에서 같은 기록을 확인합니다.

무엇을 · 왜#

다른 시스템에서 프로세스를 시작하거나 해당 시스템의 화면에서 작업을 완료할 때는 REST API를 씁니다. 이 장에서는 가장 짧은 경로만 따라갑니다. 전체 목록은 REST API 레퍼런스에 있습니다.

• 요청은 모두 게이트웨이 http://localhost:8288로 보내고 Authorization: Bearer <토큰>을 붙입니다. 이 스택에서는 세션 쿠키 없이 Bearer만으로 통과합니다.
• 사용자를 가리키는 값(endpoint)은 이메일이 아니라 사용자 이름(hong)입니다.
• 결과에서 필요한 부분만 보기 위해 jq를 씁니다.

따라 하기#

영상은 터미널에서 아래 명령을 실행한 결과를 그대로 촬영했습니다(토큰 값만 앞 24자로 줄였습니다).

1. 토큰을 받습니다.

   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)
   echo "${TOKEN:0:24}…"
   

2. 인스턴스를 시작합니다. 정의 아이디는 화면에서 저장한 경로에서 .bpmn을 뺀 값입니다.

   curl -s -X POST http://localhost:8288/instance -H "Authorization: Bearer $TOKEN" \
     -H 'Content-Type: application/json;charset=UTF-8' \
     -d '{"processDefinitionId":"튜토리얼/빠른시작/구매결재"}' | jq '{instanceId, name, status}'
   

   영상에서 받은 응답:

   {
     "instanceId": "386",
     "name": "구매 결재__2026-11-05",
     "status": "Running"
   }
   

   

3. 내 할 일에서 작업을 찾습니다. 응답 본문에는 taskId가 없고, _links.self.href 끝의 숫자가 작업 번호입니다.

   curl -s http://localhost:8288/worklist/search/findToDo -H "Authorization: Bearer $TOKEN" \
     | jq '._embedded.worklist[] | select((.instId|tostring) == "<인스턴스 번호>")
           | {taskId: (._links.self.href | split("/") | last), title, status, endpoint}'
   

   영상에서 받은 응답:

   {
     "taskId": "644",
     "title": "구매 요청",
     "status": "NEW",
     "endpoint": "hong"
   }
   

   작업 번호는 644입니다. 다음 단계의 <작업 번호> 자리에 넣습니다.
4. 작업을 완료합니다. 아규먼트 값을 parameterValues로 보냅니다. 성공하면 본문 없이 200을 반환합니다.

   curl -s -o /dev/null -w '%{http_code}\n' -X POST http://localhost:8288/work-item/<작업 번호>/complete \
     -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json;charset=UTF-8' \
     -d '{"parameterValues":{"품목":"모니터 2대","금액":600000}}'
   

5. 변수를 쓰고 읽습니다. 작업에 보낸 아규먼트 값(품목·금액)은 데이터 매핑을 하지 않아 프로세스 변수에 저장되지 않습니다. 변수는 API로 직접 쓸 수 있습니다. 값은 JSON으로 해석되므로 문자열은 따옴표를 포함해 보냅니다. 한글 이름은 주소에 넣을 때 인코딩합니다.

   curl -s -o /dev/null -w '%{http_code}\n' -X POST \
     "http://localhost:8288/instance/<인스턴스 번호>/variable/$(jq -rn --arg v 메모 '$v|@uri')" \
     -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json;charset=UTF-8' -d '"급하게 필요합니다"'
   curl -s http://localhost:8288/instance/<인스턴스 번호>/variables -H "Authorization: Bearer $TOKEN" \
     | jq 'with_entries(select(.key | test("품목|금액|메모")))'
   

   두 요청 모두 200을 반환하고, 변수 목록에는 직접 쓴 값만 있습니다(품목·금액은 없습니다).

   {
     ":메모": "급하게 필요합니다"
   }
   

   

6. 다음 작업 「결재」를 완료합니다. 3단계의 요청으로 다시 조회하면 「결재」가 보입니다. 같은 방식으로 {"parameterValues":{"결재의견":"승인합니다"}}를 보내 완료합니다.
7. 상태를 확인합니다.

   curl -s http://localhost:8288/instance/<인스턴스 번호> -H "Authorization: Bearer $TOKEN" | jq '{instanceId, name, status}'
   

   영상에서 받은 응답:

   {
     "instanceId": "386",
     "name": "구매 결재__2026-11-05",
     "status": "Completed"
   }
   

8. 화면에서도 확인합니다. 관리자 화면 /admin/<인스턴스 번호>의 「히스토리」 탭에 API로 끝낸 두 작업이 COMPLETED로 남아 있습니다.

   

설정 레퍼런스#

요청 본문#

응답 구조#

알려진 제약#

확인 문제#