DocuSign接続メッセージに対するJSON形式のサポート

Oracle CPQのDocuSign電子署名統合により、2つのアプリケーション間の相互作用が容易になり、Oracle CPQ内に最新の電子署名情報が提供されます。電子署名エンベロープが受信者によって署名または拒否されたときなど、ワークフロー・イベントがトリガーされたときには、DocuSignがCPQにメッセージを送信して通知します。DocuSign接続は、Oracle CPQがこれらのイベント・メッセージの受信に使用するWebフック・サービスです。DocuSign接続のイベント・メッセージは、JSONまたはXMLにフォーマットできます。

Oracle CPQ 24Dより前のCPQでは、XML形式でのみDocuSign接続メッセージがサポートされていました。この機能により、JSONのDocuSign接続メッセージ(JSONのSIMモードと集計モードの両方を含む)に対するOracle CPQのサポートが追加されます。DocuSign接続メッセージが送信されると、コンテンツ・タイプ・ヘッダー(JSONまたはXML)に基づいて解析され、DocuSign HMACセキュリティ・プロトコルを使用して検証されます。Oracle CPQのDocuSign統合では、JSONのイベント・メッセージを認証するために、DocuSignで生成されたセキュア接続キーが必要です。

有効化のステップ

DocuSign eSignature統合タイプを作成するには、権限を持つ管理者が次のステップを実行できます:

  1. 管理ホーム・ページの「統合プラットフォーム」セクションの「統合センター」をクリックします。
  2. 「統合の作成」をクリックします。
  3. 「タイプ」ドロップダウンから「電子署名」を選択します。
  4. 「ベンダー」ドロップダウンから「DocuSign」を選択します。DocuSign統合フィールドのエントリが表示されます。

