Share via


コードを使用してビジネス プロセス フローを操作する

業務プロセス フローにより、効率的で、より効率的な営業、サービス、および他の業務プロセスを作成できます。 それはテーブル フォーム最上部に特別なコントロールを設定することで、ビジネス プロセスのビジュアル化を作成します。 ユーザーは完了に向け、営業、マーケティング、顧客サービス プロセスのさまざまなステージで導かれます。 各プロセスでは、複数のステージおよびステップをサポートします。 ステップを追加または削除したり、ステップの順序を変更したり、ビジネス プロセス フローに新しいテーブルを追加できます。

異なるビジネス プロセス フローのインスタンスが、同じテーブル行に対して同時に実行できます。 ユーザーは同時のビジネス プロセス インスタンスを切り替えでき、プロセスの現在の段階での作業を再開できます。

このトピックでは、業務プロセス フローをプログラムで使用する方法を説明します。

Note

業務プロセス フローを使用するためにコードを記述する必要はありません。 UI を使用したビジネス プロセス フローの作成と管理についての詳細は、ビジネス プロセス フローの概要 を参照してください

業務プロセス フローの前提条件

UI フォームを更新したカスタム テーブルとテーブルによって、ビジネス プロセス フローに参加できます。 更新された UI テーブルには trueに設定された IsAIRUpdated プロパティがあります。

ビジネス プロセス フローのテーブルを有効にするには、IsBusinessProcessEnabled プロパティを true に設定します。

重要

ビジネス プロセス フローのエンティティを有効にするのは、一方向のプロセスとなります。 これを逆にはできません。

業務プロセス フローの定義

業務プロセス フローを定義するには、視覚的な業務プロセス フロー デザイナーを使用します。 詳細: 業務プロセス フローの作成

既定では、ビジネス プロセス フローのレコードは Draft 状態で作成されます。

業務プロセス フローの定義は workflow テーブルに格納され、業務プロセス フローのステージ情報は processstage テーブルに保存されます。

業務プロセス フローのアクティブ化

プロセス フローを使用するには、その前に、それをアクティブ化する必要があります。 それをアクティブ化するには、Workflow テーブルの prvActivateBusinessProcessFlow の特権が必要です。 Workflow テーブル行の状態を Activated に設定するには UpdateRequest メッセージを使用します。 詳細については、更新を使用して特化された操作を実行するを参照してください。

Note

視覚的な業務プロセス フロー デザイナーを使用して、業務プロセス フローをアクティブ化することもできます。

ビジネス プロセス フローのテーブル

対応する Workflow テーブル行の状態を変更したり、またはビジネス プロセス フロー デザイナーを使用して、ビジネス プロセス フローの定義をアクティブ化すると、以下の名前のカスタム テーブルが自動的に作成され、アクティブ化したビジネス プロセス フローの定義を格納します: "<activesolutionprefix>_<uniquename>"、ここで uniquename は指定する名前から引き出されます。

たとえば、ビジネス プロセス フローの定義の名前として "My Custom BPF" を指定して、アクティブ ソリューションの既定の発行元 (新規) を使用している場合、プロセス インスタンスの格納用に作成されたカスタム テーブルの名前は "new_mycustombpf" になります。

uniquename の値が業務プロセス フロー定義に対して存在しない場合、たとえばビジネス プロセス フローが以前のバージョンのソリューションからインポートされた場合は、カスタム テーブルの既定名が"\<activesolutionprefix>_bpf_<GUID_BPF_Definition>: になります。

重要

サンプルのビジネス プロセス フロー行は、システム テーブルを使用して、対応する業務プロセス フロー インスタンス行を格納します。

ただし、作成する新しいビジネス プロセス フロー定義すべては、前に説明したように、カスタム テーブルを使用してインスタンス行を保存します。

