他のアプリケーションとの統合方法

コンフィグレータを見積やオーダー取得などのアプリケーションと統合して、製品やサービスを構成するための対話型構成エクスペリエンスを提供できます。

コンフィグレータは、外部アプリケーションのテクノロジ・スタックに依存せず、シームレスなUI統合エクスペリエンスを実現する標準ベースのアプローチを実装します。統合アプローチでは、Representational State Transfer (REST) APIを使用して、複合品目の構成、最終構成の取得、およびコンフィギュレータ・ランタイムUIの起動用のエントリ・ポイントURL(IFrame内またはブラウザ・ウィンドウ内)の意図を作成します。 RESTはテクノロジではなく、参加者がデータ指向リソースに対してアクションを実行するクライアント・サーバー・アーキテクチャ・スタイルです。

統合アーキテクチャ

外部アプリケーションからコンフィギュレータを起動し、構成セッション後に戻る統合は、次の表で説明する要素で構成されます。

統合要素	目的
RESTリソース	次のものに対してデータ指向サービスを提供します: 構成セッションを開始するインテントの作成明細、明細属性、メッセージなどの構成詳細の取得カスタム構成アクションの実行。
外部アプリケーション・データ・モデル・エンティティ	構成ヘッダーの一意の識別子など、コンフィギュレータによる統合の確立に必要なホスト・アプリケーションからのデータを提供します。
公開エントリ・ポイントURL	コンフィギュレータ・ユーザー・インタフェース・セッションを起動するためのエントリ・ポイントを提供します。
REST入力および出力ペイロード	構成セッションへの特定の入力および出力の繰り越し。
統合タスク	統合の完了に必要な処理。

RESTリソース

外部アプリケーションは、これらのコンフィギュレータRESTリソースを利用して構成と対話できます

初期化パラメータ: 外部アプリケーションは、このリソースを使用して、構成セッションを開始するためにコンフィギュレータが実行時に使用する詳細を提供する入力ペイロードを渡すことによって、製品またはサービスを対話形式で構成する目的を指定する必要があります。

少なくとも、次の情報をこのRESTリソースに投稿する必要があります:
- CallingApplicationCode: Oracle ApplicationsのOracle applications以外の外部の場合の取引先コミュニティ・ソース・システムの管理タスクに登録されたアプリケーション・コード、またはOracle applicationsのFNDアプリケーション短縮名(コード)。
- 明細: 文字列形式で直列化されたJavaScript Object Notation ( JSON)ドキュメント。各フィールドの名前と値のペアは、販売コンテキスト明細エンティティ定義に対応します。
初期化パラメータ・リソースは、対話型構成セッションを起動するための適切なモデルおよびユーザー・インタフェースをロードするために使用されます。

初期化パラメータ・リソースは、コンフィギュレータの起動に1回のみ使用でき、そのリソースは失効済としてマークされ、再使用できません。この制限の目的は、分散型サービス拒否などの攻撃を防ぐことです。
構成: 外部アプリケーションは、構成セッションの終了後にコンフィギュレータによって返される構成識別子を使用して、このリソースを使用して構成の詳細を取得する必要があります。

構成リソースは、1つのルート・エンティティで構成され、次の3つの子エンティティが含まれます:
- ConfigurationLines: 構成内のすべての行を記述するコレクション・リソース。
- ConfigurationLineAttributes: 構成内のすべてのトランザクション属性明細を記述するコレクション・リソース。
- ConfigurationMessages: 構成に追加された1つ以上のメッセージを記述するコレクション・リソース。
構成リソースは、構成結果を返すときに、デフォルトでオプション区分明細を除外します。外部アプリケーションは、OuptutMode問合せパラメータ値をfullとして指定することで、完全な結果をリクエストできます。
構成リソースは、構成に対して実行できる次のカスタム・アクションをサポートしています:
- コピー: 見積/オーダー明細のコピー処理をミラー化する構成をコピーします。
- 検証: Oracle Order Managementに見積またはオーダーを送信して履行のために発行する前に構成を検証し、発行前に見積またはオーダー・エラーを排除します。

詳細は、次のREST API for Oracle Supply Chain Management Cloudガイドを参照してください:

初期化パラメータおよび構成のRESTエンドポイントのパラメータおよび問合せ例の説明
カスタム・アクションのユースケースの例

ノート: REST API for Oracle Supply Chain Management Cloudガイドは、SCM RESTリソースを操作するための包括的なリファレンスであり、REST APIの使用開始に関する情報が含まれています。

外部アプリケーション・データ・モデル・エンティティ

構成関連情報を保持するには、コンフィギュレータと統合されているすべての外部アプリケーションが、構成明細を表すエンティティに次の属性を追加する必要があります。

