소개
이 사용지침서에서는 Oracle EPM Cloud Planning의 Groovy 스크립트에서 외부 REST API를 호출하는 방법을 보여줍니다. 스크립트를 호출하는 메뉴 항목으로 마우스 오른쪽 버튼 누르기 작업 메뉴를 생성하는 방법과 작업 메뉴를 데이터 양식과 연계하는 방법도 알아봅니다.
섹션을 순서대로 완료합니다.
배경
Groovy EPM 객체 모델은 내부(교차 POD 또는 기타 Oracle Cloud Services) 및 외부 REST API를 호출하는 방법을 제공합니다. 이 예에서는 외부 Google Places REST API를 호출하여 ManageEmployees 양식에서 직원 주소 정보를 추가하거나 업데이트하는 Groovy 규칙을 생성하고 실행합니다.
필요 조건
Cloud EPM 실습 자습서에서는 스냅샷을 Cloud EPM Enterprise Service 인스턴스로 임포트해야 할 수 있습니다. 스냅샷은 기존 애플리케이션 또는 비즈니스 프로세스를 통해 임포트할 수 없습니다. 스냅샷을 임포트하기 전에 별도의 Cloud EPM Enterprise Service 인스턴스를 사용하거나 사용하려는 인스턴스에서 기존 애플리케이션 또는 비즈니스 프로세스를 제거하십시오. 스냅샷 가져오기는 기존 콘텐츠를 자동으로 바꾸거나 복원하지 않습니다.
이 자습서를 시작하기 전에 다음을 수행해야 합니다.
- Cloud EPM Enterprise Service 인스턴스에 대한 서비스 관리자에게 접근 권한을 부여합니다.
- 이 스냅샷을 업로드하여 Planning 인스턴스로 임포트합니다. 이전에 다른 Groovy 자습서에 대해 이 스냅샷을 업로드한 경우 동일한 스냅샷을 계속 사용할 수 있습니다.
- 이 자습서에 사용된 Places API(새로 만들기)가 포함된 Google Maps Platform API 사용을 시작하기 전에 API 키를 얻기 위해 등록하고 청구 계정을 만들어야 합니다. 자세한 내용은 Google Maps Platform 시작하기를 참조하십시오.
주:
스냅샷을 임포트하는 마이그레이션 오류가 발생하는 경우 HSS-Shared Services 구성요소는 물론 코어 구성요소의 보안 및 사용자 환경설정 아티팩트를 제외한 마이그레이션을 다시 실행합니다. 스냅샷 업로드 및 임포트에 대한 자세한 내용은 Oracle Enterprise Performance Management Cloud용 마이그레이션 관리 설명서를 참조하십시오.참고:
이 자습서에 필요한 스크립트는 각 섹션의 텍스트 파일로 링크됩니다.계획 계산 변수 로드
이 섹션에서는 Groovy 스크립트에 사용할 수 있도록 XML 파일에서 계산 변수를 업로드합니다.
- HP4_Plan2_Variables.xml에 대한 링크를 마우스 오른쪽 버튼으로 누르고 파일을 로컬 드라이브에 저장합니다.
(네비게이터)을 누른 다음 [생성 및 관리]에서 규칙을 선택하여 Calculation Manager를 엽니다.
- 시스템 뷰에서 EPM Cloud, HP4 순으로 확장합니다. Plan2을 마우스 오른쪽 단추로 누르고 임포트를 선택합니다.

- File Import Details(파일 가져오기 세부정보)에서 로컬 드라이브에서
HP4_Plan2_Variables.xml을 찾아 선택합니다.
- Location Details에서 다음 값을 선택합니다.
- 애플리케이션 유형: EPM Cloud
- 응용 프로그램: HP4
- 큐브: Plan2
- [임포트 옵션]에서 기존 객체 재정의를 선택합니다.

- 임포트를 누릅니다. 임포트 결과를 검토한 다음 확인을 누릅니다.

주:
각 객체에 대한 메시지는 "삽입됨" 또는 "업데이트됨"이라고 말할 수 있습니다. - 취소를 눌러 [임포트] 대화상자를 닫습니다.
Planning에서 명명된 연결 생성
이 섹션에서는 Google Places API에 대한 맵 연결을 생성합니다.
- Calculation Manager를 연 상태로 두고 Planning 브라우저 창으로 돌아갑니다.
(네비게이터)을 누른 다음 [도구]에서 연결을 선택합니다.
- 생성을 누릅니다.
- 기타 웹 서비스 제공자를 선택합니다.

- 다음 값을 입력합니다.
- 연결 이름:
Maps - URL:
https://places.googleapis.com/v1/places:searchText
- 연결 이름:
- 고급 옵션 표시를 누릅니다.

