コンテンツにスキップ

ERP Integration Service(erpintegrations)による自動化

このページの REST の内容は 26A、SOAP の内容は 26D の公式ガイドで確認したものです。リリースで変わることがあるため、実装時は対象リリースのガイドを確認してください。

画面での FBDI 取込は 3 つの手順でした(FBDI)。ERP Integration Service は、この手順と、その後の状況確認・ログ取得を API にしたものです。

画面の手順 API
① File Import and Export で zip をアップロード ┐
② Load Interface File for Import を実行 ├ importBulkData(1 回の呼び出し)
③ インポート・プロセス(例:Import Payables Invoices)を実行 ┘
④ スケジュール済プロセスで状態を見る ESSJobStatusRF
⑤ ログ・出力を開く ESSJobExecutionDetailsRF

公式の SOAP ガイドは、importBulkData を「指定した文書情報にもとづいて UCM にファイルをアップロードし、そのファイルをアプリケーションの表にロード・インポートする ESS ジョブを投入する操作」と説明しています。戻り値は ジョブ・リストの最初のジョブ(Load Interface File for Import)の要求 ID です。インポート・プロセスの結果は、この ID の状態だけでは判断できません(後述)。

REST の finder 名と SOAP の操作名は一致しませんが、機能は対応しています。

やりたいこと REST(erpintegrations) SOAP(ErpIntegrationService) 返るもの
取り込む(アップロード+ロード+インポート) POST importBulkData importBulkData 最初のジョブの要求 ID
UCM にファイルを置くだけ POST uploadFileToUCM uploadFileToUcm 文書 ID
ESS ジョブを 1 本投入する POST submitESSJobRequest submitESSJobRequest 要求 ID
ジョブを投入し、ログ・出力を UCM に置く POST exportBulkData exportBulkData 要求 ID
状況を見る GET finder=ESSJobStatusRF getESSJobStatus 状況
子ジョブを含む実行の詳細を見る GET finder=ESSExecutionDetailsRF getESSExecutionDetails 詳細
ログ・出力を取得する GET finder=ESSJobExecutionDetailsRF downloadESSJobExecutionDetails zip(Base64)
UCM の文書を取得する GET finder=DocumentRF getDocumentForDocumentId 文書の内容
ファイル名の先頭で文書 ID を探す GET finder=DocumentIdsByFilePrefixRF getDocumentIdsForFilePrefix 文書 ID

公式は、同等の REST があれば REST の利用を勧めています。SOAP の XML 例と WS-Security は SOAP Web サービス にあります。

  • 統合専用のユーザーを作り、人のユーザーと分けます。OIC の ERP Cloud アダプタのガイドが挙げるロールは、Integration Specialist(ジョブ・ロール)、連携対象のデータ・アクセス、ログ・出力の取得に使う AttachmentsUser です(認証・認可)。
  • 取り込むジョブを実行できる業務の権限(AP なら請求書取込のジョブロール)と、UCM アカウントへのアクセスも必要です。必要なロールは各製品のセキュリティ・リファレンスで確認します。
  • 権限が足りないと 403 などのエラーになります。本番では、必要な権限だけを持つカスタムロールにします。
  • エンドポイントは https://<your-pod>.fa.<region>.oraclecloud.com/fscmRestApi/resources/11.13.18.05/erpintegrations です。取込・実行は POST、状況・ログの取得は GET(finder)です。
  • 公式の属性表は Content-Type に application/json を挙げ、curl の例では application/vnd.oracle.adf.resourceitem+json を使っています。このサイトのモックはどちらも受け付けます。
  • 本文の属性は、公式の定義ではすべて文字列型(string)で、必須の印はありません。実際に必要な項目は OperationName ごとに決まります。REST では ReqstId も文字列で返ります(例:"14258")。

OperationName に次のどれかを指定します。公式の例が確認できるのはこの 4 つです。