属性	目的
ConfigHeaderId	コンフィギュレータにより生成される構成ヘッダーの一意の識別子
ConfigRevisionId	構成のリビジョンに対するコンフィギュレータ生成の一意の識別子
ConfiguratorPath	構成明細の品目へのコンフィギュレータ生成ランタイム在庫IDパス

ConfigHeaderIdとConfigRevisionIdの組合せによって、構成が一意に識別されます。再構成フロー時に識別属性をコンフィギュレータに渡し、履行のために見積またはオーダーを発行する場合はOracle Order Managementに渡す必要があります。

外部アプリケーションは、構成を識別する属性に加えて、構成明細エンティティに次の属性を追加して、再構成セッション中に既存の見積明細またはオーダー明細と同期できます。見積明細やオーダー明細を削除して再作成する必要はありません。この情報は、子リソースを展開したときに構成リソースを使用して取得されます。

属性	目的
ConfigLineId	コンフィギュレータにより生成される構成明細の一意の識別子
ParentConfigLineId	子明細からの親構成明細を示すコンフィギュレータ生成の一意の識別子
ConfigLineAttributeId	品目に関連付けられたトランザクション属性を表す構成明細属性に対するコンフィギュレータ生成の一意の識別子です。

パブリックUIエントリ・ポイントURL

コンフィギュレータには、IFrame内またはブラウザ・ウィンドウ内でコンフィギュレータ・ランタイムUIを起動するためのパブリック・エントリ・ポイントURLが用意されています。

コンフィギュレータ・ランタイムUIを起動するURLエントリ・ポイントは公開されており、認証済ユーザーにアクセスできるように保護されています。エントリ・ポイントには、次のURLパラメータが必要です:

ParameterId: 構成するインテントの作成時に初期化パラメータ・リソースREST APIによって生成される初期化パラメータ・リソース識別子で、初期化パラメータの属性と値のペアのセットを識別します。このパラメータ値が指定されていないか、無効な場合は、エラー・ダイアログがユーザーに表示され、コンフィギュレータはReturnUrlにリダイレクトされます。
ReturnUrl: 構成セッションの終了後に戻るホスト・アプリケーションの完全修飾URL。このパラメータ値が渡されない場合、HTTP 400エラー・コードが返されます。

エントリ・ポイントURLの構文は次のとおりです:

<protocol>://<host>:<port>/fscmUI/faces/ConfigLaunch.jspx

例:

https://acme.cloud.enterprise.com/fscmUI/faces/ConfigLaunch.jspx?ParameterId=123456&ReturnUrl=https://acme.cloud.quote.com/context/processResults.jsp

構成セッションの実行中または開始中にエラーが発生した場合、コンフィギュレータはReturnUrlにナビゲートし、ExitStatusがerrorになります。ホスト・アプリケーションは、初期化パラメータ・リソースに対してREST GET操作を実行し、ParameterIdをReturnUrlの一部として渡してエラー・メッセージの詳細全体を取得できます。

統合タスク

ホスト・アプリケーションからランタイム・コンフィギュレータをコールする準備をし、入出力ペイロードを準備および処理するには、次の高レベルのステップに従います。

外部アプリケーションを登録します:

「設定および保守」作業領域に移動してから、タスクに移動します:
- オファリング: 製品管理
- 機能領域: 製品スポーク・システム
- タスク: 取引先コミュニティ・ソース・システムの管理
詳細は、「製品スポーク・システム」を参照してください。

次に、外部アプリケーションをソース・システムとして作成または登録します。

アプリケーションが登録されると、コンフィギュレータ・モデル作業領域で、変更されたユーザー・インタフェースの適用パラメータを定義して、アプリケーションがコンフィギュレータをコールしたときにそれらのユーザー・インタフェースが表示されるようにできます。
許可されたオリジンのホワイト・リストを有効にします:

このステップは、IFrameで実行時コンフィギュレータを起動する場合に必要です。デフォルトでは、Oracle Applicationsは、同じオリジンからコールされた場合を除き、IFrameにコンテンツをレンダリングしません。構成可能なホワイト・リスト・メカニズムを使用して、IFrameにコンテンツをレンダリングできる許可された外部オリジンのリストを指定できます。許可されるオリジンを制御するには、設定およびメンテナンス作業領域の管理者プロファイル値の管理タスクを使用して、プロファイル・オプションORACLE.ADF.VIEW.ALLOWED_ORIGINSを設定します。

このステップは、ブラウザ・ウィンドウでのランタイム・コンフィギュレータの起動には必要ありません。

