承認プロセスAPI

承認プロセスAPI

Salesforce には標準で承認プロセスの機能が備わっています。通常は標準の承認プロセスを使用するのが一番手っ取り早いですし、変更時も柔軟に対応できます。しかし、

  • 承認申請を上げたとき、プロセス途中の重複する申請を自動的に取り消したい
  • 標準画面とは全く異なる Visualforce から承認申請を上げたい
  • 承認申請を上げる、承認、却下で実行ユーザの再認証を行いたい

という場合には、標準の承認プロセスだけでは実現することができません。 そんなときは、承認プロセスの API を Apex から利用して、承認プロセスをカスタマイズする必要があります。 というわけで。 今回は承認プロセスの API に関して書きます。

まず、承認プロセスを管理しているオブジェクトの構成はこんな感じになります。

ProcessInstance

sObject：承認プロセスを実行したオブジェクト

ProcessInstance：申請した承認プロセスの１プロセスごとに管理するオブジェクト

ProcessInstanceStep：完了したステップのアクションを管理するオブジェクト

ProcessInstanceWorkItem：承認待ちとなっているステップを管理するオブジェクト

それぞれのオブジェクトは参照のみです（sObject以外）。直接上記オブジェクトにデータを登録することはできません。 そこで、承認プロセス API を使用して、承認プロセスのデータを作成していくことになります。

使う API はこれです → Approval

承認の申請

承認プロセスの開始となる申請にはApproval.ProcessSubmitRequestを使います。 これで申請を上げるためのリクエストを作成し、プロセスを開始します。 コードサンプルはこんな感じ。

sample1

request.setObjectIdで、承認プロセスを開始するレコードを指定します。

ここで API ならではの技を紹介。request.setComments( comment );の部分。 通常、「承認申請」ボタンをクリックして「レコードの編集ができなくなりますよ～」のメッセージに「OK」すると、そのまま承認プロセスが開始となります。 しかし、API を使うと、この申請時に申請者のコメントを入力することができるようになります。 つまり「こういうことで申請します！！」という申請者の強い想いをこめた申請を上げることができるようになるのです！！！

ステップのアクション

承認者となるユーザにステップが渡ってきたときのアクションには承認、却下、取消があります。 このときにはApproval.ProcessWorkItemRequestを使います。 これで次へ進めるためのリクエストを作成し、プロセスを進めます。 コードサンプルはこんな感じ。

sample2

request.setWorkItemIdで現在動いているステップのID（ProcessInstanceWorkItem に存在しているID）を渡して「このステップを動かします！」を指定します。

request.setActionに渡すパラメータで、承認、却下、取消を判断します。

承認の場合はApprove

却下の場合はReject

取消の場合はRemoved

をそれぞれパラメータとして渡します。 ちなみに、承認プロセスが開始している状況でApproval.ProcessSubmitRequestをコールすると、既に承認プロセスはじまってますよ～と怒られエラーとなります。

手動で承認者を指定

承認プロセスのステップでは、承認者を自動で割り当てる方法と、手動で指定して割り当てる方法があります。自動で割り当てる場合は、サンプルコードにあるとおりApproval.processで次のプロセスに進行します。しかし、手動で指定する場合は、次の承認者を指定しないとApproval.processで Exception が発生します。

Process failed. First exception on row 0; first error: REQUIRED_FIELD_MISSING, missing required field: [nextApproverIds]

というメッセージの Exception が。

残念ながら、今のところ、API で次のステップが手動で承認者を指定する必要があるか否かを取得することができません。 そのため、Exception が発生した際、この中の「nextApproverIds」をキーワードで判断して、次のユーザを指定するような処理を実装する必要があります。 下記コードを追加して、次の承認者を指定します。

request.setNextApproverIds(new Id[] { nextApproverId });

当然ですが、予め「この承認プロセスは必ず手動で承認者を指定するんだ！！」と決まっていれば、 初めからsetNextApproverIdsを使用して次の承認者を設定しておけば良いので、Exception の判断は不要です。 なお、次の承認者はユーザID、もしくはキューのIDを指定することが可能です。

再割り当て

現在割り当っている承認者ではなく、違うユーザ（もしくはキュー）へ承認を委譲する際に行う再割り当て。

残念ながら、このアクションは API でどうこうすることができません。 再割り当てを行いたい場合は、標準画面から行う形で実現することになります。

おまけ

現在、未承認となっている承認プロセス一覧を表示する未承認申請一覧というレポートがあります。

しかし、これは管理レポートの１つとなっていて、すべてのデータの参照権限を持っていないと見ることができません。 「そうは言っても、すべてのデータの参照権限を持たない一般ユーザに未承認申請の一覧を提供してあげたい！」という場合は、冒頭に紹介した各オブジェクトからデータを取得し、その一覧を提供してあげることができます。当然画面は Visualforce で作ることになります。

また、標準のホームページコンポーネントで未承認申請というものがあります。これをホームページに表示してあげることで、自分に割り当っていて未だ処理をしていない承認申請を一覧で見ることができるようになります。このコンポーネントでは「すべてを管理」というアクションが使えて、複数の承認プロセスを一括で処理することができます。 そんな便利機能に反して「複数の承認プロセスをまとめて処理なんかするな～！」というポリシーを立てた場合は、やはり Visualforce で未承認申請の一覧を提供してあげるのが良いと思います。