帳票DX for Salesforce(document DX) ApexRESTについて

自動処理について

帳票DX for Salesforceは、ドキュメント生成やD³Worker連携を自動的に実施する手段として、以下3種の機能を提供しています。

基本的には(A)をご利用下さい。

• (A) 帳票DXアクション

  • 非同期的にドキュメント生成やD³Worker連携を行う事が出来ます。

  • レコードを作成する事でドキュメント生成や、D³Worker連携を作動させる事ができます。

  • ご利用方法は別ページで説明しています。

• (B) ドキュメント生成メソッド

  • 同期的にドキュメント生成を行う事が出来ます。

  • D³Worker連携を行う事はできません。

  • 任意のApexコード上で呼び出す事ができます。

  • ご利用方法は別ページで説明しています。

• (C) Apex REST

  • Salesforceの外からドキュメント出力やD³Worker連携を実行する場合に利用します。

  • HTTPでのリクエストによって、ドキュメント生成や、D³Worker連携を作動させる事ができます。

  • 当資料は当機能について説明します。

ドキュメント出力をリクエストする Apex REST について

• エンドポイント：https://(instance).salesforce.com/services/apexrest/docutizexa/CreateDocuments

• 利用可能なメソッド：GET または POST

GET でリクエストする場合

• 以下のようにリクエストします。

  • https://(instance).salesforce.com/services/apexrest/docutizexa/CreateDocuments/(設定名)/(出力するレコードのオブジェクトID群)/(親オブジェクト)

    • HTTPヘッダに認証情報を指定します。Windows版Curlを利用する場合は以下のようにリクエストします。

      xxxxxxxxxx
      1
      1
      curl --include -H "Authorization: Bearer (sessionId)" https://(instance.salesforce.com)/services/apexrest/docutizexa/CreateDocuments/(設定名)/(出力するレコードのオブジェクトID群)/(親オブジェクト)"
      

      • (sessionId) : SalesforceのセッションID。 sfdx org:display:user で獲得できるAccess Tokenを利用する。

      • (instance.salesforce.com) : リクエストする組織のドメインを指定します。

    • 「設定名」欄には、帳票DX for Salesforceの「設定」画面で作成した定義の名称を指定します。URLエンコードした上で指定して下さい。

    • 「出力するレコードのオブジェクトID群」欄について

      • 複数指定する場合はカンマ(,)で区切って指定します。

      • 「一覧型」の設定を利用していて、かつ「項目選択」画面の「条件」の「抽出条件」として「該当分全件」を選択している場合は、「any」を指定します。

    • 「親オブジェクト」には、以下の何れかを指定して下さい。生成するドキュメントをどのレコードに紐付けるかを指定します。

      • download : 「帳票DX for Salesforce」が内包するオブジェクトである「ダウンロード」オブジェクト(docutizexa__Download__c)内に新規レコードを作成し、そのレコードに「メモ＆添付ファイル」として紐づく形でドキュメントのレコードを生成します。

        • 自動生成される「ダウンロード」オブジェクトのレコードは、ApexRESTの処理が完了した後も残存します。当APIを利用する処理にて、ドキュメントの獲得が成功したら、親となる「ダウンロード」オブジェクトのレコードを削除するように実装して下さい。

      • permanent: 出力対象レコードの「メモ＆添付ファイル」として紐づく形でドキュメントのレコードを生成します。

      • (アクションオブジェクトのレコードID): 「アクション」オブジェクトからアウトバウンドメッセージ経由でドキュメントを出力する場合を想定。ドキュメントの添付先を、指定した「アクション」のレコードにする事が可能。

    • ドキュメントの作成先オブジェクトは、カスタム設定「document DX Static Setting」のチェックボックス「SalesforceFilesに保存」の指定によって変化します。

      • チェックしている場合、SalesforceFilesのレコードを作成します。(ContentVersionとContentDocumentにレコードを作成)

      • チェックしない場合、「添付ファイル」(Attachment)オブジェクトのレコードを作成します。

      • POSTでリクエストする場合は、カスタム設定よりも優先して動作を指定する事が可能です。詳細は後述します。

    • ドキュメント作成の際の活動履歴は、カスタム設定「document DX Static Setting」のチェックボックス「活動登録ON」がチェックされている場合に実施します。ただし、「一覧型」の設定を利用する場合は活動履歴を作成しません。

      • POSTでリクエストする場合は、カスタム設定よりも優先して動作を指定する事が可能です。詳細は後述します。

POSTでリクエストする場合

