帳票DXアクションとドキュメント生成メソッドの利用方法

帳票DXアクションとドキュメント生成メソッドの利用方法自動処理について帳票DXアクションの利用導入方法「出力定義」の作成方法実行方法実行結果「設定」がドキュメント出力の場合「設定」がD³Worker連携の場合実行結果をApex内で解釈「設定」がドキュメント出力の場合「設定」がD³Worker連携の場合ドキュメント生成メソッドの利用概要準備利用方法ドキュメント生成事前チェック実装の際の注意点

自動処理について

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

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

当資料は以下の(A)(B)について説明します。

(A) 帳票DXアクション
- 非同期的にドキュメント生成やD³Worker連携を行う事が出来ます。
- レコードを作成する事でドキュメント生成や、D³Worker連携を作動させる事ができます。
(B) ドキュメント生成メソッド
- 同期的にドキュメント生成を行う事が出来ます。
- D³Worker連携を行う事はできません。
- 任意のApexコード上で呼び出す事ができます。
(C) Apex REST
- Salesforceの外からドキュメント出力やD³Worker連携を実行する場合に利用します。
- HTTPでのリクエストによって、ドキュメント生成や、D³Worker連携を作動させる事ができます。
- ご利用方法は別ページで説明しています。

帳票DXアクションの利用

導入方法

自動的な処理を行わせるユーザーを準備します。
- アウトバウンドメッセージを利用する場合、画面上で操作するユーザーと、実際のドキュメント生成やD³Worker連携を行うユーザーは異なります。自動的な処理を行わせるユーザーを準備して下さい。
- Salesforceの設定を開き、「権限セット」を検索します。
  - ユーザー＞権限セットを開きます。
    - 「document DX General User Permission Set」に、自動的な処理を行わせるユーザーを割り当てます。
- アプリケーションランチャーにて「OPROARTS（帳票DX）」を開きます。
  - LA, XLA, D3W の配下に、自動的な処理を行わせるユーザーを追加します。
    - ALA、AXLA は自動処理用のユーザではご利用になれません。
    - LA はOffice出力を行う場合に指定します。
    - XLA はPDF出力を行う場合に指定します。
    - D3W はD³Worker連携を利用する場合に指定します。
- Salesforceの設定を開き、「ワークフロー」を検索します。
  - プロセスの自動化＞ワークフローアクション＞アウトバウンドメッセージを開きます。
    - 「Action Message V3」を開き、「編集」ボタンを押します。
      - 「送信ユーザー」の欄に、自動的な処理を実際に行わせるユーザを設定し、保存します。
  - プロセスの自動化＞ワークフローアクション＞ワークフロールールを開きます。
    - 「UnprocessedActiveAction」を開き、「有効化」ボタンを押します。
- アウトバウンドメッセージ送信の流れについて
  - 「帳票DX」のアプリケーションに、「出力定義」のタブを追加しています。
    「出力定義」オブジェクトの子オブジェクトとして「アクション」オブジェクトを設けています。
    処理の条件は「出力定義」に記述し、処理の発動や履歴は「アクション」が担います。
    「アクション」オブジェクトのレコードが、「有効」がチェックされ、かつ「ステータス」が「未完了」の状態になった場合に、ワークフロールールの条件を満たし、アウトバウンドメッセージが送信されます。
  - アウトバウンドメッセージが送信され、各種処理が完了すると、「アクション」オブジェクトのレコード内の「結果」フィールドに処理結果がJSON形式で格納されます。

「出力定義」の作成方法

「出力定義」オブジェクトのレコードは、帳票DXの「設定」の詳細画面に追加した「出力定義作成」ボタンから作成する事ができます。
- UIは概ね「ボタン生成」画面と同様ですが、以下の差異があります。アウトバウンドメッセージでの自動実行の場合、ローカルにダウンロードは出来ないため、ドキュメントを生成する場合は何らかのレコードに添付する動作になります。
  - 「コンテンツリソース(ボタンの種類)」欄はありません。
  - 「ボタンを設置する場所」欄はありません。
  - ドキュメント生成を行う「設定」の場合、「出力方法」の選択肢は以下になります。D³Worker連携の場合は、ボタンの場合と同様に、「出力方法」の欄がありません。
    - 出力元レコードに添付
      - ドキュメントを出力元レコードに添付します。
      - ボタンで出力する場合に「メモ&添付ファイル保存」を選択する場合と同等の動作になります。
      - 一覧型の「設定」の場合は選択できません。
    - アクションレコードに添付(個別に添付)
      - ワークフローの発動元となった「アクション」のレコードに対して、生成したドキュメントを添付します。
      - 複数のドキュメントの生成を行った場合、全てのドキュメントをzip圧縮せず個別に添付します。
      - 一覧型の「設定」の場合は、当設定のみが利用可能です。
    - アクションレコードに添付(複数時zip圧縮)
      - ワークフローの発動元となった「アクション」のレコードに対して、生成したドキュメントを添付します。
      - 複数のドキュメントの生成を行った場合、全てのドキュメントをzipファイルに圧縮し、1ファイルで添付します。
      - 生成されたドキュメントが1件のみの場合はzipに圧縮しません。
      - 指定したレコード群の中に、エラー条件に該当する等して処理されなかったものが生じた場合は、zipファイル内に「failed.txt」が追加されます。当ファイル内に処理失敗したレコードの情報が記載されます。ボタンの場合に「処理種別」として「ダウンロード」を指定した場合と同様の動作です。
      - 一覧型の「設定」の場合は選択できません。(一覧型の場合は常に1ファイルのみの生成となるため、zip圧縮が不要)
  - 生成するドキュメントの作成先オブジェクトを「添付ファイル」にするか、あるいはSalesforceFiles(ContentDocument等)にするかは、ボタンで出力する場合と同様に、カスタム設定の「SalesforceFilesに保存」の指定に準じます。

