postMessage를 이용한 DB연동양식 사용법 (권장)

전자결재 API 2021-09-27

panuker 1 댓글 970

1. postMessage 통신방식 도입 배경

동일 출처 정책(same-origin policy)으로 인해 기존에 (document.domain 설정을 이용해) ActProc()함수를 호출하는 방식으로 그룹웨어(전자결재)와 DB연동양식(예: ERP, HRM, ...) 간의 통신을 처리하였으나, 웹표준에서 document.domain을 더이상 권장하지않고 각종 웹브라우저에서도 지원이 중단되고 있는 실정임

이에 저희 지오유그룹웨어에서는 웹표준에서 권장하는 방식중 postMessage 를 이용하는 통신방식을 추가 지원하여 변화해가는 웹 통신환경에 발 맞추어 Cross-Origin Resource Sharing (CORS) 문제에 적극 대응하려 함.

2. postMessage를 이용한 통신 구현방법

2-1. addEventListener 설정

DB연동페이지에서 구현 - 전자결재 상신(결재상신 버튼 클릭)시 postMessage를 이용해 DB연동양식(예: ERP양식, ...)의 처리 로직을 호출할때 수신하는 javascript

window.addEventListener("message",function(e){
    ... ...
});

2-2. postMessage 설정

DB연동페이지에서 구현 - DB연동페이지의 처리가 모두 끝난 후 지오유 그룹웨어 전자결재 상신페이지에 결과를 리턴하기 위한 javascript

window.parent.postMessage({'bizgubun': inputMessage.bizgubun, 'rtnVal':rtnVal}, '*');

2-3. 결재양식의 통신방식 설정

그룹웨어 전자결재 > 환경설정 > 문서양식 관리(등록) 메뉴에서 양식별 설정 - DB연동양식별로 통신방식 설정

2-4. 결재상신 및 DB연동처리 테스트 및 확인

위의 안내대로 처리되었다면, 그룹웨어 전자결재 문서를 상신을 통해 테스트해보세요.
postMessage를 통해 데이타가 제대로 수신되는지? 또한, 그룹웨어 문서로 postMessage가 제대로 송신되는지 체크해 보시기 바랍니다.

3. 수신시 통신규약

3-1. bizgubun (그룹웨어에서 넘어오는 구분값)

actproc_{13자리숫자} 이와 같은 형태로 구성된 문자열

그대로 반환 호출의 정당성과 target구분을 위한 값으로 넘겨받은 문자열을 리턴시 그대로 되돌려 주어야 함.

3-2. status (그룹웨어에서 넘어오는 문서 처리상태값)

F 결재문서를 정상적으로 상신하는 상태

T 결재문서를 임시저장하는 상태<br>작성한 문서를 임시보관함에 저장하는 상태로 실제 상신이 이루어지지 않는 상태를 말함.

window.addEventListener('message', function(e){
    let inputMessage = e.data;
    if(inputMessage.bizgubun.substr(0,7) == 'actproc'){
        ... ... {DB연동페이지의 로직 처리}
    }
});

4. 결과 리턴시 통신규약

4-1. bizgubun

수신받은 구분값 값의 가공없이 넘겨받은 값을 그대로 리턴해야함.

4-2. rtnVal : DB연동 처리결과에 따른 리턴값

true : (boolean형) 정상처리된 상태임을 회신, 결재문서 상신처리를 진행

false : (boolean형) DB연동처리가 실패했음을 회신, 결재작성 상태 유지(상신작업 진행되지 않음)

LineNo : ('json String' or 'json Object') 사전에 설정된 결재라인 번호 회신, 정상상태이므로 결재문서 상신처리 진행

LineStr : ('json String' or 'json Object') 결재라인 문자열을 정의된 형태로 회신, 정상상태이므로 결재문서 상신처리 진행

"InputFormValidationError" : (String) DB연동양식내부에서 validation 오류 발생시 리턴, DB연동양식 내부에서 notification하므로 그룹웨어에서는 별도 알림없이 결재작성 상태 유지.