OperationName 主な入力 返るもの 用途
importBulkData DocumentContent、FileName、ContentType、DocumentAccount、JobName、ParameterList(ほか NotificationCode、CallbackURL、JobOptions) ReqstId FBDI の取込
uploadFileToUCM DocumentContent、FileName、ContentType、DocumentAccount DocumentId UCM にファイルを置くだけ
submitESSJobRequest JobPackageName、JobDefName、ESSParameters ReqstId 任意の ESS ジョブの投入
exportBulkData JobName、ParameterList(ほか NotificationCode、CallbackURL、JobOptions) ReqstId ジョブを実行し、ログ・出力を zip にして UCM に置く(アウトバウンド向け)
項目 内容 例
DocumentContent zip の中身を Base64 にした文字列。改行を含めない 1 行で渡す (長い文字列)
FileName ファイル名。ログや UCM で識別するので、日付と連番を入れる ApInvoices_20261015_01.zip
ContentType ファイルの種類。FBDI の zip は zip zip
DocumentAccount アップロード先の UCM アカウント。画面の表記(fin/payables/import)の各階層の後ろに $ を付けた形 fin$/payables$/import$
JobName 「ジョブ・パッケージ名,ジョブ定義名」をカンマでつなぐ。取込後に実行するインポート・プロセスを指す oracle/apps/ess/financials/payables/invoices/transactions,APXIIMPT
ParameterList インポート・プロセスのパラメータをカンマ区切りで並べた 1 つの文字列(次節)
CallbackURL 完了時に呼ばれる、自前の Web サービスの URL。不要なら #NULL #NULL
NotificationCode 通知の 2 桁コード(次節)。不要なら #NULL 10
JobOptions 取込の処理を指定する キー=値 のカンマ区切り(次節)

DocumentAccount は、公式の例が AP の fin$/payables$/import$ です。ほかの取込でも同じ書き方になるかは、FBDI ガイドのアカウントを確認したうえで、テスト環境で試します。

  • ParameterList は、JobName で指定したジョブのパラメータを ジョブ定義の順番どおり に並べたものです。公式の説明は「渡さないパラメータの位置は空にする」で、例では #NULL が入っています。
  • #NULL は「この位置のパラメータは渡さない」を表すプレースホルダです。位置が意味を持つため、渡さない位置も省略できません。1 つ数え間違えると、BU 名がソースの欄に入るように、値が別のパラメータに入ります。
  • 公式の AP の例(Import Payables Invoices)は 13 要素です。2 番目が BU 名、8 番目がソース、12 番目が 1 で、ほかは #NULL です。並びと意味はジョブ定義で決まる ので、自環境のジョブ定義で確認します(ESS の「ジョブ定義のパッケージ名・定義名・パラメータ順」)。
  • 値にカンマを含む名称(BU 名など)の扱いは、importBulkData については公式ガイドで確認できていません。SOAP の exportBulkData の parameterList には、値にカンマを含むときはその値を二重引用符で囲む、という説明があります(26D)。カンマを含まない名称で設計するのが安全です。

NotificationCode・JobOptions・CallbackURL

Section titled “NotificationCode・JobOptions・CallbackURL”

NotificationCode は通知の 2 桁コードです(SOAP ガイドの説明)。

桁 意味
1 桁目(方法) 1=メール、2=ベル、3=メールとベルの両方
2 桁目(条件) 0=成功でも失敗でも、1=成功したとき、2=失敗したとき

公式の例の 10 は「メール、常に」です。通知が使えるのは、loadAndImportData、importBulkData、exportBulkData、extractAndPurge の各オペレーションです。通知は人が読むためのもので、自動処理の完了判定には使いません。

JobOptions は、取込の処理とログ・出力の扱いを指定する キー=値 のカンマ区切りです。公式の REST の例は InterfaceDetails=1,ImportOption=Y ,PurgeOption = Y,ExtractFileType=ALL(原文のまま空白あり)、SOAP の例は ImportOption=Y, ExtractFileType=ALL, InterfaceDetails=1 です。公式ガイドの説明は「インバウンドの一括データ処理のバリエーションと、処理時に生成される出力ファイルの種類を指定する」とだけあり、各キーの詳細は載っていません(My Oracle Support の Doc ID 2102800.1 が参照先です)。キー名からは次のように読めますが、挙動は実機で確認してください。

  • InterfaceDetails:取込の種類(インタフェース)を示す値。公式の AP の例では 1
  • ImportOption:ロードの後にインポートまで実行するか
  • PurgeOption:取込後にインタフェース表をパージするか
  • ExtractFileType:取り出すログ・出力の種類(ALL など)