実行方法

Salesforceの画面上で手動で処理を実行する場合は以下の手順で操作します。Salesforce Lightningを利用している前提で記載します。
- 「帳票DX」アプリケーションの「出力定義」タブを開きます。
- 任意のレコードを開きます。
- 「関連」タブ内の「アクション」内の「新規」ボタンをクリックします。
- 「レコードID」欄に、処理対象とするレコード群をカンマ区切りで指定します。
- 「有効」欄をチェックします。
- 「保存」を押します。
- 作成されたレコードをクリックして詳細を表示します。
- 正常に処理を受け付けた場合、「ステータス」が自動的に「実行中」になります。少し待ってリロードすると、「完了」になります。その際に「結果」欄に具体的な処理結果がJSONで反映されます。

Apexによってアウトバウンドメッセージを実行する例

Salesforceにて開発者コンソールを開き、Ctrl + E を押して、「Enter Apex Code」(実行匿名ウィンドウ)を開きます。

以下のコードを編集した上で貼り付けます。


xxxxxxxxxx
5
1
docutizexa__Action__c action = new docutizexa__Action__c();
2
action.docutizexa__IsActive__c = true; // 有効化。
3
action.docutizexa__RecordIds__c = '0060w00000DDGe4AAH,0060w00000DDGe9AAH'; // 処理対象レコードをカンマ区切りで指定。
4
action.docutizexa__OutputSetting__c = 'a0G0w000004Wc3CEAS'; // 「出力定義」のレコードのオブジェクトIDを指定。
5
insert action;

「Execute」をクリックします。
「帳票DX」アプリケーションの「出力定義」タブを開き、該当する「出力定義」を開き、出力定義の子として新規の「アクション」のレコードが作成されている事を確認します。「ステータス」が「完了」になる事を確認します。

実行結果

「設定」の種別や、「出力方法」によって「アクション」の「結果」に出力されるJSONの構成が変化します。
以下にサンプルを示しますが、「//」以降は説明であり、実際には出力されません。

「設定」がドキュメント出力の場合

出力方法として「出力元レコードに添付」か、「アクションレコードに添付(個別に添付)」を指定した場合


xxxxxxxxxx
18
1
{
2
    "failed": [ // 失敗した処理群を配列で示す。
3
        {
4
            "message": "Salesforce REST API エラー:\n指定されたエラー条件に該当したため出力をスキップします。\r\n(商談対象外,エラー条件No.1)「商談対象外」はエラー。", // エラーメッセージ
5
            "recordId": "0060w00000DETNnAAP" // 失敗したレコードのID
6
        }
7
        // 複数ある場合はカンマ区切りで列記する。
8
    ],
9
    "success": [ // 成功した処理群を配列で示す。
10
        {
11
            "documentId": "0690w000002ABMLAA4", // 生成したドキュメントのID
12
            "outputHistoryId": "a0F0w000003fIhzEAE", // 作成した「出力履歴」のID
13
            "recordId": "0060w00000DDGe4AAH", // データの引用元としたレコードのID
14
            "taskId": "00T0w00000CcnhhEAB" // 作成した活動履歴のID
15
        }
16
        // 複数ある場合はカンマ区切りで列記する。
17
    ]
18
}

出力方法として「アクションレコードに添付(複数時zip圧縮)」を指定した場合
「出力元レコードに添付」の場合と比較して、「documentId」の出力箇所が違う点に注意が必要です。


