전자결재 품의서를 외부 서비스와 연동하기 위한 기능을 설정하는 방법을 기술 합니다.
품의서별로 연계 서비스를 설정하고, G.Pro 시스템의 고유 키값을 전달하지 않기 때문에,
모든 요청은 모든 외부연동 설정에 대해 매칭되는 유효한 설정을 찾기 때문에, 상세한 오류 메시지가 전달되지 않습니다.
설정된 값과 요청값이 매칭되지 않으면 거의 대부분 연계서비스 연동 설정을 찾을 수 없습니다. 혹은 요청 인수와 매칭되는 품의서를 찾을 수 없습니다.메시지를 수신하게 될 것입니다.
문서빌더로 양식 생성
1.
결재 > 업무양식관리 메뉴에서 양식을 추가 합니다.
양식의 기본 설정을 입력하고, 양식적용여부 값을 “예”로 변경 후 양식빌더열기 버튼을 눌러 양식 설정 모달을 호출 합니다.
전달되는 본문에 맞춰 입력양식을 생성해야 합니다.
사용자가 직접 데이터를 확인하고 상신하도록 하는 경우, 코드, 내용, 날짜 등의 필드를 추가하여 사용할 수 있습니다. 이 경우, 데이터가 전달된 필드 외의 (속성값 지정되지 않은) 필드는 사용자가 값을 입력할 수 있습니다.
문서빌더에 외부 데이터를 주입할 수 있는 필드는 인풋 형태 텍스트, 숫자, 금액, 내용, 결재금액유형의 필드만 지원 합니다.
옵션설정에서 필수입력 필드로 설정하고 본문 매핑할 때, 값을 찾을 수 없는경우 품의서 변환에 실패 합니다.
기본 일반 항목에서 목록에서 제공하는 데이터를 주입하려는 경우 “[].” 접두어를 통해 사용할 수 있습니다.
본문의 항목에서 이 접두어를 가진 역직렬화 키를 만나면, 목록 데이터 중 첫번째 행에 들어있는 값을 채택합니다.
테이블 내의 아이템에서 속성명에 “[].” 접두어를 사용하면 전달된 데이터중 [].key 해당하는 값을 찾습니다.
ex) ((Map<>) list.get(0)).get(“[].AccDate”);
아래에서 본문샘플과 그에 따른 문서양식 설정에 대해 알아봅시다
{
"email": "example@groupware.pro",
"firstName": "example",
"lastName": "groupware",
"phone": "010-1111-2222",
"summary": "전자결재 외부연동 테스트용 방화벽 요청",
"list": [
{
"date": "2025-11-15",
"source": "192.168.0.1",
"destination": "10.10.20.20",
"reason": "전자결재 서비스와 재무 서비스의 데이터 연계"
},
{
"date": "2025-11-15",
"source": "10.10.10.1",
"destination": "211.211.211.255",
"reason": "전자결재 서비스와 외부 서비스간 데이터 연계"
}
]
}
JavaScript
복사
위와 같이 입력양식 필드를 추가하고, 필드의 옵션 패널을 열어 상세 속성을 설정합니다.
옵션 패널에 속성명 항목에 전달되는 본문에서 값을 찾을 수 있는 키를 입력해야 합니다. 예제 에서는 “lastName” 입력 합니다.
테이블의 내부의 필드에 대해서도 속성명 항목은 “키”만 입력해야 합니다. 데이터 패스(ex: list.date)를 입력하면 값이 매핑되지 않습니다.
모든 필드에 대해 속성명을 지정한 후에 “저장”하고 품의서를 생성 합니다.
외부 연동 템플릿 설정
1.
결재 > 외부연동 관리 메뉴에서 + 버튼을 눌러 연동을 원하는 문서양식의 대상 법인을 추가 합니다.
2.
적용 양식 설정 섹션의 추가 버튼을 눌러 연동을 위한 문서 양식을 선택 합니다.
3.
적용 양식 설정 섹션에 추가된 양식에 대해 연동을 위한 연계 시스템에서 취급하는 문서의 고유값을 추가합니다. 여러개의 키를 복합 설정 할 수 있습니다.
4.
양식을 선택하면 우측 섹션에 데이터 전송 설정 패널이 표시 됩니다.
각 탭은 다음을 의미합니다.
각 탭에서 요청 URI 설정이 http 문자열로 시작되는 경우 양식에서 작성한 연결호스트를 무시하고 해당 값을 URL 취급 합니다.
•
공통
◦
문서,진행상태 요청/수신을 위한 통신에 모두 사용되는 전송항목 설정
•
인증
◦
문서,진행상태 전송 (G.Pro → 연계서비스) 전에 항상 요청 되는 설정
•
문서
◦
문서 정보 수신, 송신 시에 필요한 전송항목 설정
•
진행상태
◦
문서의 결재상태 정보를 수신, 송신 시에 필요한 전송항목 설정
OAuth client_credentials 토큰 발급을 위한 설정 예
위의 예제에서는 토큰을 발급 받지만, 로그인을 통해 세션을 발급받아도 무방 합니다.
위 인증 설정에 따라 생성되는 요청을 서비스로 전송하고 응답되는 헤더와, 본문은 연결된 처리에 사용됩니다.
문서, 진행상태 처리전 반드시 이 요청이 선행됩니다. 이렇게 선행 요청에서 수신받은 응답 데이터는 각 섹션의 전송항목 중 전달 유형을 사용하여 요청에 포함할 수 있습니다.
5.
문서, 진행상태 송/수신 설정
문서를 요청할 때 사용되는 정보를 입력합니다.
API 방식을 사용하는 경우 수신포맷, 데이터 패스 정보만 사용되기 때문에 나머지는 dummy 데이터로 채워도 됩니다.
데이터 패스 설정에 대해 알아봅시다.
본문 데이터가 포함된 경로까지의 패스를 [.] 기호로 체이닝해 표시하면 됩니다.
본문 데이터의 root 자체가 문서 데이터라면 . 지정하면 됩니다.
•
JSON 포맷의 경우
{
"documentId": "22eb91d5-3897-402a-8ecd-16c382571cd3",
"templateId": 1209,
"document": {
"email": "example@groupware.pro",
"firstName": "example",
"lastName": "groupware",
"phone": "010-1111-2222",
"summary": "전자결재 외부연동 테스트용 방화벽 요청",
"list": [
{
"date": "2025-11-15",
"source": "192.168.0.1",
"destination": "10.10.20.20",
"reason": "전자결재 서비스와 재무 서비스의 데이터 연계"
},
{
"date": "2025-11-15",
"source": "10.10.10.1",
"destination": "211.211.211.255",
"reason": "전자결재 서비스와 외부 서비스간 데이터 연계"
}
]
}
}
JSON
복사
◦
위와 같은 데이터를 전송한다면 document 지정해야 합니다.
•
XML 포맷의 경우
<?xml version="1.0" encoding="UTF-8" ?>
<root>
<DataSet>
<documentId>22eb91d5-3897-402a-8ecd-16c382571cd3</documentId>
<templateId>1209</templateId>
<documentBody>
<email>example@groupware.pro</email>
<firstName>example</firstName>
<lastName>groupware</lastName>
<phone>010-1111-2222</phone>
<summary>전자결재 외부연동 테스트용 방화벽 요청</summary>
<list>
<date>2025-11-15</date>
<source>192.168.0.1</source>
<destination>10.10.20.20</destination>
<reason>전자결재 서비스와 재무 서비스의 데이터 연계</reason>
</list>
<list>
<date>2025-11-15</date>
<source>10.10.10.1</source>
<destination>211.211.211.255</destination>
<reason>전자결재 서비스와 외부 서비스간 데이터 연계</reason>
</list>
</documentBody>
</DataSet>
</root>
XML
복사
◦
위와같은 데이터를 전송한다면 DataSet.documentBody 지정해야 합니다.
◦
XML 형식의 데이터의 경우 Declaration 보내도 되고 보내지 않아도 됩니다.
◦
XML 형식의 데이터의 경우 루트 태그는 Deserialize 처리시 무시되므로 DataSet 부터의 컨텐츠가 담긴 경로 까지를 작성하면 됩니다.
템플릿에 테이블이 존재하는 경우,
전달된 데이터에서 데이터패스 설정된 문서 본문데이터를 찾은 후,
그 하위에서 재귀적으로 반복객체를 찾아, 처음 발견되는 반복객체를 테이블 목록객체로 사용합니다.
전송항목 설정옵션에 대해 알아봅시다.
전송시점
전송시에 전달 해야 하거나, 수신시에 체크 해야 하는 값을 정의합니다.
양방향의 경우 전송시 해당 값을 전달하고, 수신시에는 해당 값을 확인 합니다.
전송위치
지정된 값을 포함할 위치를 지정합니다.
속성 값 유형
연계 서비스로 전달할 값을 조합 거나, 수신된 값을 사용하기 위한 속성
•
인가 아이디
◦
G.Pro 에서 발급한 인가 아이디 (현재 OAuth 인증으로 사용되도록 변경되어 옵셔널)
•
인가 시크릿
◦
G.Pro 에서 발급한 인가 시크릿 (현재 OAuth 인증으로 사용되도록 변경되어 옵셔널)
•
값
◦
고정된 값
▪
속성 값 필드에 입력된 문자열을 전송하거나, 수신된 데이터에서 해당 값이 맞는지 체크합니다.
•
전달
◦
요청 본문, 인증 본문, 인증 헤더로 수신한 값을 전달
◦
전달속성 → 전달할 키 값을 지정할 수 있습니다.
▪
예를들어 세션 인증을 받은경우
•
속성키: Set-Cookie
•
전달속성: Cookie
▪
토큰 인증을 받은경우
•
속성키: access_token
•
전달속성: Authorization
•
전달값 접두어: Bearer
•
G.Pro 고유번호
◦
그룹웨어에서 생성된 문서의 고유번호
•
상신자 이메일
◦
현재 문서를 상신한 사용자의 이메일
•
진행상태 코드
◦
현재 문서의 진행상태
•
마지막 결재자 성명
◦
해당 문서의 최종 결재자 성명
•
마지막 결재자 소속
◦
해당 문서의 최종 결재자 소속
•
마지막 결재자 이메일
◦
해당 문서의 최종 결재자 이메일
•
다음 결재자 성명
◦
해당 문서의 다음 결재 대기자 성명
•
다음 결재자 소속
◦
해당 문서의 다음 결재 대기자 소속
•
다음 결재자 이메일
◦
해당 문서의 다음 결재 대기자 이메일
•
현재 결재자 성명
◦
현재 문서의 상태를 변경한 사용자 성명
•
현재 결재자 소속
◦
현재 문서의 상태를 변경한 사용자 소속
•
현재 결재자 이메일
◦
현재 문서의 상태를 변경한 사용자 이메일
진행상태의 데이터 전송설정은 기본적으로 문서의 전송설정과 동일합니다. 다만, 수신포맷, 진행상태 코드 매핑 설정 해야 합니다. 진행상태 코드 매핑값을 설정하지 않으면 placeholder 표시되는 값이 그대로 전달 됩니다.
반드시 요청을 특정할 수 있는 전송항목이 하나 이상 정의되어야 합니다.
따라서, 모든 유형의 요청에 특정 수신값을 하나 이상 지정하는 것을 권장 합니다.
문서 설정에 반드시 작성자 이메일 항목을 설정하고 전송본문에 포함해야 합니다.
만약 모든 문서와 매핑 되도록 설정하면, 모든 템플릿 양식에 대해 외부 연동이 동작하지 않게되오니 반드시 주의하여 전송 항목을 설정해야 합니다.
연계 서비스와 데이터 연동
연계서비스에서 문서 데이터가 준비되면 다음과 같이 두가지 방법으로 연동을 요청할 수 있습니다.
사용자가 직접 문서를 확인하고 추가 데이터를 보정하여 상신하는 경우
https://stage.wf.groupware.pro/draft/external/raw
(stage → 서비스중인 워크스페이스 명으로 교체 필요)
1.
이 URL 호출하면 사용자는 인가 페이지에서 로그인을 시도합니다. (이미 로그인 된 사용자는 패스됨)
2.
인가에 성공하면 데이터 전송 설정 에서 등록된 문서설정과 일치하는 템플릿을 찾습니다.
3.
템플릿을 찾으면, 해당 설정에 정의된 데이터 전송 설정 문서 요청 URI 엔드포인트로 전송 항목값을 사용하여 문서 본문 데이터를 요청합니다.
4.
수신한 본문데이터를 품의서 양식 템플릿에 맞춰 변환 합니다.
5.
사용자가 품의서 본문을 확인 후 버튼을 눌러 상신을 진행 합니다.
6.
해당 템플릿의 진행상태 설정에 따라 연계서비스로 현재 상태정보를 전송 합니다.
API 통해 전달하는 데이터를 그대로 상신하는 경우
POST https://stage.wf.api.groupware.pro/v1/external/connect/draft/raw/:draftTemplateId
(stage → 서비스중인 워크스페이스 명으로 교체 필요)
•
draftTemplateId (Optional)
•
이 요청을 사용하는 경우 /oauth/token 엔드포인트를 통하여 client_credentials 타입의 엑세스 토큰을 발급받아야 함
1.
2.
토큰헤더와 함께 본문 전송
3.
요청 작성자의 결재선 기본 설정값 으로 문서 상신 처리
4.
해당 템플릿의 진행상태 설정에 따라 연계서비스로 현재 상태정보를 응답 본문으로 방출 합니다.
모든 방식에서 문서의 상태가 변경되면, 해당 템플릿에 설정된 진행상태 설정에 따라 연계서비스로 현재 상태정보를 전송합니다.
주의 하세요.
연계 서비스로 상태값을 전송 하지 못하더라도 결재 진행에 영향을 미치지 않습니다.
G.Pro 서비스와 연계서비스 간 설정되는 값에 대해 대/소문자 구분을 반드시 일치시켜야 합니다.
고유값이 지정되고, 송신설정에 같은 속성키 값이 지정되는 경우 송신 설정이 무시되고 저장하고 있는 고유값을 전달합니다.
문서내용 조회 요청
(stage → 서비스중인 워크스페이스 명으로 교체 필요) [GET, POST 방식만 지원]
•
문서 설정에 반드시 G.Pro 고유번호 항목을 설정하고 전송 본문에 포함해야 합니다.
진행상태 조회 요청
(stage → 서비스중인 워크스페이스 명으로 교체 필요) [GET, POST 방식만 지원]
•
문서 설정에 반드시 G.Pro 고유번호 항목을 설정하고 전송 본문에 포함해야 합니다.
OAuth 토큰을 발급받기 위한 예제 입니다.
POST https://stage.wf.api.groupware.pro/v1/oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=발급받은_클라이언트_아이디&client_secret=발급받은_클라이언트_시크릿&state=해시값(Optional)
Shell
복사
stage → 서비스중인 워크스페이스 명으로 교체
클라이언트 아이디/시크릿은 고객센터에 연락하여 서비스명을 알려주시고 받으실 수 있습니다.
응답 본문에서
token_type → PascalCase 변환
access_token 값을 추출
서비스 요청 헤더에 포함합니다.
Authorization: ${tokenType} ${accessToken}
Shell
복사