CallbackURL は、完了時にジョブの状況を受け取る、自前の Web サービスの URL です。Fusion(クラウド)から呼ばれるため、受け口に到達できる経路が必要です。使わないときは #NULL にします。コールバックで届くメッセージの項目(要求 ID や状態をどんな名前で運ぶか)は、確認した REST ガイド(26A)と SOAP ガイド(26D)の ErpIntegrationService のページには書かれていません。受け口を作るときは、対象リリースの WSDL と公式のサンプルで確認してください。OIC のアダプタ・ガイドは、importBulkData を直接呼んでコールバックを受け取るには jobOptions に値の設定が必要だとしています(接続とアダプタ)。

GET:finder で状況・ログ・文書を取得する

Section titled “GET:finder で状況・ログ・文書を取得する”

形式は ?finder=<finder名>;<変数>=<値>,<変数>=<値> です。公式の GET のガイドにある finder は次のとおりです。

finder 変数 返るもの
ESSJobStatusRF requestId ESS ジョブの状況(RequestStatus)
ESSJobExecutionDetailsRF requestId、fileType ログ・出力の zip(DocumentContent、Base64)
ESSExecutionDetailsRF requestId、jobOptions 子ジョブを含む実行の詳細
DocumentRF docId UCM の文書の内容
DocumentIdsByFilePrefixRF filePrefix、docAccount、comment ファイル名の先頭が一致する文書の ID
PrimaryKey OperationName オペレーションの定義
  • fileType は、LOG が「ログと出力の両方」、OUT が「出力だけ」です。指定しないと両方が返ります。公式の REST ガイド(26A)に書かれている値はこの 2 つだけで、ALL は載っていません。
  • SOAP の downloadESSJobExecutionDetails の fileType は意味が違い、log(ログ)、out(出力)、all(両方。既定)です(26D)。REST と SOAP で同じつもりで値を使い回さないでください。
  • ESSExecutionDetailsRF の jobOptions は、公式の説明では「将来の利用のため」です。通常は指定しません。
  • DocumentIdsByFilePrefixRF は、投入が成功したか分からないときに、アップロード済みの文書を探すのに使えます(後述の二重投入の対策)。

ESSJobStatusRF の RequestStatus が取りうる値は、REST ガイド(26A)に一覧がありません(RequestStatus と StatusCode は説明が「ESS ジョブの現在の状態(のコード)」とあるだけです)。SOAP の getESSJobStatus も、戻り値は文字列 result で、値の一覧はありません(26D)。ESS の状態(ESS の状態の一覧)に対応する値が返ると考えて、判定は「終了状態の集合に入ったら終わり、入っていなければまだ」の形で書きます。

  • 終了状態:Succeeded、Warning、Error、Canceled、Expired、Validation Failed、Finished
  • Completed(後処理中)や Blocked、Hold、Paused は 終了ではありません
  • 実機の値の綴りは、テスト環境で 1 回確認します。このサイトのモックは WAIT → RUNNING → SUCCEEDED/ERROR/WARNING を返します
  • WSDL は https://<ホスト>/fscmService/ErpIntegrationService?WSDL です。REST と同じ機能に加え、extractAndPurge(取込結果の出力を UCM に置き、インタフェース表をパージする。Web サービスのコールバックと通知付き)などがあります。
  • importBulkData の引数は構造化されています。document(Base64 の中身、ファイル名、コンテンツ・タイプ、アカウントなど)、jobDetails(ジョブ定義名、パッケージ名、パラメータ・リスト)、notificationCode、callbackURL、jobOptions です。戻り値は long で、最初のジョブの要求 ID です。
  • loadAndImportData と downloadExportOutput は非推奨と案内されています。それぞれ importBulkData、downloadESSJobExecutionDetails を使います。

OIC のアダプタは、直接呼び出しで自前に書く部分(接続、認証、呼び出し、完了の受け取り)を、設定で肩代わりします。