• Windows版のcurlでリクエストする場合を想定して例を示します。 同一ディレクトリ内に以下のファイルを用意します。

  • createDocumentsPost.bat

    xxxxxxxxxx
    1
    1
    curl --include -H "Authorization: Bearer (sessionId)" -H "Content-Type: application/json" -d @createDocumentsPost.json https://(instance.salesforce.com)/services/apexrest/docutizexa/CreateDocuments/"
    

    • (sessionId) : SalesforceのセッションID。 sfdx org:display:user で獲得できるAccess Tokenを利用する。

    • (instance.salesforce.com) : リクエストする組織のドメインを指定します。

  • createDocumentsPost.json

    以下のサンプルを参考に作成します。「//」で始まる行は説明文ですので削除して下さい。

    xxxxxxxxxx
    45
    1
    {
    2
        // 利用する「帳票DX for Salesforce」の「設定」の名前を指定します。
    3
        "reportName":"PDF_SAMPLE_001"
    4
    
    5
        // 出力対象とするレコードのオブジェクトID群を指定します。
    6
        ,"recordIds":[
    7
             "0060p00000Dgpd2AAB"
    8
        ]
    9
    
    10
        // 「親オブジェクト」を指定します。GETリクエストの場合の説明を参照して下さい。
    11
        ,"parentObject":"download"
    12
    
    13
        // SalesforceFiles上にドキュメントを生成するかを指定します。
    14
        // 省略した場合は、カスタム設定「document DX Static Setting」の「SalesforceFilesに保存」の指定に準じます。
    15
        ,"useSalesforceFiles":"true"
    16
    
    17
        // 活動履歴を作成するかを指定します。
    18
        // 省略した場合は、カスタム設定「document DX Static Setting」の「活動登録ON」の指定に準じます。
    19
        ,"createTask":"false"
    20
    
    21
        // ドキュメント出力後の更新条件を指定します。
    22
        // 「ボタン生成」画面でVisualforcePage上に生成される「updates」パラメーターの値と同様の値を設定します。
    23
        // 詳細な説明は割愛します。
    24
        ,"updates":[
    25
            {
    26
                "field":"docutizexa__NO_PACKAGE_UPD_TEXT__c"
    27
                ,"value":"hoge"
    28
            }
    29
        ]
    30
    
    31
        // v1.30.0 以降で追加。
    32
        // ドキュメント生成の前に、処理対象レコードが出力対象として適切かをチェックする事が可能です。
    33
        // 「ボタン生成」画面でVisualforcePage上に生成される「errors」パラメーターの値と同様の値を設定します。
    34
        // 生成されたコードを貼り付けて利用して下さい。ここでの詳細な説明は割愛します。
    35
        ,"errors":[
    36
            {
    37
                 "value":"テスト"
    38
                ,"type":"SINGLE"
    39
                ,"message":""
    40
                ,"fieldType":"STRING"
    41
                ,"field":"Name"
    42
                ,"compare":"NOT_EQUAL"
    43
            }
    44
        ]
    45
    }
    

レスポンス

以下のようなレスポンスが得られます。(GET,POST共通)

• 返却されたJSONの内容を解釈して、生成されたドキュメントのIDを獲得し、別途ドキュメントを獲得する処理を実装して下さい。

• 「親オブジェクト」として「download」を指定した場合、「downloadObjId」欄に生成されたレコードのIDが格納されます。当レコードは一時的に生成するものですので、ドキュメントの獲得が完了したらレコードを削除する処理を実装して下さい。