let rtnVal;

//정상상태
rtnVal = true; 

//실패상태
rtnVal = false; 

//LineNo리턴, json Object, 정상상태
rtnVal = {'LineNo':4}; 

//LineNo리턴, json String, 정상상태
rtnVal = "{'LineNo':4}"; 

//LineStr리턴, json Object, 정상상태
rtnVal = {'LineStr':'gildong|홍길동|2|개발팀|연구원|102|K|Y|YYN|||15|?'}; 

//LineStr리턴, json String, 정상상태
rtnVal = "{'LineStr':'gildong|홍길동|2|개발팀|연구원|102|K|Y|YYN|||15|?'}"; 

//실패상태, DB연동페이지내에서 validation오류인 경우 notification함
rtnVal = "InputFormValidationError"; 

//최종 리턴처리(전자결재페이지로 리턴)
window.parent.postMessage({'bizgubun':inputMessage.bizgubun, 'rtnVal':rtnVal}, '*');

5. 샘플코드

<html>
<head>
<title>postMessage 통신을 위한 DB연동양식페이지 샘플</title>
<script type="text/javascript" language="javascript">
  //그룹웨어 결재상신화면에서 상신버튼을 클릭시 postMessage()를 통해서 호출되는 addEventListener
  window.addEventListener("message",function(e){ 
    let inputMessage = e.data;

    //필수체크 (actproc_{13자리숫자} 이런형태의 값이 넘어옴, 예:actproc_1631686714158)
    if(inputMessage.bizgubun.substr(0,7) == "actproc"){
      //inputMessage.status => "F":결재상신상태, "T":임시저장상태

      .... .... // DB연동내부처리로직 구현


      let rtnVal;  //리턴되는값 (true, false, LineStr, LineNo, "InputFormValidationError")
      rtnVal = true;

      /*
       그룹웨어의 결재상신페이지에 리턴
        1. 'bizgubun' : window.addEventListener()에서 받은값(inputMessage.bizgubun)을 그대로 다시 전달
        2. 'rtnVal' : 리턴되는값 (true, false, LineStr, LineNo, "InputFormValidationError")
      */
      window.parent.postMessage({'bizgubun':inputMessage.bizgubun, 'rtnVal':rtnVal},"*");
    }
  });
</script>
</head>
<body>

  .... .... .... <!--DB연동페이지 내용 HTML-->

</body>
</html>

6. 주의사항

비표준 document.domain 값을 설정하는 구문 사용불가. 웹표준에서도 사용하지 않도록 권장하는 방식임.

ActProc() 불필요 - 연동하는 페이지내의 javascript함수를 직접적으로 호출하는 방식이 아니므로 function ActProc()함수는 필요없음.

bizgubun 그대로 전달 넘겨받은 bizgubun값을 가공없이 window.parent.postMessage 호출시 넘겨준다. <br>절대 가공하면 안되는 값이며 해당 값이 변경될 경우 정상적인 결재문서의 상신처리가 진행되지 않습니다.

status 작성한 문서에 대한 그룹웨어에서의 처리상태를 나타내며, "F"인 경우는 정상적으로 결재상신한 상태이며, "T"인 경우는 실제 상신하는 것이 아니라 임시보관함에 저장하는 상태를 말함.<br>연동하는 외부시스템(예:ERP, ...등등)에서는 해당 처리상태값에 따라 관련 로직의 처리를 구분하여 처리하면 됩니다.

양식설정 postMessage 통신방식을 사용할 DB연동양식은 반드시 지오유그룹웨어 > 전자결재 > 환경설정 > 문서양식 관리(등록)에서 해당 양식의 설정값(Header > "문서내용(본문)") 중 "통신방식"의 값을 "PostMessage방식(권장)"으로 설정하여야 정상적으로 처리됨.

질문이 있으십니까?