観点 OIC の ERP Cloud アダプタ 直接呼び出し(REST/SOAP)
取込の呼び出し アクション Import Bulk Data into Oracle ERP Cloud。ジョブは画面で選ぶ importBulkData を自分で組み立てる
完了の受け取り Enable Callback を選ぶと ErpImportBulkDataEvent が発行され、コールバック統合が起動する ポーリング、または CallbackURL
ログ・出力の取得 Extract File(All/Error/Log/Out/None)、コールバック側の Download Options ESSJobExecutionDetailsRF
向く場面 OIC がある。スケジュールやファイル処理と組み合わせる 移行ツール、スクリプト、OIC 以外のミドルウェア
注意 公式は直接呼び出しよりアダプタを推奨 コールバックには jobOptions の設定が必要
  • アダプタの使い方は 接続とアダプタ、スケジュール統合との組み合わせは スケジュール統合とファイル処理 と OIC 演習1 を参照してください。
  • OIC の取込に使う zip は、CSV に加えて、ジョブ名とパラメータを書いた manifest/properties ファイルを含む形が案内されています。公式 REST ガイドの例の zip にも、CSV のほかに .PROPERTIES ファイルが入っています(中身は「ジョブ・パッケージ名,ジョブ定義名,名前,パラメータの並び」)。
  • ビジネスイベントには、取込の完了を知らせる ERP Integration Inbound と、exportBulkData の完了を知らせる ERP Integration Outbound があります(ビジネスイベント)。
方式 仕組み 長所 注意点
ポーリング ReqstId で ESSJobStatusRF を一定間隔で呼ぶ 受け口が不要で、社内ネットワークの内側から動かせる。実装が単純 待つ間も呼び出しが続く。間隔と上限時間の設計が要る
コールバック(CallbackURL) 完了時に、Fusion が自前の Web サービスを呼ぶ 呼び出しが少なく、完了をすぐ知れる 受け口を用意し、認証と到達経路を設計する。届かない場合に備える
ビジネスイベント(OIC) ErpImportBulkDataEvent を購読する統合が起動する OIC の中で完結する OIC が前提。イベントの欠落・重複を想定する

どれを選ぶかは、完了の通知を受ける側の都合で決まります。移行ツールやバッチスクリプトはポーリングで十分です。常時動くサービスや OIC があるなら、コールバックを主にして、一定時間たっても通知が来ない投入だけをポーリングで確認する 併用 が堅実です。

  • 終了状態の集合で判定する:Completed や Blocked で打ち切りません。
  • 間隔は短く始めて伸ばす:最初は数秒〜十数秒おきにし、長いジョブでは間隔を広げます。値は公式の基準がないので、リハーサルの実測で決めます。
  • 上限時間を決める:超えたら「状態不明」として運用に通知します。ジョブは Fusion 側で動き続けている可能性があるため、再投入せず、ReqstId で確認し直します。
  • ポーリングの失敗は再試行する:429・503・タイムアウトは待ってから再試行します(401・403 は再試行しても直りません)。

POST の importBulkData がタイムアウトしても、Fusion 側では受け付けられている可能性があります。そのまま再送すると、同じファイルを二重にロードしてしまいます。

  • 応答を受け取れたら、すぐ ReqstId を記録します。受け取れなかったときは、再送の前に DocumentIdsByFilePrefixRF(FileName の先頭で UCM の文書を探す)やスケジュール済プロセスの画面で、投入済みかを確認します。
  • FileName に日付と連番を入れ、取込のまとまりを識別する値(AP の Import Set、GL の Group ID)を毎回一意にします。
  • 「ファイル名・ReqstId・投入時刻・結果」を台帳に残します。
  • 取込の後の検証・会計などのジョブは、ESS のプロセス・セット、完了を確認してからの submitESSJobRequest、OIC のオーケストレーションのいずれかでつなぎます(ESS)。
  • 大量データは、ファイルを分割して Import Set(GL なら Group ID)を分け、並列に投入します。ESS の同時実行数と、同じジョブの自己非互換(Blocked)を考慮して、投入側で並列数を絞ります(移行設計 の「性能」)。