次の方法のいずれかを使用してビジネス プロセス フロー テーブルの名前を取得できます。

  • UI を使用する: 業務プロセス フロー テーブルを参照するカスタマイズ UI を使用します:

    UI を使用してビジネス プロセス フロー テーブルを参照します。

  • Web API を使用する: 次の要求を使用します:

    要求

    GET [Organization URI]/api/data/v9.0/workflows?$filter=name eq 'My Custom BPF'&$select=uniquename HTTP/1.1
    

    回答

    {  
    "@odata.context":"[Organization URI]/api/data/v9.0/$metadata#workflows(uniquename)",
    "value":[  
         {  
             "@odata.etag":"W/\"1084677\"",
             "uniquename":"new_mycustombpf",
             "workflowid":"2669927e-8ad6-4f95-8a9a-f1008af6956f"
         }
      ]
    }
    
  • 組織サービスを使用する: 次のコード サンプルを使用します :

    QueryExpression query = new QueryExpression
    {
        EntityName = "workflow",
        ColumnSet = new ColumnSet("uniquename"),
        Criteria = new FilterExpression
        {
            Conditions =
            {
                new ConditionExpression
                {
                    ColumnName = "name",
                    Operator = ConditionOperator.Equal,
                    Values = { "My Custom BPF" }
                }
            }
        }
    };
    Workflow Bpf = (Workflow)_serviceProxy.RetrieveMultiple(query).Entities[0]; 
    

Note

IsBPFEntity プロパティは、ビジネス プロセス フロー テーブルに対しては true となります。 インスタンス内のビジネス プロセス フロー テーブルをすべて取得するには、次の Web API 要求を実行します。

GET [Organization URI]/api/data/v9.0/EntityDefinitions?$select=SchemaName,LogicalName,DisplayName&$filter=IsBPFEntity eq true HTTP/1.1

業務プロセス フローのセキュリティを管理する

ビジネス プロセス フローをアクティブにしたときに、ビジネス プロセス フローのインスタンスを格納するためのカスタム テーブルが自動的に作成されますが、このテーブルは Microsoft Dataverse の他のカスタム テーブルと同様に標準のセキュリティ モデルに従います。 つまり、そのテーブルに付与された特権に基づいて、実行時にビジネス プロセス フローのユーザーに付与される許可が定義されます。

カスタム ビジネス プロセス フロー テーブルの対象は組織です。 このテーブルに対する通常の作成、取得、更新、削除の特権によって、ユーザーが自分に割り当てられたロールに基づいて持つことになるアクセス許可が定義されます。 既定では、ビジネス プロセス フローのカスタム テーブルが作成されるときにアクセス許可が付与されるセキュリティ ロールは、システム管理者システム カスタマイザー のみであるため、新しいビジネス プロセス フローのテーブル (この例では My Custom BPF) にその他のセキュリティ ロールが必要な場合は明示的にアクセス許可を与える必要があります。

セキュリティ ロールの管理。

ビジネス プロセス フローのテーブル行 (プロセス インスタンス) の作成、取得、更新、削除

ビジネス プロセス フロー定義をアクティブにしたときに自動的に作成されるカスタム テーブルに、そのビジネス プロセス フロー定義に対応するすべてのプロセス インスタンスが格納されます。 このカスタム テーブルは、Web API と CRM 2011 エンドポイントを使用する、標準的なプログラミングによる行 (プロセス インスタンス) の作成と管理をサポートしています。

重要

テーブル行のプロセス インスタンスを別のインスタンスに切り替えることは、UI (クライアント) で行うか、このセクションで示す情報を使用してプログラミングで行うことだけがサポートされています。 SetProcess メッセージ (SetProcess Action または SetProcessRequest) を使用してプログラミングでターゲット テーブル行のプロセスを切り替える (別のビジネス プロセス フローをアクティブなプロセス インスタンスとして設定する) ことはできなくなりました。

複数のテーブルにまたがる業務プロセス フローがあるとします。名前は "My Custom BPF" で、S1:Account、S2:Account、S3:Contact の 3 つのステージがあります。

カスタム ビジネス プロセス フロー。

1 つのビジネス プロセス フロー テーブルに対応する行 (インスタンス) をすべて取得する

ビジネス プロセス フロー テーブルの名前が "new_mycustombpf" の場合に、このビジネス プロセス フロー テーブルに対応する行 (プロセス インスタンス) をすべて取得するには次のクエリを使用します:

GET [Organization URI]/api/data/v9.0/new_mycustombpfs HTTP/1.1 