統合センター - 電子署名DocuSign統合の作成 

  1. 「管理ユーザーID」を入力します。この情報を取得するには、次の手順を参照してください。
  2. 「アカウントID」を入力します。この情報を取得するには、次の手順を参照してください。
  3. 「OAuth URL」に「https://account.docusign.com」と入力します。
  4. エンドポイントURLを入力します。これには、restapiバージョン情報が追加されたDocuSignアカウント・ベースURIが含まれます(例: https://prodsite.docusign.net/restapi/v2)。この情報を取得するには、次の手順を参照してください。

ノート: このURLは、承認済ドメインの許可リストに含まれている必要があります。

  1. DocuSign接続がJSON形式のメッセージをOracle CPQに送信するように構成されている場合は、「接続キー」を入力します。これはDocuSign接続メッセージの認証に使用されるキーで、DocuSignで生成されてOracle CPQに提供されます。接続キーは、DocuSignイベント通知ヘッダーで検証されます。この情報を取得するには、次の手順を参照してください。

ノート: DocuSign電子署名統合を保存すると、接続キーが格納され、接続キーに関連付けられた最終変更日が自動的に移入されます。

  1. DocuSign接続がXML形式のメッセージをOracle CPQに送信するように構成されている場合は、「接続証明書」をアップロードします。接続証明書を追加するには、「ファイルの選択」をクリックし、ハード・ドライブ上の有効な証明書(例: a.crtファイル)にナビゲートします。この証明書は、DocuSign環境で作成されたものと同じである必要があります。

ノート: DocuSignとOracle CPQの証明書が一致する必要があります。

  1. 「保存」をクリックして、接続証明書とともに統合の詳細を保存します。

: DocuSign電子署名統合を保存すると、証明書が保存され、ダウンロードできるようになります。また、証明書に関連付けられている最終変更日も自動的に移入されます。

  1. 「生成」を選択して、「管理トークン」を生成します。OAuthベースの統合を初めて設定する場合は、DocuSignの同意を確認する必要があります。DocuSignからの同意が必要であることを示す警告が表示されます。

「同意する」の警告

  1. 「同意する」をクリックして、同意警告ボックスを閉じます。必要に応じて、DocuSignにログインする必要があります。

Oracle CPQがDocuSignへのアクセスを要求していることを示す新しい「DocuSign」タブが開きます。

Oracle CPQのアクセス要求

  1. 「アクセスの許可」をクリックして、Oracle CPQのアクセスを許可します。

アクセス許可の通知 

  1. Oracle CPQのDocuSign電子署名統合センター・ページにナビゲートし、「生成」をクリックします。

統合センター - 電子署名DocuSign統合

Oracle CPQのDocuSign電子署名の「統合センター」ページには、「生成」ボタンのかわりに、「管理トークン」の「取消」ボタンが表示されます。これは、アクセスが許可され、統合接続が確立されていることを示します。

DocuSignフィールド値の取得

Oracle CPQのDocuSign電子署名統合を設定するには、管理者はDocuSignから必要なフィールド・データを取得する必要があります。次に、DocuSignフィールドおよびDocuSignとOracle CPQの対応するフィールド名を見つけるステップの概要を示します。

  1. DocuSignにログインします。
  2. 「Settings」タブ内の「Integration」セクションにナビゲートします。
  3. 「Integration」セクション内の「Apps and Keys」をクリックします。「Apps and Keys」ページが表示されます。
  4. 「My Account Information」セクション内の次のフィールド値を書き留めます。これらの値は、Oracle CPQのDocuSign電子署名統合の対応するフィールドに入力する必要があります。
DocuSignの「App and Key」フィールド Oracle CPQのDocuSign統合フィールド
User ID 管理ユーザーID
API Account ID アカウントID
Account Base URI

エンドポイントURL

REST APIバージョン情報が追加されたアカウント・ベースURIを入力します(例: https://prodsite.docusign.net/restapi/v2)
  1. 「Integration」セクションから「Connect」をクリックします。「Connect」ページが表示されます。
  2. 「Connect Key」セクションで、「Add Secret Key」をクリックします。これにより、秘密キーが作成されます。
  3. コピー・アイコンを使用して秘密キー値をコピーします。
  4. Oracle CPQのDocuSignの「統合センター」ページの「接続キー」フィールドに秘密キーの値を貼り付けます。
  5. 「保存」をクリックして、秘密キーを保存します。

DocuSignプロパティの構成

DocuSignで文書ステータスが変わったときにOracle CPQの「受入」処理が適切に実行されるためには、次のステップに従ってDocusignを構成する必要があります:

  1. DocuSignにログインします。
  2. 「Settings」タブ内の「Integration」セクションにナビゲートします。
  3. 「Integration 」セクションから「Connect」を選択します。「Connect」ページが表示されます。
  4. 「Configuration」タブで、「Add Configuration」をクリックしてカスタム構成を作成します。
  5. 「Listener Settings」の「Status」フィールドから「Active Connection」を選択します。
  6. 「Name」フィールドに、構成の名前を入力します。
  7. 「URL to Publish」フィールドに、統合するOracle CPQホスト名を次のように入力します:

https://<cpqhost>/notification/receiver/

  1. 「Enable Log」および「Require Acknowledgement」チェック・ボックスを選択します。
  2. 「Event Settings」で、「Data Format」に対して次のいずれかを選択します:
  • JSONメッセージ形式の場合は「REST v2.1」。ステップ10に進みます。
  • XMLメッセージ形式の「Legacy」。スキップしてステップ11に進みます。
  1. JSONメッセージ形式の場合は、次を実行してDocuSignの構成を完了します:
  1. 「Event Message Delivery Mode」で、ビジネス・ニーズに基づいて次のいずれかを選択します:
  • Send Individual Message (SIM)
  • Aggregate Message
  1. 「Trigger Events」で、「Envelopes & Recipients」セクションを展開し、次を選択します:
  • Envelope Signed/Completed
  • Envelope Declined
  • Envelope Voided
  1. 「Envelopes & Recipients」の「Include Data」セクションを展開し、次を選択します:
  • Document PDFs
  • Document Fields
  1. 「Integration and Security Settings」セクションで、「Include HMAC Signature (Recommended)」オプションを選択します。
  2. 「Manage Keys」を選択して「Connect Key」タブに移動し、秘密キーを作成します。
  3. 「Connect Key」セクションで、「Add Secret Key」をクリックします。これにより、秘密キーが作成されます。
  4. コピー・アイコンを使用して秘密キー値をコピーします。
  5. Oracle CPQのDocuSignの「統合センター」ページの「接続キー」フィールドに秘密キーの値を貼り付けます。
  6. 「構成の追加」をクリックして、JSONメッセージ形式のDocuSignプロパティを保存します。

ノート: DocuSign接続でのHMACセキュリティの実装およびベスト・プラクティスの詳細は、DocuSignのDeveloper Centerを参照してください。Oracle CPQでは、企業が定めたセキュリティ・ポリシーに従って、適切な頻度で秘密キーをローテーションすることをお薦めします。

  1. XMLメッセージ形式の場合は、次を実行してDocuSignの構成を完了します:
  1. 「Trigger Events」で、「Envelopes & Recipients」セクションを展開し、次を選択します:
  • Envelope Signed/Completed
  • Envelope Declined
  • Envelope Voided
  1. 「Envelopes & Recipients」の「Include Data」セクションを展開し、次を選択します:
  • Document PDFs
  • Document Fields
  1. 「Use SOAP Interface (SOAP Method: DocuSignConnectUpdate)」を選択します。
  2. サーバーへの通知要求で使用するSOAP「Namespace」を入力します。デフォルトのプロパティ・エンベロープではなく、フルパスのネームスペースが指定されていることを確認します。
  3. 「Include XML Digital Signature in SOAP Header」を選択して、SOAP XMLメッセージがデジタル署名されるようにします。
  4. 「構成の追加」をクリックして、XMLメッセージ形式のDocuSignプロパティを保存します。

ノート: DocuSign構成設定が正しく設定されていないと、管理者のエラー・ログにエラー・メッセージが表示されることがあります。

ヒントと考慮事項

  • Oracle CPQ 24Dでは、JSONとXMLの両方がサポートされています。これは、DocuSignの構成ページから構成します。
  • 24Dにアップグレードした後、既存のDocuSign接続はこの機能の影響を受けません。
  • Oracle CPQ DocuSign統合を設定する際の、メッセージ形式フィールドの要件は次のとおりです:
  • JSONベースのメッセージ形式の場合は、「接続キー」フィールドが必須です
  • XMLベースのメッセージ形式の場合は「接続証明書」フィールドが必須です
  • JSONとXMLベースの両方のメッセージ形式を実装する場合は、「接続キー」と「接続証明書」フィールドが必須です

ノート: DocuSign接続キーは、最終変更日から3年後に失効します。Oracle CPQでは、接続キーの失効日の4週間前から、Eメール通知リマインダが管理者に毎週送信されます。接続キーが失効すると、DocuSignエンベロープ・ステータスが機能しなくなります。