• レスポンスされるJSONについて、サンプル内にコメントを挿入して説明します。実際に返却されるJSONは整形されておらず、「//」で始まる行も存在しません。

  xxxxxxxxxx
  57
  1
  {
  2
       "results":{
  3
          //  利用したテンプレートの名前
  4
           "templateName":"arts20230803162910040_Excel001"
  5
  
  6
          // 作成された「活動履歴」のID群
  7
          ,"taskIds":[
  8
               "00T0p00000JQJmwEAH"
  9
          ]
  10
          
  11
          // 処理成功したID群。
  12
          // キー：ドキュメント生成が成功したレコードのID。
  13
          // 値：生成されたドキュメントのID。
  14
          ,"successfulIds":{
  15
               "0060p00000DgexDAAR":"00P0p000007ui64EAA"
  16
          }
  17
          
  18
          // 利用した「帳票DX for Salesforce」の「設定」の名前
  19
          ,"reportId":"a0G0p00000BRQYhEAP"
  20
          
  21
          // 作成された「出力履歴」のID群
  22
          ,"outputHistoryIds":[
  23
               "a0E0p00000HAXQOEA5"
  24
          ]
  25
  
  26
          // 生成されたドキュメントの拡張子
  27
          ,"extension":".xlsx"
  28
  
  29
          // 生成した「ダウンロード」オブジェクト(docutizexa__Download__c)のレコードのオブジェクトID
  30
          // 「親オブジェクト」として「download」を指定した場合だけ当項目が生じます。
  31
          ,"downloadObjId":"a060p000004fs3lAAA"
  32
  
  33
          // 生成されたドキュメントのID群。(successfulIdsの値部分と同一)
  34
          ,"createdDocumentIds":[
  35
               "0690p000001F5DhAAK"
  36
          ]
  37
      }
  38
  
  39
      // レコードの名前を獲得できるMap。(v1.30.0 以降で追加)
  40
      // 生成対象として指定したレコードのオブジェクトがNameフィールドを持たない場合は空配列を返却する。
  41
      // キー：生成対象として指定したレコードのオブジェクトID
  42
      // 値：生成対象として指定したレコードのNameフィールドの値。
  43
      ,"labels":{
  44
           "0060p00000DgexDAAR":"テスト商談"
  45
      }
  46
  
  47
      // リクエスト時に指定された条件を返却する。
  48
      // ApexREST側でリクエスト内容がどのように解釈されたかを確認する事が可能。
  49
      // v1.30.0 以降ではnullの項目は除外される。
  50
      ,"conditions":{
  51
           "reportName":"Excel001"
  52
          ,"recordIds":[
  53
               "0060p00000DgexDAAR"
  54
          ]
  55
          ,"parentObject":"download"
  56
      }
  57
  }
  

   

D³Worker連携をリクエストする Apex REST について

• エンドポイント：https://(instance).salesforce.com/services/apexrest/docutizexa/CreateDocuments

• 利用可能なメソッド：GET または POST

GET でリクエストする場合

• 以下のようにリクエストします。

  • https://(instance).salesforce.com/services/apexrest/docutizexa/RequestD3Worker/(設定名)/(出力するレコードのオブジェクトID群)

    • HTTPヘッダに認証情報を指定します。Windows版Curlを利用する場合は以下のようにリクエストします。

      xxxxxxxxxx
      1
      1
      curl --include -H "Authorization: Bearer (sessionId)" https://(instance.salesforce.com)/services/apexrest/docutizexa/RequestD3Worker/(設定名)/(出力するレコードのオブジェクトID群)"
      

      • (sessionId) : SalesforceのセッションID。 sfdx org:display:user で獲得できるAccess Tokenを利用する。

      • (instance.salesforce.com) : リクエストする組織のドメインを指定します。

    • 「設定名」欄には、帳票DX for Salesforceの「設定」画面で作成した定義の名称を指定します。URLエンコードした上で指定して下さい。

    • 「出力するレコードのオブジェクトID群」欄について

      • 複数指定する場合はカンマ(,)で区切って指定します。

      • 「一覧型」の設定を利用していて、かつ「項目選択」画面の「条件」の「抽出条件」として「該当分全件」を選択している場合は、「any」を指定します。

    • ドキュメント生成での「親オブジェクト」にあたる欄はありません。

    • ドキュメント作成の際の活動履歴は、カスタム設定「document DX Static Setting」のチェックボックス「活動登録ON」がチェックされている場合に実施します。ただし、「一覧型」の設定を利用する場合は活動履歴を作成しません。

      • POSTでリクエストする場合は、カスタム設定よりも優先して動作を指定する事が可能です。詳細は後述します。

POSTでリクエストする場合