- 다음 값을 사용하여 API-key 헤더를 정의합니다.
- 유형: 헤더
- 보안: 선택됨
- 이름:
X-Goog-Api-Key - 값: Google Maps API 키
API 키를 안전하게 유지합니다.
(추가)을 누르고 다음 값을 사용하여 다른 헤더를 정의합니다.- 유형: 헤더
- 보안: 지워짐
- 이름:
X-Goog-FieldMask - 값:
places.formattedAddress

- 저장 및 닫기를 눌러 접속을 저장합니다.

Groovy 스크립트 생성
이 섹션에서는 미리 정의된 ManageEmployees 폼을 사용하여 사원의 주소를 갱신하는 Groovy 규칙을 생성합니다.

- Calculation Manager 브라우저 창으로 돌아갑니다.
- 시스템 뷰 탭에서 EPM Cloud, HP4, Plan2 순으로 확장합니다. 규칙을 마우스 오른쪽 버튼로 누르고 새로 작성을 선택합니다.

- [이름]에
Groovy Add or Update Employee Address을 입력한 다음 확인을 누릅니다.
- 규칙 편집기에서 디자이너 옵션을 스크립트 편집으로 변경하고 스크립트 유형을 Groovy 스크립트로 설정합니다.

- 이 스크립트를 복사하여 편집기에 붙여넣습니다.
/*RTPS: {Employee} {EmployeeAddress} {Scenario} {Year} {Period} {Entity} {Version}*/
Member employee = rtps.Employee.member
// Get the complete address using the Google Places API (New).
// Use the original RTP value if Google Maps can't find the address.
def address = rtps.EmployeeAddress
HttpResponse<String> jsonResponse = operation.application
.getConnection("Maps")
.post()
.header("Content-Type", "application/json")
.body(json([
"textQuery": rtps.EmployeeAddress.enteredValue
]))
.asString()
println("Google Maps HTTP status: ${jsonResponse.status}")
println("Google Maps response:")
println(jsonResponse.body)
ReadContext ctx = JsonPath.parse(jsonResponse.body)
List places = ctx.read('$.places') as List
if (jsonResponse.status >= 200 && jsonResponse.status < 300 && places && !places.isEmpty()) {
String formattedAddress = ctx.read('$.places[0].formattedAddress')
println("Google Maps formatted address: ${formattedAddress}")
address = getTextCellId(formattedAddress, true)
} else {
println("Google Maps did not return a place. Using original address: ${rtps.EmployeeAddress.enteredValue}")
}
// Generate the calc script to save the employee address
"""SET CREATENONMISSINGBLK ON;
FIX(${fixValues(rtps.Scenario, rtps.Year, rtps.Period, rtps.Entity, rtps.Version, employee)}, "USD")
"Employee Address" = $address;
ENDFIX;"""
첫 번째 라인에서 이 규칙에 사용되는 모든 RTP(런타임 프롬프트)를 정의합니다.
사원 RTP에서 지정한 사원에 대한 Member객체를 가져옵니다.
형식이 지정된 주소가 지정되지 않은 경우 EmployeeAddress RTP를 기본 주소로 사용합니다.
맵 접속을 사용하여 HTTP POST 요청을 전송합니다. 콘텐츠 유형을 application/json로 설정하고 JSONtextQuery필드에 입력된 EmployeeAddress 값을 전달합니다.
문제 해결을 위해 HTTP 상태 및 응답 본문을 기록합니다.
JsonPath를 사용하여 JSON 응답을 구문분석합니다. places배열을List로 명시적으로 변환하여 정적 유형 검사로isEmpty()를 분석할 수 있습니다. 응답 상태가 성공이고 목록이 비어 있지 않은 경우places[0].formattedAddress을 읽고 텍스트 셀 ID로 변환한 후address에 지정합니다. 그렇지 않으면 원래 RTP 값을 유지합니다.
계산 스크립트를 생성하여 RTP로 지정된 교차점에 사원 주소를 저장합니다.주:
맵 연결은 Groovy 스크립트와 Google Places API(새로 만들기) 리소스 간의 통신 링크입니다. - 도구모음에서
(저장)을 누릅니다. 확인을 눌러 정보 메시지를 닫습니다.주:
스크립트를 저장하면 변수 탭에 변수가 표시됩니다.

- 변수 탭에서 직원, 엔티티, 기간, 시나리오, 버전 및 연도에 대해 숨김 여부를 선택하면 사용자가 EmployeeAddress에 대해서만 값을 입력합니다.
주:
사용자가 form에서 규칙을 실행하면 이러한 숨겨진 변수는 form 컨텍스트에서 값을 받습니다.
(저장)을 다시 누릅니다. 확인을 눌러 정보 메시지를 닫습니다.
(검증 및 배포)을 누릅니다. 검증을 위해 다음 RTP 값을 입력합니다.- 직원:
"Full Time Employees" - 엔티티:
"No Entity" - 기간:
Jan - 시나리오:
Current - 버전은
"BU Version_1"입니다. - 연도:
FY26

