openFrameAPI - 클라이언트

  • 릴리스 버전: Washingtondc
  • 업데이트 날짜 2024년 02월 01일
  • 읽기15분

    • OpenFrame은 통신 파트너가 시스템을 ServiceNow 플랫폼에 통합하는 데 사용할 수 있는 유비쿼터스 프레임입니다.

    핵심 요구사항 중 하나는 파트너 하위 시스템과 원활하게 연결할 수 있는 여러 도메인의 코드를 연결하고 제공하는 기능입니다. 이 교차 도메인 연결은 교차 도메인 문제 없이 연결 및 콜백을 통신 시스템에 등록하는 데 필요합니다.

    OpenFrame에는 ServiceNow 애플리케이션에 있는 부분(TopFrame이라고 함)과 파트너 애플리케이션에서 제공되는 이 API라는 두 가지 중요한 부분이 있습니다. 이 API는 TopFrame과 통신하고 OpenFrame의 시각적 기능을 제어하는 데 필요한 방법을 제공합니다.
    주:
    최신 OpenFrame 라이브러리 참조가 필요한 경우 다음 자원 URI를 사용합니다. https://[servicenow instance]/scripts/openframe/latest/openFrameAPI.min.js.

    openFrameAPI - hide()

    TopFrame에서 OpenFrame을 숨깁니다.

    표 1. 매개변수
    이름 유형 설명
    없음
    표 2. 반환
    유형 설명
    void 
    openFrameAPI.hide()

    openFrameAPI - init(config 객체, successCallback 함수, failureCallback 함수)

    OpenFrame을 초기화하며 첫 번째로 호출되는 메서드여야 합니다.

    이 메서드는 TopFrame으로의 통신을 초기화하고 config 매개변수에 전달된 모든 시각적 요소를 초기화 합니다.

    표 3. 매개변수
    이름 유형 설명
    구성 객체 키 값 쌍의 객체입니다. 사용 가능한 키는 height, width, title, subTitle 및 titleIcon입니다. 모든 키는 옵션입니다.
    successCallback 함수 init 메서드가 성공할 경우 사용되는 콜백 함수입니다. 시스템에 저장된 openframe 구성은 매개변수로 콜백 함수에 전달됩니다.
    failureCallback 함수 init 메서드가 실패할 경우 사용되는 콜백 함수입니다.
    표 4. 반환
    유형 설명
    void 
    var config = {
height: 300,
width: 200
}
function handleCommunicationEvent(context) {
console.log("Communication from Topframe", context);
}
function initSuccess(snConfig) {
console.log("openframe configuration",snConfig);
//register for communication event from TopFrame
openFrameAPI.subscribe(openFrameAPI.EVENTS.COMMUNICATION_EVENT,
handleCommunicationEvent);
}
function initFailure(error) {
console.log("OpenFrame init failed..", error);
}
openFrameAPI.init(config, initSuccess, initFailure);

    openFrameAPI - isVisible(callback 함수)

    TopFrame에 OpenFrame이 표시되는지 확인합니다.

    표 5. 매개변수
    이름 유형 설명
    callback 함수 callback 함수는 true 또는 false 값을 가진 매개변수를 받습니다. OpenFrame이 표시되면 true이고 표시되지 않으면 false입니다.
    표 6. 반환
    유형 설명
    void 
    function callback(isVisible) {
console.log(isVisible)
}
openFrameAPI.isVisible(callback)

    openFrameAPI - openCustomURL(details 문자열)

    TopFrame에서 사용자 지정 URL을 엽니다.

    표 7. 매개변수
    이름 유형 설명
    URL 문자열 2083자 이하의 문자열입니다.
    표 8. 반환
    유형 설명
    void 
    openFrameAPI.openCustomURL('10_cool_things.do');

    openFrameAPI - openServiceNowForm(details 객체)

    양식 URL을 엽니다.

    에이전트가 걸려오는 전화를 받으면 OpenFrame 창에 계정, 연락처 또는 소비자와 같은 정보가 표시됩니다. OpenFrame 창에서 링크를 클릭하면 해당 기록이 표시됩니다.
    • 플랫폼 인터페이스에서 이 API는 TopFrame에 양식 URL을 엽니다.
    • 에이전트 작업 공간에서는 이 API가 상호작용 탭 관리를 지원합니다. 에이전트 작업 공간에서는 상호작용 기록이 상위 탭에 열리고 지정된 엔터티 기록이 상호작용 탭 아래의 하위 탭에 열립니다.
    표 9. 매개변수
    이름 유형 설명
    details 객체 열려는 양식 URL을 식별 하는 키-값 쌍입니다. 
    "details": {
  "entity": "String";
  "interaction_sys_id": "String";
  "query": "String"
}
    details.entity 문자열 테이블 또는 엔터티 이름입니다.
    details.interaction_sys_id 문자열 옵션입니다. 에서 상위 탭으로 에이전트 작업 공간열 상호작용 기록의 Sys_id입니다.
    주:
    플랫폼 인터페이스에서는 interaction_sys_id가 무시됩니다.
    details.query 문자열 열려는 기록을 식별하는 쿼리입니다(예: query:'sys_id=<record_sys_id>').
    표 10. 반환
    유형 설명
    void

    다음 예제는 플랫폼에서의 기본 사용법을 보여줍니다.

    openFrameAPI.openServiceNowForm({entity:'customer_account', 
query:'sys_id=447832786f0331003b3c498f5d3ee452', 'interaction_sys_id':'3be092313b711300758ce9b534efc4dd'});

    다음 예제는 매개변수를 통해 query sysparm_query 및 인코딩된 쿼리를 사용하여 Workspace의 이름 및 성 필드를 채워 양식에 제공된 데이터로 새 기록을 생성하는 방법을 보여줍니다.

    openFrameAPI.openServiceNowForm({ entity: 'sys_user',
query: 'sys_id=-1&sysparm_query=first_name=Ivan^last_name=Greggor' });

    openFrameAPI - openServiceNowFormwithChildTabIf()

    ServiceNow 작업 공간에서 호출되면 하위 탭이 있는 양식을 열고, UI16 인터페이스에서 호출되면 엔터티를 엽니다.

    표 11. 매개변수
    이름 유형 설명
    openServiceNowFormwithChildTab 객체 API가 작업 공간에서 호출되는 ServiceNow 경우 하위 탭이 있는 양식을 열거나 UI16 인터페이스에서 호출되는 경우 엔터티를 여는지 정의합니다.
    openFrameAPI.openServiceNowFormwithChildTablf({
	entity: “String”,
	sys_id: “String”, 	
	parent_entity: “String”,	
	parent_entity_sys_id: “String”,
    openServiceNowFormwithChildTab.entity 문자열 테이블의 이름입니다.
    openServiceNowFormwithChildTab.sys_id 문자열 열려는 기록의 Sys_id입니다.
    openServiceNowFormwithChildTab.parent_entity 문자열 상위 탭으로 열 테이블의 이름입니다.
    openServiceNowFormwithChildTab.parent_entity_sys_id 문자열 열려는 상위 기록의 Sys_id입니다.
    표 12. 반환
    유형 설명
    없음

    다음 예제에서는 구성된 작업 공간에서 상위 엔터티를 상위 탭으로 열거나, UI16에서 호출되는 경우 엔터티만 엽니다.

    openFrameAPI.openServiceNowFormwithChildTablf({
	entity: “customer_account”, 
	sys_id: “447832786f0331003b3c498f5d3ee452”, 	
	parent_entity: “interaction”, 
	parent_entity_sys_id: “3be092313b711300758ce9b534efc4dd”
});

    openFrameAPI - openServiceNowList(details 객체)

    TopFrame에서 목록 URL을 엽니다.

    표 13. 매개변수
    이름 유형 설명
    details 객체 키 값 쌍의 객체입니다. 가능한 키는 다음과 같습니다.
    • 엔터티, 테이블 이름
    • 쿼리, 인코딩된 쿼리 문자열
    표 14. 반환
    유형 설명
    void 
    openFrameAPI.openServiceNowList({entity:'case', query:'active=true'});

    openFrameAPI - setFrameMode(mode)

    OpenFrame 모드를 설정합니다.

    이 API에 전달된 모드:
    • 헤더에 적절한 아이콘을 설정합니다(축소 또는 확장).
    • CTI의 관련 이벤트를 발생시킵니다.
      • openFrameAPI.EVENTS.COLLAPSE
      • openFrameAPI.EVENTS.EXPAND
    표 15. 매개변수
    이름 유형 설명
    Mode 문자열 OpenFrame 모드를 설정합니다. 열거 옵션:
    1. openFrameAPI.FRAME_MODE.COLLAPSE
    2. openFrameAPI.FRAME_MODE.EXPAND
    표 16. 반환
    유형 설명
    void 
    openFrameAPI.setFrameMode(openFrameAPI.FRAME_MODE.COLLAPSE);

    openFrameAPI - setHeight(height)

    OpenFrame 높이를 설정합니다.

    표 17. 매개변수
    이름 유형 설명
    높이 번호 높이(픽셀)
    표 18. 반환
    유형 설명
    void 
    openFrameAPI.setHeight(100);

    openFrameAPI - setIcons(icons 배열)

    OpenFrame 헤더에는 닫기 아이콘 옆에 배치된 아이콘이 포함될 수 있습니다.

    표 19. 매개변수
    이름 유형 설명
    icons 배열 각 아이콘 구성이 imageURL, imageTitle 및 기타 필요한 컨텍스트와 같은 키 값을 가진 객체인 아이콘 구성 목록입니다.
    표 20. 반환
    유형 설명
    void 
    openFrameAPI.setIcons([{imageURL:'https://mydomian.com/image/mute.png',
imageTitle:'mute', id:101}, {imageURL:'https://mydomian.com/image/hold.png',
imageTitle:'hold', id:102}]);

    openFrameAPI - setPresenceIndicator(presence)

    작업 영역에서 에이전트 가용성을 표시하도록 현재 상태 표시기를 설정합니다.

    OpenFrame 구성에 대한 자세한 내용은 OpenFrame 구성 생성을 참조하십시오.

    표 21. 매개변수
    이름 유형 설명
    state 문자열 에이전트의 현재 상태입니다.

    기본 상태:

    • 연락 가능
    • 자리 비움
    • 오프라인

    사용자 지정 상태를 지정할 수도 있습니다.
    color 문자열 작업 영역의 현재 상태 표시기 색입니다.

    지원되는 색:

    • 빨간색
    • 주황색
    • 회색
    • 녹색
    표 22. 반환
    유형 설명
    void 
    openframeAPI.setPresenceIndicator('Available', 'green');

    openFrameAPI - setSize(width 숫자, height 숫자)

    OpenFrame 크기를 설정합니다.

    표 23. 매개변수
    이름 유형 설명
    width 번호 0보다 커야 합니다.
    height 번호 0보다 커야 합니다.
    표 24. 반환
    유형 설명
    void 
    openFrameAPI.setSize(300, 370);

    openFrameAPI - setSubtitle(subTitle 문자열)

    OpenFrame 부제목을 설정합니다.

    표 25. 매개변수
    이름 유형 설명
    subTitle 문자열 256자 이하의 문자열입니다.
    표 26. 반환
    유형 설명
    void 
    openFrameAPI.setSubtitle('+18888888888');

    openFrameAPI - setTitle(title 문자열)

    OpenFrame 제목을 설정합니다.

    표 27. 매개변수
    이름 유형 설명
    제목 문자열 256자 이하의 문자열입니다.
    표 28. 반환
    유형 설명
    void 
    openFrameAPI.setTitle('Incoming Call');

    openFrameAPI - setTitleIcon(icon 객체)

    OpenFrame의 제목 아이콘을 설정합니다.

    표 29. 매개변수
    이름 유형 설명
    icon 객체 키 값 쌍의 객체입니다. 키에는 imageURL, imageTitle 및 기타 필요한 컨텍스트가 포함됩니다.
    표 30. 반환
    유형 설명
    void 
    openFrameAPI.setTitleIcon({imageURL:'/my/image/path.png', imageTitle:'mute', id:101});
    openFrameAPI.setTitleIcon({imageURL:'https://mydomian.com/image/path.png',
imageTitle:'mute', id:101});

    openFrameAPI - setWidth(width)

    OpenFrame 너비를 설정합니다.

    표 31. 매개변수
    이름 유형 설명
    너비 번호 너비(픽셀)
    표 32. 반환
    유형 설명
    void 
    openFrameAPI.setWidth(100);

    openFrameAPI - show()

    TopFrame에서 OpenFrame을 표시합니다.

    표 33. 매개변수
    이름 유형 설명
    없음
    표 34. 반환
    유형 설명
    void 
    openFrameAPI.show()

    openFrameAPI - subscribe(openFrameAPIEVENT 이벤트, eventCallback 함수)

    이벤트를 구독합니다.

    표 35. 매개변수
    이름 유형 설명
    이벤트 openFrameAPIEVENT 다음 이벤트 중 하나입니다.
    • openframe_agent_off_interaction: 채팅 중인 에이전트의 현재 상태를 꺼짐 또는 사용 가능으로 나타냅니다.
    • openframe_awa_agent_presence: 고급 작업 할당(AWA)에서 에이전트 현재 상태가 변경될 때 발생하는 이벤트입니다. 컴퓨터 전화 통합 시스템(CTI) 개발자는 이 이벤트를 구독하여 현재 상태 변경 내용을 수신할 수 있습니다.
    • openframe_awa_workitem_accepted: 에이전트가 작업 항목을 수락하면 발생합니다.
    • openframe_awa_workitem_offered: 에이전트에게 작업 항목이 제공될 때 발생합니다.
    • openframe_awa_workitem_rejected: 에이전트가 작업 항목을 거부할 때 발생합니다.
    • openframe_before_destroy: TopFrame이 언로드되기 전에 발생합니다.
    • openframe_collapse: OpenFrame 헤더에서 축소 아이콘을 클릭하면 발생합니다.
    • openframe_communication: 애플리케이션에 한정되며 사용자 지정할 수 있습니다.
    • openframe_communication_failure: TopFrame으로의 통신이 실패하면 발생합니다.
    • openframe_expand: OpenFrame 헤더에서 확장 아이콘을 클릭하면 발생합니다.
    • openframe_header_icon_clicked: 사용되지 않습니다. 대신 openframe_icon_clicked 또는 openframe_title_icon_clicked를 사용하십시오.
    • openframe_hidden: OpenFrame이 숨겨지면 발생합니다.
    • openframe_icon_clicked: OpenFrame 바닥글에서 닫기 아이콘 이외의 아이콘을 클릭하면 발생합니다. callback이 icon 객체를 매개변수로 받습니다.
    • openframe_shown: OpenFrame이 표시되면 발생합니다.
    • openframe_title_icon_clicked: OpenFrame에서 제목 아이콘을 클릭하면 발생합니다. callback이 titleIcon 객체를 매개변수로 받습니다.
    eventCallback 함수 지정된 이벤트가 발생할 때 호출되는 함수입니다.
    표 36. 반환
    유형 설명
    별도의 설명이 없는 한 없습니다. 대부분의 이벤트 구독에는 반환 값이 없으며, 다음의 경우는 예외입니다.
    AWA에서 openframe_awa_agent_presence 이벤트는 presence 객체를 반환합니다.
    • presence: 에이전트의 현재 상태 및 채널에 대한 정보입니다. 출력 예제는 아래와 같습니다.
    • presence.name: 에이전트의 현재 상태의 이름입니다.
    • presence.sys_id: 현재 상태 sys_id. 현재 상태 [awa_presence_state] 테이블에 있습니다.
    • presence.available: 에이전트를 사용할 수 있는지 여부를 나타내는 플래그입니다.
    • presence.channels: 에이전트와의 사용 가능한 통신 채널을 설명하는 객체 목록입니다.
    • presence.channels.name: 채팅 또는 전화 같은 채널 이름입니다.
    • presence.channels.available: 채널을 사용할 수 있는지 여부를 나타내는 플래그입니다.
    • presence.channels.sys_id: 채널 sys_id. 서비스 채널 [awa_service_channel] 테이블에 있습니다.
    • presence.channels.restrict_update: 사용자가 업데이트를 제한할 수 있는지 여부를 나타내는 플래그입니다.

    예제

    function handleIconClick(context) {
console.log("Icon was clicked", context);
}
openFrameAPI.subscribe(openFrameAPI.events.openframe_awa_agent_presence, handleIconClick);

    출력

    // Sample presence object output
// openframe_awa_agent_presence event only

{
   "result":{
      "presence":{
         "name":"Available",
         "sys_id":"<SysID>",
         "available":true,
         "channels":[
            {
               "name":"Chat",
               "available":true,
               "sys_id":"<SysID>",
               "restrict_update":false
            },
            {
               "name":"Phone",
               "available":true,
               "sys_id":"<SysID>",
               "restrict_update":false
            }
         ]
      }
   }
}

    openFrameAPI - version()

    OpenFrame API 버전을 반환합니다.

    표 37. 매개변수
    이름 유형 설명
    없음
    표 38. 반환
    유형 설명
    문자열 OpenFrame API 버전 
    var version = openFrameAPI.version();

console.log("API version " + version);