段階 症状 見る場所 対処
呼び出し自体 400、401、403、404、415 応答本文のメッセージ JSON・Base64・必須項目・JobName の形式・Content-Type・認証・権限を直して再送する(再試行では直らない)
一時的な障害 429、500、503、タイムアウト 応答のステータス、Retry-After 間隔を空けて再試行する。POST は二重投入に注意する
ジョブが Error ESSJobStatusRF が ERROR ESSJobExecutionDetailsRF のログ ログのエラーから原因を特定する
ロードの失敗 子ジョブ(ロード)が Error ESSExecutionDetailsRF、ログ zip の中身・ファイル名・列数を確認し、CSV を作り直して再投入する
インポートで拒否 ジョブは終了、一部の行が拒否 インポート・プロセスの出力、インタフェース表 Correct Import Errors で直して再インポート、またはパージして再ロード
終わらない Wait や Blocked のまま スケジュール済プロセスの Status Details 非互換の相手の終了を待つ、または取り消す
  1. 呼び出しのたびに ReqstId を記録しておきます。調査はここから始まります。
  2. ESSJobStatusRF で状態を確認します。
  3. 終了していれば、ESSJobExecutionDetailsRF(fileType=LOG)で zip を取得し、ログ(log)と出力(out)を読みます。zip の中のファイル名はジョブによって違うので、拡張子で扱います。
  4. ESSExecutionDetailsRF で、どのジョブが失敗したかを見ます。取込の複数のジョブのうち、親(ロード)だけを見て成功と判断しません。
  5. 画面でも同じ ID を確認できます。ナビゲータ > ツール > スケジュール済プロセスで検索し、Process Details のログ・出力を開きます。
  6. 業務データは、インタフェース表の行(FBDI の SQL)と Correct Import Errors で確認します。
  7. それでも分からないときは、ReqstId、投入時刻、JobName、ParameterList、ログを添えて Oracle サポートに問い合わせます。
importBulkData で AP 請求書の zip を取り込む(実機)
export FA_HOST="https://<your-pod>.fa.<region>.oraclecloud.com"
export API="$FA_HOST/fscmRestApi/resources/11.13.18.05"
# FA_USER と FA_PASS は環境変数に設定済みとする(コードに直書きしない)
# base64 < ファイル | tr -d '\n' は、改行のない 1 行の Base64 を作る書き方(Linux・macOS 共通)
curl -s -u "$FA_USER:$FA_PASS" \
-H "Content-Type: application/json" \
-X POST "$API/erpintegrations" -d @- <<EOF
{
"OperationName": "importBulkData",
"DocumentContent": "$(base64 < ApInvoices_20261015_01.zip | tr -d '\n')",
"ContentType": "zip",
"FileName": "ApInvoices_20261015_01.zip",
"DocumentAccount": "fin\$/payables\$/import\$",
"JobName": "oracle/apps/ess/financials/payables/invoices/transactions,APXIIMPT",
"ParameterList": "#NULL,JP01 Business Unit,#NULL,#NULL,#NULL,#NULL,#NULL,External,#NULL,#NULL,#NULL,1,#NULL",
"CallbackURL": "#NULL",
"NotificationCode": "10"
}
EOF
# → 応答の ReqstId を控える。ParameterList の並びは自環境のジョブ定義で確認する

JobOptions は、ここでは省略しています。必要な値は My Oracle Support の Doc ID 2102800.1 と、OIC アダプタのガイドで確認します。

公式の例には、submitESSJobRequest でロード用のジョブを直接投入するものと、exportBulkData があります。

submitESSJobRequest(公式の例)
{
"OperationName": "submitESSJobRequest",
"JobPackageName": "oracle/apps/ess/financials/commonModules/shared/common/interfaceLoader",
"JobDefName": "InterfaceLoaderController",
"ESSParameters": "1,10420,N,N"
}
exportBulkData(公式の例。Purge Interface Tables を実行してログ・出力を UCM に置く)
{
"OperationName": "exportBulkData",
"JobName": "oracle/apps/ess/financials/commonModules/shared/common/interfaceLoader,InterfaceLoaderPurge",
"ParameterList": "1,27921,#NULL,#NULL,#NULL,ORA_FBDI,USER,#NULL,#NULL",
"CallbackURL": "#NULL",
"NotificationCode": "10",
"JobOptions": "ExtractFileType=ALL"
}
状況の確認とログ・出力の取得
REQ_ID="14258" # importBulkData の応答の ReqstId(値は例)
# 状況
curl -s -u "$FA_USER:$FA_PASS" \
"$API/erpintegrations?finder=ESSJobStatusRF;requestId=$REQ_ID&onlyData=true"
# ログと出力(fileType=LOG はログと出力、OUT は出力だけ)。DocumentContent が Base64 の zip
curl -s -u "$FA_USER:$FA_PASS" \
"$API/erpintegrations?finder=ESSJobExecutionDetailsRF;requestId=$REQ_ID,fileType=LOG&onlyData=true"