パブリック・エントリ・ポイントURLを使用して、IFrameまたはブラウザ・ウィンドウでランタイム・コンフィギュレータUIをコールします:

パブリック・エントリ・ポイントURIは/fscmUI/faces/ConfigLaunch.jspxです。 URLパラメータParameterIdおよびReturnUrlは必須です。

実行時コンフィギュレータを呼び出すには、次のステップが必要です。

初期化ペイロードを準備します。

JSON形式を使用してRESTペイロードを準備します。

最小限必要なペイロードを示す例:

{ "CallingApplicationCode":"CZ",
   "Line":"{\"InventoryItemNumber\":\"AS100\",\"RequestOn\":\"2017-01-22T09:09:28-0700\",\"InventoryOrganizationCode\":\"V1\"}"
}

ペイロードを初期化パラメータ・リソースにポストします。

次のURIを使用して、POST操作を使用してペイロードを初期化パラメータRESTリソースに送信

/fscmRestApi/resources/latest/initializationParameters

latestを、必要なインストール済リリースのOracle Supply Chain Management(11.13.18.02など)を指定する文字列で置き換えることができます。文字列latestは、最新のインストール済リリースのシノニムです。

cURLコマンドライン・ツールの使用例:

curl ' https://acme.cloud.enterprise.com:7000/fscmRestApi/resources/latest/initializationParameters' \
-i \
-X POST \
-H "Content-Type:application/json" \
-u myuserid:mypass \
-d '{  "CallingApplicationCode":"CZ",
   "Line":"{\"InventoryItemNumber\":\"AS100\",\"RequestOn\":\"2017-01-22T09:09:28-0700\",\"InventoryOrganizationCode\":\"V1\"}"}'

例に示すペイロード・リクエストの場合、初期化パラメータ・リソースからのレスポンスは次のようになります:

{
    "ParameterId": 300100116074154,
    "CallingApplicationCode": "CZ",
    "Header": null,
    "Line": "{\"UnitQuantity\":1,\"InventoryItemNumber\":\"AS100\",\"RequestOn\":\"2018-01-11T09:09:28-0700\",\"InventoryOrganizationCode\":\"V1\",\"InventoryOrganizationId\":204,\"InventoryItemId\":300100016171847}",
    "CustomParameters": null,
    "ManualPriceAdjustments": null,
    "PageTitlePrefix": null,
    "ExpiredFlag": false,
    "ErrorMessageText": null,
    "TerminalActionCaption": null,
    "ValidationCannotAlterFlag": true,
    "ValidationFailFastFlag": true,
    "links": [
        {
            "rel": "self",
            "href": "<a target="_blank" href="https://node001.my.srvr.com:7021/fscmRestApi/resources/latest/initializationParameters/300100116074154",">https://node001.my.srvr.com:7021/fscmRestApi/resources/latest/initializationParameters/300100116074154",</a>
            "name": "initializationParameters",
            "kind": "item"
        },
        {
            "rel": "canonical",
            "href": "<a target="_blank" href="https://node001.my.srvr.com:7021/fscmRestApi/resources/latest/initializationParameters/300100116074154",">https://node001.my.srvr.com:7021/fscmRestApi/resources/latest/initializationParameters/300100116074154",</a>
            "name": "initializationParameters",
            "kind": "item"
        }
    ]
}

ParameterIdを抽出します。

構成の初期化時に初期化パラメータRESTリソースによって生成されたパラメータ識別子ParameterIdを取得するには、外部アプリケーションがPOST操作からレスポンス・ペイロードを処理する必要があります。この例の値は次のとおりです:
```
"ParameterId": 300100116074154
```
パブリック・エントリ・ポイントURLをコールします。

ParameterIdに対して取得された値は、パブリック・エントリ・ポイントConfigLaunch.jspxをコールするときにURLパラメータ値として渡されます。初期化ペイロードで指定された製品を構成するセッションでランタイム・コンフィギュレータ・ユーザー・インタフェースを起動する結果のURLの例は、次のとおりです:
```
https://acme.cloud.enterprise.com/fscmUI/faces/ConfigLaunch.jspx?ParameterId=300100089663945&ReturnUrl=https://acme.cloud.quote.com/context/processResults.jsp
```

エンド・ユーザーの対話型構成セッションはこの時点で行われます。