この時点で、何も存在しない場合は、応答でインスタンスを取得しない場合もあります。 このトピック後半の業務プロセス フローの定義のインスタンスを作成した後に、この要求を実行します。

Note

業務プロセス フロー テーブルの名前を取得する方法を確認するには、前述のセクション、業務プロセス フロー テーブル を参照してください。

ビジネス プロセス フロー テーブル行 (プロセス インスタンス) の作成

UI を使用しないでテーブル行の別のビジネス プロセス フローに切り替えるには、ビジネスプロセス フロー テーブル行 (プロセス インスタンス) をプログラムで作成します。

ビジネス プロセス フロー テーブル行を作成するには、次の値を指定する必要があります:

  • @odata.bind 注釈を使用して単一値ナビゲーション プロパティを設定することによって、主テーブル行に、ビジネス プロセス フロー テーブル行を関連付けます。 ビジネス プロセス フローの定義の主テーブル行を指すナビゲーションプロバティ名を確認するには、CSDL $metadata ドキュメント を使用します。

  • @odata.bind 注釈を使用して単一値ナビゲーション プロパティを設定することによって、ビジネス プロセス フローの定義で指定される有効なステージにビジネスプロセス フロー テーブル行を関連付けます。 ビジネス プロセス フローの定義のステージ行を指すナビゲーション プロバティ名 (通常 activestageid) を確認するには、CSDL $metadata ドキュメント を使用します。

    また、ビジネス・プロセス・フロー定義のIDが 2669927e-8ad6-4f95-8a9a-f1008af6956fであると仮定して、次のWeb API要求を使用することでビジネス プロセス フロー定義のすべてのステージに関する情報を取得することができます:

    要求

    GET [Organization URI]/api/data/v9.0/processstages?$select=stagename&$filter=processid/workflowid eq 2669927e-8ad6-4f95-8a9a-f1008af6956f HTTP/1.1
    

    応答

    {
        "@odata.context": "[Organization URI]/api/data/v9.0/$metadata#processstages(stagename)",
        "value": [
            {
                "@odata.etag": "W/\"858240\"",
                "stagename": "S1",
                "processstageid": "9a9185f5-b75b-4bbb-9c2b-a6626683b99b"
            },
            {
                "@odata.etag": "W/\"858239\"",
                "stagename": "S3",
                "processstageid": "a107e2fd-7543-4c1a-b6b4-b8060ecb1a1a"
            },
            {
                "@odata.etag": "W/\"858238\"",
                "stagename": "S2",
                "processstageid": "19a11fc0-3398-4214-8522-cb2a97f66e4b"
            }
        ]
    }
    

次に、以下のリクエストを使用して、取引先企業行 (ID=a176be9e-9a68-e711-80e7-00155d41e206) のビジネス プロセス フローの定義およびプロセス インスタンスの最初のステージとしてアクティブ ステージ セット、S1 (ID=9a9185f5-b75b-4bbb-9c2b-a6626683b99b) のインスタンスを作成します:

要求

POST [Organization URI]/api/data/v9.0/new_mycustombpfs HTTP/1.1 
Content-Type: application/json; charset=utf-8 
OData-MaxVersion: 4.0 
OData-Version: 4.0 
Accept: application/json 

{
    "bpf_accountid@odata.bind": "/accounts(a176be9e-9a68-e711-80e7-00155d41e206)",
    "activestageid@odata.bind": "/processstages(9a9185f5-b75b-4bbb-9c2b-a6626683b99b)"    
}

応答

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v9.0/new_mycustombpfs(cc3f721b-026e-e811-80ff-00155d513100)

最初のステージ以外のステージでアクティブ ステージ セットによる業務プロセス フローの定義のインスタンスを作成する場合は、要求で traversedpath も提供する必要があることに注意してください。 渡ったパスは業務プロセス フロー インスタンスのアクセス済みステージを表すプロセス ステージ ID のコンマ区切り文字列です。 次の要求は、取引先企業行 (ID=679b2464-71b5-e711-80f5-00155d513100) のインスタンスを作成し、第二ステージ S2 (ID=19a11fc0-3398-4214-8522-cb2a97f66e4b) としてアクティブ ステージ セットを作成します。