• Windows版のcurlでリクエストする場合を想定して例を示します。 同一ディレクトリ内に以下のファイルを用意します。

  • requestD3WorkerPost.bat

    xxxxxxxxxx
    1
    1
    curl --include -H "Authorization: Bearer (sessionId)" -H "Content-Type: application/json" -d @requestD3WorkerPost.json https://(instance.salesforce.com)/services/apexrest/docutizexa/RequestD3Worker/"
    

    • (sessionId) : SalesforceのセッションID。 sfdx org:display:user で獲得できるAccess Tokenを利用する。

    • (instance.salesforce.com) : リクエストする組織のドメインを指定します。

  • requestD3WorkerPost.json

    以下のサンプルを参考に作成します。「//」で始まる行は説明文ですので削除して下さい。

    xxxxxxxxxx
    40
    1
    {
    2
        // 利用する「帳票DX for Salesforce」の「設定」の名前を指定します。
    3
        "reportName":"PDF_SAMPLE_001"
    4
    
    5
        // 出力対象とするレコードのオブジェクトID群を指定します。
    6
        ,"recordIds":[
    7
             "0060p00000Dgpd2AAB"
    8
        ]
    9
    
    10
        // 活動履歴を作成するかを指定します。
    11
        // 省略した場合は、カスタム設定「document DX Static Setting」の「活動登録ON」の指定に準じます。
    12
        ,"createTask":"false"
    13
    
    14
        // ドキュメント出力後の更新条件を指定します。
    15
        // 「ボタン生成」画面でVisualforcePage上に生成される「updates」パラメーターの値と同様の値を設定します。
    16
        // 生成されたコードを貼り付けて利用して下さい。ここでの詳細な説明は割愛します。
    17
        // D³Workerに連携を実施した時点で更新するのでご注意下さい。
    18
        // D³Worker上でジョブが正常終了するまで待ってから更新するものではありません。
    19
        ,"updates":[
    20
            {
    21
                "field":"docutizexa__NO_PACKAGE_UPD_TEXT__c"
    22
                ,"value":"hoge"
    23
            }
    24
        ]
    25
    
    26
        // v1.30.0 以降で追加。
    27
        // ドキュメント生成の前に、処理対象レコードが出力対象として適切かをチェックする事が可能です。
    28
        // 「ボタン生成」画面でVisualforcePage上に生成される「errors」パラメーターの値と同様の値を設定します。
    29
        // 生成されたコードを貼り付けて利用して下さい。ここでの詳細な説明は割愛します。
    30
        ,"errors":[
    31
            {
    32
                 "value":"テスト"
    33
                ,"type":"SINGLE"
    34
                ,"message":""
    35
                ,"fieldType":"STRING"
    36
                ,"field":"Name"
    37
                ,"compare":"NOT_EQUAL"
    38
            }
    39
        ]
    40
    }
    

レスポンス

以下のようなレスポンスが得られます。(GET,POST共通)

• 当APIはD³Workerに対してワークの実行を要求するまでが処理範囲です。発行されたD³Worker上のジョブの処理結果の確認までは行いません。必要に応じて、別途処理結果を確認する処理を実装して下さい。

• レスポンスされるJSONについて、サンプル内にコメントを挿入して説明します。実際に返却されるJSONは整形されておらず、「//」で始まる行も存在しません。

  54
  1
  {
  2
      "results":{
  3
  
  4
          // 実行されたD³Worker上のワークの名前。
  5
           "workName":"テストワーク"
  6
  
  7
          // D³Workerが返却したステータスコード
  8
          ,"statusCode":200
  9
  
  10
          // D³Workerが返却した「status」の値。受信可否判定結果。
  11
          ,"status":"OK"
  12
  
  13
          // 処理対象として指定された「帳票DX for Salesforce」の「設定」のレコードのオブジェクトID
  14
          ,"reportId":"a0G0p000007i1ieEAA"
  15
  
  16
          // 生成対象として指定されたオブジェクトID群。
  17
          ,"recordIds":[
  18
               "0060p00000DgexDAAR"
  19
          ]
  20
  
  21
          // D³Workerにて発行されたジョブのプロセスID。
  22
          ,"processId":"PGe7ZK5NdRD_GCN"
  23
  
  24
          // D³Workerが返却した「isSuccess」の値。trueの場合受信成功。
  25
          ,"isSuccess":true
  26
  
  27
          // D³Workerの履歴確認画面のURL。ブラウザ上で開く事で該当するジョブの状態を確認する事が可能。
  28
          ,"historyUrl":"https://d3w.ap.oproarts.com/d3w/a/(テナント名)/history/?process_id=PGe7ZK5NdRD_GCN"
  29
  
  30
          // 「帳票DX for Salesforce」上の「連携履歴」のID。
  31
          ,"historyId":"a040p000004mK3iAAE"
  32
  
  33
          // リクエスト先URL。
  34
          ,"apiUrl":"https://d3w.ap.oproarts.com/d3w/api/(テナント名)/"
  35
      }
  36
  
  37
      // レコードの名前を獲得できるMap。(v1.30.0 以降で追加)
  38
      // 生成対象として指定したレコードのオブジェクトがNameフィールドを持たない場合は空配列を返却する。
  39
      // キー：生成対象として指定したレコードのオブジェクトID
  40
      // 値：生成対象として指定したレコードのNameフィールドの値。
  41
      ,"labels":{
  42
           "0060p00000DgexDAAR":"テスト商談"
  43
      }
  44
  
  45
      // リクエスト時に指定された条件を返却する。
  46
      // ApexREST側でリクエスト内容がどのように解釈されたかを確認する事が可能。
  47
      // v1.30.0 以降ではnullの項目は除外される。
  48
      ,"conditions":{
  49
           "reportName":"D3Worker_parentList"
  50
          ,"recordIds":[
  51
               "0060p00000DgexDAAR"
  52
          ]
  53
      }
  54
  }