エンド・ユーザーは、ランタイム・コンフィギュレータ・ユーザー・インタフェースで対応するボタンをクリックすることで、対話型構成セッションを完了し、次のいずれかのアクションを使用してコンフィギュレータを終了できます:
- 取消: エンド・ユーザーは、構成セッションを単に取り消すことができます。構成に加えられた変更の損失に関する警告ダイアログがエンド・ユーザーに表示されます。 ReturnUrlパラメータにcancelの終了ステータスが指定され、戻って処理する変更がないことをホスト・アプリケーションに示します。
- 一時保存: エンド・ユーザーは、構成を保存して後から完了するように決定します。 ReturnUrlパラメータにsaveの終了ステータスが指定され、構成に変更があることをホスト・アプリケーションに示します。ホスト・アプリケーションは、構成識別子(ConfigHeaderIdとConfigRevisionId)を使用して構成の詳細を取得できます。
- 終了または終了してレビュー: エンド・ユーザーは、自動補完プロセスを暗黙的に実行して構成を完了し、ホスト・アプリケーションに戻ります。 ReturnUrlパラメータにsaveの終了ステータスが指定され、構成に変更があることをホスト・アプリケーションに示します。ホスト・アプリケーションは、構成識別子(ConfigHeaderIdとConfigRevisionId )を使用して構成の詳細を取得できます。
構成結果を処理します:

エンド・ユーザーが対話型の構成セッションを完了して終了すると、コンフィギュレータは構成セッションの起動時に指定されたReturnUrlに移動し、構成識別子と終了ステータスをURLパラメータ値として追加します。外部アプリケーションは、終了ステータスを決定するためにURLパラメータ値を使用し、適切なページにナビゲートするために必要な処理を実行する必要があります。
- ExitStatusパラメータは、終了メソッドを示します。指定可能な値は、save、cancelおよびerrorです。
- 終了ステータスがsaveの場合、次の構成識別子が含まれます:
  - ConfigHeaderId: 構成の識別子。
  - ConfigRevisionId: 構成改訂の識別子。
  ConfigHeaderIdとConfigRevisionIdの組合せを一緒に使用すると、構成が一意に識別されます。例:
```
q=ConfigHeaderId=300100112392208;ConfigRevisionId=300100112392209
```
- ExitStatusがsaveの場合、外部アプリケーションは、URLパラメータ値を構成RESTリソースに渡すことによって構成結果を取得する必要があります。構成RESTリソースのURIは次のとおりです:
```
/fscmRestApi/resources/latest/configurations
```
  必須のURLパラメータは次のとおりです:
```
q=ConfigHeaderId=000;ConfigRevisionId=000
```
  例U RL指定された構成の構成RESTリソースを問い合せ、オプション区分明細(OutputMode=full)およびトランザクション属性明細(expand=ConfigurationLines,ConfigurationLineAttributes)を含むすべての構成明細を返します:
```
https://acme.cloud.enterprise.com:7000/fscmRestApi/resources/latest/configurations?q=ConfigHeaderId=300100112392208;ConfigRevisionId=300100112392209;OutputMode=full&expand=ConfigurationLines,ConfigurationLineAttributes&onlyData=true
```
  このRESTリソースは、1つの構成に対して次の構造でJSONドキュメントを生成します:
```
Configuration
    ConfigurationLines (collection)
        ConfigurationLine [0...n]
    ConfigurationLineAttributes (collection)
        ConfigurationLineAttribute [0...n]
    ConfigurationMessages (collection)
        ConfigurationMessage [0...n]
```
  外部アプリケーションは、JSONドキュメントを処理して、見積りまたはオーダー明細を作成する必要があります。
再構成フロー。

外部アプリケーションは、新しい構成と同じ統合ステップに従って既存の構成を再構成できますが、ルート行の構成識別子とコンフィギュレータ・パス情報を初期化パラメータ・ペイロードに含める必要があります。最小限必要なペイロードを示す例:
```
{
  "CallingApplicationCode":"ABC_CPQ",
  "Line": "{\"InventoryItemNumber\":\"AS100\", \"InventoryOrganizationCode\":\"V1\",\"RequestOn\":\"2016-04-07 13:00:00\"}",
\"ConfigHeaderId\":300100112392208, \"ConfigRevisionId\":300100112392209, \"ConfiguratorPath\":\"987654321\"}
}
```
外部アプリケーションは、終了ステータスに基づいて、構成識別子を使用して構成結果を取得できます。外部アプリケーションは、見積明細またはオーダー明細を削除して再作成するかわりに、構成明細識別子を使用して既存の明細を同期できます。重要な点は、コンフィギュレータが新しい構成フローと同じ行識別子を再構成フローで返すことです。ただし、構成内の明細は順序付けされず、ソート順序を指定できません。

詳細と例については、「Oracle Supply Chain Management CloudのREST API」に移動し、展開します:

Order Management > 構成初期化パラメータ
Order Managementの「構成」
「ユースケース」→「コンフィギュレータ」