xxxxxxxxxx
18
1
{
2
    "documentId": "0680w000002A4QnAAK", // 生成したドキュメントのID
3
    "failed": [ // 失敗した処理群を配列で示す。
4
        {
5
            "message": "[error.salesforce.rest.fault(指定されたエラー条件に該当したため出力をスキップします。\r\n(商談対象外,エラー条件No.1)「商談対象外」はエラー。)]", // エラーメッセージ
6
            "recordId": "0060w00000DETNnAAP" // 失敗したレコードのID
7
        }
8
        // 複数ある場合はカンマ区切りで列記する。
9
    ],
10
    "success": [ // 成功した処理群を配列で示す。
11
        {
12
            "outputHistoryId": "a0F0w000003fIj2EAE", // 作成した「出力履歴」のID
13
            "recordId": "0060w00000DDGe4AAH", // データの引用元としたレコードのID
14
            "taskId": "00T0w00000Ccnj9EAB" // 作成した活動履歴のID
15
        }
16
        // 複数ある場合はカンマ区切りで列記する。
17
    ]
18
}

「設定」がD³Worker連携の場合

出力方法の指定欄は無し。


xxxxxxxxxx
21
1
{
2
    "apiUrl": "https://d3w.ap.oproarts.com/d3w/api/hoge/", // リクエスト先のD³WorkerのURL
3
    "failed": [ // 失敗した処理群を配列で示す。
4
        {
5
            "message": "Salesforce REST API エラー:\n指定されたエラー条件に該当したため出力をスキップします。\r\n(商談対象外,エラー条件No.1)「商談対象外」は処理しません。", // エラーメッセージ
6
            "recordId": "0060w00000DETNnAAP" // 失敗したレコードのID
7
        }
8
        // 複数ある場合はカンマ区切りで列記する。
9
    ],
10
    "success": [ // 成功した処理群を配列で示す。
11
        {
12
            "historyId": "a050w000004OeZxAAK", // 作成した「連携履歴」のID
13
            "processId": "PGeJhsxZuqC_3ZX", // D³Worker上に発行されたジョブのID
14
            "recordId": "0060w00000DDGe4AAH", // データの引用元としたレコードのID
15
            "status": "OK", // D³Workerが処理受付の際にレスポンスしたステータス
16
            "taskId": "00T0w00000Ccno9EAB" // 作成した活動履歴のID
17
        }
18
        // 複数ある場合はカンマ区切りで列記する。
19
    ],
20
    "workName": "テストワーク" // D³Worker上で実行されたワークの名称
21
}

実行結果をApex内で解釈

上記の処理結果をApex内で読解する場合、帳票DX for Salesforce が内蔵するglobalメソッドによって内容を読解する事ができます。ドキュメント生成後の後続処理を実装する際にご利用ください。

「設定」がドキュメント出力の場合

Salesforceにて開発者コンソールを開き、Ctrl + E を押して、「Enter Apex Code」(実行匿名ウィンドウ)を開きます。以下のコードを入力する事で docutizexa.GenerateResult型のインスタンスを生成する事ができます。


xxxxxxxxxx
2
1
docutizexa.GenerateResult result = docutizexa.GenerateResult.parseFromAction('結果を調査したい帳票DXアクションのレコードのID');
2
System.debug('result:' + result);

出力されたログを見ると、どのように解釈されたかを確認する事ができます。


xxxxxxxxxx
1
1
09:43:15.0 (118747876)|USER_DEBUG|[4]|DEBUG|detail:GenerateResultDetail:[documentIds=(0691m000002U9jcAAC, 0691m000002U9jdAAC), outputHistoryIds=(a0F1m000005MSWPEA4, a0F1m000005MSWQEA4), recordId=0061m00000AqleXAAR, taskIds=(00T1m000005CbY8EAK, 00T1m000005CbY9EAK)]

「設定」がD³Worker連携の場合

Salesforceにて開発者コンソールを開き、Ctrl + E を押して、「Enter Apex Code」(実行匿名ウィンドウ)を開きます。以下のコードを入力する事で docutizexa.D3WorkerActionResult型のインスタンスを生成する事ができます。


xxxxxxxxxx
2
1
docutizexa.D3WorkerActionResult result = docutizexa.D3WorkerActionResult.parseFromAction('結果を調査したい帳票DXアクションのレコードのID');
2
System.debug('result:' + result);

出力されたログを見ると、どのように解釈されたかを確認する事ができます。