動く最小例です。完全なスクリプト(投入・ログ取得・エラー処理)は 自動化演習 にあります。

wait_for_job.py(ESSJobStatusRF で終了状態まで待つ)
import time
import requests
# ESS の終了状態(Completed・Blocked などは含めない)。綴りは実機で確認する
TERMINAL = {"SUCCEEDED", "WARNING", "ERROR", "CANCELED", "CANCELLED", "EXPIRED", "VALIDATION_FAILED", "FINISHED"}
def wait_for_job(api, auth, req_id, interval=10, timeout=1800):
"""終了状態になるまで待ち、その RequestStatus を返す。時間切れなら TimeoutError"""
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
r = requests.get(
f"{api}/erpintegrations",
auth=auth,
params={"finder": f"ESSJobStatusRF;requestId={req_id}", "onlyData": "true"},
timeout=30,
)
r.raise_for_status()
items = r.json().get("items", [])
status = (items[0].get("RequestStatus") or "").upper().replace(" ", "_") if items else ""
if status in TERMINAL:
return status
time.sleep(interval)
raise TimeoutError(f"要求 ID {req_id} が {timeout} 秒以内に終了しませんでした")

実務での拡張ポイントです。

  • 一時的なエラー(429・503・タイムアウト)の再試行と、Retry-After の尊重
  • 間隔を伸ばす(指数バックオフ)。上限時間を超えたら「状態不明」として通知する
  • 終了後に ESSJobExecutionDetailsRF でログを取得して保存し、結果を台帳に記録する

落とし穴とベストプラクティス

Section titled “落とし穴とベストプラクティス”
  • 設定値は外に出す:JobName、ParameterList、DocumentAccount は、コードではなく設定ファイルと設計書で管理します。
  • ログ zip は保存する:失敗時だけでなく、成功時のログと出力も監査用に残します。
  • 段階を踏んで試す:このサイトのモックで流れを確認し、テスト環境で実ジョブを動かし、最後に本番へ進みます。
  • ジョブ運用表に載せる:投入ユーザー、スケジュール、前提ジョブ、通知、失敗時の対応を ESS のジョブ運用表で管理します。
  • OIC 模擬テスト:ERP Cloud アダプタの Import Bulk Data into Oracle ERP Cloud、コールバック(ErpImportBulkDataEvent)、ERP Integration Inbound/Outbound イベント
  • AP 模擬テスト・GL 模擬テスト:外部システムからの取込の流れ(FBDI の 2 段階と、その自動化)

覚えておくことです。

  • OperationName は importBulkData、uploadFileToUCM、submitESSJobRequest、exportBulkData の 4 つ
  • importBulkData が返す要求 ID は、最初のジョブ(Load Interface File for Import)のもの
  • NotificationCode は 2 桁(方法 1=メール・2=ベル・3=両方、条件 0=常に・1=成功・2=失敗)。不要なら #NULL
  • #NULL は、その位置のパラメータを渡さない印。ParameterList は位置で意味が決まる
  • finder は ESSJobStatusRF(状況)、ESSJobExecutionDetailsRF(ログ・出力)、ESSExecutionDetailsRF(子ジョブを含む詳細)、DocumentRF(文書)

本サイトは学習目的で個人が作成した非公式の教材であり、Oracle Corporation およびその関連会社とは関係ありません。内容の正確性は保証しません。最新の仕様・試験範囲は必ず公式ドキュメントと Oracle University の情報で確認してください。

模擬テストの問題は公開されている出題範囲(Exam Topics)と公式ドキュメントをもとに独自に作成したもので、実際の試験問題ではありません。

Oracle、Java、MySQL は Oracle Corporation およびその子会社、関連会社の米国およびその他の国における登録商標です。その他の製品名・会社名は各社の商標です。

© 2026 Fusion ERP 実装ラボ