POST [Organization URI]/api/data/v9.0/new_mycustombpfs HTTP/1.1 
Content-Type: application/json; charset=utf-8 
OData-MaxVersion: 4.0 
OData-Version: 4.0 
Accept: application/json 

{
    "bpf_accountid@odata.bind": "/accounts(679b2464-71b5-e711-80f5-00155d513100)",
    "activestageid@odata.bind": "/processstages(19a11fc0-3398-4214-8522-cb2a97f66e4b)",
    "traversedpath":"9a9185f5-b75b-4bbb-9c2b-a6626683b99b,19a11fc0-3398-4214-8522-cb2a97f66e4b"   
}

ビジネス プロセス フロー テーブル行 (プロセス インスタンス) の更新

次または前のステージへの移動、プロセス インスタンスの破棄、プロセス インスタンスを再アクティブ化、またはプロセス インスタンスの完了を行うためにプロセス インスタンスを更新できます。

ステージ ナビゲーション

別のステージに移動するには、プロセス インスタンス行を更新して、アクティブ ステージ ID を変更し、それに応じて渡ったパスを更新する必要があります。 業務プロセス フロー インスタンスを更新する際、次または前のステージに移動するだけでなければならないことに注意してください。

ステージ ナビゲーションを行うには、更新する業務プロセス フロー インスタンスの ID が必要です。 ビジネス プロセス フローのすべてのインスタンスを取得するには、ビジネス プロセス フロー テーブルのすべての行 (インスタンス) を取得する を先に参照してください。

更新するプロセス インスタンスの ID が dc2ab599-306d-e811-80ff-00155d513100 であると仮定して、次のリクエストを使用して、S1 から S2 にアクティブ ステージを更新します:

PATCH [Organization URI]/api/data/v9.0/new_mycustombpfs(dc2ab599-306d-e811-80ff-00155d513100) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

{
    "activestageid@odata.bind": "/processstages(19a11fc0-3398-4214-8522-cb2a97f66e4b)",
    "traversedpath": "9a9185f5-b75b-4bbb-9c2b-a6626683b99b,19a11fc0-3398-4214-8522-cb2a97f66e4b"
}

プロセス インスタンスの状態の変更: 中止、再アクティブ化、または終了

プロセス インスタンスには、次の状態のうち 1 つを使用できます: アクティブ終了、または中止。 状態はプロセス インスタンス行の次の列によって決まります:

  • statecode: プロセス インスタンスの状態を表示します。

    ラベル
    0 Active
    1 非アクティブ
  • statuscode: プロセス インスタンスの状態に関する情報を表示します。

    Value ラベル
    1 Active
    2 終了
    3 中止

そのため、プロセスのインスタンスを中止するには、次の要求を使用して statecodestatuscode の値を適切に設定します:

PATCH [Organization URI]/api/data/v9.0/new_mycustombpfs(dc2ab599-306d-e811-80ff-00155d513100) HTTP/1.1   
Content-Type: application/json   
OData-MaxVersion: 4.0   
OData-Version: 4.0 
  
{ 
    "statecode" : "1", 
    "statuscode": "3" 
}

Note

任意のステージでプロセス インスタンスを中止できます。

同様に、プロセス インスタンスを再アクティブ化するには、上記のコードのstatecodestatuscode の値を01にそれぞれ置き換えます。

最後に、プロセス インスタンスの状態を、プロセス インスタンスの最終ステージでのみ有効な終了に設定するには、上記のコードの statecodestatuscode の値を02 にそれぞれ置き換えます。

クロス テーブル ナビゲーション

この例にて使用するテーブル間のナビゲーションでは、プロセス インスタンスのアクティブ ステージを最終ステージ S3 (ID=a107e2fd-7543-4c1a-b6b4-b8060ecb1a1a) に設定し、移動パスをそれに応じて更新し、ビジネス プロセス フロー定義に従って連絡先行をプライマリテーブル行として設定する必要があります。

