46 CPQ CloudからのJCS - SaaS Extension RESTful Webサービスの使用

Oracle Configure, Price, and Quote Cloudは、ERP、CRM、データベースまたはJCS - SaaS Extensionアプリケーションを含む様々なタイプの外部システムと統合できます。RESTful Webサービスのコールは、このような統合に使用できる共通のメカニズムです。

このドキュメントでは、文書を見積もるためにパネル、属性およびアクションを追加することにより、CPQ CloudのUIをカスタマイズする方法について学習します。また、CPQ CloudのBML (BigMachines Extensible Language)も使用して、JCS - SaaS Extensionインスタンスでホストされる外部RESTful Webサービスを起動します。

アクションを作成し、これを使用してBMLエディタからRESTful Webサービス・コールを作成する方法について学習します。

注意:

他のCPQ Cloudエンティティを使用して、属性、承認フロー、文書などの同様の結果を得ることができます。このドキュメントでは、例としてアクションを選択しました。この決定は、特定のビジネス・ロジックや要件によって異なる可能性があります。「CPQ Cloudを拡張するための戦略の選択」を参照してください。

トピック

• 前提条件

• CPQ CloudのBML URLアクセス関数について

• カスタム機能を実行するためのボタンのCPQ Cloud見積りへの追加

• CPQ Cloud BML APIを使用したRESTful Webサービスの起動

前提条件

Oracle CPQ Cloudのコマース・ワークフローをカスタマイズする前に、次の各事項について検討する場合があります。

• (ユーザーを作成または変更できる)「スーパー・ユーザー」権限を伴うFullAccessロールを持つユーザーが少なくとも1人いることを確認します。

  注意:

  FullAccessロールを持つユーザーがいない場合、管理者に確認してください。

• デプロイされて稼働中のJCS - SaaS Extensionアプリケーションがあることを確認します。「ADFを使用しない場合の開発に関する考慮事項」を参照してください。

• 「CPQ Cloudのカスタマイズ機能および統合機能の理解」を必ず読んでおいてください。

CPQ CloudのBML URLアクセス関数について

BML URLアクセス関数を使用して、RESTful WebサービスからHTTPメッセージを直接送受信できます。これを目的として、urldatabypostおよびurldatabygetと呼ばれる2つのライブラリ関数を使用して、それぞれPOSTおよびGETをコールできます。次の表に、URLアクセス関数で使用可能なすべてのメソッドをまとめます。