- 직원:
- 규칙에 값 적용을 선택하여 해당 값을 검증의 기본값으로 저장한 다음 확인을 누릅니다.
주:
검증이 규칙을 실행하지 않지만 검증을 성공하려면 적합한 멤버가 필요합니다. - 프롬프트가 표시되면 확인을 누른 다음 Calculation Manager를 닫습니다.

Groovy 스크립트를 실행할 계획 작업 메뉴 생성
이 섹션에서는 Groovy 규칙을 실행하는 메뉴 항목이 있는 [직원 관리] 작업 메뉴를 생성합니다.
- Planning에서
(네비게이터)을 누른 다음 [생성 및 관리]에서 작업 메뉴를 선택합니다.주:
다른 Groovy 자습서를 완료한 경우 직원 관리 작업 메뉴가 이미 있을 수 있습니다. 그렇지 않으면 4단계로 진행하십시오.
(메뉴 생성)을 눌러 작업 메뉴를 생성합니다.
- [메뉴 이름]에
Manage Employees을 입력한 다음 확인을 누릅니다.
- 직원 관리 작업 메뉴를 선택한 다음
(편집 메뉴)을 누릅니다.
(1차 하위 구성요소 추가)을 누릅니다. 다음 값을 입력하거나 선택합니다.옵션 필드 값 메뉴 항목 Update Employee Address레이블 Update Employee Address유형 비즈니스·규칙 필수 파라미터 직원 큐브 Plan2 비즈니스·규칙 Groovy 사원 주소 추가 또는 업데이트 
- Save를 누릅니다. 확인 메시지에서 확인을 누릅니다.

- 저장을 눌러 작업 메뉴를 저장합니다. 확인 메시지에서 확인을 누릅니다.


- 작업 메뉴 편집기를 닫으려면 취소를 누릅니다.
계획 조치 메뉴와 화면 연관
이 섹션에서는 [직원 관리] 작업 메뉴를 ManageEmployees 양식에 연결합니다.
(네비게이터)을 누른 다음, 데이터를 선택합니다.- 양식을 열려면 ManageEmployees을 누릅니다.

- 작업을 누른 후 편집을 선택하여 폼을 편집합니다.
새 동적 탭이 양식 편집기와 함께 표시됩니다.

- 기타 옵션 탭을 선택합니다.

- 선택한 메뉴 목록에 직원 관리를 추가한 다음 저장을 누릅니다.

- 확인을 눌러 정보 메시지를 닫습니다.

- 페이지 하단에서 ManageEmployees 편집 동적 탭을 닫아 데이터 양식으로 돌아갑니다.
Groovy 스크립트 테스트
이 섹션에서는 열린 ManageEmployees 폼에서 규칙을 실행하여 전체 주소를 검색하고 저장한 다음 작업 로그를 검토합니다.
- 직원 1을 마우스 오른쪽 버튼으로 누르고 직원 주소 업데이트를 선택합니다.

- 직원 주소 프롬프트에서
Oracle, Redwood Shores을 입력한 다음 실행을 누릅니다.
- 확인을 눌러 정보 메시지를 닫습니다.

성공적으로 완료되면 Google지도에서 반환된 전체 주소가 직원 1의 주소로 저장됩니다.

(네비게이터)을 누른 다음 [애플리케이션]에서 작업을 선택하여 작업 콘솔을 엽니다.
- 직원 주소 추가 또는 업데이트를 눌러 직무 세부정보를 표시합니다.

- 실행 상태에서 완료됨을 확장하여 Groovy 스크립트로 인쇄된 로그 메시지를 봅니다.

관련 링크
- Planning 자습서 - 관심 영역 목록에서 Groovy 구현을 선택하여 추가 Groovy 자습서를 탐색합니다.
- Groovy 규칙용 Java API 참조 — Groovy 규칙 및 템플리트 개발에 사용할 수 있는 Groovy API를 탐색합니다.
- Oracle Fusion Cloud EPM용 REST API — Cloud EPM 태스크 관리 및 자동화에 사용할 수 있는 REST API를 살펴봅니다.
추가 학습 자원
docs.oracle.com/learn에서 다른 랩을 탐색하거나 Oracle Learning YouTube 채널에서 더 많은 무료 학습 콘텐츠에 액세스하세요. 또한 education.oracle.com/learning-explorer를 방문하여 Oracle Learning Explorer가 되십시오.
제품 설명서는 Oracle Help Center를 참조하십시오.