PATCH [Organization URI]/api/data/v9.0/new_mycustombpfs(dc2ab599-306d-e811-80ff-00155d513100) HTTP/1.1   
Content-Type: application/json   
OData-MaxVersion: 4.0   
OData-Version: 4.0 
  
{
    "activestageid@odata.bind": "/processstages(a107e2fd-7543-4c1a-b6b4-b8060ecb1a1a)",
    "traversedpath":"9a9185f5-b75b-4bbb-9c2b-a6626683b99b,19a11fc0-3398-4214-8522-cb2a97f66e4b,a107e2fd-7543-4c1a-b6b4-b8060ecb1a1a",
    "bpf_contactid@odata.bind": "/contacts(0e3f10b0-da33-e811-80fc-00155d513100)"
}

ビジネス プロセス フロー テーブル行 (プロセス インスタンス) の削除

次の Web API 要求を使用します:

要求

DELETE [Organization URI]/api/data/v9.0/new_mycustombpfs(dc2ab599-306d-e811-80ff-00155d513100) HTTP/1.1

回答

この行が存在する場合は、削除に成功したことを示す状態が 204 の通常応答を受け取ります。 このテーブルが存在しなかった場合は、状態が 404 の応答を受け取ります。

RetrieveProcessInstances and RetrieveActivePath メッセージを使用する

RetrieveProcessInstances メッセージ (RetrieveActivePath Function または RetrieveProcessInstancesRequest) を使用して、すべてのビジネス プロセス フローの定義でテーブル行のすべてのビジネス ビジネス フローのインスタンスを取得します。 テーブルに対して返されるビジネス プロセス フロー インスタンスは、インスタンスの modifiedon 列に基づいて順序付けられます。 たとえば、最後に変更されたビジネス プロセス フロー インスタンスは、返されたコレクションの 最初 の行になります。 最後に変更されたビジネス プロセス フロー インスタンスは、テーブル行の UI でアクティブなインスタンスです。

RetrieveProcessInstances メッセージを使用した結果としてテーブル行に対して返された各ビジネス プロセス フロー インスタンス行は、アクティブ ステージの ID を processstageid 鉄に格納します。この ID は、アクティブ ステージを検出して、前または次のステージに移動するために使用されます。 これを行うには、まずビジネス プロセス フロー インスタンスのアクティブ パスと、RetrieveActivePath メッセージ (RetrieveActivePath Function または RetrieveActivePathRequest) を使用してプロセス フロー インスタンスで使用できるステージを見つける必要があります。

アクティブ ステージと業務プロセス フロー インスタンスのアクティブ パス情報を取得したら、その情報を使用してアクティブ パスの前または次のステージに移動できます。 ステージの前方へのナビゲーションは、順番に実行する必要があります。つまり、アクティブなパスの次のステージに進むだけです。

組織サービス を使用してコードがこれら 2 つのメソッドおよびステージ ナビゲーションを示す完全なサンプルについては、サンプル: 業務プロセス フローの使用 を参照してください。

テーブル行の作成時にビジネス プロセス フローを適用する

このセクションでは、Dataverse で作成された新しいテーブル行にビジネス プロセス フローを自動的に適用するための既定の動作、およびそれを上書きして新しいテーブル行に自分で選択したビジネス プロセス フローを適用する方法について説明します。