xxxxxxxxxx
1
1
09:51:22.0 (76856702)|USER_DEBUG|[2]|DEBUG|result:D3WorkerActionResult:[apiUrl=https://d3w.ap.oproarts.com/d3w/api/hoge/, failed={}, success=(D3WorkerActionResultDetail:[historyId=a051m000003G96TAAS, processId=PGeTATh9ySH_Gpz, recordId=0061m00000AqleSAAR, status=OK, taskId=00T1m000005CYoREAW]), workName=テストワーク送信]

ドキュメント生成メソッドの利用

概要

ドキュメント生成処理をApexによって同期的に実行する事が出来ます。ドキュメント生成が完了した後の処理を即座に作動させる事が可能になります。

「帳票DXアクション」を利用する場合であっても、「帳票DXアクション」のレコードの状態が「完了」になった際に発火するワークフロールールを設ける事で任意の後処理を作動させる事が可能ですので、基本的には「帳票DXアクション」を利用する事を推奨します。

D³Worker連携機能を提供するメソッドはありません。「帳票DXアクション」をご利用下さい。

準備

あらかじめ「出力定義」のレコードを作成しておく必要があります。作成方法は当ドキュメント内の『「出力定義」の作成方法』の欄を参照して下さい。

「出力定義」を作成する際に、「出力方法」欄にて「出力元レコードに添付」を選択して下さい。それ以外の項目を選択した「出力定義」を利用する事はできません。(メソッドから実行する場合、「帳票DXアクション」のレコードは作成されないため)

利用方法

ドキュメント生成

「帳票DXアクション」を利用せず、Apex上で、帳票DX for Salesforce が提供する global メソッドを利用して、ドキュメントを生成する事も可能です。

以下は実装例です。Salesforceにて開発者コンソールを開き、Ctrl + E を押して、「Enter Apex Code」(実行匿名ウィンドウ)を開き、そこに以下コードを入力する事で、実際の動作を確認する事が出来ます。


xxxxxxxxxx
7
1
try{
2
    docutizexa.GenerateResult result = new docutizexa.DocumentGenerator().generate('利用する「出力定義」のID', new List<String>{'出力対象とするレコードのID'});
3
    System.debug('result:' + result);
4
} catch (docutizexa.DocumentGeneratorException ex){
5
    System.debug('failed:' + ex);
6
    throw ex;
7
}

あらかじめ「出力定義」のレコードを設けておく必要があります。「設定」にて「出力定義作成」ボタンを押して作成してください。
出力定義の内容が不正の場合等、致命的なエラーが検出された場合は、docutizexa.DocumentGeneratorException を投げます。
致命的ではないエラーのみが検出された場合は、出力対象とするレコードのうち、処理可能なものは正常にドキュメントを出力します。

出力対象とするレコードが1件だけの場合は、generateメソッドの第2引数は単一の文字列にしても受け付けられます。


xxxxxxxxxx
1
1
docutizexa.GenerateResult result = new docutizexa.DocumentGenerator().generate('利用する「出力定義」のID', '出力対象とするレコードのID');

一覧型のドキュメントを生成する場合は、setAttachToメソッドによって添付先のレコードを指定して下さい。
一覧型かつIDの指定を不要とするよう設定した「帳票」を利用する場合、generateメソッドの第２引数は省略できます。


xxxxxxxxxx
1
1
docutizexa.GenerateResult result = new docutizexa.DocumentGenerator().setAttachTo('生成したドキュメントの添付先とするレコードのID').generate('利用する「出力定義」のID');

事前チェック

generateメソッドは、致命的なエラーが生じない限り、処理対象としたレコードの中にエラーとなるレコードが含まれていたとしても、その他のレコードは正常に処理します。処理対象の中にエラーとなるレコードが含まれるかを事前に確認したい場合は、check メソッドを利用して下さい。

一覧型の場合


xxxxxxxxxx
1
1
Map<Id, String> checkResult = new DocumentGenerator().check('利用する「出力定義」のID');

ヘッダー明細型の場合


xxxxxxxxxx
1
1
Map<Id, String> checkResult = new DocumentGenerator().check('利用する「出力定義」のID', new List<String>{'出力対象とするレコードのID'});

出力定義の内容が不正の場合等、致命的なエラーが検出された場合は、docutizexa.DocumentGeneratorException を投げます。
戻り値は Map<Id, String> です。キーは出力対象レコードのID、値はエラーメッセージです。

実装の際の注意点

ドキュメント生成を行う DocumentGenerator#generate は、以下の場合に「You have uncommitted work pending. Please commit or rollback before calling out」のエラーが発生します。

DMLを実行した後で呼び出した場合
連続して呼び出した場合

以下のように @future(callout=true) のアノテーションを付加したメソッドを設けて、これを呼び出すように実装する事で、上記の問題を回避する事ができます。


11
1
    @future(callout=true)
2
    public static void genTest(Id outputSettingId, Id targetId){
3
        try{
4
            GenerateResult result = new DocumentGenerator().generate(outputSettingId, targetId);
5
            System.debug('result:' + result);
6
            // 生成後の処理
7
        } catch (DocumentGeneratorException ex){
8
            System.debug('failed:' + ex);
9
            throw ex;
10
        }
11
    }