関数	パラメータ	説明
String makeurlparam({'key':value})	{‘key1’:value1,’key2’:value2…}という形式でカンマ区切りのペアが含まれるJSONに似たフォーマットの文字列	この関数を使用して、アンパサンド(&)で区切られたURLパラメータを構築します。
String urldata(String url, String httpMethod, [Dictionary headers, [String parameters]])	url (String)、 httpMethod (“GET”または“POST”)、 headers (Dictionary)、 parameters (String)	この関数を使用して、渡されたパラメータに応じてHTTP GETまたはPOSTを使用してURLからデータを取得します。
String urldatabyget(URL, url_param, default_value)	url (String)、 url_param (String)、 default_value (String)	この関数を使用して、GETメソッドを使用してURLからデータを取得します。
String urldatabypost(String url, String parameters, String defaultValue, [Dictionary headers, [Boolean returnErrorResponse]])	url (String)、 parameters (String)、 default_value (String)、 headers (Dictionary)、 returnErrorResponse (Boolean)	この関数を使用して、POSTメソッドを使用してURLにデータを送信します。
urldatabypostasync((String url, String parameters, String defaultValue, String callbackActionVarName, [Dictionary headers, [Boolean returnErrorResponse]])	url (String)、 parameters (String)、 defaultValue (String)、 callbackActionVarName (String)、 headers (Dictionary)、 returnErrorResponse (Boolean)	この関数を使用して、POSTメソッドを使用して非同期でコールするか、カスタムHTTPヘッダーを渡します。

「CPQ Cloudのカスタマイズ機能および統合機能の理解」を参照してください。BML API内の他のBML関数について学習するには、オンライン・ヘルプの「BMLの使用」、「関数およびスクリプト」を参照してください。

カスタム機能を実行するためのボタンのCPQ Cloud見積りへの追加

レイアウト・エディタを使用してパネル、フィールド、ルールおよびアクション・ボタンを追加することにより、CPQ Cloud見積りをカスタマイズしたり、デフォルト機能を拡張したりできます。

たとえば、アクション・ボタンが含まれる新しいカスタム・パネルを作成可能で、そのボタンをクリックすると、コマース・プロセス・ワークフロー内のデータをフェッチする外部JCS - SaaS Extension RESTful Webサービスを起動することができます。

新規属性の作成

既存のCPQ Cloud見積りで新しい属性を作成する手順:

1. CPQ Cloudにログインします。
2. 管理プラットフォーム・アイコンをクリックします。
   
   図admin.jpgの説明
3. コマースおよび文書の下で、「プロセス定義」をクリックします。
4. カスタマイズするコマース・プロセス文書の下にある「ナビゲーション」ドロップダウンから「文書」を選択し、下図に示すように、「リスト」ボタンをクリックします。
   
   図commerce_document.jpgの説明

   「文書」ウィンドウに移動します。

5. 「ナビゲーション」ドロップダウンから最上位レベルの「文書」の下の「属性」を選択し、「リスト」ボタンをクリックします。
   
   図window.jpgの説明

   コマース・プロセス・ワークフローに対して作成したすべての変数が含まれる「属性リスト」ウィンドウに移動します。

6. 「追加」ボタンをクリックし、新しい「属性」を作成します。
7. 「属性エディタ」インタフェースで、ラベルおよび変数名を入力し、「属性タイプ」ドロップダウンからタイプを選択します。たとえば、テキスト・フィールドを作成する場合は「テキスト」を選択します。
   
   図new_attribute.jpgの説明
8. 「追加」ボタンをクリックしてから、次の画面で「更新」ボタンをクリックします。
   これで、新しく作成した変数が「属性」リストにリストされます。

新規アクションの作成

アクションは、コマース・ワークフロー内のイベントをトリガーできるCPQ Cloud内の論理コンポーネントです。

アクション内では、CPQ Cloudには、属性、文書および他のCPQ Cloudエンティティなどの他のコンポーネントより複雑なユースケースを実現する機能が用意されています。CPQ Cloudにより、一連のデフォルト・アクション(システム生成済)が作成され、カスタム・アクションも使用可能になります。これらのアクションは、ボタンやリンクなどのUIウィジェットにアタッチできます。

RESTful Webサービス・コールを起動するボタン上の新しいカスタム・アクションを作成する手順:

1. CPQ Cloudにログインします。
2. 管理プラットフォーム・アイコンをクリックします。
   
   図admin.jpgの説明
3. コマースおよび文書の下で、「プロセス定義」をクリックします。
4. カスタマイズするコマース・プロセス文書の下にある「ナビゲーション」ドロップダウンから「文書」を選択し、下図に示すように、「リスト」ボタンをクリックします。
   
   図commerce_document.jpgの説明

   これで、「文書」画面に移動します。

5. 「ナビゲーション」ドロップダウンから最上位レベルの「文書」の下の「アクション」を選択し、「リスト」ボタンをクリックします。
   
   図document_window_actions.jpgの説明
6. 「追加」ボタンをクリックし、新しい「アクション」を作成します。
7. 「管理者アクション」画面で、アクション・ラベル名および変数名を入力し、「アクション・タイプ」ドロップダウンからアクションのタイプを選択します。たとえば、「変更」を選択し、「追加」ボタンをクリックします。
8. 「管理者アクション」画面で、 拡張変更 – 式の後の下の 拡張変更の定義 – 式の後を選択し、関数の定義ボタンを選択します。
   
   図advanced_modify_actions.jpgの説明
9. 「変数を選択」画面で、関数が相互作用する属性またはシステム変数を選択します。
   
   図select_variables.jpgの説明
10. 「Next」ボタンをクリックします。

    これで、BMLエディタ画面に移動します。この画面で、BML URLアクセス・ライブラリを使用してRESTful Webサービスを起動するBMLコードを追加できます。

11. BMLコード(「CPQ Cloud BML APIを使用したRESTful Webサービスの起動」を参照)を追加し、「保存して閉じる」ボタンをクリックします。これで、「管理者アクション」画面に戻り、「更新」ボタンをクリックします。

    ヒント:

    BMLコードを編集する場合は常に、「アクション・リスト」画面で作成したアクションをクリックし、「管理者アクション」およびBMLエディタ画面に戻ることができます。

レイアウト・エディタを使用したUIの更新

レイアウト・エディタを使用して、CPQ Cloudの見積りUIを更新し、コマース・ワークフロー内の文書を作成またはカスタマイズできます。

レイアウト・エディタを使用して既存のレイアウトを更新する手順:

1. CPQ Cloudにログインします。
2. 管理プラットフォーム・アイコンをクリックします。
   
   図admin.jpgの説明
3. コマースおよび文書の下で、「プロセス定義」をクリックします。
4. カスタマイズするコマース・プロセス文書の下にある「ナビゲーション」ドロップダウンから「文書」を選択し、下図に示すように、「リスト」ボタンをクリックします。
   
   図commerce_document.jpgの説明

   「文書」ウィンドウに移動します。

5. 「ナビゲーション」ドロップダウンから最上位レベルの「文書」の下の「アクション」を選択し、「リスト」ボタンをクリックします。
   
   図document_window_actions.jpgの説明
6. 「新規アクションの作成」で作成したアクションをクリックします。次に、「管理者アクション」画面で、デスクトップ・レイアウトの保存および編集ボタンをクリックし、レイアウト・エディタに移動します。
   
   図admin_action.jpgの説明
7. 「レイアウト・エディタ」画面で、「追加」ドロップダウン・メニューをクリックし、「レイアウト」を選択します。
   
   図add_layout.jpgの説明

   レイアウト要素と呼ばれる新しいポップアップ・ウィンドウが表示され、コマース文書に追加できる様々なUIアイテムが示されます。

8. レイアウト要素ポップアップ・ウィンドウで、新規パネルの追加ヘッダーをクリックして既存のレイアウトにドラッグし、新しいパネルを追加します。別のポップアップ・ウィンドウが開きます。
   
   図panel_popup.jpgの説明
9. 「ラベル」の下に名前を入力し、「OK」ボタンをクリックします。

   ヒント:

   「縮小可能」チェック・ボックスをクリックすると、縮小可能パネルを作成できます。これらの構成オプションの詳細を確認するには、疑問符アイコンにマウス・カーソルを置きます。
10. 「レイアウト・エディタ」画面の「追加」ドロップダウンをクリックしてから、「属性」をクリックします。
    
    図add_attributes.jpgの説明
11. 作成した属性をクリックして新しいパネルにドラッグします。「新規属性の作成」を参照してください。
12. 「レイアウト・エディタ」画面の「追加」ドロップダウンをクリックしてから、「アクション」をクリックします。「アクション・リスト」のすべてのアクションを示す別のポップアップ・ウィンドウが開きます。
    
    図add_actions.jpgの説明
13. レイアウト要素ポップアップから新規アクション・ストリップの追加をクリックして新しいパネルにドラッグします。
14. 作成したアクション(「新規アクションの作成」を参照)をクリックして新しいパネル内の緑色のアクション・ストリップにドラッグします。
    
    図add_action_strip.jpgの説明
15. 「保存」ボタンをクリックしてから、「戻る」ボタンをクリックし、「ドキュメント・リスト」に戻ります。

ヒント:

「プレビュー」ボタンをクリックすると、進行中の作業をプレビューできます。

新規パネルのデプロイ

新しいパネルをデプロイする手順:

1. CPQ Cloudにログインします。
2. 管理プラットフォーム・アイコンをクリックします。
   
   図admin.jpgの説明
3. コマースおよび文書の下で、「プロセス定義」をクリックします。
4. 「ナビゲーション」ドロップダウンからデプロイメント・センターを選択してから、「クイックリンク」列の下にある「開く」リンクをクリックします。クイックリンクの処理ウィンドウが開きます。
   
   図quick_links_window.jpgの説明
5. 「デプロイ」ボタンをクリックし、変更を公開します。

CPQ Cloud BML APIを使用したRESTful Webサービスの起動

BML URLアクセス・ライブラリの機能を使用して、BMLエディタを使用してRESTful Webサービス・コールを作成できます。

たとえば、RESTful Webサービスに対するコールを作成するには、「新規アクションの作成」のステップに従い、BMLエディタで、次のコードを追加します。

1. CPQ Cloud OAuthアイデンティティ・プロバイダ・エンドポイントへのURLを保持するための変数を作成します。たとえば、次のようにします。

   url = “https://<IdentityProviderURL>/oam/oauth2/tokens/”;

   <<IdentityProviderURL>は、アイデンティティ・プロバイダのURLです。

2. HTTPヘッダーを含めるためのDictionary変数を作成します。

   headers = dict("string"); 

3. CPQ Cloudデータ表に格納されていたOAuthの資格証明を保持するための変数を作成します。「JCS - SaaS Extensionとの統合をサポートするためのセキュアな列を備えたCPQ Cloudデータ表の使用」を参照してください。

   encodedCreds = util.getBasicAuthCredentials("jcs1_2leggedclient", "NOT FOUND");

   この変数は、JCS - SaaS Extension OAuthの資格証明が含まれるCPQ Cloudデータ表に問い合わせるgetBasicAuthCredentialsと呼ばれるユーティリティ関数をコールします。この問合せは、BMQL言語を使用して実行されます。

   clientname = accountName; clients = bmql("select username, password from Credentials where integrationName=$clientname"); for client in clients { encodedCreds= encodebase64( get(client, "username") + ":" + get(client, "password")); return encodedCreds; }

4. put BML関数を使用してディクショナリにHTTPヘッダーを追加し、ドメインのJCS - SaaS Extension OAuthトークン・エンドポイントからアクセス・トークンを取得します。

   put(headers, "Content-Type", "x-www-form-urlencoded;charset=UTF-8"); put(headers, "Accept", "application/json"); put(headers, "Authorization", "Basic" + encodeCreds);

   OAuthトークンの生成方法の詳細は、「CPQ Cloud OAuthプロバイダ用のOAuth 2.0エンドポイント」を参照してください。
5. JCS - SaaS Extension OAuthトークン・エンドポイントに対するBMLのurldatabypost関数を使用してRESTコールを作成し、レスポンスを変数に保存します。

   response=  urldatabypost(url,"grant_type=client_credentials&scope=<JCS-URL>/","NO DATA", headers); 

   <<JCS-URL>は、/>JCS - SaaS Extensionアプリケーション・ドメインです。

6. JSONレスポンスを正しい方法で処理します。たとえば、スペース、中括弧、引用符などを削除します。

   attrs = split( substring(trim(resp), 1, -1) , ","); //trim for spaces, remove begin-end "{" of json, and then split token = ""; for attr in attrs { attrInfo = split(attr, ":"); attrName = substring(trim(attrInfo[0]), 1, -1); //remove spaces, and then begin-end quotes if("access_token" == attrName) { token = substring(trim(attrInfo[1]), 1, -1); } }

   ヒント:

   print関数print(get(response, "Status-Code"));を使用することにより、コンソール内のレスポンスのJSON構造をレビューできます。
7. これで、アクセス・トークンを入手できたので、次に、JCS - SaaS Extensionアプリケーション・エンドポイントに対するRESTコールを作成します。

   headers = dict("string"); put(headers, "Content-Type", "application/json"); put(headers, "Accept", "application/json"); put(headers, "Authorization", "Bearer " + token); serviceResponse = urldatabypost("https://<JCS-URL>/<AppName>/<Endpoint>", "{ \"data\":\"" + <someData> + "\"}", "NO DATA", headers);

8. ボタン関数を使用して更新している属性に結果を戻します。

   return “1~attributeVariable~”+serviceResponse; 

   1~attributeVariable~は、処理したレスポンスの戻り先であるトランザクションおよび属性変数を表します。

CPQ Cloud BMLエディタ・コンソールを使用したRESTful Webサービス・コールのテスト

BMLエディタで、「実行」ボタンをクリックし、コードをテストできます。また、組込みデバッガを使用して、一部の変数をハードコードすることもできます。

1. BMLエディタ画面の上部にある「デバッガ」タブをクリックします。
2. 「デバッガ」画面で、「新規アクションの作成」で選択したシステムまたは属性変数に対するテスト値を入力してから、「実行」ボタンをクリックします。
   
   図debugger_screen.jpgの説明

   コンソールには、結果、print文またはエラーが表示されます。

   注意:

   変数を選択していない、または変数を再選択する場合、画面の右下隅の「再選択」ボタンをクリックします。
3. 「保存して閉じる」ボタンをクリックし、コードを保存し、「管理者アクション」ウィンドウに戻ります。
4. 変更をデプロイするには、新規パネルのデプロイのステップに従います。

アプリケーションのテスト

アプリケーションをテストする手順:

1. ホーム・ページの上部にある「トランザクション・マネージャ」リンクをクリックします。このリンクは一般的に、[コマース・プロセス名]マネージャという名前です。

   注意:

   ホーム・ページの上部には、複数のトランザクション・マネージャ・リンクがリストされている場合があります。どのトランザクション・リンクがコマース・プロセスに属するのかは、管理者に確認してください。
2. 「トランザクション・マネージャ」画面の上部にある「新規トランザクション」ボタンをクリックします。
3. トランザクションの名前を入力し、「保存」ボタンをクリックします。
   「トランザクション・マネージャ」画面内のトランザクション番号列に、新しく作成したトランザクションが作成されます。