既定では、複数のビジネス プロセス フローが定義されているテーブルの場合、システムは次のマルチステップ ロジックを使用して新しいテーブル行にビジネス プロセス フローを適用します。

  1. ビジネス プロセス フロー定義行の Workflow.PrimaryEntity 列に基づいて、新しいテーブル行に適用可能なすべてのビジネス プロセス フローを識別します。
  2. 現在のユーザーがアクセスできる業務プロセス フロー定義を識別します。 業務プロセス フローへのアクセスがどのように決定され管理されるかについては、このトピックで前述した「業務プロセス フローのセキュリティを管理する」を参照してください。
  3. システム内のすべての業務プロセス フローには、テーブルごとにグローバル順序が適用されます。 ビジネス プロセス フローの順序は、Workflow.ProcessOrder 列に格納されています。 テーブルのビジネス プロセス フローの定義は、この順序に基づいて並べ替えられ、順序の値が最も低いものが選択されます。
  4. 最後に、テーブル行がビジネス アプリ (アプリ モジュール) から作成された場合、新しいテーブル行に自動的に適用されるビジネス プロセス フローを選択するために、フィルタリングの追加のレベルが適用されます。 アプリで操作する場合、ユーザーはビジネス アプリに割り当てられたセキュリティ ロールゆえにアクセスできる該当するテーブル、ビジネス プロセス フロー、ビュー、およびフォームにしかアクセスできません。
    • ビジネス アプリに業務プロセス フローが含まれない場合、手順 3 まで説明されたとおりに業務プロセス フローが適用されます。
    • ビジネス アプリに 1 つ以上の業務プロセス フローがある場合、アプリにある業務プロセス フローのみが適用されます。 この場合、ユーザーがビジネス アプリのコンテキスト内で作業しているなら、手順 3 の業務プロセス フローのリストはアプリ モジュール内にあるビジネス アプリの一部であるものにフィルタリングされ、プロセス順序に基づいて並べ替えられます。
    • テーブルのビジネス アプリに業務プロセス フローがない場合、またはユーザーがアクセスできるものにビジネス プロセス フローがない場合、新しいテーブル行にビジネス プロセス フローは適用されません。

新しいテーブル行に自動的に適用されるビジネス プロセス フローの既定のロジックは上書きできます。 上書きするには、新規テーブル行を作成する際にテーブルの ProcessId 列を次のいずれかの値に設定します。

  • 新しいテーブル行のビジネス プロセス フローの設定をスキップするには、Guid.Empty に設定します。 これは、テーブル行を一括作成するもののビジネス プロセス フローを適用しない場合に行えます。
  • 特定のビジネス プロセス フローのテーブルに設定します (テーブル参照として)。 この場合、システムは既定ロジックの代わりに、選択した特定の業務プロセス フローを適用します。

新規テーブル行の作成時に ProcessId 列の値を設定しない場合、システムは前述したように既定のロジックを適用します。

Note

新しいテーブル行に自動的に適用されるビジネス プロセス フローの既定のロジックを上書きすることは、プログラムでのみサポートされています。 UI を使用して行うことはできません。

ビジネス プロセス フローに対応するテーブルの従来のプロセス関連の列 (ProcessIdStageIdTraversedPath など) は、既に非推奨になっています。 ターゲット テーブル行に対してこのような従来のプロセス関連の属性を操作すると、ビジネス プロセス フローの状態の一貫性を保証できません。サポートされるシナリオ ではありません。 推奨されている方法は、セクション ビジネス プロセス フロー テーブル行の作成、取得、更新、および削除 (プロセス インスタンス) の前半で説明されるように、ビジネス プロセス フロー テーブルの列を使用することです

これの唯一の例外は、プログラムで ProcessId 列を変更すると同時に、前のセクション: テーブル列の作成時にビジネス プロセス フローを適用する で説明されているように、ビジネス プロセス フローの既定のアプリケーションを新しい行で上書きすることです。

業務プロセス フローのクライアント側でのプログラムのサポート

フォーム スクリプトの中でビジネス プロセス フローと対話するために使用できるクライアント サイドのオブジェクトがあります。 ビジネス プロセス フローは、プロセスがレコードに適用されたり、ステージが変更されたり、状態が ActiveFinished、または Aborted に変更されたりするたびにクライアント側のイベントをトリガします。 詳細: formContext.data.process (クライアント API 参照)

プロセス、ステージおよび手順の最大数

テーブルごとの、アクティブ化された業務プロセス フローの最大数の既定値は 10 です。 Organization.MaximumActiveBusinessProcessFlowsAllowedPerEntity 列を使用して別の値を指定できます。 ただし、値が 10 より大きい場合、プロセスを切り替えるとき、または業務プロセス フローが割り当てられている列を開くときのシステム パフォーマンスが低下することがあります。 このことは、プロセスが複数のテーブルにまたがっている場合に特に顕著です。

次の設定はカスタマイズできません。

  • プロセス内のテーブルあたりの最大数が 30 です。

  • 各ステージのステップの最大数は 30 です。

  • プロセス フローに参加できるテーブルの最大数は 5 です。